Doxygen生成API接口说明文档配置

Doxygen是API文档生成工具，可以根据代码注释生成文档的工具。支持HTML、CHM、PDF等格式。主要支持C语言、Python语言，其它C语系语言也支持（如C++、Java、C#等）。
本文档描述的内容包括：Doxygen工具下载安装、基本使用和配置、哪些注释支持Doxygen识别转换、Doxygen工具生成的LaTex文件转PDF的方法、Doxygen工具生成chm的方法等。

1 下载安装软件

Doxygen支持LINUX、Windows、Mac OS
Doxygen下载路径：https://www.doxygen.nl/download.html

Doxygen默认生成HTML文件。

生成PDF文件需要安装的依赖软件：
CTex：https://mirrors.tuna.tsinghua.edu.cn/ctex/legacy/2.9/
TexWorks：https://sourceforge.net/projects/texworks.mirror/
MiTex：https://miktex.org/download

生成chm文件需要安装的依赖软件：
HTML Help Workshop微软官方用于生成HTML格式的help文件
Graphviz一种dot工具可以用来渲染出效果更好的图表

2 Doxygen使用方法

2.1 向导：

2.2 高级配置：

所有高级设置（包括编码设置）都在“Expert”标签，重要的设置项如下：
2.2.1 project

2.2.2 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
  ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

2.2.3 input

2.2.4 Source Browser

2.2.5 HTML

1） 生成chm的名称
2） HTML Help Workshop hhp.exe的路径
3） 这里设置Doxygen生成的CHM索引文件的编码，以前是不能设置的，默认为UTF-8，而微软的编译器不能识别UTF-8编码的索引文件，所以最终造成左边目录导航栏乱码。我们设置它为GBK，这样Doxygen将为我们生成GBK编码的索引文件（.hhc、.hhk、.hhp）
2.2.6 Dot

2.3 Run点击运行即可生成
Chm文件：

Xml文件：

3 TeXworks将tex文件转成pdf

1） 选择需要转换的Tex文件
2） 点击开始转换

4． Doxygen注释语法
4.1 注释格式
块注释建议统一使用

/**

……

*/

行注释建议统一使用

///< …

/** …… */

4.2 Doxygen常用注释命令
@exception {exception description} 对一个异常对象进行注释。
@warning {warning message } 一些需要注意的事情
@todo { things to be done } 对将要做的事情进行注释，链接到所有TODO 汇总的TODO 列表
@bug 缺陷，链接到所有缺陷汇总的缺陷列表
@see {comment with reference to other items } 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。
@relates 通常用做把非成员函数的注释文档包含在类的说明文档中。
@since {text} 通常用来说明从什么版本、时间写此部分代码。
@deprecated
@pre { description of the precondition } 用来说明代码项的前提条件。
@post { description of the postcondition } 用来说明代码项之后的使用条件。
@code 在注释中开始说明一段代码，直到@endcode命令。
@endcode 注释中代码段的结束。
@code … @endcode 包含一段代码
@addtogroup 添加到一个组。
@brief 概要信息
@deprecated 已废弃函数
@details 详细描述
@note 开始一个段落，用来描述一些注意事项
@par 开始一个段落，段落名称描述由你自己指定
@param 标记一个参数的意义
@fn 函数说明
@ingroup 加入到一个组
@return 描述返回意义
@retval 描述返回值意义
@include 包含文件
@var、@enum、@struct、@class 对变量、枚举、结构体、类等进行标注
3.3 Doxygen注释示例
4.3.1 文件注释

3.3.2 函数注释

4.3.3 枚举、结构体等注释