Docstrings Functions in Python

Posted by AbundantCode

This tutorial will teach you how to add documentation to a function using docstrings.

Help() is a Python built-in function that displays a function’s documentation.

The print() function documentation is demonstrated in the following example:

help(print)
print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

The help() function can be used to display documentation for modules, classes, functions, and keywords. This tutorial only covers function documentation.

Documenting functions with docstrings in Python

You can use docstrings to document your functions. The docstring conventions are defined in PEP 257.

Python will interpret the first line of the function body as a docstring if it is a string. For instance:

def add(a, b):
    "Return the sum of two arguments"
    return a + b

You can also look up the documentation for the add() function using the help() function:

help(add)

Output

add(a, b) Return the sum of two arguments

Typically, multi-line docstrings are used:

def add(a, b):
    """ Add two arguments
    Arguments:
        a: an integer
        b: an integer
    Returns:
        The sum of the two arguments
    """
    return a + b

Output

add(a, b) Add the two arguments Arguments: a: an integer b: an integer Returns: The sum of the two arguments

Python saves the docstrings in the function’s doc property.

The following example demonstrates how to use the add() function’s doc property:

add.__doc__
Tags: