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

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

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

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

在文档字符串中指定它接受 a 并返回 a+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."""

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

关于python - 编写文档字符串 - 指定函数参数和返回值，我们在Stack Overflow上找到一个类似的问题：https://stackoverflow.com/questions/4524450/