概述
Doxygen是一个从程序源码生成文档的工具，主要用于C/C++源码，也支持其他如PHP, Java, Python等代码。具体来说，Doxygen服务于以下两个目的：
- 从带注释标记的源码中生成文档，一般是HTML格式，当然也支持其他可离线查看的格式。生成的文档是直接从源码的注释中提取的，这样程序员就可以边写代码边写注释，同时完成编码和文档工作。
- 从源码中提取代码结构，生成整个工程的框架文档，并且提供可视化的展示，比如UML类图，继承图，头文件包含等。
除了从源码中生成文档外，Doxygen也支持直接创建正常的文档，这点Doxygen和Gitbook类似，Doxygen的在线文档就是用Doxygen编写的。
参考链接：
https://www.doxygen.nl/index.html
https://www.cnblogs.com/silencehuan/p/11169084.html
安装
参考https://www.doxygen.nl/manual/install.html，在Ubuntu系统下，直接 apt install doxygen 即可，安装完成之后，Doxygen的执行程序为doxygen 。
| 代码块 |
|---|
# doxygen --version 1.8.13 |
使用
参考https://www.doxygen.nl/manual/starting.html, doxygen的使用包括3个步骤：
- 生成模板配置文件
- 调整模板配置文件中的选项
- 根据配置生成文档
使用 doxygen -g <config-file> 命令生成模板配置文件，<config-file>为指定的配置文件名，如果不提供文件名，默认使用Doxyfile作为配置文件名。如果当前目录已经存在同名的文件，那doxygen会将当前目录的文件重命名成<config-file>.bak，再创建配置文件。
生成的配置文件包含了一系列的键值对，格式为TAGNAME = VALUE的形式， # 开头的为注释，其中比较重要的注释项有以下几项：
| 代码块 |
|---|
# 指定编码为utf-8 DOXYFILE_ENCODING = UTF-8 # 项目名 PROJECT_NAME = "sylar" # 项目描述 PROJECT_BRIEF = "C++高性能服务器框架" # 语言(中文) OUTPUT_LANGUAGE = Chinese # 不生成LATEX文档 GENERATE_LATEX = NO |
下一步是生成文档，使用 doxygen <config-file> 命令即可，生成的HTML文档位于当前目录的html文件夹，入口是index.html。
注释规范
使用Doxygen重点就是根据Doxygen指定的格式来写注释，只有符合Doxygen格式要求的注释才会体现在生成的文档中，这里参考官方文档，把一些常用的注释格式过一遍。另外，如果你使用的是VS Code编辑器，那么可以通过安装Doxygen Documentation Generator这个插件来自动补全Doxygen注释，非常方便。
Doxygen的文档注释一般位于要注释对象的前面，如果是文件的注释，则一般在文件开头。注释以注释块或单行注释的形式体现，其中注释块一般使用下面的格式：
| 代码块 |
|---|
/**
* ...
*/ |
单行注释一般格式为：
| 代码块 |
|---|
/// ... |
以上两种格式的注释可被Doxygen识别并生成到文档中，除此外，Doxygen还支持其他格式的注释块，这点参考官方文档 Special comment blocks。
在注释块里可以加入命令，以实现更详细的标注，比如提示函数功能，参数，返回值等，以下是一个示例：
| 代码块 |
|---|
/**
* @brief 获取当前栈信息的字符串
* @param[in] size 栈的最大层数
* @param[in] skip 跳过栈顶的层数
* @param[in] prefix 栈信息前输出的内容
* @return 栈回溯字符串描述
*/
std::string BacktraceToString(int size = 64, int skip = 2, const std::string& prefix = ""); |
该注释块会生成以下的文档信息：
Doxygen支持众多注释命令，所有的命令都以\或@开头，下面是一些常用的命令，另外，这里有一份完整的命令列表。
| 命令 | 功能 |
|---|---|
| \author { list of authors } | 描述作者 |
| \version { version number } | 描述版本 |
| \date { date description } | 描述日期 |
| \brief { brief description } | 概要注释 |
| \details { detailed description } | 详细注释，位于概要注释下面，另起一行 |
| \param['dir'] <parameter-name> { parameter description } | 参数说明，可附带参数方向("[in]", "[out]" "[in,out]") |
| \return { description of the return value } | 描述返回含义 |
| \retval <return value> { description } | 描述返回值的含义，可以有多个\retval |
| \note | 描述注意事项 |
| \pre | 描述前置条件 |
| \post | 描述后置条件 |
| \deprecated | 描述已作废函数 |
\code \endcode | 在注释中写一段代码 |
| \bug | 描述一个bug |
| \warning | 描述一个警告 |
| \copyright | 声明版权 |
Doxygen注释实例
项目注释
| 代码块 |
|---|
/**@mainpage sylar C++高性能服务器框架
*******************************************************************************
* <table>
* <tr><th>Project <td>sylar
* <tr><th>Author <td>sylar
* <tr><th>Source <td>https://github.com/sylar-yin/sylar
* </table>
* @section 项目描述
* C++高性能分布式服务器框架,webserver,websocket server,自定义tcp_server（包含日志模块，配置模块，线程模块，协程模块，协程调度模块，io协程调度模块，hook模块，socket模块，bytearray序列化，http模块，TcpServer模块，Websocket模块，Https模块等, Smtp邮件模块, MySQL, SQLite3, ORM,Redis,Zookeeper)
*
* @section 日志模块
*支持流式日志风格写日志和格式化风格写日志，支持日志格式自定义，日志级别，多日志分离等等功能 流式日志使用：SYLAR_LOG_INFO(g_logger) << "this is a log"; 格式化日志使用：SYLAR_LOG_FMT_INFO(g_logger, "%s", "this is a log"); 支持时间,线程id,线程名称,日志级别,日志名称,文件名,行号等内容的自由配置
*
* @section 配置模块
*采用约定由于配置的思想。定义即可使用。不需要单独去解析。支持变更通知功能。使用YAML文件做为配置内容。支持级别格式的数据类型，支持STL容器(vector,list,set,map等等),支持自定义类型的支持（需要实现序列化和反序列化方法)使用方式如下：
@code
static sylar::ConfigVar<int>::ptr g_tcp_connect_timeout =
sylar::Config::Lookup("tcp.connect.timeout", 5000, "tcp connect timeout");
@endcode
*定义了一个tcp连接超时参数，可以直接使用 g_tcp_connect_timeout->getValue() 获取参数的值，当配置修改重新加载，该值自动更新 上述配置格式如下：
@code
tcp:
connect:
timeout: 10000
@endcode
*
**********************************************************************************
*/ |
渲染效果：
类注释
| 代码块 |
|---|
/*!
* \brief Pretty nice class.
* \details This class is used to demonstrate a number of section commands.
* \author John Doe
* \author Jan Doe
* \version 4.1a
* \date 1990-2011
* \pre First initialize the system.
* \bug Not all memory is freed when deleting an object of this class.
* \warning Improper use can crash your application
* \copyright GNU Public License.
*/
class SomeNiceClass {}; |
渲染效果：
VSCode Doxygen Documentation Generator
| 目录 |
|---|