"""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
"""
Have a look at the reStructuredText (also known as "reST") format, which is a plaintext/docstring markup format, and probably the most popular in the Python world. And you should certainly look at Sphinx, a tool to generate documentation from reStructuredText (used for eg. the Python documentation itself). Sphinx includes the possibility to extract documentation from the docstrings in your code (see sphinx.ext.autodoc), and recognizes reST field lists following certain conventions. This has probably become (or is becoming) the most popular way to do it.
Your example could look as follows:
"""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
"""
Or extended with type information:
"""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
"""
Follow Google Python Style Guide. Note that Sphinx can also parse this format using the Napolean extension, which will come packaged with Sphinx 1.3 (this is also compatible with 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
Example taken from the Napolean documentation linked above.
A comprehensive example on all types of docstrings here.
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 '')
"""
The appropriate comment for your method would be something like
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 '')
"""
Take a look at Documenting Python, a page "aimed at authors and potential authors of documentation for Python."
In short, reStructuredText is what's used for documenting Python itself. The developer's guide contains a reST primer, style guide, and general advice for writing good documentation.
发布评论
评论（4）
查看 reStructuredText（也称为“reST”）格式，它是一种纯文本/docstring 标记格式，可能是 Python 世界中最流行的。你当然应该看看 Sphinx，一个从 reStructuredText 生成文档的工具（例如用于 Python 文档本身） ）。 Sphinx 可以从代码中的文档字符串中提取文档（请参阅 sphinx.ext.autodoc），并识别遵循某些约定的其余字段列表。这可能已经成为（或正在成为）最流行的方式。
您的示例可能如下所示：
或使用类型信息进行扩展：
Have a look at the reStructuredText (also known as "reST") format, which is a plaintext/docstring markup format, and probably the most popular in the Python world. And you should certainly look at Sphinx, a tool to generate documentation from reStructuredText (used for eg. the Python documentation itself). Sphinx includes the possibility to extract documentation from the docstrings in your code (see sphinx.ext.autodoc), and recognizes reST field lists following certain conventions. This has probably become (or is becoming) the most popular way to do it.
Your example could look as follows:
Or extended with type information:
遵循 Google Python 风格指南 。请注意，Sphinx 还可以使用 Napolean 扩展来解析此格式，该扩展将与Sphinx 1.3（这也与 PEP257 兼容）：
示例来自上面链接的 Napolean 文档。
有关所有类型文档字符串的综合示例 在这里。
Follow Google Python Style Guide. Note that Sphinx can also parse this format using the Napolean extension, which will come packaged with Sphinx 1.3 (this is also compatible with PEP257):
Example taken from the Napolean documentation linked above.
A comprehensive example on all types of docstrings here.
Python 文档字符串的标准在 Python 增强提案 257 中进行了描述。
您的方法的适当注释类似于
The standard for python documentation strings is described in Python Enhancement Proposal 257.
The appropriate comment for your method would be something like
看一下 Documenting Python，该页面“针对以下文档的作者和潜在作者”： Python。”
简而言之，reStructuredText 是用于记录 Python 本身的内容。开发人员指南包含 reST 入门书、风格指南以及编写良好文档的一般建议。
Take a look at Documenting Python, a page "aimed at authors and potential authors of documentation for Python."
In short, reStructuredText is what's used for documenting Python itself. The developer's guide contains a reST primer, style guide, and general advice for writing good documentation.