Python——文档字符串

Python——文档字符串

在使用“def”关键字定义一个函数时，其后必须跟有函数名和包括形式参数的园括号。从函数体的第一行可以是字符串，这个字符串就是文档字符串。例如:

def add(x, y):
    """
    返回参数x和y的两数之和

Parameters
----------
x : int
    第一个参数
y : int
    第二个参数

Returns
-------
int
    返回 x + y
    """
    return x + y
print(add(1, 2))
print(add.__doc__)

执行结果如下：

3

    返回参数x和y的两数之和

Parameters
----------
x : int
    第一个参数
y : int
    第二个参数

Returns
-------
int
    返回 x + y

从执行的结果可以看到，文档字符串可以使用_doc_(注意双下划线）获取。如果你已经在Python中使用过help()，就说明你已经看过文档字符串的使用了，它所做的只是抓取函数的_doc_属性，然后整洁地展示给你。
例如：

def add(x, y):
    """
    返回参数x和y的两数之和

Parameters
----------
x : int
    第一个参数
y : int
    第二个参数

Returns
-------
    返回 x + y
"""
    return x + y

help(add)

执行结果如下（按Q键退出help）：

Help on function add in module __main__:

add(x, y)
        返回参数x和y的两数之和
    
    Parameters
    ----------
    x : int
        第一个参数
    y : int
        第二个参数
    
    Returns
    -------
        返回 x + y

自动化工具也能以同样的方式从你的程序中提取文档。