Changes between Version 1 and Version 2 of documentation

Timestamp:

09/22/14 15:45:42 (10 years ago)

Author:

mhnguyen

Comment:

Adding some information how to document codes

documentation

@@ -188 +188 @@
 Parallel writing from each client process (or server process) in attached mode (or server mode) to one file.
 Mode available only with "netcdf4_par" as complation option.
+
+== Documentation policy ==
+The documentation is compliant with DOXYGEN syntax and all html documentations are automatically generated in directory doc
+There are some general points which we should follow:
+  * The language of documentation is English
+  * Function declarations are documented with brief (one-line, one-sentence) comments and only brief comments.
+  * Function definitions (inline or not) are documented with detailed comments.
+Below are instructions to document codes in details
+
+1. File
+Here 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.
+{{{
+/*!
+   \file context.hpp
+   \author Yann Meurdesoif 
+   \date 25 jan 2011
+   \since 3 mar 2007
+
+   \brief comment.
+
+   next part of detailed comment
+ */
+}}}
+  * The macro \date indicates file creation date
+  * The macro \since specifies the latest modification
+  * The macro \brief provides overview information of file
+In case of multiple authors, the macro \authors should be used
+{{{
+/*!
+   \file context.hpp
+   \authors Yann Meurdesoif, Arnaud Caubel 
+   \date 25 jan 2011
+   \since 3 mar 2007
+
+   \brief comment.
+
+   next part of detailed comment
+ */
+}}}
+
+2. Class, typedef, enum and struct
+A class documentation is written just before the class declaration/definition in the
+ header file with the following structure:
+{{{
+/*!
+    \class A
+    \brief comment associated to A
+
+    next part of detailed comment associated to A
+ */
+class A {
+...
+};
+}}}
+For typedef, enum and struct, instead of the macro \class, the corresponding macros \typedef, \enum and \struct should be used.
+
+3. Attributes
+Simply, attributes should be commented with one of these syntaxes
+{{{
+class A {
+  public :
+    //! comment associated to i
+    int i;
+    double j; //!< comment associated to j
+    /*!
+      comment associated to k
+     */
+    B k;
+    ...
+}}}
+ 
+4. Functions and constructors
+Function declaration is documented with a brief comment, and only a brief comment. 
+All of the following syntaxes, shown here for in-class function but also valid for external ones, can be used 
+{{{
+class A {
+  public :
+    ...
+   //! brief comment associated to declaration of f
+   void f();
+
+   /*! 
+       brief comment associated to declaration of g
+    */
+   void g();
+   
+   void h(); //!< comment associated to declaration of h
+};
+}}}
+Functions definitions (inline or not) are documented with detailed comments.
+If the declaration has not been commented first, the first line of the comment will be the
+brief comment. The below syntaxes are for inline operations but valid for the other types
+{{{
+class A {
+  public :
+    B b;
+    ...
+   //! comment associated to definition of f
+   void f() {
+   ...
+   }
+   void g() //! comment associated to definition of g
+   {
+   ...
+   }
+   A() //! comment associated to definition of composite constructor
+   : B() 
+   {
+   ...
+   }
+
+   /*!
+      comment associated to definition of h
+    */
+   void h() {
+   ...
+   }
+};
+}}}
+
+5. Arguments
+Only in the case of a function definition, arguments and return value might be documented with following convention
+{{{
+/*!
+    comment of function f
+ */
+int f (double d, //!< comment of d
+       int i //!< comment of i
+      ) {
+...
+}
+/*!
+    comment of function g
+    \param [in] d comment of d
+    \param [in/out] i comment of i
+    \return comment of return value
+ */
+int g (double d, int i) {
+...
+}
+}}}