How to document Python code properly for Pydoc

[Lie Ryan]

jorma kala wrote:
> Hi,
> Do you know where I can find the rules for documenting Python code, so
> that automatic document generation with Pydoc makes the most of the
> comments inserted in the code?
> I know about documenting class and method through triple quote just
> under the class definition. But how do you comment a specific field or
> variable, or how do you document function arguments so that they are
> extracted like in javadoc?
> Thanks very much

pydoc is a simple tool, and doesn't do much. You write in freeform,
although generally you'll do something like this:

def myfunc(a, b):
    '''
    short description of myfunc

    longer description of myfunc, if necessary, and typically includes
    description of the arguments and the behaviors. Also includes the
    description of the return value.
    '''

    pass

pydoc doesn't recognize any special markups. If you want to get more
from the docstring, you need other documentation generator such as
epydoc, Doxygen, or Sphinx.