一般的,我们在编写代码或 定义方法函数时,经常会添加注释。在创建函数、类以及类方法时,可以为它们添加说明性文档,即分别在函数体、类体以及类方法内部的首行添加具有说明性的字符串即可。例如:
以该工程下example_01.py和example_02.py为例子进行叙述,先来看看这2个文件中的内容
example_01.py
#!/usr/bin/env python
# -*- coding: utf-8 -*-
# @Time : 2021/7/3 22:09
# @Author : ywb
# @Site : 反转一个3位整数
# @File : example_01.py
# @Software: PyCharm
import ddt
def reverse_three_int_number(num):
"""
反转一个3位整数
:param num: 3位整数
:return: 3位整数反转后的结果
"""
return int(''.join(list(reversed(str(num)))))
if __name__ == '__main__':
print(reverse_three_int_number(123))
print(reverse_three_int_number(900))
example_02.py
#!/usr/bin/env python
# -*- coding: utf-8 -*-
# @Time : 2021/7/3 22:15
# @Author : ywb
# @Site : 将两个新的升序数组合并成一个新的有序数组
# @File : example_02.py
# @Software: PyCharm
def combine_two_arrays_to_new_ordered_arrays(one_array, other_array):
"""
将两个新的升序数组合并成一个新的有序数组
:param one_array: 第一个升序数组
:param other_array: 第二个升序数组
:return: 合并后的新的有序数组
"""
one_array.extend(other_array)
return sorted(one_array)
if __name__ == '__main__':
print(combine_two_arrays_to_new_ordered_arrays([1], [1]))
print(combine_two_arrays_to_new_ordered_arrays([1, 2, 3, 4], [2, 4, 5, 6]))
print(combine_two_arrays_to_new_ordered_arrays([1, 4], [1, 2, 3]))
在此基础上,我们可以使用help()函数或者doc属性来获取函数或者方法的说明性文档,代码如下:
print(help(reverse_three_int_number))
result:
Help on function reverse_three_int_number in module __main__:
reverse_three_int_number(num)
反转一个3位整数
:param num: 3位整数
:return: 3位整数反转后的结果
None
print(combine_two_arrays_to_new_ordered_arrays.__doc__)
result:
将两个新的升序数组合并成一个新的有序数组
:param one_array: 第一个升序数组
:param other_array: 第二个升序数组
:return: 合并后的新的有序数组
但是该方法产生的说明文档只能在代码输出结果中进行查看,且要编写代码,便利性不是很好,所以下面会介绍pydoc模块来来生成更为便利的说明文档