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