Question

我不确定我是否已经看到了具体的答案，但我对我的python docstrings的返回值的样式约定有疑问。

考虑如下函数：

def foo(ex):
    output = 2*ex
    return output

在PyCharm中，如果我为这个函数创建了一个docstring，它看起来像是：

def foo(ex):
    """
    Sample text....
    :param ex: description...
    :return: description of return value
    """
    output = 2*ex
    return output

我的问题是我是否应该在docstring中命名我的返回值？即

：return：返回值的描述

：return：输出：返回值的说明

是否有针对此的编码标准，还是主要依据个人喜好？

Answer 1

文档字符串约定实际上是在PEP-257中定义的（而PEP-8仅引用它），但仅涵盖了一般格式，不是内容。

文档字符串的内容通常由名为Sphinx的 Python文档生成器解释，而在Sphinx中，存在info fields之后：

param，parameter，arg，argument，key，keyword：参数说明。

type：参数的类型。如果可能，创建一个链接。

raises，raise，except，exception：引发特定异常（以及何时）。

var，ivar，cvar：变量说明。

vartype：变量的类型。如果可能，创建一个链接。

returns，return：返回值的说明。

rtype：返回类型。如果可能，创建一个链接。

请注意返回类型的rtype。

因此，您可以使用rtype指定返回类型，但对象返回的实际（本地）名称无关紧要。

def foo(x):
    """Sample text.
    :param x: parameter description
    :type x: int
    :return: description of return value
    :rtype: int
    """
    output = 2*ex
    return output

Answer 2

正如randomir已经提到的，Python PEP没有指定应该如何构造文档字符串的内容。然而，大型编码项目通常有自己的文档内容指南，您可以调整其中一个。

我个人喜欢Numpy docstring格式（请参阅here和here）。 Numpy样式的文档字符串中不包含返回值的本地名称。函数的docstring如下所示：

def foo(ex):
    """One-line function description.

    Parameters
    ----------
    ex : float
        Description of parameter.

    Returns
    -------
    float
        Description of return value.

    """
    output = 2*ex
    return output

Sphinx文档生成器也支持Numpy风格的文档字符串。

Python PEP-8返回值格式

2 个答案: