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

Question

我对用于记录 classes 的 PEP257 标准感到有点困惑。

它说，"The docstring for a class should summarize its behavior and list the public methods and instance variables"

但它也说所有函数都应该有 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 输出重复：它打印我的 class 文档字符串，然后说 "Methods defined here" 并继续通过它们自己的文档字符串列出所有方法。

所以，这个重复真的是 PEP257 的一部分，还是我误读了它？我是否应该删除 class 文档字符串的 "Methods" 部分，因为每个方法都有自己的文档字符串？还是这种重复真的是标准的一部分？

TIA

Answer 1

是的，只需从 class 文档字符串中删除方法部分。 ~~我从来没有见过这样的东西。~~^{（它在 standard library 的几个地方使用.)} class 文档字符串只需要描述 class 和各个方法的文档字符串，然后处理描述它们自己。

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

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

Answer 2

示例：

class Animal:
    """
    A class used to represent an Animal

    ...

Attributes
----------
says_str : str
    a formatted string to print out what the animal says
name : str
    the name of the animal
sound : str
    the sound that the animal makes
num_legs : int
    the number of legs the animal has (default 4)

Methods
-------
says(sound=None)
    Prints the animals name and what sound it makes
"""

says_str = "A {name} says {sound}"

def __init__(self, name, sound, num_legs=4):
    """
    Parameters
    ----------
    name : str
        The name of the animal
    sound : str
        The sound the animal makes
    num_legs : int, optional
        The number of legs the animal (default is 4)
    """

    self.name = name
    self.sound = sound
    self.num_legs = num_legs

def says(self, sound=None):
    """Prints what the animals name is and what sound it makes.

    If the argument `sound` isn't passed in, the default Animal
    sound is used.

    Parameters
    ----------
    sound : str, optional
        The sound the animal makes (default is None)

    Raises
    ------
    NotImplementedError
        If no sound is set for the animal or passed in as a
        parameter.
    """

    if self.sound is None and sound is None:
        raise NotImplementedError("Silent Animals are not supported!")

    out_sound = self.sound if sound is None else sound
    print(self.says_str.format(name=self.name, sound=out_sound))

是的，在 class 文档字符串中列出方法，然后根据此标准再次记录每个方法。不过，我建议使用 sphinx：https://www.sphinx-doc.org/en/master/contents.html

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

Should I list class methods in the class docstring?

python

docstring