10
Я знаю, что является стандартным способом документировать функции, классы и модули, но как мне документировать пакеты - я помещаю docstring в __init__.py или что-то еще?Как документировать пакет python
A
ответ
14
Да, так же, как для функции или класса комментарий, то первый элемент в файле __init__.py должна быть строка комментария:
"""
This is the xyz package.
"""
Теперь, если импортировать пакет и использовать помощь (пакет), вы увидите свою docstring. Подробнее здесь: http://www.python.org/dev/peps/pep-0257/
3
См PEP257
Пакет может быть документированы в модуле строку документации файла __.py __ инициализации в каталоге пакета.
-3
Документирование является хорошей идеей, до тех пор, пока вы не задокументировать то очевидное в вашем коде
Пытаться понять, что большинство людей, читающих ваш источник поймет питона, поэтому комментировать или документировании линии, как это бессмысленно:
a = 1 #this assigns 1 to a
Но комментарий или документирование довольно сложной функции или класса - хорошая идея.
Общее правило: представьте, что следующий человек, над которым работает ваш код, является маньяком, владеющим топором, и они знают, где вы живете.
Таким образом, вы всегда будете оставлять "полезные" комментарии/doc's