利用Doxygen为C程序生成注释文档

一、Doxygen工具的安装

利用Doxygen工具生成API帮助文档需要下载安装以下三个软件：

(1)Doxygen：可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的

LATEX、RTF参考手册。本文中所使用的版本为：Doxygen-1.8.18.

(2)Htmlhelp：该软件可以帮助您建立 HTML 格式的 HELP 文件。用于创建.chm文件，可

以从微软官方网站下载。

(3)Graphviz：是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图

形，与Doxygen配合使用，用于提取函数之间，头文件之间的调用关系本文

中所使用的版本为:graphviz-2.38。

二、Doxygen工具的配置

1.打开Doxygen软件如下图所示：进行工程设置

2.模式设置如下图所示

3.设置输出格式如下图所示

4.设置函数调用配置如下图所示

5.输出文档字符集配置

6.Build页面，这个页面比较关键：

(1)EXTRACT_ALL：输出所有的函数，但是private和static函数不属于其管制。

(2)EXTRACT_PRIVATE：输出private函数。

(3)EXTRACT_STATIC：输出static函数。

(4)SHOW_INCLUDE_FILES ：是否显示包含文件，如果开启，帮助中会专门生成一个页面，

里面包含所有包含文件的列表。

(4)INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词

来标明。

(5)SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排

序，否则按照解释的顺序显示。

(6)GENERATE_TODOLIST ：是否生成TODOLIST页面，如果开启，那么包含在@todo注解

中的内容将会单独生成并显示在一个页面中，其他的GENERATE选项同。

(7)SHOW_USED_FILES ：是否在函数或类等的帮助中，最下面显示函数或类的来源文件。

(8)SHOW_FILES ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

7.Input选项设置

对源文件的编码进行设置，设置的编码格式应与源文件的编码格式相同，如果源文件不是

UTF-8编码需要对源文件进行转换一下，否则生成的帮助文档会出现中文乱码现象。

8.Source Browser设置

9.chm配置

10.配置Grapviz

11.运行Doxygen

三、Doxygen注释格式

1.文件注释

文件注释是源代码文件进行注释，包含源文件和头文件，文件注释位于文件的开头。主要包含以下内容：文件名(@file )作者(@author)版本(@version)日期(@date)和简要说明(@brief)，还可以包含：详细描述(@details)版权(@copyright)注意(@attention)等。

2.函数注释

函数注释是对本函数进行说明，位于函数定义上方。函数注释主要包含以下内容：简要说明(@brief)参数说明(@param)函数返回值情况(@return)函数返回值类型(@retval)

3.宏定义类型的注释

4.结构体和枚举类型定义

结构体注释

枚举类型注释

5.项目注释

主要对本项目进行简单描述，通常位于main.c主函数文件头部。注释为/**@mainpage  */。主要包含项目名称、功能描述、项目详细描述、用法描述和软件更新记录等。

四、Doxygen常用的注释命令

1.@author       作者信息

2.@brief        简要说明概要信息

3.@bug          被标记的代码会在Bug列表中出现

4.@class        对类进行标注

5.@data         日期

6.@file         文件名

7.@param        主要用于函数说明，对参数进行说明

8.@return       描述函数的返回值情况

9.@retval       描述函数返回值类型

10.@note        注解

11.@attention   注意

12.@name        分组名

13.@warning     警告信息

14.@enum        引入了某个枚举

15.@var         引入了某个变量

16.@exception   可能产生的异常描述

17.@todo        对将要做的事情进行注释

18.@see         一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接

19.@relates     通常用做把非成员函数的注释文档包含在类的说明文档中

20.@since       从哪个版本后开始有这个函数的

21.@code        在注释中开始说明一段代码，直到@endcode结束

22.@endcode     在注释中代码段的结束

23.@remarks     备注

24.@pre         说明代码项的前提条件

25.@post        说明代码项之后的使用条件

26.@deprecated  这个函数可能会在将来的版本中取消

27.@defgroup    模块名

   @{           模块开始

   @}           模块结束

28.@version     版本号

29.@par         开始一个段落

30.@detail      详细描述