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

Question

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

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

我想为这个函数写一个文档字符串。

在文档字符串中，怎么写才能说明这个函数接收一个参数a，并返回a+1呢？

Answer 1

关于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，建议你浏览一下，因为里面有一些关于Python设计决策和理念的有趣话题。

Answer 2

PEP 257 可能会对你有帮助！

Answer 3

文档字符串的目的是给用户一个基本的概述，让他们知道这个功能是干什么的，输入和输出是什么，而不需要告诉他们太多具体的实现细节。在这个例子中：

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

对于一个不那么简单的例子，我喜欢在《Dive Into Python》中关于文档化函数的部分里的例子：

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

    Return string."""

显然，一个更复杂的函数需要更长的文档字符串。只要确保文档字符串讨论的是发生了什么（输入了什么，返回了什么），而不是具体是怎么实现的（实现细节不应该包含在内）。