Documenting extension modules?

[Francois De Serres]

Simon Dahlbacka wrote:

>Re: assigning a PyStr object to __doc__, take a look at Py_InitModule3,
>which does that for you.
>
>  
>
got it, thx.

>Then you have the PyDoc_STRVAR macro in python.h that you might want to
>use (see definition below). But as Robert already told you, you'll need
>to provide the necessary information about i.e. parameters yourself in
>the docstrings.
>
>/* Define macros for inline documentation. */
>#define PyDoc_VAR(name) static char name[]
>#define PyDoc_STRVAR(name,str) PyDoc_VAR(name) = PyDoc_STR(str)
>#ifdef WITH_DOC_STRINGS
>#define PyDoc_STR(str) str
>#else
>#define PyDoc_STR(str) ""
>#endif
>
>  
>
beautiful.

PS: The following snip from http://python.fyxm.net/peps/pep-0007.html 
was helpful to me in understanding usage of these macros:

    - 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.