A variety of objects now have a new attribute, __doc__, which
is supposed to contain a documentation string (if no documentation is
present, the attribute is None). New syntax, compatible with
the old interpreter, allows for convenient initialization of the
__doc__ attribute of modules, classes and functions by placing
a string literal by itself as the first statement in the suite. It
must be a literal --- an expression yielding a string object is not
accepted as a documentation string, since future tools may need to
derive documentation from source by parsing.
Here is a hypothetical, amply documented module called Spam:
"""Spam operations.
This module exports two classes, a function and an exception:
class Spam: full Spam functionality --- three can sizes
class SpamLight: limited Spam functionality --- only one can size
def open(filename): open a file and return a corresponding Spam or
SpamLight object
GoneOff: exception raised for errors; should never happen
Note that it is always possible to convert a SpamLight object to a
Spam object by a simple method call, but that the reverse operation is
generally costly and may fail for a number of reasons.
"""
class SpamLight:
"""Limited spam functionality.
Supports a single can size, no flavor, and only hard disks.
"""
def __init__(self, size=12):
"""Construct a new SpamLight instance.
Argument is the can size.
"""
# etc.
# etc.
class Spam(SpamLight):
"""Full spam functionality.
Supports three can sizes, two flavor varieties, and all floppy
disk formats still supported by current hardware.
"""
def __init__(self, size1=8, size2=12, size3=20):
"""Construct a new Spam instance.
Arguments are up to three can sizes.
"""
# etc.
# etc.
def open(filename = "/dev/null"):
"""Open a can of Spam.
Argument must be an existing file.
"""
# etc.
class GoneOff:
"""Class used for Spam exceptions.
There shouldn't be any.
"""
pass
After executing ``import Spam'', the following expressions
return the various documentation strings from the module:
Spam.__doc__ Spam.SpamLight.__doc__ Spam.SpamLight.__init__.__doc__ Spam.Spam.__doc__ Spam.Spam.__init__.__doc__ Spam.open.__doc__ Spam.GoneOff.__doc__
There are emerging conventions about the content and formatting of documentation strings.
The first line should always be a short, concise summary of the object's purpose. For brevity, it should not explicitly state the object's name or type, since these are available by other means (except if the name happens to be a verb describing a function's operation). This line should begin with a capital letter and end with a period.
If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description. The following lines should be one of more of paragraphs describing the objects calling conventions, its side effects, etc.
Some people like to copy the Emacs convention of using UPPER CASE for function parameters --- this often saves a few words or lines.
The Python parser does not strip indentation from multi-line string literals in Python, so tools that process documentation have to strip indentation. This is done using the following convention. The first non-blank line after the first line of the string determines the amount of indentation for the entire documentation string. (We can't use the first line since it is generally adjacent to the string's opening quotes so its indentation is not apparent in the string literal.) Whitespace ``equivalent'' to this indentation is then stripped from the start of all lines of the string. Lines that are indented less should not occur, but if they occur all their leading whitespace should be stripped. Equivalence of whitespace should be tested after expansion of tabs (to 8 spaces, normally).
In this release, few of the built-in or standard functions and modules have documentation strings.