编写文档字符串 - 指定函数参数和返回答案

【问题标题】：Writing docstrings - specifying functions arguments and returns编写文档字符串 - 指定函数参数和返回
【发布时间】：2010-12-24 05:38:56
【问题描述】：

假设我有一个函数，比如说：

>>> def foo(a):
        return a+1

我想为它写一个文档字符串。

在文档字符串中指定接受 a 并返回 a+1 的约定是什么？

【问题讨论】：

【解决方案1】：

文档字符串的想法是让用户对正在发生的事情和即将发生的事情有一个基本的了解，而无需过多地告诉他们这是如何发生的。在这种情况下：

def foo(a):
    """Take a number a and return its value incremented by 1."""
    return a + 1

举一个不那么琐碎的例子，我喜欢Dive Into Python's section on documenting functions:中的那个

def build_connection_string(params):
    """Build a connection string from a dictionary of parameters.

    Return string."""

显然，更复杂的函数需要更大的文档字符串。只需确保文档字符串正在谈论正在发生的事情（传入的内容，返回的内容）而不是如何发生的（不应包含实现细节）。

【讨论】：

【解决方案2】：

PEP 257 应该有帮助！

【讨论】：

【解决方案3】：

对于 Python 约定（关于本主题和其他主题），我建议首先尝试 Python 增强提案。

Python PEP 257 建议使用一行文档字符串来指定您的函数，如下所示：

def function(a, b):
"""Do X and return a list."""

但不是这样：

def function(a, b):
"""function(a, b) -> list"""

因为后一个例子可以通过其他方式来预测。

只浏览了它们，但 PEP 的链接看起来会转到其他 PEP，这些 PEP 会涉及到文档字符串的本质。

作为一般说明，如果您尚未浏览 PEP，我会浏览一下 PEP，因为其中有一些关于 Python 设计决策和哲学的有趣主题。

【讨论】：

【解决方案4】：

我个人喜欢内置函数使用的样式。

>>> 帮助(len)

len(...)

len(object) -> integer

Return the number of items of a sequence or mapping.

【讨论】：