Как написать значимые строки документации?

Question

Что, по вашему мнению, является значимой строкой документов? Что вы ожидаете там описать?

Например, рассмотрим класс Python __init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

Считаете ли вы это значимым? Опубликуйте ваши хорошие / плохие примеры для всех (и общий ответ, чтобы их можно было принять).

Answer 1

Я согласен с «Все, что вы не можете отличить от подписи метода». Это также может означать объяснение того, что возвращает метод / функция.

Вы также можете использовать Sphinx (и синтаксис reStructuredText) для документирования внутри ваших строк документации. Таким образом, вы можете легко включить это в свою документацию. Для примера проверьте, например, repoze.bfg , который широко использует это ( файл примера , пример документации ).

Еще одна вещь, которую можно поместить в строки документации, это также doctests . Это может иметь смысл, особенно для строк документации модуля или класса, вы также можете показать, как использовать его и иметь этот тестируемый одновременно.

Answer 2

С PEP 8 :

Условные обозначения для написания хороших строк документации (a.k.a. "строки документов") увековечены в PEP 257 .

• Запись строк документации для всех общедоступных модулей, функций, классов и методов. Строки документации не нужны для закрытых методов, но вы должен иметь комментарий, который описывает, что делает метод. это комментарий должен появиться после строки "def".
• PEP 257 описывает правила документирования. Обратите внимание, что наиболее важно, "" ", который заканчивает многострочную строку документации, должен быть на сама по себе строка, и желательно, чтобы ей предшествовала пустая строка.
• Для одной строки документации лайнера, можно держать закрывающий "" "на той же строке.

Answer 3

Посмотрите на строки документации numpy для хороших примеров (например, http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).

Строки документов разбиты на несколько разделов и выглядят так:

Compute the sum of the elements of a list.

Parameters
----------
foo: sequence of ints
   The list of integers to sum up.

Returns
-------
res: int
   sum of elements of foo

See also
--------
cumsum:  compute cumulative sum of elemenents

Answer 4

Что должно идти туда:

Все, что вы не можете отличить от подписи метода. В этом случае единственный полезный бит: displayName - если пусто будет установлено имя поля.

Answer 5

Самое поразительное, что я могу включить в строку документации, это то, что неочевидно. Обычно это включает информацию о типе или требованиях к возможностям - например. Msgstr "Требуется объект типа файла". В некоторых случаях это будет видно из подписи, а в других - нет.

Еще одна полезная вещь, которую вы можете вставить в строки документации, это doctest.

Answer 6

Мне нравится использовать документацию, чтобы как можно более подробно описать, что делает функция, особенно поведение в угловых случаях (например, крайние случаи). В идеале программист, использующий функцию, никогда не должен смотреть на исходный код - на практике это означает, что всякий раз, когда другому программисту приходится смотреть на исходный код, чтобы выяснить некоторые детали того, как работает функция, эта деталь, вероятно, должна была быть упоминается в документации. Как сказал Фредди, все, что не добавляет деталей к сигнатуре метода, вероятно, не должно быть в строке документации.

Answer 7

Обычно целью добавления добавления строки документа в начале функции является описание функции, что она делает, что она будет возвращать, и описание параметров. Вы можете добавить детали реализации, если это необходимо. Даже вы можете добавить информацию об авторе, который написал код для будущего разработчика.