Doxygen是API文档生成工具，可以根据代码注释生成文档的工具。支持HTML、CHM、PDF等格式。主要支持C语言、Python语言，其它C语系语言也支持（如C++、Java、C#等）。
第1章 安装
在Linux下可以通过apt install doxygen安装命令行工具，然后用apt install doxygen-gui安装图形界面。对Linux用户来说，命令行工具可以通过doxygen命令运行，而图形界面可以通过doxywizard命令运行。
而Windows用户可以在这里下载，安装完毕后，直接双击就能运行图形界面。
1.1 基本使用
图形工具的基本使用如图1-1、图1-2所示，有非常多的配置选项，这里我们只填入必要的配置，其它配置都用默认值。
我们的工作目录如下：
.
├── out
└── src
└── math.h
其中math.h代码如下：
/*! \file math.h */
/*!
用于求一个角度的sin值，输入是字符串以便同时支持弧度制和角度制表示
\li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角
\li 角度制用d结尾，例如：360d表示一圈、90d表示直角
\li 输入也可以是数值，例如：输入3.14159大约表示180度
\param a 用弧度制或角度制表示都行，字符串必须用'\0'表示结束
\param[out] res 是输出参数，用于保存sin运算的结果
\return 错误码，0表示成功，其它表示失败
\todo 在xxx的情况下存在BUG，预计下一版本修复
*/
int sin(char *a, double *res);
Doxygen生成的HTML会放到out目录下，生成的HTML如图1-3所示。
1.2 保存配置
在1.1节中我们配置了一些选项，也成功生成了HTML文档。我们希望下次代码改动后能够继续沿用上次配置，那么我们可以把这些配置保存成Doxyfile文件，见图1-4。
1.3 命令行运行Doxygen
有了配置文件后我们完全可以通过命令行来生成API文档，假设配置文件名为Doxyfile，那么我们只需要执行doxygen /path/to/Doxyfile即可生成API文档。
通过命令行生成文档有许多好处，其中最主要的好处就是：能够集成到持续集成之类的自动化系统中。
第2章 为代码编写注释
2.1 什么样的注释会被Doxygen识别？
Doxygen能识别这几种风格的注释：
/**
* ... text ...
*/
/*!
* ... text ...
*/
///
/// ... text ...
///
//!
//!... text ...
//!
文件的开头必须有文件注释，否则该文件不会被识别：
/*! \file math.h */
2.2 注释怎么写
这个自己看官网例子体会吧。
第3章 为其它编程语言生成注释
Doxygen主要支持C语言，其它语法跟C差不多的语言（如：C++/C#/PHP/Java）也能够支持，我们称这类语言为「C语系语言」。而哪些跟C语法差异较大的语言叫做「非C语系语言」。
对于大多非C语系语言，Doxygen都是支持的，Doxygen原生支持这些语言：IDL、Java、Javascript、C#、C、C++、D、PHP、Objective-C、Python、Fortran、VHDL。
万一项目需要的语言（例如：Lua）Doxygen官方并不支持，那么只能自行编写「第三方语言扩展」来支持了。
3.1 Doxygen官方支持的语言
见图3-1，文件名符合FILE_PATTERNS都会被处理。其中包括了.c、.h、.py等等。
如果我们的扩展名并不在FILE_PATTERNS内，那么可以加上去。例如我们项目下的所有.ccc文件，其实是C语言代码（这很奇葩，举个例子而已）。那我们可以编辑Doxyfile配置文件满足这一需求，需要2个步骤。
(1) 在FILE_PATTERNS中添加*.ccc，如图3-2
(2) 在EXTENSION_MAPPING中添加映射规则ccc=C，如图3-3。语法是ext=language，其中language可以取的值有：IDL、Java、Javascript、C#、C、C++、D、PHP、Objective-C、Python、Fortran、VHDL。
3.2 Doxygen官方不支持的语言
以Lua语言为例，它的代码是长这样的：
-- \file lmath.h
--[[
用于求一个角度的sin值，输入是字符串以便同时支持弧度制和角度制表示
\li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角
\li 角度制用d结尾，例如：360d表示一圈、90d表示直角
\li 输入也可以是数值，例如：输入3.14159大约表示180度
\param a 字符串类型，表示角度，用弧度制或角度制表示都行
\return 返回sin运算的结果
\todo 在xxx的情况下存在BUG，预计下一版本修复
--]]
function sin(a)
return 1.123
end
可以看到Lua的语法既不像C也不像Python。本节以Lua为例，介绍如何为Doxygen编写Lua语言扩展。
好吧，大多数人没有这种需求，这里就不介绍了。
第4章 定制Doxygen的输出
4.1 定制页面样式
Doxygen输出的默认HTML比较难看，如图4-1。
如果嫌生成的HTML不好看，可以自定义HTML页面头部、尾部以及页面整体CSS样式表。
(1) 生成默认的风格的配置文件，敲这个命令：doxygen -w html header.html footer.html customdoxygen.css，可以生成header.html、footer.html、customdoxygen.css。
(2) 根据自己的需求修改这三个文件。
(3) 配置HTML_HEADER、HTML_FOOTER、HTML_STYLESHEET指向修改后的文件，如图4-2。
Doxygen默认的页面主色调大约是天蓝色的，可以通过HTML_COLORSTYLE_HUE、HTML_COLORSTYLE_SAT、HTML_COLORSTYLE_GAMMA修改主色调，这3个配置分别对应色相、饱和度、Gamma校正，见图4-3。如果不太懂色相、饱和度是啥意思，请自行百度「色彩模式」或参考Photoshop相关教程。
经过图4-3的修改，页面的主色调变为图4-4的样子。
4.2 导航栏
Doxygen中「导航栏」有两种展示方式：Treeview和Index，分别是竖向和横向的，如图4-5。
可以配置DISABLE_INDEX和GENERATE_TREEVIEW来控制是否显示它们，如图4-6。
4.3 自定义「导航栏」的目录结构
我们已经知道Doxygen中「导航栏」有Treeview和Index两种了。这节介绍如何定制导航栏的目录结构。这需要三个步骤。
(1) 执行doxygen -l，生成DoxygenLayout.xml文件
(2) 编辑DoxygenLayout.xml文件，修改其中的布局
(3) 修改LAYOUT_FILE配置，使其指向DoxygenLayout.xml文件，如图4-7
(4) 运行Doxygen
那么如何修改XML文件呢？默认的DoxygenLayout.xml代码如下：
XML对应了导航栏的目录树结构，我们通过该文件改变布局。标签的type属性取值除了上面列出的这些预定义值以外，还可以是type="user"或type="usergroup"，我们只能通过这两个type自定义布局，例如下面这段代码，生成的效果如图4-8：
4.4 完全自定义
如果Doxygen输出的界面实在不入你的法眼，4.1~4.3介绍的定制化功能也不能彻底满足你的需求。那么你需要根据Doxygen输出的XML数据自行生成界面了。
(1) 将GENERATE_XML配置为YES
(2) 去输出目录寻找生成的XML文件，XML文件包括了函数信息、注释信息等
(3) 自己写程序读取XML文件，并生成漂亮的文档
转载链接