【Python】函数 ⑤ ( 函数说明文档 | 函数说明文档内容建议 | 代码示例 )

一、函数说明文档

1、函数说明文档简介

函数说明文档 就是 通过 注释 对 函数的作用进行解释说明 ;

函数说明文档 用法 :

在 函数定义 后 , 函数体的第一行位置 , 输入六个双引号 , 此时光标会自动停留在第三个双引号之后 ,

在 光标停留在 第三个 双引号 之后 闪烁的状态下 , 敲击回车键 , 会自动生成如下 函数说明文档 的注释格式 , 其中包括

• :param 形参: 参数说明格式 ,
• :return: 返回值说明格式 ;

注意 : 函数的解释文字 , 要与 第一个形参说明所在行 , 两行之间间隔 1 行 ;

2、函数说明文档内容建议

Python 函数说明文档 建议包含如下内容 :

• 函数功能描述 : 对函数的功能 进行简单或详细介绍 , 如 : 输入的形式参数 和 返回值 之间的关系 ;
• 函数参数列表 : 介绍函数参数列表 , 包括函数接受的参数及其类型、默认值等信息 ;
• 函数返回值 : 函数返回值 介绍 ;
• 函数示例 : 给出该函数调用的代码示例 , 让开发者更容易理解使用该函数 ;
• 函数注意事项 : 介绍函数调用时的注意事项 , 如 : 函数的兼容性、异常情况、性能等问题 ;

2、代码示例 - 函数说明文档

代码示例 :

"""
函数说明文档 代码示例
"""

def add(a, b):
    """
    函数作用

    :param a: 参数一形参说明
    :param b: 参数二形参说明
    :return: 返回值说明
    """
    return a + b

sum = add(1, 2)

此时 , 如果将鼠标放在 add 函数上 , 在弹出的提示框中 , 会显示 函数说明文档 的内容 ;