Re: Documenting extension modules?

Discussion in 'Python' started by Francois De Serres, Jul 15, 2005.

  1. Robert Kern wrote:

    >Francois De Serres wrote:
    >
    >
    >>Hiho,
    >>
    >>I can't seem to find a proper way to document my extension module.
    >>Following the C API doc:
    >>
    >>static PyMethodDef ioMethods[] = {
    >> {"o_count", o_count, METH_VARARGS, "Return the count of available
    >>MIDI outputs."},
    >>....
    >>}
    >>
    >>lacks:
    >>a) module level documentation
    >>
    >>

    >
    >In your init<module> function, assign a PyStr object to __doc__.
    >
    >
    >
    >>b) function parameters
    >>
    >>

    >
    >Add that information to your docstring. I don't think that there is a
    >way to get this information via inspect.
    >
    >
    >
    >>Also, I'd like to know if there's a typical format for the help string
    >>(but in C), compatible with docstring's
    >>"""short desription
    >>
    >>long description"""
    >>
    >>

    >
    >char *o_count__doc__;
    >char *o_count__doc__ = "short description\n"\
    >"\n"\
    >"long description\n";
    >
    >
    >

    Mucho thankees Robert.
     
    Francois De Serres, Jul 15, 2005
    #1
    1. Advertising

  2. Re: assigning a PyStr object to __doc__, take a look at Py_InitModule3,
    which does that for you.

    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
     
    Simon Dahlbacka, Jul 15, 2005
    #2
    1. Advertising

  3. 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.
     
    Francois De Serres, Jul 15, 2005
    #3
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Tim Almond

    Documenting ASP.NET

    Tim Almond, Jul 11, 2003, in forum: ASP .Net
    Replies:
    1
    Views:
    463
    Kevin Spencer
    Jul 12, 2003
  2. Nikhil Patel

    documenting projects

    Nikhil Patel, Oct 11, 2004, in forum: ASP .Net
    Replies:
    1
    Views:
    289
    Rakesh Rajan
    Oct 11, 2004
  3. Jussi Jumppanen

    ANN: zOxygen Documenting Utility

    Jussi Jumppanen, Apr 21, 2004, in forum: Java
    Replies:
    0
    Views:
    315
    Jussi Jumppanen
    Apr 21, 2004
  4. Anand
    Replies:
    3
    Views:
    908
    Tim Daneliuk
    Nov 8, 2003
  5. Francois De Serres

    Documenting extension modules?

    Francois De Serres, Jul 15, 2005, in forum: Python
    Replies:
    0
    Views:
    289
    Francois De Serres
    Jul 15, 2005
Loading...

Share This Page