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所示，有非常多的配置选项，这里我们只填入必要的配置，其它配置都用默认值。

图1-1 doxywizard使用步骤

图1-2 doxywizard使用步骤

我们的工作目录如下：

.
├── 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-3 HTML界面

1.2 保存配置

在1.1节中我们配置了一些选项，也成功生成了HTML文档。我们希望下次代码改动后能够继续沿用上次配置，那么我们可以把这些配置保存成Doxyfile文件，见图1-4。

图1-4 保存Doxyfile配置文件

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等等。

图3-1

如果我们的扩展名并不在FILE_PATTERNS内，那么可以加上去。例如我们项目下的所有.ccc文件，其实是C语言代码（这很奇葩，举个例子而已）。那我们可以编辑Doxyfile配置文件满足这一需求，需要2个步骤。

(1) 在FILE_PATTERNS中添加*.ccc，如图3-2

图3-2

图3-3

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。

图4-1 默认的HTML样式

如果嫌生成的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。

图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。

图4-5

图4-6

4.3 自定义「导航栏」的目录结构

我们已经知道Doxygen中「导航栏」有Treeview和Index两种了。这节介绍如何定制导航栏的目录结构。这需要三个步骤。
(1) 执行doxygen -l，生成DoxygenLayout.xml文件
(2) 编辑DoxygenLayout.xml文件，修改其中的布局
(3) 修改LAYOUT_FILE配置，使其指向DoxygenLayout.xml文件，如图4-7
(4) 运行Doxygen

图4-7

那么如何修改XML文件呢？默认的DoxygenLayout.xml代码如下：

<doxygenlayout version="1.0">
  <navindex>
    <tab type="mainpage" visible="yes" title=""/>
    <tab type="pages" visible="yes" title="" intro=""/>
    <tab type="modules" visible="yes" title="" intro=""/>
    <tab type="namespaces" visible="yes" title="">
      <tab type="namespacelist" visible="yes" title="" intro=""/>
      <tab type="namespacemembers" visible="yes" title="" intro=""/>
    </tab>
    <tab type="classes" visible="yes" title="">
      <tab type="classlist" visible="yes" title="" intro=""/>
      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
      <tab type="hierarchy" visible="yes" title="" intro=""/>
      <tab type="classmembers" visible="yes" title="" intro=""/>
    </tab>
    <tab type="files" visible="yes" title="">
      <tab type="filelist" visible="yes" title="" intro=""/>
      <tab type="globals" visible="yes" title="" intro=""/>
    </tab>
    <tab type="examples" visible="yes" title="" intro=""/>  
  </navindex>
</doxygenlayout>

XML对应了导航栏的目录树结构，我们通过该文件改变布局。标签的type属性取值除了上面列出的这些预定义值以外，还可以是type="user"或type="usergroup"，我们只能通过这两个type自定义布局，例如下面这段代码，生成的效果如图4-8：

<doxygenlayout version="1.0">
  <navindex>
    <tab type="usergroup" visible="yes" title="友情链接（演示如何外链）">
      <tab type="user" visible="yes" title="百度" url="http://www.baidu.com" />
      <tab type="user" visible="yes" title="163" url="http://www.163.com" />
    </tab>
    <tab type="usergroup" visible="yes" title="数学库（演示如何链接文件）">
      <tab type="user" visible="yes" url="@ref math.h" title="math" />
      <tab type="user" visible="yes" url="@ref math2.h" title="math2" />
    </tab>
    <tab type="usergroup" visible="yes" title="三角函数（演示链接函数、结构体）">
      <tab type="user" visible="yes" url="@ref sin" title="sin" />
      <tab type="user" visible="yes" url="@ref sin2" title="sin2" />
    </tab>
  </navindex>
</doxygenlayout>

图4-8

4.4 完全自定义

如果Doxygen输出的界面实在不入你的法眼，4.1~4.3介绍的定制化功能也不能彻底满足你的需求。那么你需要根据Doxygen输出的XML数据自行生成界面了。
(1) 将GENERATE_XML配置为YES
(2) 去输出目录寻找生成的XML文件，XML文件包括了函数信息、注释信息等
(3) 自己写程序读取XML文件，并生成漂亮的文档

第5章 Markdown支持

Markdown在工业界是非常流行的文档格式，文件名以.md结尾，其简洁直观的语法深受广大程序员喜爱。对Markdown本身的介绍超出了本文范围，本章介绍Doxygen对Markdown的支持。

5.1 为.md文件生成文档

5.2 在代码注释中使用Markdown语法

第6章 搜索功能