参考：https://blog.csdn.net/Candy1232009/article/details/80786179
Doxygen的使用、配置及实例
1.简介
- Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，可以从一套归档源文件开始，生成API文档的工具。
- Doxygen是一个程序的文档产生工具，可以将程序中的注释转换成说明文档或者说是API参考手册，从而减少程序员整理文档的时间。当然这里程序中的注释需要遵循一定的规则书写，才能让Doxygen识别和转化。
总结：Doxygen 就是在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文档了。
目前Doxygen可处理的程序语言包含C/C++、Java、Objective-C、IDL等，可产生出来的文档格式有HTML、XML、LaTeX、RTF等，此外还可衍生出不少其它格式，如HTML可以打包成CHM格式，而LaTeX可以通过一些工具产生出PS或是PDF文档等。
2.安装
Doxygen官网分别提供Linux和Windows下的源代码编译安装包和二进制安装包。二进制安装包：
2.1 Linux平台下，下载完成后，输入：
./configure
Make install
可执行的二进制文件将被安装到/bin 目录下。默认路径为/usr/local，可使用配置脚本的–prefix选项来修改安装的默认路径。
2.2 Linux 平台可用 apt安装：
sudo apt-get install doxygen-gui
sudo apt-get install graphviz
另外，也可以安装一些辅助工具来生成更加漂亮的文档。如可以使用graphviz中的dot工具来渲染出效果更好的图表，因此，如果需要在注释中加入图表可以下载并安装GraphViz(http://www.graphviz.org/Download..php)； Windows平台下还可以安装 Windows Help Workshop来生成 CHM 格式的文档等等
2.3 运行
终点输入
doxywizard
3.代码的注释风格
并非所有程序代码中的注释都会被Doxygen所处理，而是必须依照正确的格式撰写。原则上，Doxygen仅处理与程序结构相关的注释，如Function，Class等。对于Function内部的注释则不做处理。Doxygen可处理下面几种类型的注释。
3.1 JavaDoc类型：
/**
* ... 批注 ...
*/
3.2 qt 类型
/*!
* ... 批注 ...
*/
3.3 单行型式的批注：
/// ... 批注 ...
或
//! ... 批注 ...
3.4 说明
此外，由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说，任何一个批注都是在说明其后的程序代码。如果要批注前面的程式码则需用下面格式的批注符号。
/*!< ... 批注 ... */
/**< ... 批注 ... */
//!< ... 批注 ...
///< ... 批注 ...
3.5 案例
/**
* 我的自订类别说明 ...
*/
class MyClass {
public:
int member1 ; ///< 第一个member说明 ...
int member2: ///< 第二个member说明 ...
int member_function(int a, int b);
};
/**
* 自订类别的member_funtion说明 ...
*
* @param a 参数a的说明
* @param b 参数b的说明
*
* @return 传回a+b。
*/
int MyClass::member_function( int a, int b )
{
return a+b ;
}
首先，我们先说明在Doxygen 中对于类别或是函数批注的一个特定格式
/**
* class或function的简易说明...
*
* class或function的详细说明...
* ...
*/
- 在Doxygen 处理一个class 或是function注解时，会先判断第一行为简易说明。
- 这个简易说明将一直到空一行的出现。或是遇到第一个"." 为止。之后的批注将会被视为详细说明。
- 两者的差异在于Doxygen 在某些地方只会显示简易说明，而不显示详细说明。如：class 或function的列表。
另一种比较清楚的方式是指定@brief的指令。这将会明确的告诉Doxygen，何者是简易说明。例如：
/**
* @brief class或function的简易说明...
*
* class或function的详细说明...
* ...
* /
除了这个class 及function外，Doxygen 也可针对档案做说明，条件是该批注需置于档案的前面。主要也是利用一些指令，通常这部分注解都会放在档案的开始地方。如：
/*! \file myfile.h
\brief 档案简易说明
详细说明.
\author 作者信息
*/
档案批注约略格式如上，请别被"" 所搞混。其实，""
与"@" 都是一样的，都是告诉Doxygen 后面是一个指令。两种在
Doxygen 都可使用。笔者自己比较偏好使用"@"。
接着我们来针对一些常用的指令做说明：
| 参数 | 说明 |
|---|---|
| @file | 档案的批注说明 |
| @author | 作者的信息 |
| @brief | 用于class 或function的批注中，后面为class或function的简易说明 |
| @param | 格式为2 arg_name 参数说明 |
| @return | 后面接函数传回值的说明。用于function的注释说明，说明函数的返回值 |
| @retval | 格式为@retval value传回值说明，主要用于函数说明中，说明特定传回值的意义 ，所以后面要先接一个传回值。然后在放该传回值的说明 |
/**
* @file example.c
* @brief 文件简要说明
*
* 详细说明
*
* @author 作者信息
*/
#define EXAMPLE_OK 0 /**< 注释EXAMPLE_OK*/
/**
* @brief 结构体简要说明
*/
typedef struct
{
int member1 ; /**< 注释member1*/
...
}STRUCT_T;
/**
* Function1() 的简易说明...
* Function1()的详细说明...
* @param a 用来相加的参数
* @param b 用来相加的参数
* @return 传回两个参数相加的结果
*/
int Function1(int a, char b)
{
return (a+b);
}
/**
* Function2()的简易说明
*
* @param c 传进的字符指针
* @retval NULL 空字符串
* @retval !NULL 非空字符串
*/
char *Function2(char *c)
{
return c;
}
4.配置
Doxygen产生文档可以分为三个步骤，
- 在程序代码中加上符合Doxygen所定义注释格式；
- 使用Doxywizard进行配置；
- 使用Doxygen来产生注释文档。现在我们假定电脑中已经安装了Doxygen并且代码中的注释已经符合Doxygen规范，下面我们来通过设置配置来生成注释文档。
1.Doxygen的主界面
按照界面提示，填写Doxygen的工作目录、项目名称、源文件目录、生成文档的存放目录，同时递归搜索源文件目录的选项也要勾选。其中，Doxygen的工作目录是指用来存放配置文件的目录
2.选择Wizard标签下的Output项
3.选择Expert标签下的Project项
其中，编码格式，UTF-8是首选。如果需要显示中文则选择GB2313。OPTIMIZE_OUTPUT_FOR_C 这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果是纯C代码，建议选择。SUBGROUPING这个选项选择后，输出将会按类型分组
4.选择Expert标签下的Build项
这个页面是生成帮助信息中比较关键的配置页面：
- EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。
- EXTRACT_PRIVATE 表示：输出private函数。
- EXTRACT_STATIC 表示：输出static函数。同时还有几个EXTRACT，相应查看文档即可
- HIDE_UNDOC_MEMBERS表示：那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。
- INTERNAL_DOCS 主要指：是否输出注解中的@internal部分。如果没有被启动，那么注解中所有的@internal部分都将在目标帮助中不可见。
- CASE_SENSE_NAMES 表示：是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。对于C/C++这种字母相关的语言来说，建议永远不要开启。
- HIDE_SCOPE_NAMES 表示：域隐藏，建议永远不要开启。
- SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列表。
- INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。
- SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显示。
- GENERATE_TODOLIST ：是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显示在一个页面中，其他的GENERATE选项同。
- SHOW_USED_FILES ：是否在函数或类等的帮助中，最下面显示函数或类的来源文件。
- SHOW_FILES ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。
5.选择Expert标签下的Input项
其中输入的源文件的编码，要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。
6.选择Expert标签下的HTML项
为了解决DoxyGen生成的文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。
7.选择 Run 标签
点Run doxygen按钮，Doxygen 就会从源代码中抓取符合规范的注释生成定制的格式的文档。