Python快速从注释生成文档的方法

yipeiwu_com5年前Python基础

作为一个标准的程序猿,为程序编写说明文档是一步必不可少的工作,如何才能写的又好又快呢,下面我们就来详细探讨下吧。

今天将告诉大家一个简单平时只要注意的小细节,就可以轻松生成注释文档,也可以检查我们写的类方法引用名称是否重复有问题等。

一看别人专业的大牛们写的文档多牛多羡慕,不用担心我们可以让python为我们生成基本满足的说明文档,一来可以提高代码整体阅读性,二来可以将代码的整体结构看着也更清晰,这样在交接的时候可以省很多麻烦,其它同事在接手你工作的时候也不会一行行去问你这是什么那是什么的,因为注释已经很直观的表述了,在整合的时候可当说明文档给客户简单说明(主要是给你BOSS看的).

那么进入正题怎么实现看下面我简单的代码格式,注意注释的地方和函数名类名都是与__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)

这里要强调说明下py的名字要和你当前工作的py名字一样(我这里创建的py名字就是pythonzhushi,最后导入也是这名字),因为下面的测试中import的导入的是自身所以,im port 名称 和Help(名称)以及你的文件名称要一致才可以。为了更加直观请看下面这图:

当然还可以从其它文件引用的方式导入这里用到python常用的导入方式from从哪个目录import导入什么文件pythonzhushi

当然我这里还是用图片来展示以下:

是不是一目了然,这样也可以导入我们需要做的注释文档,help帮助方法就是帮我们查看到此文件中所包含的类,函数,的一个简单帮助文档,类似于readme文档的一个说明。最后来看看掩饰效果吧:

是不是简单的打印出我们程序的说明文档,后面步骤直接可以建一个文本把这个粘贴过去,就完成一个readme的文档说明,经过测试有几点注意是,想要写#这种注释不要写到def放发内要写到它的上面位置和装饰器类似,相反三引号'''不要写到def外面,这样也是没显示效果的。大家赶紧去试试吧。感谢观看。。

相关文章

Python多线程学习资料

一、Python中的线程使用: Python中使用线程有两种方式:函数或者用类来包装线程对象。 1、 函数式:调用thread模块中的start_new_thread()函数来产生新线程...

python中字符串变二维数组的实例讲解

python中字符串变二维数组的实例讲解

有一道算法题题目的意思是在二维数组里找到一个峰值。要求复杂度为n。 解题思路是找田字(四边和中间横竖两行)中最大值,用分治法递归下一个象限的田字。 在用python定义一个二维数组时可以...

Python实现SVN的目录周期性备份实例

本文实例讲述了Python实现SVN的目录周期性备份方法。分享给大家供大家参考。具体如下: 起因:今天用SVN时,不小心把远程SVN服务器上的目录删掉了,然后在本地又手贱地还原了一下项目...

python 实现方阵的对角线遍历示例

任务描述 对一个方阵矩阵,实现平行于主对角线方向的对角线元素遍历。 从矩阵索引入手: [[ 1 2 3 4 5] [ 6 7 8 9 10] [11 12 13 14 15]...

用Python徒手撸一个股票回测框架搭建【推荐】

用Python徒手撸一个股票回测框架搭建【推荐】

通过纯Python完成股票回测框架的搭建。 什么是回测框架? 无论是传统股票交易还是量化交易,无法避免的一个问题是我们需要检验自己的交易策略是否可行,而最简单的方式就是利用历史数...