对 Python 文档使用 javadoc

我目前正在开始使用 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)
104465 次浏览
小开

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 '')
"""
小开
最佳答案

看一下 ReStructuredText(也称为“ reST”)格式，它是一种明文/docstring 标记格式，可能是 Python 世界中最流行的格式。您当然应该看看 狮身人面像，它是一个从 ReStructuredText 生成文档的工具(例如，用于 Python 文档本身)。Sphinx 提供了从代码中的 docstring 提取文档的可能性(参见 Sphinx.ext.autodoc) ，并且可以识别遵循某些约定的 reST外勤工作表。这可能已经成为(或正在成为)最流行的方式做到这一点。

你的例子可以是这样的:

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

或扩展类型信息:

"""Replace 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，这是一个“面向 Python 文档的作者和潜在作者”的页面

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

小开

跟着 Google Python 风格指南。注意，Sphinx 还可以使用 拿破仑扩展解析这种格式，它将与 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

上面链接的那不勒斯文档中的例子。

关于所有类型文档字符串 给你的综合示例。


提交答案