[Doc-SIG] PEP: Docstring Conventions

[David Goodger]

PEP: ???
Title: Docstring Conventions
Version: $Revision$
Author: dgoodger@bigfoot.com (David Goodger)
Discussions-To: doc-sig@python.org
Status: Draft
Type: Informational
Created: 29-May-2001
Post-History:


Abstract

    This PEP documents the semantics and conventions associated with Python
    docstrings.


Copyright

    This document has been placed in the public domain.


Acknowledgements

    The "Specificaton" text comes mostly verbatim from the Python Style
    Guilde by Guido van Rossum [1].

    (If it's OK with him, I will add GvR as an author of this PEP. I am
    quite confident that the BDFL doesn't want to own this PEP :-). Apart
    from minor editing, proposed additions to the Style Guide text are
    marked with '[+]' to the left of each line, and proposed omissions are
    marked with '[-]'. If it is deemed that this PEP is unnecessary, then
    it can be taken as suggestions for Style Guide modification.)

    This document borrows ideas from the archives of the Python Doc-SIG
    [2]. Thanks to all members past & present.


Specification

    All modules should normally have docstrings, and all functions and
    classes exported by a module should also have docstrings. Public
    methods (including the __init__ constructor) should also have doc
    strings.

    [+] A package may be documented in the module docstring of the
    [+] __init__.py file in the package directory.

    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 screenfuls) 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.

    For consistency, always use """triple double quotes""" around doc
    strings.
    [+] Use r"""raw triple double quotes""" if you use any
    [+] backslashes in your docstrings.

    There are two forms of docstrings: one-liners and multi-line
    docstrings.

    One-line Docstrings
    --------------------

    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'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 parameters (which can be obtained by introspection).
    [+]   Don't do:

    [+]       def function(a, b):
    [+]           """function(a, b) -> list"""

    [+]   This type of docstring is only appropriate for C functions (such
    [+]   as built-ins), where introspection is not possible.

    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 entire docstring is indented the same as the quotes at its first
    line (see example below). Docstring processing tools will strip an
    amount of indentation from the second and further lines of the
    docstring equal to the indentation of the first non-blank line after
    the first line of the docstring. Relative indentation of later lines in
    the docstring is retained.

    Insert a blank line before and after all docstrings (one-line or
    multi-line) that document a class -- generally speaking, the class'
    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.
    Docstrings documenting functions generally don't have this requirement,
    unless the function'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 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 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 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).

    *Do not* use the Emacs convention of mentioning the arguments of
    functions or methods in upper case in running text. Python is case
    sensitive and the argument names can be used for keyword arguments, so
    the docstring should document the correct argument names. It is best to
    list each argument on a separate line,
    [-] with two dashes separating the name from the description,
    like this:

        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
            ...

    [-] The BDFL [3] recommends inserting a blank line between the
    [-] last paragraph in a multi-line doc string and its closing quotes,
    [-] placing the closing quotes on a line by themselves. This way,
    [-] Emacs' fill-paragraph command can be used on it.

    [+] Attribute Docstrings: see DPS Generic Implementation Details PEP

    [+] Additional Docstrings: see DPS Generic Implementation Details PEP


References and Footnotes

    [1] http://www.python.org/doc/essays/styleguide.html

    [2] http://www.python.org/sigs/doc-sig/

    [3] Guido van Rossum, Python's Benevolent Dictator For Life.


Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: