将 javadoc 用于 Python 文档

如何解决将 javadoc 用于 Python 文档

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

解决方法

我目前是从 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)