Doxygen注释模板

1 简介

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

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

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

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

2 常用命令

命令 生成字段名 说明 @{ 模块开始 @} 模块结束 @addtogroup 添加到一个组 @attention 注意 @author 作者 @brief 简要注释 @bug 缺陷 链接到所有缺陷汇总的缺陷列表 @class 类名 @code 引用代码段 代码块开始，与“nendcode”成对使用 @date 日期 @defgroup 模块名 @details 详细注释 @endcode 引用代码段结束 代码块结束，与“ncode”成对使用 @exception 函数抛异常描述 @file 文件名 可以默认为空，DoxyGen会自己加 @fn 函数说明 @include 包含文件 @ingroup 加入到一个组 @name 分组名 @note 开始一个段落 用来描述一些注意事项 @par 开始一个段落 段落名称描述由你自己指定 @param 函数参数 用在函数注释中 @post 函数后置条件 比如对系统状态的影响或返回参数的结果预期 @pre 函数前置条件 比如对输入参数的要求 @remarks 备注 @return 函数返回值描述 用在函数注释中 @retval 描述返回值意义 @see see also字段 @since 从哪个版本后开始有这个函数的 @test 被标记的代码会在Test列表中出现 @todo TODO 链接到所有TODO汇总的TODO列表 @version 版本号 @warning 函数使用中需要注意的地方

3 注释模板

为了保持注释的统一性和完整性，我们有必要定制一些常用的注释模板。下面给出个人常使用的几个注释模板，仅作为参考。

3.1 文件注释

//////////////////////////////////////////////////////////////////////////////////////////////////////@file///@author///@date///@brief///@details///////////////////////////////////////////////////////////////////////////////////////////////////

3.2 class、struct、enum、union等

///@brief///@details

3.3 函数

///@brief///@details///@param[in]///@param[out]///@return///@attention

3.4 单行注释

若要在在代码代码上方进行注释，则在代码上方添加“///注释内容”，若要在代码右方添加注释，则在代码右方添加“///<注释内容”，如下图所示：

4 相关网站

• Doxygen官网
• Doxygen详细介绍
• Doxygen使用教程
• Doxygen配置详解
• Doxygen特定命令