Python入门教程第27篇 函数之文档注释

Posted 2022-02-10 不剪发的Tony老师

本篇我们介绍一下如何利用文档注释（docstrings）为函数增加帮助文档。

help() 函数

Python 提供了一个内置的函数 help()，用于显示函数的帮助文档。

以下示例输出了 print() 函数的帮助文档：

help(print)

输出结果如下：

print(...)
    print(value, ..., sep=' ', end='\\n', file=sys.stdout, flush=False)

    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

help() 函数可以用于显示模块、类、函数以及关键字的帮助信息，本文主要涉及函数相关内容。

编写函数帮助文档

如果想要编写函数的帮助文档，可以使用文档注释功能。PEP 257 描述了文档注释相关的规范。

如果函数体的第一行代码是字符串，Python 会将它们当作一个文档注释。例如：

def add(a, b):
    "Return the sum of two arguments"
    return a + b

然后我们可以使用 help() 函数返回 add() 函数的说明文档：

help(add)

输出结果如下：

add(a, b)
    Return the sum of two arguments

通常来说，我们会使用多行文档注释：

def add(a, b):
    """ Add two arguments
    Arguments:
        a: an integer
        b: an integer
    Returns:
        The sum of the two arguments
    """
    return a + b

再次使用 help(add) 函数的输出结果如下：

add(a, b)
    Add the two arguments
    Arguments:
            a: an integer
            b: an integer
        Returns:
            The sum of the two arguments     

实际上，Python 将文档注释存储在函数的 doc 属性中。

以下示例演示了如何访问 add() 函数的 doc 属性：

add.__doc__

总结

• 使用 help() 函数获取函数的帮助文档。
• 将字符串（单行或多行字符串）作为函数体中的第一行代码就可以为函数添加帮助文档。