docstring

Links

http://docutils.sourceforge.net/docs/peps/pep-0257.html PEP 257, Docstring Conventions.
Pykaboo

What is a Docstring?

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

Standards

All modules should normally have docstrings.
All functions and classes exported by a module should have docstrings.
Public methods (including the __init__ constructor) should also have docstrings.
A package may be documented in the module docstring of the __init__.py file in the package directory.
For consistency, always use """``*triple double quotes*”””`` around docstrings. Use r"""``*raw triple double quotes*”””`` if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""".

One-line Docstrings

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

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

Note:

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 …”.
The one-line docstring should NOT be a “signature” reiterating the function/method parameters (which can be obtained by introspection). Don’t do:
```
def function(a, b):
    """function(a, b) -> list"""
```
However, the nature of the return value cannot be determined by introspection, so it should be mentioned. The preferred form for such a docstring would be something like:
```
def function(a, b):
    """Do X and return a list."""
```

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 (17/02/2011, I like it on the next line).

The entire docstring is indented the same as the quotes at its first line (see example below).

def complex(real=0.0, imag=0.0):
    """
    Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero

Class

Insert a blank line before and after all docstrings (one-line or multi-line) that document a class - generally speaking, the class’s methods are separated from each other by a single blank line, and the docstring needs to be offset from the first method by a blank line; for symmetry, put a blank line between the class header and the docstring.
The docstring for a class should summarize its behavior and list the public methods and instance variables.
If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring).
The class constructor should be documented in the docstring for its __init__ method.
Individual methods should be documented by their own docstring.
If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences.

Use the verb “override” to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb “extend” to indicate that a subclass method calls the superclass method (in addition to its own behavior).

Functions and Methods

Docstrings documenting functions or methods generally don’t have the requirement to insert a blank line before and after, unless the function or method’s body is written as a number of blank-line separated sections - in this case, treat the docstring as another section, and precede it with a blank line.
The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable).
Optional arguments should be indicated.
It should be documented whether keyword arguments are part of the interface.
The docstring should document the argument names. It is best to list each argument on a separate line (see example above).

Modules and Packages

The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each (these summaries generally give less detail than the summary line in the object’s docstring.)
The docstring for a package (i.e., the docstring of the package’s __init__.py module) should also list the modules and subpackages exported by the package.

Script

The docstring of a script (a stand-alone program) should be usable as its “usage” message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a “-h” option, for “help”).

Such a docstring should document the script’s function and command line syntax, environment variables, and files.

Usage messages can be fairly elaborate (several screens full) and should be sufficient for a new user to use the command properly, as well as a complete quick reference to all options and arguments for the sophisticated user.

View

Use the help method to view the docstring comments for a class:

>>> from trac.ticket import Ticket
>>> help(Ticket)