bk commit - mysqldoc@docsrva tree (paul:1.3399)

[paul]

Below is the list of changes that have just been committed into a local
mysqldoc repository of paul. When paul does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html

ChangeSet
  1.3399 05/08/25 17:58:55 paul@stripped +1 -0
  internals.xml:
    Apply Konstantin's patch.

  internals/internals.xml
    1.22 05/08/25 17:58:43 paul@stripped +58 -6
    Apply Konstantin's patch.

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	paul
# Host:	frost.snake.net
# Root:	/Volumes/frost2/MySQL/bk/mysqldoc

--- 1.21/internals/internals.xml	2005-08-22 15:05:10 -05:00
+++ 1.22/internals/internals.xml	2005-08-25 17:58:43 -05:00
@@ -2110,9 +2110,9 @@
 
 <programlisting>
     {
-      code,code,code
+      code, code, code
       {
-        code,code,code
+        code, code, code
       }
     }
 </programlisting>
@@ -2166,11 +2166,11 @@
         </para>
 
 <programlisting>
-   if (code,code,code)
+   if (code, code, code)
    {
-     code,code,code;
+     code, code, code;
    }
-   for (code,code,code)
+   for (code, code, code)
    {}
 </programlisting>
       </listitem>
@@ -2271,7 +2271,8 @@
 <programlisting>
 int *var;
 
-if (x == y + 2) function_call();
+if (x == y + 2)
+  function_call();
 </programlisting>
       </listitem>
 
@@ -2412,6 +2413,12 @@
           Avoid capitalization except for class names; class names
           should begin with a capital letter.
         </para>
+
+<programlisting>
+class Item;
+class Query_arena;
+class Log_event;
+</programlisting>
       </listitem>
 
       <listitem>
@@ -2512,6 +2519,19 @@
 
       <listitem>
         <para>
+          Align short side <literal>//</literal> or /* ... */ comments
+          by 48 column (start the comment in column 49).
+        </para>
+
+<programlisting>
+  {
+    qc*= 2;                                     /* double the estimation */
+  }
+</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>
           Function comments are important! When commenting a function,
           note the IN parameters (the word IN is implicit).
         </para>
@@ -2519,6 +2539,38 @@
         <para>
           Every function should have a description unless the function
           is very short and its purpose is obvious.
+        </para>
+
+        <para>
+          Use the following example as a template for function comments:
+        </para>
+
+<programlisting>
+/*
+  Initialize SHA1Context
+
+  SYNOPSIS
+    sha1_reset()
+    context in/out       The context to reset.
+
+  DESCRIPTION
+    This function will initialize the SHA1Context in preparation
+    for computing a new SHA1 message digest.
+
+  RETURN VALUE
+    SHA_SUCCESS          ok
+    != SHA_SUCCESS       sha Error Code.
+*/
+
+int sha1_reset(SHA1_CONTEXT *context)
+{
+ ...
+
+</programlisting>
+
+        <para>
+          Additional sections can be used: WARNING, NOTES, TODO, SEE
+          ALSO, ERRORS, REFERENCED BY.
         </para>
       </listitem>