python-peps/pep-0257.txt

PEP: 257
Title: Docstring Conventions
Version: $Revision$
Last-Modified: $Date$
Author: dgoodger@bigfoot.com (David Goodger),
        guido@digicool.com (Guido van Rossum)
Discussions-To: doc-sig@python.org
Status: Draft
Type: Informational
Created: 29-May-2001
Post-History: 13-Jun-2001


Abstract

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


Rationale

    The aim of this PEP is to standardize the high-level structure of
    docstrings: what they should contain, and how to say it (without
    touching on any markup syntax within docstrings).  The PEP
    contains conventions, not laws or syntax.

        "A universal convention supplies all of maintainability,
        clarity, consistency, and a foundation for good programming
        habits too.  What it doesn't do is insist that you follow it
        against your will.  That's Python!"

        --Tim Peters on comp.lang.python, 2001-06-16

    If you violate the conventions, the worst you'll get is some dirty
    looks.  But some software (such as the Docstring Processing System
    [1]) will be aware of the conventions, so following them will get
    you the best results.


Specification

    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.

    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
    docstrings.  A package may be documented in the module docstring
    of the __init__.py file in the package directory.

    String literals occuring elsewhere in Python code may also act as
    documentation. They are not recognized by the Python bytecode
    compiler and are not accessible as runtime object attributes
    (i.e. not assigned to __doc__), but two types of extra docstrings
    are recognized by software tools:

    1. String literals occuring immediately after a simple assignment
       at the top level of a module, class, or __init__ method
       are called "attribute docstrings".

    2. String literals occuring immediately after another docstring
       are called "additional docstrings".

    Please see PEP 258 "DPS Generic Implementation Details" [2] for a
    detailed description of attribute and additional docstrings.

    For consistency, always use """triple double quotes""" around
    docstrings.  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'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.  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 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.

    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.

    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. For
    example::

        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 docstring and its closing quotes,
    placing the closing quotes on a line by themselves.  This way,
    Emacs' fill-paragraph command can be used on it.


References and Footnotes

    [1] PEP 256, Docstring Processing System Framework, Goodger
        http://www.python.org/peps/pep-0256.html

    [2] PEP 258, DPS Generic Implementation Details, Goodger
        http://www.python.org/peps/pep-0258.html

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

    [4] PEP 8, Style Guide for Python Code, van Rossum, Warsaw
        http://www.python.org/peps/pep-0008.html

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


Copyright

    This document has been placed in the public domain.


Acknowledgements

    The "Specification" text comes mostly verbatim from the Python
    Style Guide by Guido van Rossum [4].

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


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