使用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)

- JF Dion

---

在此之前的问题链接中也有许多其他答案，而本问题是一个重复的问题。请参考那些答案。 - Alex Dupuy

可能是Python标准文档字符串格式是什么？的重复问题。 - zvone

Answer 1

请查看reStructuredText（也称为“reST”）格式，这是一种纯文本/文档字符串标记格式，并且可能是Python世界中最流行的格式。你应该确保查看Sphinx，这是一种从reStructuredText生成文档的工具（例如用于Python文档本身）。Sphinx包括从代码中提取文档的可能性（请参见sphinx.ext.autodoc），并识别遵循某些约定的reST field lists。这可能已经成为（或正在成为）最流行的方法。

您的示例可能如下所示：

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

- Steven

---

如果需要在长描述中换行，应该怎么做？这会是什么样子？ - Skylar Saveland

请参考reStructuredText文档中的内容，特别是字段列表部分：http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists。 - Steven

从1.3版本开始，Sphinx还通过sphinx.ext.napoleon扩展支持更好的格式。 - Petri

请问有人能指向最好的文件说明这些特殊文档字符串，比如“：param____:”和“：returns:”吗？目前似乎很难找到这样的文档。 - krumpelstiltskin

我喜欢这个...扁平比嵌套好。我只是在参数中包含类型，而不是将类型行单独放在一起。 - radtek

其他类、方法（在本类和其他类中）等的链接怎么办？我找不到详细说明这一点的reStructuredText信息。 - user118967

Answer 2

请遵循Google Python Style Guide。请注意，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文档中摘取的示例。

有关所有类型的文档字符串的详细示例在此处。

- confused00

---

对于所有阅读文档字符串的人类 - Waylon Flinn

更新了Google Python风格指南的链接。 - confused00

@confused00 我该如何记录我的方法返回一个对象数组？ - Cito

现在我有点糊涂了！是args还是params? https://dev59.com/x3I-5IYBdhLWcg3wkJMA - KRoy

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

- srgerg

---

PEP257并没有明确说明参数部分的实际格式。它只声明应该写出来，并且给出了一个例子。但这只是一个例子。因此，我强烈建议使用Sphinx约定，这样您就不会违反PEP257规范，并且可以使用可以被Sphinx解析的格式。 - vaab

除了上面提供的第一份文档外，其它文档太丑陋且包含了许多对于人类来说冗余的信息。我更愿意采用一种规范，使我的源代码在不需要先被解析的情况下也能轻松阅读。 - confused00

Answer 4

请查看Python文档编写，这是一个“面向Python文档作者和潜在作者”的页面。

简而言之，reStructuredText是用于记录Python本身的工具。开发者指南包含了reST入门指南、样式指南以及撰写良好文档的一般建议。

- David Cain