Использование javadoc для документации по Python [закрыто]

162

В настоящее время я начинаю с 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)
ДФ Дион
источник
6
У Теры также есть много других ответов на этот вопрос на более раннем вопросе, дубликат которого есть.
Алекс Дюпюй

Ответы:

227

Взгляните на формат reStructuredText (также известный как «reST»), который является форматом разметки в виде простого текста / строки документа и, вероятно, самым популярным в мире Python. И вам, безусловно, следует взглянуть на Sphinx , инструмент для генерации документации из reStructuredText (используется, например, для самой документации Python). Sphinx включает в себя возможность извлекать документацию из строк документации в вашем коде (см. 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
"""
Стивен
источник
7
что вы делаете, если вам нужно разбить строку для длинного описания? Как это будет выглядеть?
Skylar Saveland
6
См. Ссылку reStructuredText и, в частности, списки полей: documentstils.sourceforge.net/docs/ref/rst/…
Стивен
6
Обратите внимание, что способ выражения здесь не соответствует PEP 257 . Это должно быть Replace template place holder with values.вместо replaces template place holder with values- Обратите внимание на предложение, заглавную букву в начале и точку в конце (.) В конце.
Кратенко
1
Начиная с версии 1.3, Sphinx также поддерживает более приятный формат через sphinx.ext.napoleonрасширение.
Петри
3
Может ли кто-нибудь указать мне лучшую документацию с указанием таких специальных строк документации, как ": param ____:" и ": return:"? Такой документ сейчас довольно сложно найти.
krumpelstiltskin
75

Следуйте Руководству по стилю 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

Пример взят из наполеоновской документации, ссылки на которую приведены выше.

Подробный пример всех типов строк документации здесь .

confused00
источник
20
для всех людей, которые читают строки документации
Уэйлон Флинн
1
Обновлена ​​ссылка на руководство по стилю Google Python
confused00
@ confused00 как я могу документировать, что мой метод возвращает массив объектов?
Cito
1
Теперь я в замешательстве! args или params? stackoverflow.com/questions/1788923/parameter-vs-argument
shuva
25

Стандарт для строк документации Python описан в предложении по улучшению Python 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 '')
    """
srgerg
источник
17
PEP257 ничего не говорит о фактическом форматировании аргументной части. Это только заявляет, что это должно быть написано, и приводит пример. Но это только пример. Поэтому я бы настоятельно рекомендовал использовать соглашение Sphinx, поскольку вы не нарушаете PEP257 и используете форматирование, которое может быть проанализировано sphinx.
Вааб
7
За исключением того, что первая документация, представленная выше, уродлива и содержит много избыточной информации для людей. Я бы предпочел использовать соглашение, которое делает мой исходный код приятным для чтения без предварительного анализа
confused00
1

Взгляните на Documenting Python , страницу, «предназначенную для авторов и потенциальных авторов документации для Python».

Короче говоря, reStructuredText - это то, что используется для документирования самого Python. Руководство разработчика содержит учебник для начинающих, руководство по стилю и общие рекомендации по написанию хорошей документации.

Дэвид Кейн
источник