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