Documentation Strings

Comments

In Python, you can make a comment using a # character.

# this is a comment

A comment can be made on its own line or after code:

favorite_numbers = [5, 7, 13]  # I like primes

Everything on the line after the # is ignored by Python. We can use this to document intentions that may not be entirely clear.

Python does not have multi-line comments like C and Java do. There are only single-line comments. To make a comment over multiple lines, you’ll need to start every line with a #.

Documentation Strings

Comments are great, but there’s a more powerful tool we can use to document our code.

There is a convention in Python of putting a string at the top of your function, module, or class for documentation:

def power(x, y):
    """Return x raised to the y-th power."""
    return x ** y

This is called a “docstring”.

Python actually uses docstrings to generate the help text for objects.

Note that we have used a triple-quoted string and we wrote a single sentence, starting our string with an uppercase letter and ending it with a period.

Python Enhancement Proposal (PEP) 257 dictates the preferred way to make docstrings.

PEP 257 states that one-line docstrings should:

use triple quotes to make it easier to turn them into multi-line docstrings
not have blank lines before or after them
be a phrase ending in a period written in the imperative tense (in the form of a command)

PEP 257 also dictates suggestions for multi-line docstrings. This PEP is part of the recommended reading.

Docstring all the things

We can document both functions and modules in Python.

Let’s document our greetings.py file:

"""
Greet the user based on the name given.

Usage::

    $ python greetings.py Trey
    Hello Trey

"""
import sys


def greet(name):
    """Print a greeting to given name."""
    print(f"Hello {name}!")


if __name__ == "__main__":
    greet(sys.argv[1])

Docstrings must be the first string in a function or a module.

The use of docstrings

Docstrings are used to generate the documentation text shown when we use the help function an object:

>>> import greetings
>>> help(greetings)

When parsing our code, Python stores docstrings in a __doc__ attribute on our objects:

>>> greetings.greet.__doc__
'Print a greeting to given name.'

There are a number of tools which can understand and use Python docstrings. Sphinx, the tool used for creating this website, is one of those tools. Sphinx is used for creating documentation and it can generate documentation for Python code based on docstrings.

Invalid docstrings

Docstrings are not multi-line comments. These strings should only be used at the beginning of functions, classes, and modules.

Is this a docstring?

def greet(name):
    print(f"Hello {name}!")
    """Print a greeting to given name."""

Nope:

>>> print(greet.__doc__)
None

Is this a docstring?

def greet(name):
    x = """Print a greeting to given name."""
    print(f"Hello {name}!")

Nope:

>>> print(greet.__doc__)
None

Is this a docstring?

def greet(name):
    "Print a greeting to given name."
    print(f"Hello {name}!")

It is!

>>> print(greet.__doc__)
Print a greeting to given name.

Is this a docstring?

def greet(name):
    'Print a greeting to given name.'
    print(f"Hello {name}!")

This is a docstring also:

>>> print(greet.__doc__)
Print a greeting to given name.