将 javadoc 用于 Python 文档 [关闭]

Question

我目前从 Python 开始，我有很强的 PHP 背景，在 PHP 中我习惯使用javadoc 作为文档模板。

我想知道 javadoc 是否在 Python 中作为 docstring 文档的位置。 这里的既定惯例和/或官方准则是什么？

例如像这样的东西太复杂了，不适合 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

看看reStructuredText（也称为“reST”）格式，它是一种纯文本/文档字符串标记格式，可能是 Python 世界中最流行的格式。你当然应该看看Sphinx，这是一个从 reStructuredText 生成文档的工具（用于例如 Python 文档本身）。 Sphinx 包括从代码中的文档字符串中提取文档的可能性（请参阅sphinx.ext.autodoc），并按照某些约定识别 reST field lists。这可能已成为（或正在成为）最流行的方式。

您的示例可能如下所示：

"""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 Style Guide。请注意，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

示例取自上面链接的拿破仑文档。

所有类型文档字符串的综合示例here。

Answer 3

Python Enhancement Proposal 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 '')
    """

Answer 4

查看Documenting Python，这是一个“针对 Python 文档的作者和潜在作者”的页面。

简而言之，reStructuredText 用于记录 Python 本身。开发人员指南包含一个 reST 入门、样式指南和编写良好文档的一般建议。