Что добавить в строку документации модуля 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__. Отдельные методы должны быть задокументированы их собственной строкой документации.

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