Использование 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)
4 ответов:
посмотреть reStructuredText (также известный как "reST") формат, который представляет собой формат разметки открытого текста/docstring и, вероятно, самый популярный в мире Python. И вы, конечно, должны смотреть на Сфинкс инструмент для генерации документации с помощью языка разметки restructuredtext (используется, например, для. сама документация Python). Sphinx включает в себя возможность извлечения документации из docstrings в вашем коде (см. сфинкс.доб.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 Style Guide. Обратите внимание, что 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пример взят из наполеоновской документации, приведенной выше.
исчерпывающий пример для всех типов docstrings здесь.
стандарт для строк документации 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 '') """
посмотри Документирование Python, страница", предназначенная для авторов и потенциальных авторов документации для Python."
короче, reStructuredText это то, что используется для документирования самого Python. Руководство разработчика содержит букварь reST, руководство по стилю и общие рекомендации по написанию хорошей документации.
Comments