How to document Python code properly for Pydoc
lie.1296 at gmail.com
Wed Jul 22 13:43:14 EDT 2009
jorma kala wrote:
> 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.
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.
More information about the Python-list