当前位置：首页 > news >正文

工具应用—Doxygen文档工具的应用

news 2026/4/21 6:54:47

一、文档工具和Doxygen

在实际的开发中，写文档是最让开发者抵触的。对于大多数的开发者来说，写代码比写文档要感觉爽很多。但在实际的开发过程中，文档又是必不可少的。且不说给协作者提供相关的接口文档，公司但凡正规一些要过一些标准或者拿什么资格，都是需要提供大量的文档的。这些文档中，涉及到具体的开发者的说明文档，不同的语言又有不同的文档工具推荐，比如Javadoc、Doxygen等。还有的开发者可能用过一些接口管理文档如OpenAPI‌和ShowDoc等。这些文档形形色色，应用非常广泛。但对于C++来说，Doxygen是一个不错的文档工具。
Doxygen作为一个强大的开源工具，它能从源代码中依照规定格式的注释里，自动提取信息并生成专业的文档（比如常见的HTML、PDF等）。利用Doxygen，可以让开发者从厌烦的文档抽取编写工作中跳出来，只专注于代码开发本身，实现所谓的良好的代码注释即可。

二、下载和安装

Doxygen可以安装在Windows、Linux和Mac等主流的开发平台上。下面对其在Ubuntu22.04中的安装进行简单的说明，其它平台的安装也非常简单。

去官网下载安装包
打开官网“https://www.doxygen.nl/download.html”，下载相关的压缩包，解压缩即可使用。当然为了方便，可以将其注册到环境变量或直接拷贝到本地可执行目录下（/usr/local/bin）
使用apt安装
使用命令“sudo apt install doxygen”进行安装，安装成功即可使用
安装相关工具
为了能够更好的使用Doxygen，可以安装Graphviz（用于可视化）和LaTeX（用于生成高质量的PDF），安装方法为“sudo apt install graphviz”和“sudo apt install texlive-full”

基本上按照上述的流程安装后就可以使用Doxygen。

三、环境配置和整体操作流程

在使用Doxygen进行文档处理前，需要进行一些相关的环境设置，主要包括：

生成工程配置文件
打开命令窗口（终端），进入工程的根目录，运行“doxygen -g”，自动生成一个名称为Doxyfile的默认的配置文件。这个文件用来进行文档相关的编辑实现。
编辑工程配置文件
打开上面生成的Doxyfile文件，修改其中的几个关键选项：
PROJECT_NAME：项目名称
PROJECT_NUMBER：版本号
INPUT：指定源代码的目录
RECURSIVE：设为YES，表示Doxygen递归处理INPUT目录下的子文件夹
OUTPUT_DIRECTORY：指定生成文档的输出目录
编译代码中的注释
即在代码中使用相关规则来编写注释
利用Doxygen生成文档
在完成上述操作后，在命令行中输入“doxygen”即可读取Doxyfile中的配置并生成文档
Reivew文档并反馈修改
在指定的输出目录下查看生成的相关文档，并根据实际要求结果加以完善和修改并再次执行生成
交付使用
Review并反馈迭代的最终文档就可以交付给相关方使用了

Doxygen文档工具，应用起来还是比较方便的，但这就需要开发者把注释写得清晰准确，不能想当然的编写注释或者干脆不写注释。

四、工程应用

Doxygen支持多种语言，所以也支持多种的注释风格。常见的一般就是Javadoc和Qt风格以及简单的C++风格。可以理解为如何启动注释与Doxygen交互的接口。下面简要说明一下：

JavaDoc风格
这种风格一般和C语言的注释风格类似，即“/** * @brief 函数说明 */”
Qt风格
这种风格一般是以符号“！”开头，即“/*! * @brief 函数说明 */”
简单的C++风格
这种风格一般以“///”或“//！”开始，即“/// @brief 函数说明或 //! @brief 函数说明”

Doxygen中的注释块中，一般是以“@”或“\”开头来标记特定的内容。Doxygen将命令分成了几类：

文件结构和描述相关命令
函数和逻辑命令
代码显示和布局命令
状态与维护命令

常用的注释命令如：

@brief: 基础的命令，用于描述一个函数、类或变量的基础说明
@param: 对函数参数和相关内容进行说明
@return: 函数返回值的描述
@file: 代码源文件的注释说明，一般用于文件头部
@see: 指示对其他部分引用的相关“参见”

其它还有很多，如基础的@author（作者），@date(日期)，@note(注解)，@post,@pre(前后置条件)等等。这个没有什么难度，看看文档说明就会了。下面看一个简单的例子：

/** * @brief 计算整数和 * * 通过一个加法函数，来举例说明Doxygen命令 * * @param[in] a 第一个整数 * @param[in] b 第二个整数 * @return 返回a和b和 * * @note 不支持浮点数运算 * @warning 有可能整数溢出 * * @code * int ret = add(1, 6); * // ret 将是7 * @endcode * * @see subtract() * @author 开发者 * @version 0.1 */intadd(inta,intb){returna+b;}

五、问题和说明

使用Doxygen在生成中文文档时，如果出现乱码，请将源代码文件和配置文件修改为使用UTF-8编码并将Doxyfile中的 OUTPUT_LANGUAGE设置为Chinese。一般情况下都会解决乱码的问题。
另外，在注释进行完善和修改后，只需保存后在命令行中重新运行doxygen即可自动进行更新。
在Doxygen可以通过简单的@class和相关的继承命令（如@extends）等来实现类等的关系图。如果启用了GRAPHICAL_HIERARCHY和HAVE_DOT，则可以使用前面安装的Graphviz来生成类图。同样如查在配置中使用了UML_LOOK和 HAVE_DOT，则也可以生成UML风格的协作图。可见，Doxygen工具的功能还是非常强大的，如果想使用好这个工具，还需要开发者仔细的学习相关的说明文档（在前面的下载地址中有相关说明文档的下载）。
本文对Doxygen工具的说明是一个极简的入门说明，目的很简单就是让开发者能够迅速的明白Doxygen的作用和简单应用，从而可以有步骤的在实践中引入相关的文档开发，节省开发时间和编写文档的烦恼。