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

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

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

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

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

Answer 2

От ПКП 8:

Соглашения по написанию хороших строк документации (т.«строки документации») увековечены в ПЭП 257.

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

Answer 3

Что там должно быть:

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

Answer 4

Ознакомьтесь с строками документации 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 5

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

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

Answer 6

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

Answer 7

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