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

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