\(\newcommand{L}[1]{\| #1 \|}\newcommand{VL}[1]{\L{ \vec{#1} }}\newcommand{R}[1]{\operatorname{Re}\,(#1)}\newcommand{I}[1]{\operatorname{Im}\, (#1)}\)

Docstrings

Quoting from the Python glossary, a docstring is a “A string literal which appears as the first expression in a class, function or module.”.

A string literal is a string contained within quotes or triple quotes.

Here is a docstring in a function:

>>> def func(arg1):
...     "This is the function docstring"
...     return arg1 * 4

It is useful to write docstrings for several reasons:

• the process of writing the docstring forces you to explain the function to yourself, and therefore write clearer code with better design;
• you and others using your function can read the docstring to see how to use your function;
• Python (via “help()”) and IPython (via “func?”) can read the docstring and return it to you, when you are working interactively;
• there are good tools, such as Sphinx, that can process the docstrings to make attractive documentation. See Documentation guidelines.

Using docstrings

You can use docstrings at your interactive Python or IPython prompt:

>>> help(func)
Help on function func:
<BLANKLINE>
func(arg1)
    This is the function docstring
<BLANKLINE>

In fact Python puts the docstring into the __doc__ attribute of the function:

>>> print(func.__doc__)
This is the function docstring

One of the most useful features of IPython is its ability to return docstrings when you add a question mark and press return after the name of the function you are interested in:

In [1]: def func(arg1):
   ...:     "This is the function docstring"
   ...:     return arg1 * 4
   ...:

In [2]: func?
Signature: func(arg1)
Docstring: This is the function docstring
File:      ~/<ipython-input-2-0233609cddfb>
Type:      function