Doxygen 入门

Doxygen 可以通过解析代码中的特殊注释来生成详细的文档。以下是完整的操作流程：

1. 安装 Doxygen

Windows

bash

# 使用 Chocolatey
choco install doxygen# 或从官网下载安装包
# https://www.doxygen.nl/download.html

macOS

bash

brew install doxygen

Linux

bash

# Ubuntu/Debian
sudo apt-get install doxygen# CentOS/RHEL
sudo yum install doxygen

2. 在代码中添加 Doxygen 注释

C/C++ 示例

cpp

/*** @brief 计算两个数的和* * @param a 第一个加数* @param b 第二个加数* @return int 两个数的和*/
int add(int a, int b) {return a + b;
}/*** @class Calculator* @brief 简单的计算器类*/
class Calculator {
public:/*** @brief 构造函数* @param initial_value 初始值*/Calculator(double initial_value = 0);/*** @brief 乘法运算* @param factor 乘数* @return Calculator& 返回自身的引用，支持链式调用*/Calculator& multiply(double factor);private:double value_;  ///< 当前的计算结果
};

Python 示例

python

class DataProcessor:"""@brief 数据处理类@details 这个类提供了多种数据处理的工具方法，包括数据清洗、转换和分析功能。"""def __init__(self, config_file):"""@brief 构造函数@param config_file 配置文件路径@exception FileNotFoundError 当配置文件不存在时抛出"""self.config = self._load_config(config_file)def process_data(self, data):"""@brief 处理输入数据@param data 要处理的数据，可以是列表或字典@return dict 处理后的数据@warning 输入数据必须包含必要的字段"""# 处理逻辑return processed_data

Java 示例

java

/*** @brief 用户管理类* @author 开发者姓名* @version 1.0*/
public class UserManager {private List<User> users;/*** @brief 根据ID查找用户* @param userId 用户ID* @return User 找到的用户对象，未找到返回null* @see User*/public User findUserById(int userId) {return users.stream().filter(user -> user.getId() == userId).findFirst().orElse(null);}
}

3. 配置 Doxygen

生成配置文件

bash

# 生成默认配置文件 Doxyfile
doxygen -g

常用配置选项

编辑 Doxyfile 文件：

text

# 项目相关配置
PROJECT_NAME           = "我的项目"
PROJECT_BRIEF          = "项目简要描述"
PROJECT_LOGO           = ./logo.png# 输入文件配置
INPUT                  = ./src
RECURSIVE              = YES
FILE_PATTERNS          = *.cpp *.h *.java *.py# 输出格式
GENERATE_HTML          = YES
GENERATE_LATEX         = NO# 提取信息配置
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES# 源码浏览
SOURCE_BROWSER         = YES
INLINE_SOURCES         = YES# 图表生成
HAVE_DOT               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES

4. 生成文档

命令行方式

bash

# 使用配置文件生成文档
doxygen Doxyfile# 或者直接指定配置
doxygen -g myconfig && doxygen myconfig

使用 GUI 工具（Doxywizard）

bash

# 启动 GUI 配置工具
doxywizard

5. 常用 Doxygen 命令

基本命令

text

@brief    简要描述
@details  详细描述
@param    参数说明
@return   返回值说明
@see      参考链接
@note     注意事项
@warning  警告信息
@deprecated 已弃用说明

分组命令

cpp

/*** @defgroup network 网络模块* @brief 处理网络通信的相关功能*//*** @ingroup network* @brief 建立网络连接*/
void connect();/*** @addtogroup network* @{*/
void sendData();
void receiveData();
/** @} */

6. 查看生成的文档

生成完成后，在输出目录（通常是 html/ 文件夹）中打开 index.html 即可浏览完整的 API 文档。

7. 高级功能

包含示例代码

cpp

/*** @brief 使用示例* @code{.cpp}* Calculator calc;* calc.multiply(5).multiply(2);* @endcode*/

数学公式

cpp

/*** @brief 计算圆的面积* * 公式：\f$ A = \pi r^2 \f$* * 或者行内公式：\f$\pi\f$ 是圆周率*/

自定义页面

创建 custom_docs.md：

markdown

/*! @mainpage 项目主页面** @section intro_sec 介绍* 这里是项目的详细介绍...** @section install_sec 安装* 安装说明...*/

在配置文件中添加：

text

INPUT = ./src custom_docs.md

这样你就可以生成专业、完整的代码文档了。记得保持注释的及时更新，确保文档与代码同步。