svn commit - mysqldoc@docsrva: r5168 - trunk/internals

[kosipov]

Author: kosipov
Date: 2007-03-05 14:13:46 +0100 (Mon, 05 Mar 2007)
New Revision: 5168

Log:
Update the Coding Guidelines with Doxygen information and references.


Modified:
   trunk/internals/coding-guidelines.xml


Modified: trunk/internals/coding-guidelines.xml
===================================================================
--- trunk/internals/coding-guidelines.xml	2007-03-05 06:51:12 UTC (rev 5167)
+++ trunk/internals/coding-guidelines.xml	2007-03-05 13:13:46 UTC (rev 5168)
Changed blocks: 5, Lines Added: 53, Lines Deleted: 24; 4431 bytes

@@ -467,7 +467,34 @@
 
       <listitem>
         <para>
-          When writing multi-line comments: put the '/*' and '*/' on
+          MySQL uses Doxygen comments for file, section, class,
+          structure, function and mehtod comments.
+          The source code documentation generated by Doxygen is
+          available
+          <ulink url="http://dev.mysql.com/sources/doxygen/mysql-5.1/">
+          online</ulink>.
+        </para>
+
+
+        <para>
+          MySQL prefers the Javadoc flavor of Doxygen commenting
+          style: we use @tag rather than \tag. The basic tags in
+          use are @brief, @class, @fn, @param, @return, @retval,
+          @see, @note, @file.
+        </para>
+
+        <para>
+          The general guideline is to put a comment in front of its
+          subject. In particular, function and method comments
+          should be placed in front of implementation rather than
+          declaration. Class comments should be put in front of
+          class declaration.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          When writing multi-line comments please put the '/*' and '*/' on
           their own lines, put the '*/' below the '/*', put a line break
           and a two-space indent after the '/*', do not use additional
           asterisks on the left of the comment.

@@ -523,7 +550,7 @@
 
       <listitem>
         <para>
-          When commenting members of a structure or a class , align
+          When commenting members of a structure or a class, align
           comments by 48th column. If a comment doesn't fit into one
           line, move it to a separate line. Do not create multiline
           comments aligned by 48th column.

@@ -549,38 +576,35 @@
 
       <listitem>
         <para>
-          Function comments are important! When commenting a function,
-          note the IN parameters (the word IN is implicit).
+          Every structure, class, method or function should have a
+          description unless it is very short and its purpose is
+          obvious.
         </para>
 
         <para>
-          Every function should have a description unless the function
-          is very short and its purpose is obvious.
+          When commenting a function, note the IN and OUT
+          parameters. IN is implicit, but can be specified with
+          tag @param[in]. For OUT and INOUT parameters you can use
+          tags @param[out] and @param[in,out] respectively.
         </para>
 
-        <remark role="todo">
-          [MC] Need to add notes on Doxygen
-        </remark>
-
         <para>
-          Use the following example as a template for function comments:
+          Use the following example as a template for function or
+          method comments:
         </para>
 
 <programlisting>
 /*
-  Initialize SHA1Context
+  @brief Initialize SHA1Context
 
-  SYNOPSIS
-    sha1_reset()
-      context in/out     The context to reset.
+  @details This function will initialize the SHA1Context in
+  preparation for computing a new SHA1 message digest.
 
-  DESCRIPTION
-    This function will initialize the SHA1Context in preparation
-    for computing a new SHA1 message digest.
+  @param[in,out]  context  The context to reset.
 
-  RETURN VALUE
-    SHA_SUCCESS          ok
-    != SHA_SUCCESS       sha Error Code.
+  @return Operation status
+    @retval SHA_SUCCESS      ok
+    @retval != SHA_SUCCESS   sha Error Code.
 */
 
 int sha1_reset(SHA1_CONTEXT *context)

@@ -589,8 +613,13 @@
 </programlisting>
 
         <para>
-          Additional sections can be used: WARNING, NOTES, TODO, SEE
-          ALSO, ERRORS, REFERENCED BY.
+          Additional sections can be used: @warning, @note, @todo,
+          @see. Please refer to
+          <ulink
+          url="http://www.stack.nl/~dimitri/doxygen/manual.html">Doxygen
+          Manual</ulink> and <ulink
+          url="http://forge.mysql.com/wiki/CommunityDoxygenProject">
+          CommunityDoxygenProject</ulink> for additional information.
         </para>
       </listitem>
 

@@ -993,7 +1022,7 @@
 set smartindent
 set cindent
 set cinoptions=g0:0t0c2C1(0f0l1
-"set expandtab "uncomment if you don't want to use tabstops
+set expandtab
 </programlisting>
 
     <para>