Python学习笔记010——函数文档字符串

Posted 2020-10-16

函数文档字符串documentation string （docstring）是在函数开头，用来解释其接口的字符串。简而言之：帮助文档

1. 包含函数的基础信息
2. 包含函数的功能简介
3. 包含每个形参的类型，使用等信息
4. 是接口设计的重要部分。
5. 注：一个良好的接口不能简单、清晰的表述该函数，则说明该函数还有优化改进的空间

函数文档的使用

1. 必须在函数的首行，经过验证前面有注释性说明是可以的，不过最好函数文档出现在首行
2. 使用三引号注解的多行字符串（当然，也可以是一行），因三引号可以实现多行注解（展示）(‘‘‘ ‘‘‘) 或(""" """)
3. 函数文档的第一行一般概述函数的主要功能，第二行空，第三行详细描述。

查看方式

1. 在交互模式下可以使用ｈｅｌｐ查看函数，帮助文档，该界面会跳到帮助界面，需要输入q退出界面
2. 使用__doc__属性查看，该方法的帮助文档文字直接显示在交互界面上。

举例说明

def test():
    ‘‘‘
        函数名：test
        功能：测试
        参数：无
        返回值：无
    ‘‘‘
    print("函数输出成功")

test()

 在交互模式下输入

 >>> import day10
 >>> help(day10.test)

最后在帮助界面显示如下 

 按q键退出

 

同样在交互模式下出入

>>> import day10
>>> print(day10.test.__doc__)

        函数名：test
        功能：测试
        参数：无
        返回值：无
    
>>> 

截图如下

在其下直接显示帮助文档。