В настоящее время я начинаю с Python и имею большой опыт работы с PHP, а в PHP я привык использовать javadoc
в качестве шаблона документации.
Мне было интересно, если javadoc
есть свое место в качестве docstring
документации в Python. Каковы здесь установленные соглашения и / или официальные правила?
Например, что-то вроде этого слишком сложное, чтобы вписаться в мышление Python, или я должен стараться быть максимально кратким?
"""
replaces template place holder with values
@param string timestamp formatted date to display
@param string priority priority number
@param string priority_name priority name
@param string message message to display
@return string formatted string
"""
И если я слишком исчерпывающий, я должен пойти с чем-то вроде этого (где большая часть документации не печатается с помощью __doc__
метода)?
# replaces template place holder with values
#
# @param string timestamp formatted date to display
# @param string priority priority number
# @param string priority_name priority name
# @param string message message to display
#
# @return string formatted string
def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
"""
replaces template place holder with values
"""
values = {'%timestamp%' : timestamp,
'%priorityName%' : priority_name,
'%priority%' : priority,
'%message%' : message}
return self.__pattern.format(**values)
python
documentation
javadoc
docstring
ДФ Дион
источник
источник
Ответы:
Взгляните на формат reStructuredText (также известный как «reST»), который является форматом разметки в виде простого текста / строки документа и, вероятно, самым популярным в мире Python. И вам, безусловно, следует взглянуть на Sphinx , инструмент для генерации документации из reStructuredText (используется, например, для самой документации Python). Sphinx включает в себя возможность извлекать документацию из строк документации в вашем коде (см. Sphinx.ext.autodoc ) и распознает списки полей reST в соответствии с определенными соглашениями. Это, вероятно, стало (или становится) самым популярным способом сделать это.
Ваш пример может выглядеть следующим образом:
Или дополнен информацией о типе:
источник
Replace template place holder with values.
вместоreplaces template place holder with values
- Обратите внимание на предложение, заглавную букву в начале и точку в конце (.) В конце.sphinx.ext.napoleon
расширение.Следуйте Руководству по стилю Google Python . Обратите внимание, что Sphinx также может анализировать этот формат, используя расширение Napolean , которое будет поставляться в комплекте со Sphinx 1.3 (это также совместимо с PEP257 ):
Пример взят из наполеоновской документации, ссылки на которую приведены выше.
Подробный пример всех типов строк документации здесь .
источник
Стандарт для строк документации Python описан в предложении по улучшению Python 257 .
Соответствующий комментарий для вашего метода будет что-то вроде
источник
Взгляните на Documenting Python , страницу, «предназначенную для авторов и потенциальных авторов документации для Python».
Короче говоря, reStructuredText - это то, что используется для документирования самого Python. Руководство разработчика содержит учебник для начинающих, руководство по стилю и общие рекомендации по написанию хорошей документации.
источник