Должен ли я перечислять методы класса в строке документации класса?

Question

Меня немного смущает стандарт PEP257 для документирования классов.

Он говорит: «Строка документации для класса должна суммировать его поведение и перечислять методы publi c и переменные экземпляра»

Но он также говорит, что все функции должны иметь строки набора (что, конечно, я хочу, чтобы 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, тогда я должен не забыть обновить документы в двух местах, что, я гарантирую, я забуду.

Он также дублирует вывод pydo c: он печатает строку документации моего класса, но затем говорит: «Методы, определенные здесь», и переходит к перечислению всех методов через их собственные строки документации.

Итак, действительно ли это дублирование является частью PEP257, или я неправильно его читаю? Следует ли мне удалить раздел «Методы» в строке документации класса, поскольку у каждого метода есть собственная строка документации? Или это дублирование действительно является частью стандарта?

TIA

Answer 1

Да, просто удалите раздел методов из строки документации класса. Я никогда не видел такого использованного. Строка документации класса должна просто описывать класс и строку документации отдельных методов, а затем обрабатывать описание самих себя.

Также формулировка в PEP для меня означает, что строка документации класса «должна» перечислить методы публикации c, но не описывать их каким-либо другим образом. Но, как было сказано выше, я бы никогда этого не сделал, так как код говорит сам за себя, и такие списки обязательно устареют.

Заключительное примечание: я лично предпочитаю использовать Стиль строки документации Google , потому что для меня он самый ясный и чистый.

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))

Да, перечисление методов в строке документации класса, затем каждый метод снова документируется в соответствии с этим стандартом. Я рекомендую использовать sphinx: https://www.sphinx-doc.org/en/master/contents.html