Add information about writing docstrings in C code.

pep-0007.txt

@@ -140,6 +140,54 @@ Naming conventions
       for example: PyString_AS_STRING, Py_PRINT_RAW.
 
 
+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
 
     [1] PEP 8, Style Guide for Python Code, van Rossum, Warsaw