Python 编写docstring-指定函数参数和返回

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

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

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

---

在docstring中指定接受a并返回+1的惯例是什么？

应该会有帮助

docstring的思想是让用户对输入和输出的内容有一个基本的概述，而不告诉他们太多关于如何发生的事情。在这种情况下：

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

对于一个不那么琐碎的例子，我喜欢

显然，更复杂的函数需要更大的docstring。只需确保docstring谈论的是发生了什么（传入了什么、返回了什么），而不是发生的方式（不应包括实现细节）。

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

建议使用单行docstring指定函数，如下所示：

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

但不是这样：

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

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

虽然只是浏览了一下，但是PEP的链接看起来会转到其他PEP，从而深入到文档字符串的本质

---

一般来说，如果您还没有阅读过PEP，我会浏览一下，因为有一些关于Python设计决策和哲学的有趣话题。

我个人喜欢内置软件使用的风格

>>>帮助（len）

len（…）

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

len(object) -> integer

Return the number of items of a sequence or mapping.