[Python-checkins] python/nondist/peps pep-0007.txt,1.2,1.3

[fdrake@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/peps
In directory usw-pr-cvs1:/tmp/cvs-serv2775

Modified Files:
	pep-0007.txt 
Log Message:
Add information about writing docstrings in C code.


Index: pep-0007.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0007.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** pep-0007.txt	5 Jul 2001 18:53:01 -0000	1.2
--- pep-0007.txt	20 Jun 2002 18:56:11 -0000	1.3
***************
*** 141,144 ****
--- 141,192 ----
  
  
+ Documentation Strings
+ 
+     - Use the PyDoc_STR() or PyDoc_STRVAR() macro for docstrings to
+       support building Python without docstrings (./configure
+       --without-doc-strings).
+ 
+       For C code that needs to support versions of Python older than
+       2.3, you can include this after including Python.h:
+ 
+         #ifndef PyDoc_STR
+         #define PyDoc_VAR(name)         static char name[]
+         #define PyDoc_STR(str)          (str)
+         #define PyDoc_STRVAR(name, str) PyDoc_VAR(name) = PyDoc_STR(str)
+         #endif
+ 
+     - The first line of each fuction docstring should be a "signature
+       line" that gives a brief synopsis of the arguments and return
+       value.  For example:
+ 
+         PyDoc_STRVAR(myfunction__doc__,
+         "myfunction(name, value) -> bool\n\n\
+         Determine whether name and value make a valid pair.");
+ 
+       Always include a blank line between the signature line and the
+       text of the description.
+ 
+       If the return value for the function is always None (because
+       there is no meaningful return value), do not include the
+       indication of the return type.
+ 
+     - When writing multi-line docstrings, be sure to always use
+       backslash continuations, as in the example above, or string
+       literal concatenation:
+ 
+         PyDoc_STRVAR(myfunction__doc__,
+         "myfunction(name, value) -> bool\n\n"
+         "Determine whether name and value make a valid pair.");
+ 
+       Though some C compilers accept string literals without either:
+ 
+         /* BAD -- don't do this! */
+         PyDoc_STRVAR(myfunction__doc__,
+         "myfunction(name, value) -> bool\n\n
+         Determine whether name and value make a valid pair.");
+ 
+       not all do; the MSVC compiler is known to complain about this.
+ 
+ 
  References