Существует ли консенсус в отношении того, что должно быть документировано в классах и init docstrings?

Я не нашел никакой лучшей практики относительно того, что должно быть задокументировано в классах и строках документации __init__. Иногда я нахожу, что аргументы конструктора уже задокументированы в строке документации классов, иногда они описаны в строке документации __init__. Я предпочитаю описывать конструкцию внутри docstring классов, так как это то, что вы называете при создании нового экземпляра. Но что тогда должно быть документировано в строке документации по методам __init__?

Редактирование:

Я знаю о руководстве по стилям Google и о стиле goc docstring, но оба не отвечают на мой вопрос. Пример стиля строки документа говорит

Метод __init__ может быть задокументирован на уровне класса строка документа или как строка документа самого метода __init__. Любая форма является приемлемой, но эти два не должны смешиваться. Выбери один соглашение о документировании метода __init__ и его соблюдении.

Но если я решу поместить строку документации функции __init__ в строку документации уровня класса, что должна содержать строка документации __init__?

Ответ 1

Фактическое использование класса инициализируется такой командой, как SampleClass(args), и ни один пользователь не собирается вводить SampleClass.__init__(args), поэтому с точки зрения конечного пользователя, когда они в замешательстве, они гораздо чаще набирают

help(SampleClass)

вместо

help(SampleClass.__init__)

Поэтому я думаю, что имеет смысл поместить всю документацию в строку документации SampleClass.
И в __init__ docstring вставьте "Пожалуйста, смотрите help(SampleClass) для получения дополнительной информации" на случай, если есть вероятность, что кто-то (или какая-то программа) смотрит на это.

Ответ 2

Я лично стараюсь использовать руководство по стилю Google, когда это возможно

Когда вы создаете новый экземпляр с __init__, должно быть задокументировано, какие переменные-члены инициализируются. Тогда другие люди знают, чего они могут ожидать, когда им понадобится доступ к ним позже в их коде.

Пример из руководства по стилю Google:

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

Ответ 3

Я не знаю никакого консенсуса по этому вопросу.

Однако модуль sphinx autodoc позволяет создавать документацию из вашей docstring. Поэтому он имеет тенденцию обеспечивать согласованную документацию документации docstring.

В вашем случае я бы документировал, что class и аргументы конструктора в docstring class:

class MyClass:
    """I am a class.
    I do funny stuff

    :type tags: dict
    :param tags: A dictionary of key-value pairs
    """

    def __init__(tags):
        self.tags = tags

Ответ 4

Официальный ответ в PEP 257 (PEP строки документации), который, возможно, является авторитетным:

Конструктор класса должен быть задокументирован в строке документации для его метода __init__.

Это вполне логично, поскольку это обычная процедура для функций и методов, и __init__() не является исключением.

Как следствие, это помещает код и его документацию в одно место, что помогает в обслуживании.

Наконец, инструменты, которые отображают документацию для пользователя (например, Jupyter), с большей вероятностью правильно отображают документацию вашего кода.

Ответ 5

Numpy говорит, что вы должны документировать __init__ в документе класса. https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

Вот пример, который вы можете увидеть, где __init__ не имеет строки документации. Вместо этого это появляется в документе класса.https://github.com/numpy/numpy/blob/master/numpy/core/records.py

Ответ 6

У Google есть своя инструкция по стилю для Python, о которой не стоит упоминать. Вот ссылка на то, что они считают передовыми методами для doc-строк: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

Ответ 7

Пример строки документа Google действительно отвечает на ваш вопрос. Если вы решите документировать свой метод __init__ в строке документации уровня класса, строка документации __init__ останется пустой. Например:

class ExampleError(Exception):
    """Exceptions are documented in the same way as classes.

    The __init__ method may be documented in either the class level
    docstring, or as a docstring on the __init__ method itself.

    Either form is acceptable, but the two should not be mixed. Choose one
    convention to document the __init__ method and be consistent with it.

    Note:
        Do not include the 'self' parameter in the ''Args'' section.

    Args:
        msg (str): Human readable string describing the exception.
        code (:obj:'int', optional): Error code.

    Attributes:
        msg (str): Human readable string describing the exception.
        code (int): Exception error code.

    """

    def __init__(self, msg, code):
        self.msg = msg
        self.code = code

Либо разделите эту строку документации между уровнем класса и строкой документации __init__.