使用javadoc获取Python文档

Question

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

我想知道它是否在Python文档中javadoc占有一席之地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字段列表。这可能已经成为（或正在成为）最流行的方法。

您的示例如下所示：

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