This is taken straight out of docutils/statemachine.py, in which I experimented with a simple documentation methodology. Another variation I've thought of exploits the Grouch-compatible "classifier" element of definition lists. For example:
:Parameters:
`lines` : [string]
List of one-line strings without newlines.
`until_blank` : boolean
Stop collecting at the first blank line if true (1).
`strip_indent` : boolean
Strip common leading indent if true (1, default).
Field lists could even be used in a one-to-one correspondence with JavaDoc @tags, although I doubt if I'd recommend it. Several ports of JavaDoc's @tag methodology exist in Python, most recently Ed Loper's "epydoc".
Can we extract comments from parsed modules? Could be handy for documenting function/method parameters:
def method(self,
source, # path of input file
dest # path of output file
):
This would save having to repeat parameter names in the docstring.
Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG] Documentation tool":
it would be quite hard to add a new param to this method without realising you should document it
Frederic Giacometti's iPhrase Python documentation conventions is an attachment to his Doc-SIG post of 2001-05-30.