Python利用__all__与help快速生成文档说明

作为开发人员，编写程序说明文档是不可或缺的工作环节。为了能够高效且高质量地完成这一任务，我们需要深入探讨具体的实现方法。

本文将介绍一个简单且日常需注意的细节，通过该方式可以轻松生成注释文档，同时还能检查类和方法的引用名称是否存在重复或冲突问题。

许多专业开发者撰写的文档令人赞叹，但我们可以通过Python自动生成基本满足需求的说明文档。这样做不仅提升了代码的整体可读性，使代码结构更加清晰，还能在人员交接时减少诸多麻烦。其他同事接手工作时无需逐行询问代码含义，因为直观的注释已能说明问题。在整合项目时，这些文档也可作为向客户或上级汇报的基础材料。

接下来介绍具体实现方法，请参考下方的代码格式。需要注意的是，注释部分以及函数名、类名均需要与__all__列表中的内容相关联。

#!/usr/bin/env python

# -*-coding:utf-8 -*-

'''

 
文档快速生成注释的方法介绍,首先我们要用到__all__属性

在Py中使用为导出__all__中的所有类、函数、变量成员等

在模块使用__all__属性可避免相互引用时命名冲突

'''

__all__ = ['Login', 'check', 'Shop', 'upDateIt', 'findIt', 'deleteIt', 'createIt']

class Login:

'''

测试注释一可以写上此类的作用说明等

例如此方法用来写登录

'''

def __init__(self):

'''

初始化你要的参数说明

那么登录可能要用到

用户名username

密码password

'''

pass

def check(self):

'''

协商你要实现的功能说明

功能也有很多例如验证

判断语句，验证码之类的

'''

pass

class Shop:

'''

商品类所包含的属性及方法

update改/更新

find查找

delete删除

create添加

'''

def __init__(self):

'''

初始化商品的价格、日期、分类等

'''

pass

def upDateIt(self):

'''

用来更新商品信息

'''

pass

def findIt(self):

'''

查找商品信息

'''

pass

def deleteIt(self):

'''

删除过期下架商品信息

'''

pass

def createIt(self):

'''

创建新商品及上架信息

'''

pass

if __name__=="__main__":

import pythonzhushi

print help(pythonzhushi)

这里需要特别强调，Python文件的名称必须与当前工作模块的名称保持一致（例如本例中创建的py文件名为pythonzhushi，导入时也使用相同名称）。因为在后续测试中，import导入的是自身模块，所以import的名称、Help()函数的参数以及文件名必须完全一致才能正确生成文档。为了更直观地理解，请参考下图。

此外，还可以采用从其他文件引用的方式进行导入，这里使用Python常用的from...import语法，指定从哪个目录导入pythonzhushi模块。

此处仍通过图片展示具体操作过程。

效果是否一目了然？这种方法可以导入我们所需的注释文档。help帮助方法用于查看文件中包含的类、函数等信息，生成简单的帮助文档，类似于README文件的说明作用。最后来看看实际演示效果。

是否简单地打印出了程序的说明文档？后续步骤可以直接新建一个文本文件，将打印内容粘贴进去，即可完成README文档的编写。经过测试，有几点注意事项：如果要使用#符号进行注释，不要写在def方法内部，而应写在方法上方，这与装饰器的写法类似；相反，三引号'''注释不要写在def方法外部，否则将没有显示效果。大家不妨尝试一下。感谢观看。