Docstrings by Example: Documenting Python Code the Right Way

Last updated:
Table of Contents

ReStructuredText (reST) Docstring example

ReStructuredText is a markup language, much like Markdown, that's been used to document code (among other uses).

See full directives here

  • The most common format

  • Arguably a bit hard to read

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    :param int arg1: Description of arg1.
    :param str arg2: Description of arg2.
    :raises ValueError if arg1 is equal to arg2
    :return: Description of return value
    :rtype: bool
    """

    if arg1 == arg2:
        raise ValueError('arg1 may not be equal to arg2')
    return True
Twitter Linkedin YC Hacker News Reddit

Google-style Docstring

See more examples here

  • Uses more horizontal space (compared with numpy-style)

  • Better for short and simple docstrings.

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    Raises:
        AttributeError: The ``Raises`` section is a list of all exceptions
            that are relevant to the interface.
        ValueError: If `arg2` is equal to `arg1`.

    Examples:
        Examples should be written in doctest format, and should illustrate how
        to use the function.

        >>> a=[1,2,3]
        >>> print [x + 3 for x in a]
        [4, 5, 6]

    """
    if arg1 == arg2:
        raise ValueError('arg1 may not be equal to arg2')
    return True

Numpy-style Docstring

See more examples here

  • Uses more vertical space (compared to google-style)

  • Better for long and in-depth docstrings

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    Raises
    ------
    AttributeError
        The ``Raises`` section is a list of all exceptions
        that are relevant to the interface.
    ValueError
        If `arg2` is equal to `arg1`.

    See Also
    --------
    otherfunc : some other related function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    if arg1 == arg2:
        raise ValueError('arg1 may not be equal to arg2')
    return True
Twitter Linkedin YC Hacker News Reddit

Doctests

Doctests are a special form of docstring, used to inform users how to use a method but also to actually run tests.

Any documentation style can be used with doctests, provided you add a small call at the end of the file, the following example (let's call it doctest-example.py)

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    >>> func(1,2)
    True
    >>> func(1,1)
    Traceback (most recent call last):
    ...
    ValueError: arg1 may not be equal to arg2
    """

    if arg1 == arg2:
        raise ValueError('arg1 may not be equal to arg2')
    return True

if __name__ == "__main__":
    import doctest
    doctest.testmod()

If you run this example with the verbose flag (python doctest-example.py -v), you see the test output:

$ python doctest-example.py -v
Trying:
    func(1,2)
Expecting:
    True
ok
Trying:
    func(1,1)
Expecting:
    Traceback (most recent call last):
    ...
    ValueError: arg1 may not be equal to arg2
ok
1 items had no tests:
    __main__
1 items passed all tests:
   2 tests in __main__.func
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

References