Doxygen 使用指南

news2025/2/12 21:27:29

Doxygen 是一个文档生成工具，可以从源代码中的注释生成高质量的文档，支持多种编程语言（如 C/C++、Python、Java 等）。以下是 Doxygen 的基本使用方法。

1. 安装 Doxygen

1.1 下载 Doxygen

访问 Doxygen 官网。
根据操作系统选择合适的版本并安装：
- Windows: 提供可执行安装包。
- Linux: 使用包管理器安装，例如 apt install doxygen。
- macOS: 使用 Homebrew 安装：brew install doxygen。

1.2 安装 Graphviz（可选）

Graphviz 可以用来生成类图、调用图等。

Graphviz 下载

安装完成后，将 dot 命令路径添加到环境变量中。
在这里插入图片描述

2. 准备代码

确保源代码中包含标准的注释格式（如 Doxygen 风格），以下是 C++ 的注释示例：

/**
 * @brief 计算两个整数的和
 * @param a 第一个整数
 * @param b 第二个整数
 * @return 两个整数的和
 */
int add(int a, int b) {
    return a + b;
}

3. 配置 Doxygen

3.1 创建配置文件

在项目根目录运行以下命令生成配置文件：
```
doxygen -g
```
此命令会生成一个 Doxyfile，即 Doxygen 的配置文件。
修改配置文件
打开 Doxyfile，根据需要编辑以下内容：
- PROJECT_NAME：设置项目名称。
```
PROJECT_NAME = "MyProject"
```
- OUTPUT_DIRECTORY：指定生成文档的输出目录。
```
OUTPUT_DIRECTORY = docs
```
- INPUT：指定源文件目录。
```
INPUT = src
```
- GENERATE_HTML：启用 HTML 文档生成。
```
GENERATE_HTML = YES
```
- GENERATE_LATEX：启用 PDF 文档生成（需要 LaTeX 环境）。
```
GENERATE_LATEX = NO
```
- DOT_PATH：如果安装了 Graphviz，设置 dot 命令路径以生成类图和调用图。
```
HAVE_DOT = YES
DOT_PATH = /path/to/graphviz/bin
```

4. 生成文档

运行以下命令生成文档：

doxygen Doxyfile

成功运行后，docs 目录中会生成文档：

HTML 文档：docs/html/index.html
PDF 文档（如果启用 LaTeX）：需要进入 LaTeX 文件夹手动编译。

打开 index.html 查看生成的 HTML 文档。
在这里插入图片描述

5. 添加注释

5.1 基本注释格式

Doxygen 支持多种注释格式，以下是常见示例：

文件注释

/**
 * @file main.cpp
 * @brief 主程序入口
 */

类注释

/**
 * @brief 表示一个简单的矩形类
 */
class Rectangle {
public:
    /**
     * @brief 构造函数
     * @param w 矩形的宽度
     * @param h 矩形的高度
     */
    Rectangle(double w, double h);

    /**
     * @brief 获取矩形的面积
     * @return 矩形的面积
     */
    double getArea() const;

private:
    double width;  ///< 矩形的宽度
    double height; ///< 矩形的高度
};

函数注释

/**
 * @brief 打印一个问候语
 * @param name 用户的名字
 */
void sayHello(const std::string& name);

5.2 常用 Doxygen 标签

标签	描述
`@brief`	简短描述
`@param`	描述函数参数
`@return`	描述返回值
`@file`	文件级别注释
`@class`	类级别注释
`@deprecated`	标记函数或类已过时
`@see`	参考相关函数或类

6. 高级功能

6.1 类图和调用图

启用 Graphviz 后，Doxygen 会自动生成类图和调用图，图形会嵌入到 HTML 文档中。

调用图：显示函数的调用关系。
被调用图：显示函数被哪些函数调用。

确保以下选项启用：

HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES

6.2 多语言支持

通过修改 LANGUAGE 选项支持多种编程语言（如 C++、Python、Java）：

OPTIMIZE_OUTPUT_FOR_C = YES

7. 集成到项目

7.1 使用 CMake 自动生成文档

在 CMake 文件中添加以下内容：

find_package(Doxygen REQUIRED)

set(DOXYGEN_INPUT_DIR "${CMAKE_SOURCE_DIR}/src")
set(DOXYGEN_OUTPUT_DIR "${CMAKE_BINARY_DIR}/docs")

set(DOXYGEN_CONFIG_FILE "${CMAKE_BINARY_DIR}/Doxyfile")

add_custom_target(doc
    COMMAND doxygen ${DOXYGEN_CONFIG_FILE}
    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
    COMMENT "Generating API documentation with Doxygen"
    VERBATIM)

运行 make doc 即可生成文档。