文档化开发注释规范
原则
- 在语言要求的地方注释,以标准的注释语法!
- 注释说明必要的信息,我们不期望精彩的小说在注释中诞生!
- 适当的版本标识
- 尽量使用CVS等版本管理系统自动提供的解析
- 因为如果自个儿来写的话难以统一修改
- 适当的设计思路描述
- 适当的算法设计描述
文档化标签
- 由于开发语言非常丰富,所以选择了最通用和稳定的文档化工具来支持:
-
-
DoxyGen 是种支持 C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) 以及 PHP, C# and D 等等语言的文档化工具.
- 成熟,功能强大,支持广泛
- 甚至于提供了图形界面的管理工具
- 对于所有支持多行注释的语言其实都可以应用
-
epydoc
- 是纯Python 实现的 Python 专用文档化工具
- 与Python 结合非常自然,稳定,可扩展
基础标签命令
仅仅列举我们推荐使用的文档化标签,进一步的标签命令,请自行进入相关页面学习
EpyDoc注释规范 | DoxyGen注释规范 |
epydoc 解析支持的标签规范
py常用命令
讲述基本的常用标签命令
py文献信息
@author: ... | 作者 | @license: ... | 版权 | @contact: ... | 联系 |
py状态信息
@version: ... | 版本推荐使用$Id$ | @todo [ver]: ... | 改进,可以指定针对的版本 |
py模块信息
@var v: ... | 模块变量v 说明 | @type v: ... | 模块变量类型v 说明 |
py函式信息
@param p: ... | 参数 p 说明 | @type v: ... | 参数 p 类型说明 | @return: ... | 返回值说明 | @rtype: ... | 返回值类型说明 |
py提醒信息
@note: ... | 注解 | @attention: ... | 注意 | @bug: ... | 问题 | @warning: ... | 警告 |
py关联信息
py标签格式
约定文档化标签的语法
- epydoc 支持三种标签的语法!
-
Epytext: @tag: 内容... -
ReStructuredText: :tag: 内容... -
Javadoc: @tag 内容... - 为了简化学习,在新浪标准化开发中我们推荐统一使用
@tag: 内容... 格式
py注释风格
约定文档化标签放置
- 依照Python 本身的注释风格自然的进行
-
切换行号显示
1
2 """Otter Tools main script
3 @version: $Id$
4 @author: U{Zoom.Quiet<mailto:Zoom.Quiet@gmail.com>}
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 ...
19
-
__init__.py 中的注释成为包文档 - 文件头部注释成为模块文档
- 紧贴 class 声明后的注释成为类文档
- 紧贴 def 声明后的注释成为函式文档
-- ZoomQuiet (2005-01-26)
|