概述

Doxygen是一个从程序源码生成文档的工具，主要用于C/C++源码，也支持其他如PHP, Java, Python等代码。具体来说，Doxygen服务于以下两个目的：

  1. 从带注释标记的源码中生成文档，一般是HTML格式，当然也支持其他可离线查看的格式。生成的文档是直接从源码的注释中提取的，这样程序员就可以边写代码边写注释，同时完成编码和文档工作。
  2. 从源码中提取代码结构，生成整个工程的框架文档，并且提供可视化的展示，比如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个步骤：

  1. 生成模板配置文件
  2. 调整模板配置文件中的选项
  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。

注释规范

VSCode Doxygen Documentation Generator