Hur man ska dokumentera kod.

Här beskrivs hur funktioner utöver självförklarande kod och förklarande linje kommentarer ska dokumenteras.

One-liners

One-liners are for really obvious cases. They should really fit on one line. For example:

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...

Notes:

• Triple quotes are used even though the string fits on one line. This makes it easy to later expand it.

• The closing quotes are on the same line as the opening quotes. This looks better for one-liners.

• There's no blank line either before or after the docstring.

• The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".

Multi-line docstrings

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line. The summary line may be on the same line as the opening quotes or on the next line.

pep-0257