Подумайте о том, что кто-то делает 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)
Как вы видите, подробная информация о классах (и функциях тоже, хотя я здесь их не показываю) уже включена в строки документации этих компонентов; собственная строка документации модуля должна описывать их очень кратко (если вообще) и скорее концентрироваться на кратком изложении того, что модуль в целом может сделать для вас, в идеале с некоторыми подтвержденными примерами (точно так же, как в идеале функции и классы должны иметь приведенные примеры в их документы).
Я не вижу, как метаданные, такие как имя автора и авторское право / лицензия, помогают пользователю модуля - он может идти в комментариях, так как он может помочь кому-то подумать, использовать ли модуль повторно или модифицировать.
help()
в интерпретаторе используется больше пользователей, чем пользователей, которые просто читают код.Чтобы процитировать спецификации :
Строка документа функции или метода - это фраза, заканчивающаяся точкой. Он предписывает эффект функции или метода как команда («Сделай это», «Верни это»), а не как описание; Например, не пишите «Возвращает путь ...». Строка многострочного документа для функции или метода должна обобщать ее поведение и документировать ее аргументы, возвращаемые значения, побочные эффекты, возникающие исключения и ограничения на то, когда он может быть вызван (все, если применимо). Необязательные аргументы должны быть указаны. Должно быть задокументировано, являются ли ключевые аргументы частью интерфейса.
источник