epydoc 解析支持的标签规范
1. py常用命令
讲述基本的常用标签命令
1.1. py文献信息
@author: ... |
作者 |
@license: ... |
版权 |
@contact: ... |
联系 |
1.2. py状态信息
@version: ... |
版本推荐使用$Id$ |
@todo [ver]: ... |
改进,可以指定针对的版本 |
1.3. py模块信息
@var v: ... |
模块变量v 说明 |
@type v: ... |
模块变量类型v 说明 |
1.4. py函式信息
@param p: ... |
参数 p 说明 |
@type v: ... |
参数 p 类型说明 |
@return: ... |
返回值说明 |
@rtype v: ... |
返回值类型说明 |
1.5. py提醒信息
@note: ... |
注解 |
@attention: ... |
注意 |
@bug: ... |
问题 |
@warning: ... |
警告 |
1.6. py关联信息
@see: ... |
参考资料 |
2. py标签格式
约定文档化标签的语法
- epydoc 支持三种标签的语法！
Epytext:
@tag: 内容...
:tag: 内容...
Javadoc:
@tag 内容...
- 为了简化学习，在新浪标准化开发中我们推荐统一使用
@tag: 内容...
格式
3. py注释风格
约定文档化标签放置
- 依照Python 本身的注释风格自然的进行
1 # OtTool.py文件(模块)头部 2 """Otter Tools main script 3 @version: $Id$ 4 @author: U{Zoom.Quiet<mailto:[email protected]>} 5 @see: 参考资料链接等等 6 """ 7 import sys,string 8 class ottool: 9 """Otter Tools 主类 10 - 组织其它小工具，完成任务 11 @todo: 计划完成…… 12 """ 13 def __init__(self): 14 """调用相关模块，初始化(当前比较简单，对象初始化时就完成所有任务) 15 - 应用 OtCUI 参数理解;获得有效变量 16 """ 17 self.cui = OtCUI.otcui() 18 ...
__init__.py 中的注释成为包文档
- 文件头部注释成为模块文档
- 紧贴 class 声明后的注释成为类文档
- 紧贴 def 声明后的注释成为函式文档
-- ZoomQuiet (2005-01-26)