Что положить в строку документации модуля Python? [закрыто]

Итак, я прочитал как PEP 8, так и PEP 257 , и я написал много строк документации для функций и классов, но я немного не уверен в том, что должно входить в строку документации модуля. Я подумал, что, как минимум, он должен документировать функции и классы, которые экспортирует модуль, но я также видел несколько модулей, которые перечисляют имена авторов, информацию об авторских правах и т. Д. У кого-нибудь есть пример того, как хорошая строка документации Python должна быть структурированным?

Подумайте о том, что кто-то делает 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)

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

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

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

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

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

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

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