使用javadoc for Python文档

Question

我目前从Python开始,我有一个强大的PHP背景,在PHP中我习惯使用javadoc作为文档模板.

我想知道它是否javadoc有它作为docstringPython文档的位置.这里有既定的惯例和/或官方的guildelines？

例如,这样的东西太精巧,不适合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 字段列表.这可能成为(或正在成为)最受欢迎的方式.

您的示例可能如下所示:

"""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还可以使用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

从上面链接的Napolean文档中获取的示例.

这里有关于所有类型文档字符串的综合示例.

Answer 3

python文档字符串的标准在Python Enhancement Proposal 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 '')
    """