Використання 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)

Погляньте на формат reStructuredText (також відомий як "reST"), який є форматом розмітки в простому тексті / docstring і, мабуть, найпопулярнішим у світі Python. І ви, звичайно, повинні подивитися на Sphinx , інструмент для генерації документації з reStructuredText (використовується, наприклад, для самої документації Python). Сфінкс включає можливість вилучення документації з документації у вашому коді (див. 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
"""

Дотримуйтесь посібника зі стилю Google Python . Зауважте, що Сфінкс також може проаналізувати цей формат за допомогою наполеового розширення, яке буде поставлено у комплекті з Сфінксом 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

Приклад взятий з наполеовської документації, зв'язаної вище.

Комплексний приклад всіх типів рядків документації тут .

Стандарт для рядків документації python описаний у пропозиції 257 щодо вдосконалення Python .

Відповідний коментар до вашого методу був би чимось подібним

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

Подивіться на Documenting Python , сторінку, "націлену на авторів та потенційних авторів документації для Python".

Коротше кажучи, reStructuredText - це те, що використовується для документування самого Python. Посібник розробника містить ґрунтовку, що відповідає решті, посібник зі стилів та загальні поради щодо написання гарної документації.