python - 如何在 Google 文档字符串样式中格式化长行的参数描述

Question

这是 Google 样式文档字符串的摘录:

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/

    """

如果描述跨越一行，我该如何格式化参数？

Answer 1

当描述跨越多行时，您可以换行并缩进。在你的例子中:

"""
`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/

"""

这使文档字符串保持可读性和行长较短。如果您要导出到 Sphinx，它还会保留格式。 .

这是 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...