11. 警告
当然对于意外情况， epydoc 不会崩溃，只是进行警告，你可以根 据提示进行修正
12. 块结构
象文章分章节一样 注释文本也能定义各种语义区块
12.1. 段落
@par 命令引出
/*! \class Test 普通文字
@par 用户定义第一段. 段落可以包含多行
@par */
这是第二段. 段落间通过空行来区分
@tag: 内容...格式
5. py注释风格
约定文档化标签放置
依照Python 本身的注释风格自然的进行
1 # OtTool.py文件(模块)头部
2 """Otter Tools main script
3 @version: $Id$
4 @author: U{Zoom.Quiet<mailto:Zoom.Quiet@>} 5 @see: 参考资料链接等等
15
- 应用 OtCUI 参数理解;获得有效变量
16
"""
17
self.cui = OtCUI.otcui()
18 ...
__init__.py 中的注释成为包文档 文件头部注释成为模块文档 紧贴 class 声明后的注释成为类文档 紧贴 def 声明后的注释成为函式文档
6. dox常用命令
讲述基本的常用标签命令
6.5. dox提醒信息
@note ... @attention ... @bug ... @warning ...
6.6. dox关联信息
@sa ...
作者 摘要 文件声明
版本推荐使用$Id$ 改进,可以指定针对的版本
模块变量 说明 模块变量类型说明
参数 p 说明 列表说明参数 信息 返回值说明 返回值类型说明
依照C/C++ JAVA 类别语言注释风格自然的进行
/** * 一个示范类，描述在此
*/ class Test{
public: /** * 一个 enum. * 详细描述可以多行
*/ enum TEnum {
TVal1, /**单行注释*/
} *enumPtr, /**< enum pointer. Details. */ /** * 构造器函式 * 详细描述可以多行
2. 文档化标签
由于开发语言非常丰富，所以选择了最通用和稳定的文档化工具来支持:
DoxyGen 是种支持 C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) 以及 PHP, C# and D 等等语言的文档化工具.
成熟，功能强大,支持广泛 甚至于提供了图形界面的管理工具 对于所有支持多行注释的语言其实都可以应用
6 """
7 import sys,string
8 class ottool: 9 """Otter Tools 主类
10
- 组织其它小工具，完成任务
11 @todo: 计划完成……
12 """
13 def __init__(self):
14
"""调用相关模块，初始化(当前比较简单，对象初始化时就完成所有任务)
3.3. py模块信息
@var v: ... @type v: ...
3.4. py函式信息
@param p: ... @type v: ... @return: ... @rtype v: ...
3.5. py提醒信息
@note: ... @attention: ... @bug: ...
作者 版权 联系
注解 注意 问题 警告
参考资料
7. dox标签格式
约定文档化标签的语法
epydoc 支持两种标签的语法！ doxygen: \tag 内容... Javadoc: @tag 内容... 为了简化学习，在新浪标准化开发中我们推荐统一使用
@tag: 内容...格式
8. dox注释风格
约定文档化标签放置
版本推荐使用$Id$ 改进,可以指定针对的版本
模块变量v 说明 模块变量类型v 说明
参数 p 说明 参数 p 类型说明 返回值说明 返回值类型说明
注解 注意 问题
@warning: ...
警告
3.6. py关联信息
@see: ...
4. py标签格式
参考资料
约定文档化标签的语法
epydoc 支持三种标签的语法！ Epytext: @tag: 内容... ReStructuredText: :tag: 内容... Javadoc: @tag 内容... 为了简化学习，在新浪标准化开发中我们推荐统一使用
/** * ... text ... */
Qt 样式的:
/*! ... text ... */
C++ 样式的:
/// /// ... text ... /// or //! //! ... text ... //!
我们推荐简化的 Qt 风格 /*! 引发的多行注释 ... */ 正常結束
8.1. 输出美化控制
""" [...] 将生成:
此段不在任何章节中
9.3.1. 第 1 章
这为第 1 章中的段落
9.3.1.1. 章节 1.1
此为章节 1.1 中的段落
9.3.2. 第 2 章
此为第 2 章 中的段落.
9.4. 引用块
同样是利用ReStructuredText 的引用声明 def example(): """ 使用“：：”引出引用块:: 原文 / / 引用块 此为在引用块后的段落 还是空行来区分. """ [...]
2. 此为列表第二项 可以包含段落和测试引用
>>> print '此为测试引用语句' 此为测试引用语句
此为第二段 """
[...] 将生成文档为:
此为段落.
此为列表项
此为子列表 子列表第二项
此为次层列表,同样可以继续列表下去 只要有一致的缩进
此为列表第二项
可以包含段落和测试引用 >>> print '此为测试引用语句' 此为测试引用语句 此为第二段
具体实例参考:
@li 命令
12.3. 章节
@section 命令引发 不过，只能在 @page 命令后作用 即通过 @page 命令，声明创建一个相关页面，内容将组织到最终的“相关页面”中，与
Todo Bug 列表页面等等并列在一起! 例如 /*! @page page1 A documentation page
*/ Test(); /**
* 一个普通函式 描述和参数等等的叙述 * @param a 整数参数 * @param s 字串指针参数 * @see Test() 参看.. * @return 返回值描述
*/ int testMe(int a,const char *s); /** * 纯虚成员函式 * @see testMe() 参看 * @param c1 第一参数
1. 原则
在语言要求的地方注释，以标准的注释语法! 我们禁止惊奇！一切规范化到谁都可以准确的猜测出正确的结果最好！(就象 FreeBSD 的组织方式...)
注释说明必要的信息，我们不期望精彩的小说在注释中诞生! 适当的版本标识 尽量使用CVS等版本管理系统自动提供的解析 因为如果自个儿来写的话难以统一修改 适当的设计思路描述 适当的算法设计描述
py文献信息
py状态信息 py模块信息 py函式信息 py提醒信息 py关联信息
py标签格式 py注释风格
3. py常用命令
讲述基本的常用标签命令
3.1. py文献信息
@author: ... @license: ... @contact: ...
3.2. py状态信息
@version: ... @todo [ver]: ...
对应生成文档:
The epydoc homepage The Python homepage Edward Loper
10.1.2. 交叉引用
L{text<object>} 可以自动生成到其它对象的文档页面链接 text 处是说明文字 <object> 是具体对象的名称，类/函式/变量 名
* @param c2 第二参数 */ virtual void testMeToo(char c1,char c2) = 0; /** * 一个公共变量 * 详细描述 */ int publicVar; };
DoxyGen 支持多种注释声明,仅仅是在标准基础上添加一点儿:
JavaDoc 样式的:
具体实例参考:
@par 命令 输出的HTML
12.2. 列表
@li 命令引发 可以混合其它格式命令
@li \c AlignLeft left alignment. @li \c AlignCenter center alignment. @li \c AlignRight right alignment 无类型的列表项也支持
6.1. dox文献信息
@author ... @brief ... @file ...
6.2. dox状态信息
@version ... @todo ...
6.3. dox模块信息
@var ... @typedef ...
6.4. dox函式信息
@param p ... @arg ... @return ... @retval ...