利用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 详细描述
