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

Question

В настоящее время я начинаю с 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)

Answer 1

Взглянуть на реструктурированный текст (также известный как «отдых») формат, который представляет собой формат разметки/наценки с открытым текстом/Docstring, и, вероятно, самый популярный в мире Python. И вы, конечно, должны посмотреть на Сфинкс, инструмент для генерации документации из реструктурированного текста (например, для самой документации Python). SPHINX включает в себя возможность извлечения документации из DocStrings в вашем коде (см. sphinx.ext.autodoc) и распознает отдых Полевые списки Следуя определенным соглашениям. Это, вероятно, стало (или становится) самым популярным способом сделать это.

Ваш пример может выглядеть следующим образом:

"""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
"""

Answer 2

Следовать Руководство по стилю Google Python. Анкет Обратите внимание, что Sphinx также может анализировать этот формат, используя Наполеан расширение, которое будет упаковано с 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

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

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

Answer 3

Стандарт строк документации 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 '')
    """

Answer 4

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

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