Doxygen注释规范

发表于 | 分类于 | 评论数：
Doxygen注释规范

Doxygen注释规范

简介|来自百度百科

  Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxygen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。

  Doxygen 是一个程序的文件产生工具，可将程序中的特定注释转换成为说明文件。通常我们在写程序时，或多或少都会写上注释，但是对于其它人而言，要直接探索程序里的注释，与打捞泰坦尼克号同样的辛苦。大部分有用的注释都是属于针对函数、类型等等的说明。所以，如果能依据程序本身的结构，将注释经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。

  对于未归档的源文件，也可以通过配置Doxygen来提取代码结构。或者借助自动生成的包含依赖图（includedependency graphs）、继承图（inheritance diagram）以及协作图（collaborationdiagram）来可视化文档之间的关系。Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML和Unixman page等。

  一个好的程序设计师，在写程序时，都会在适当的地方加上合适的注释。如果，能够在撰写注释时，稍微符合某种格式，接着就可以透过一个工具程序依据程序结构及您的批注产生出漂亮的文件。这将令许多工作繁重的程序设计师有时间多喝几杯咖啡。

  Doxygen 就是这样的一个工具。在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文件了。因此，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文件。

适用语言

1
2
3
4
5
6
7
8
9
* C/C++
* Java
* Objective-C
* Python
* IDL (Corba, Microsoft及KDE-DCOP类型)
* Fortran
* VHDL
* PHP
* C#

注释模板

文件注释模板
1
2
3
4
5
6
7
/** @brief  	摘要
 *  @file   	文件名
 *  @author 	作者
 *  @version	版本
 *  @date  	日期
 *  @note    注解(写一些功能及注意事项等...)
 */
函数注释模板
1
2
3
4
5
6
7
8
9
10
/**  
 * @brief         函数摘要
 * @param1        参数1
 * @param2        参数2
 * @param3   	  参数3
 * @retval        返回值类型
 * @return		  返回值
 * @warning       警告: 例如: 参数不能为空
 * @note          注解
 */
行注释模板
1
2
1--   /**< 在这里写你要加的东西 */
2--   ///< 在这里写你要加的东西
常用注释关键字
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@author     作者
@brief      摘要
@bug        被标记的代码会在Bug列表中出现
@class      类名，格式：@class <name> [<header-file>] [<header-name>] eg:@class Test"test/test.h"
@date       日期
@file       文件名，可以默认为空，DoxyGen会自己加
@param      函数参数名及其说明
@return     描述该函数的返回值情况eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval     描述返回值类型 eg: @retval NULL 空字符串。
@retval !NULL 非空字符串。
@note       注解
@attention  注意
@name       分组名
@warning    警告信息
@enum       引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg：@enum CTest::MyEnum
@var        引用了某个变量，Doxygen会在该枚举处产生一个链接 eg：@var CTest::m_FileKey
@exception  可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常
@todo       对将要做的事情进行注释
@see        see also字段
@relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。
@since      从哪个版本后开始有这个函数的
@code       在注释中开始说明一段代码，直到@endcode命令。
@endcode    在注释中代码段的结束。
@remarks    备注
@pre        用来说明代码项的前提条件。
@post       用来说明代码项之后的使用条件。
@deprecated 这个函数可能会在将来的版本中取消。
@defgroup   模块名
@{          模块开始
@}          模块结束
@class      声明一个类 
@version    版本号
@fn         声明一个函数
@par        开始一个段落，段落名称描述由你自己指定，比如可以写一段示例代码
-           一级项目符号
-#          二级项目符号