如何以 Google 文档字符串样式格式化长行参数描述答案

【问题标题】：How to format long lines of argument description in Google docstring style如何以 Google 文档字符串样式格式化长行参数描述
【发布时间】：2019-11-19 09:27:09
【问题描述】：

这是一个谷歌风格的文档字符串的摘录：

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/

    """

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

【问题讨论】：

标签： python styles args docstring

【解决方案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中推荐的方法

按名称列出每个参数。描述应跟在名称后面，并用冒号和空格分隔。 如果说明太长而不能放在 80 个字符的一行中，请使用 2 或 4 个空格的悬挂缩进（与文件的其余部分保持一致）。 如果代码不包含相应的类型注释，则描述应包含所需的类型...

【讨论】：