Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Re: Documenting extension modules?

Reply
Thread Tools

Re: Documenting extension modules?

 
 
Francois De Serres
Guest
Posts: n/a
 
      07-15-2005
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.
 
Reply With Quote
 
 
 
 
Simon Dahlbacka
Guest
Posts: n/a
 
      07-15-2005
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

 
Reply With Quote
 
 
 
 
Francois De Serres
Guest
Posts: n/a
 
      07-15-2005
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.








 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Documenting VisionSet Java 10 02-01-2006 09:10 PM
Documenting extension modules? Francois De Serres Python 0 07-15-2005 10:29 AM
documenting projects Nikhil Patel ASP .Net 1 10-11-2004 05:03 PM
ANN: zOxygen Documenting Utility Jussi Jumppanen Java 0 04-21-2004 05:46 AM
Documenting ASP.NET Tim Almond ASP .Net 1 07-12-2003 03:21 PM



Advertisments