# HG changeset patch
# User Olivier Delalleau <delallea@iro>
# Date 1284755969 14400
# Node ID 9ebd40d31a1bab2777f7e580949fe545ecbb2df5
# Parent  67f4edabb0cc9c462977a0b57a2cdd4a2edeacbf
API_coding_style: Added some comments following up on what was discussed during meeting

diff -r 67f4edabb0cc -r 9ebd40d31a1b doc/v2_planning/API_coding_style.txt
--- a/doc/v2_planning/API_coding_style.txt	Fri Sep 17 16:23:51 2010 -0400
+++ b/doc/v2_planning/API_coding_style.txt	Fri Sep 17 16:39:29 2010 -0400
@@ -44,7 +44,8 @@
     * Use only one space (not two) after a sentence-ending period in comments.
 
     * You do not need to add an extra blank line before the closing quotes of
-      a multi-line docstring.
+      a multi-line docstring. Also, we ask that the first line of a multi-line
+      docstring should contain only the opening quotes.
 
       .. code-block:: python
 
@@ -310,11 +311,15 @@
             cond_2 and
             cond_3):
 
+            # Note that we added a blank line above to avoid confusion between
+            # conditions and the rest of the code (this would not have been
+            # needed if they were at significantly different indentation levels).
             ... 
         # Bad.
         if cond_1 and \
            cond_2 and \
            cond_3:
+
             ...
 
     * When indenting multi-line statements like lists or function arguments,