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

Question

假设我有一个功能，说：

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

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

在docstring中指定它需要a并返回+ 1的约定是什么？

Answer 1

文档字符串的想法是为用户提供进出的内容的基本概述，而不会过多地告诉他们如何发生这种情况。 在这种情况下：

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

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

Answer 2

PEP 257应该有所帮助！

Answer 3

对于Python约定（关于这个和其他主题），我建议首先尝试Python Enhancement Proposals。

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（...）

 len(object) -> integer Return the number of items of a sequence or mapping.