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

Question

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

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

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

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

Answer 1

文档字符串的想法是让用户对正在发生的事情和发生的事情有一个基本的概述，而不告诉他们太多关于这是如何发生的。在这种情况下：

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

对于一个不那么简单的例子，我喜欢深入了解Python关于记录函数的部分：

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

    Return string."""

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

Answer 2

PEP 257 应该有帮助！

Answer 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，我会浏览一下，因为其中有一些关于 Python 设计决策和哲学的有趣主题。

Answer 4

我个人喜欢内置函数使用的风格。

>>>帮助（长度）

len(...)

len(对象) ->整数

返回序列或映射的项目数。