Что добавить в docstring модуля python?

Хорошо, поэтому я прочитал как PEP 8 и PEP 257, и я написал много docstrings для функций и классов, но я немного не уверен, что должно идти в модуле docstring. Я решил, что, как минимум, он должен документировать функции и классы, которые экспортирует модуль, но я также видел несколько модулей, в которых перечислены имена авторов, информация об авторских правах и т.д. Есть ли у кого-нибудь пример того, как хорошая докшлина python должна быть структурированным?

ОТВЕТЫ

Ответ 1

Подумайте о том, кто-то делает help(yourmodule) в приглашении интерактивного интерпретатора - что они хотят знать? (Другие способы извлечения и отображения информации примерно эквивалентны help с точки зрения количества информации). Итак, если у вас есть x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

то

>>> import x; help(x)

показывает:

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

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

Я не вижу, как метаданные, такие как имя автора и авторское право/лицензия, помогают пользователю модуля - он скорее может идти в комментариях, так как он может помочь кому-то подумать, следует ли повторно использовать или модифицировать модуль.

Ответ 2

Чтобы процитировать спецификации:

Докст. строки script(автономная программа) следует использовать в качестве сообщения "использования", которое печатается при вызове script с неправильными или отсутствующими аргументами (или, возможно, с параметром "-h" для "справки" ). Такая документация должна документировать функцию script и синтаксис командной строки, переменные среды и файлы. Сообщения об использовании могут быть достаточно сложными (несколько экранов заполнены) и должны быть достаточными для того, чтобы новый пользователь мог правильно использовать эту команду, а также полную краткую ссылку на все параметры и аргументы для сложного пользователя.

Документ для модуля обычно должны перечислять классы, исключения и функции (и любые другие объекты), которые экспортируются модулем, с однострочной сводкой каждого из них. (Эти резюме обычно дают меньше деталей, чем сводная строка в объектной docstring.) В docstring для пакета (то есть, docstring модуля пакета __init__.py) также должны перечислять модули и подпакеты, экспортированные пакетом.

docstring для класса следует обобщить его поведение и перечислить общедоступные методы и переменные экземпляра. Если класс предназначен для подкласса и имеет дополнительный интерфейс для подклассов, этот интерфейс должен быть указан отдельно (в docstring). Конструктор класса должен быть документирован в docstring для его метода __init__. Индивидуальные методы должны быть документированы по их собственной документации.

Метод docstring метода или это фраза, заканчивающаяся периодом. Он предписывает эффект функции или метода как команду ( "Сделать это", "Вернуть это" ), а не как описание; например не пишите "Возвращает путь...". Многострочная docstring для функции или метода должна суммировать ее поведение и документировать его аргументы, возвращаемые значения, побочные эффекты, поднятые исключения и ограничения на то, когда это можно назвать (все, если применимо). Необязательные аргументы должны быть указаны. Необходимо документировать, являются ли аргументы ключевого слова частью интерфейса.