Использование javadoc для документации Python
В настоящее время я начинаю с 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)
Ответы
Ответ 1
Посмотрите на формат reStructuredText (также известный как "reST" ), который является форматом разметки plaintext/docstring и, вероятно, самым популярным в Python Мир. И вы обязательно должны взглянуть на Sphinx, инструмент для создания документации из reStructuredText (используемый, например, для самой документации Python). Sphinx включает в себя возможность извлекать документацию из docstrings в вашем коде (см. sphinx.ext.autodoc) и распознает поле reST списки, следуя определенным соглашениям. Вероятно, это стало (или становится) самым популярным способом сделать это.
Ваш пример может выглядеть следующим образом:
"""Replaces template placeholder with values.
:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""
Или расширен с информацией о типе:
"""Replaces template placeholder with values.
:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""
Ответ 2
Следуйте Руководству по стилю Google Python. Обратите внимание, что Sphinx также может анализировать этот формат, используя расширение Napolean, которое будет поставляться в комплекте с Sphinx 1.3 (это также совместимо с PEP257):
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return True
Пример, взятый из документации Наполеона, приведенной выше.
Подробный пример для всех типов docstrings здесь.
Ответ 3
Стандарт для строк документации python описан в Python Enhancement Proposal 257.
Соответствующий комментарий для вашего метода будет выглядеть как
def format(...):
"""Return timestamp string with place holders replaced with values.
Keyword arguments:
timestamp -- the format string (default '')
priority -- priority number (default '')
priority_name -- priority name (default '')
message -- message to display (default '')
"""
Ответ 4
Взгляните на Документирование Python, страницу, предназначенную для авторов и потенциальных авторов документации для Python.
Короче говоря, reStructuredText - это то, что используется для документирования самого Python. Руководство разработчика содержит праймер reST, руководство по стилю и общие рекомендации для написания хорошей документации.
