7

This is an excerpt from a Google style docstring:

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """

How do I format the args in case the description spans a line ?

Tom271
  • 161
  • 6
Ivo
  • 71
  • 1
  • 3

1 Answers1

8

When the description spans more than one line, you can break the line and indent. In your example:

"""
`PEP 484`_ type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:

Args:
    param1 (int): A really long description of the first parameter that
        spans more than one line. If you've got a really long description
        you can continue to break the line where you want, indent and 
        continue describing your parameter
    param2 (str): The second parameter.

Returns:
    bool: The return value. True for success, False otherwise.

.. _PEP 484:
    https://www.python.org/dev/peps/pep-0484/

"""

This keeps the docstring readable and the line length short. It also preserves the formatting if you are exporting to Sphinx.

This is the recommended method in the Google Python Style Guide

List each parameter by name. A description should follow the name, and be separated by a colon and a space. If the description is too long to fit on a single 80-character line, use a hanging indent of 2 or 4 spaces (be consistent with the rest of the file). The description should include required type(s) if the code does not contain a corresponding type annotation...

Tom271
  • 161
  • 6