Re: [Epydoc-devel] __init__ params for extension type?

[Edward L. <ed...@gr...>]

On Jul 12, 2006, at 9:58 AM, Barry Warsaw wrote:
> FTR: still currently using epydoc 2.1
>
> Where would I document the parameters for extension types?  I thought
> I could add @param and @type fields to the docstring for the tp_doc
> slot, but when I generate the documentation I just get warnings like:
>
> In foo.Bar docstring:
>      - Warning: Invalid context for field tag 'param'
>
> In the generated documentation for the class's __init__() you see:
>
> x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Try something like this as your docstring:

"x.__init__(a, b, c) -- initializes x, using parameters a, b, and c."

This is the convention that's used by most builtin functions, and  
epydoc understands it.  (I.e., epydoc will detect the signature in  
the docstring, parse it, and extract the variable names.)  Epydoc  
also understands a bunch of variants -- for the details, search for  
"SIGNATURE_RE" in epydoc/objdoc.py.

Once you've provided the signature in the first line of the  
docstring, you can then use @param, @type, etc., if you want to  
provide more info about some of the parameters.  E.g.:

"""foo(x,y) -> z -- performs a foo action.

@param y: The y parameter for the foo action.  Should be positive.
@param z: The z parameter for the foo action.  Should be negative."""

-Edward