我应该在类文档字符串中列出类方法吗？

Question

我对记录类的 PEP257 标准有点困惑。

它说，“一个类的文档字符串应该总结它的行为并列出公共方法和实例变量”

但它也说所有函数都应该有 dosctrings（当然，我想要，这样 help() 工作）。

但这似乎涉及重复，即

class foo:
    """A class

    Attributes
    ----------
    bar : str 
        A string

    Methods
    -------
    __init__(fish):
        Constructor, fish is a str which self.bar will be set to.
    baz():
        A function which does blah

    """

    def __init__(self, fish):
    """
    Constructs an XRTProductRequest object.

    Parameters
    ----------
    fish : str
        A string, which the self.bar attribute will be set to.
    """
    etc...

这很容易出错，因为这意味着当我意识到__init__还需要接收一个 int 时，我必须记住在 2 个地方更新文档，我可以保证我会忘记。

它还使 pydoc 输出重复：它打印我的类文档字符串，然后说“此处定义的方法”并继续通过它们自己的文档字符串列出所有方法。

那么，这个重复真的是 PEP257 的一部分，还是我误读了它？我是否应该删除类文档字符串的“方法”部分，因为每个方法都有自己的文档字符串？或者这种重复真的是标准的一部分吗？

TIA

Answer 1

是的，只需从类文档字符串中删除方法部分。我从来没有见过这样的东西。^{（这是在少数地方使用标准库）}  类文档字符串需要仅仅描述了类和各个方法的文档字符串，然后处理自己的描述。

此外，PEP 中的措辞对我来说意味着类文档字符串“应该”列出公共方法，但不以任何其他方式描述它们。^{（这也是上述标准库示例的做法。）}  但^如上所述，我什至永远不会这样做，因为代码不言自明，而且这种列表肯定会过时。

最后一点：我个人更喜欢使用Google docstring style，因为对我来说它是最清晰和最干净的。