使用的Javadoc Python文档[关闭]使用的Javadoc Python文档[关闭](Usi

我目前正在与Python的开始，我有一个强大的PHP背景和PHP我已经把使用习惯javadoc的文档模板。

我在想，如果javadoc有作为的地方docstring在Python文档。 什么是既定的惯例和/或在这里正式= 138161？

例如，是这样的太复杂，以适应在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:

看一看在新结构化（也被称为“休息”）格式，这是明文/文档字符串标记格式，并在Python世界中可能是最流行的。而且你当然应该看看狮身人面像，以生成新结构化文档的工具（用于例如，Python文档本身）。狮身人面像包括可能性代码（见来提取文档字符串文件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
"""

Answer 2:

按照谷歌的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

从上述链接的文档拿破仑拍摄的实施例。

在所有类型的文档字符串的一个详细的例子在这里。

Answer 3:

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