Changes between Version 1 and Version 2 of documentation


Ignore:
Timestamp:
09/22/14 15:45:42 (6 years ago)
Author:
mhnguyen
Comment:

Adding some information how to document codes

Legend:

Unmodified
Added
Removed
Modified
  • documentation

    v1 v2  
    188188Parallel writing from each client process (or server process) in attached mode (or server mode) to one file. 
    189189Mode available only with "netcdf4_par" as complation option. 
     190 
     191== Documentation policy == 
     192The documentation is compliant with DOXYGEN syntax and all html documentations are automatically generated in directory doc 
     193There are some general points which we should follow: 
     194  * The language of documentation is English 
     195  * Function declarations are documented with brief (one-line, one-sentence) comments and only brief comments. 
     196  * Function definitions (inline or not) are documented with detailed comments. 
     197Below are instructions to document codes in details 
     198 
     1991. File 
     200Here is the structure of the comment one developer should write to document a file (header or source). This part of comment must be at the beginning of a file, before anything else. 
     201{{{ 
     202/*! 
     203   \file context.hpp 
     204   \author Yann Meurdesoif  
     205   \date 25 jan 2011 
     206   \since 3 mar 2007 
     207 
     208   \brief comment. 
     209 
     210   next part of detailed comment 
     211 */ 
     212}}} 
     213  * The macro \date indicates file creation date 
     214  * The macro \since specifies the latest modification 
     215  * The macro \brief provides overview information of file 
     216In case of multiple authors, the macro \authors should be used 
     217{{{ 
     218/*! 
     219   \file context.hpp 
     220   \authors Yann Meurdesoif, Arnaud Caubel  
     221   \date 25 jan 2011 
     222   \since 3 mar 2007 
     223 
     224   \brief comment. 
     225 
     226   next part of detailed comment 
     227 */ 
     228}}} 
     229 
     2302. Class, typedef, enum and struct 
     231A class documentation is written just before the class declaration/definition in the 
     232 header file with the following structure: 
     233{{{ 
     234/*! 
     235    \class A 
     236    \brief comment associated to A 
     237 
     238    next part of detailed comment associated to A 
     239 */ 
     240class A { 
     241... 
     242}; 
     243}}} 
     244For typedef, enum and struct, instead of the macro \class, the corresponding macros \typedef, \enum and \struct should be used. 
     245 
     2463. Attributes 
     247Simply, attributes should be commented with one of these syntaxes 
     248{{{ 
     249class A { 
     250  public : 
     251    //! comment associated to i 
     252    int i; 
     253    double j; //!< comment associated to j 
     254    /*! 
     255      comment associated to k 
     256     */ 
     257    B k; 
     258    ... 
     259}}} 
     260  
     2614. Functions and constructors 
     262Function declaration is documented with a brief comment, and only a brief comment.  
     263All of the following syntaxes, shown here for in-class function but also valid for external ones, can be used  
     264{{{ 
     265class A { 
     266  public : 
     267    ... 
     268   //! brief comment associated to declaration of f 
     269   void f(); 
     270 
     271   /*!  
     272       brief comment associated to declaration of g 
     273    */ 
     274   void g(); 
     275    
     276   void h(); //!< comment associated to declaration of h 
     277}; 
     278}}} 
     279Functions definitions (inline or not) are documented with detailed comments. 
     280If the declaration has not been commented first, the first line of the comment will be the 
     281brief comment. The below syntaxes are for inline operations but valid for the other types 
     282{{{ 
     283class A { 
     284  public : 
     285    B b; 
     286    ... 
     287   //! comment associated to definition of f 
     288   void f() { 
     289   ... 
     290   } 
     291   void g() //! comment associated to definition of g 
     292   { 
     293   ... 
     294   } 
     295   A() //! comment associated to definition of composite constructor 
     296   : B()  
     297   { 
     298   ... 
     299   } 
     300 
     301   /*! 
     302      comment associated to definition of h 
     303    */ 
     304   void h() { 
     305   ... 
     306   } 
     307}; 
     308}}} 
     309 
     3105. Arguments 
     311Only in the case of a function definition, arguments and return value might be documented with following convention 
     312{{{ 
     313/*! 
     314    comment of function f 
     315 */ 
     316int f (double d, //!< comment of d 
     317       int i //!< comment of i 
     318      ) { 
     319... 
     320} 
     321/*! 
     322    comment of function g 
     323    \param [in] d comment of d 
     324    \param [in/out] i comment of i 
     325    \return comment of return value 
     326 */ 
     327int g (double d, int i) { 
     328... 
     329} 
     330}}}