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 these conventions, the worst you'll get is some dirty looks. But some software (such as the Docutils [4] docstring processing system [1][2]) 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 occurring 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 may be extracted by software tools:
1. String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called "attribute docstrings".
2. String literals occurring immediately after another docstring are called "additional docstrings".
Please see PEP 258, "Docutils Design Specification" [2], for a detailed description of attribute and additional docstrings.
XXX Mention docstrings of 2.2 properties.
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""".
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 or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".
