Re: [Epydoc-devel] __init__ params for extension type?
Brought to you by:
edloper
From: Edward L. <ed...@gr...> - 2006-07-12 16:22:11
|
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 |