Doxygen 使用指南

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

---

1. 安装 Doxygen

1.1 下载 Doxygen

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

1.2 安装 Graphviz（可选）

1. Graphviz 可以用来生成类图、调用图等。
2. Graphviz 下载

安装完成后，将 dot 命令路径添加到环境变量中。

---

2. 准备代码

确保源代码中包含标准的 Doxygen 注释格式：

• 使用 /// 或 //! 表示单行注释
• 使用 /** */ 或 /*! */ 表示多行注释

以下是 C++ 的注释示例：

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

---

3. 配置 Doxygen

3.1 创建配置文件

1. 在项目根目录运行以下命令生成配置文件：

   doxygen -g
   

   此命令会生成一个 Doxyfile，即 Doxygen 的配置文件。
2. 修改配置文件
   打开 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
     

   • OUTPUT_LANGUAGE：修改输出的语言（设置中文）。

     OUTPUT_LANGUAGE = Chinese
     

---

4. 生成文档

运行以下命令生成文档：

doxygen Doxyfile

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

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

打开 index.html 查看生成的 HTML 文档。

---

5. 添加注释

5.1 基本注释格式

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

1. 文件注释

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

2. 类与结构体

   /**
   * @brief 表示一个简单的矩形类
   */
   class Rectangle {
   public:
      /**
       * @brief 构造函数
       * @param w 矩形的宽度
       * @param h 矩形的高度
       */
      Rectangle(double w, double h);
   
      /**
       * @brief 获取矩形的面积
       * @return 矩形的面积
       */
      double getArea() const;
   
   private:
      double width;  ///< 矩形的宽度
      double height; ///< 矩形的高度
   };
   

3. 函数注释

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

4. 模块与分组
   使用 @defgroup 和 @ingroup 可以组织代码到逻辑模块中：

   /** @defgroup Math 数学模块 */
   
   /** @ingroup Math */
   int add(int a, int b);
   

5. 图表支持
   Doxygen 支持使用 @dot 或与 Graphviz 配合生成类图、调用图等。

   /**
    * @dot
    * digraph G { A -> B; }
    * @enddot
    */
   

5.2 常用 Doxygen 标签

标签	描述
@mainpage	设置首页内容
@brief	简短描述
@param	描述函数参数
@return	描述返回值
@file	文件级别注释
@class	类级别注释
@deprecated	标记函数或类已过时
@see	参考相关函数或类
@section 和 @subsection	分节
@ref	创建内部链接

---

6. 示例展示与导航（@example）

若希望在导航栏中添加 Examples 示例页面，应使用 @example 标签引用示例文件。需要注意，@example 通常用于其他文档或源文件中对示例文件的引用，而不应直接写在示例文件本身内部。

6.1 准备示例文件

在项目中创建 examples/test.c 文件：

/**
 * @file test.c
 * @brief 示例文件：演示加法函数
 */

int add(int a, int b) {
    return a + b;
}

int main() {
    return add(2, 3);
}

6.2 使用 @example 引用

在主注释中引用示例文件：

/**
 * @example test.c
 * 演示如何使用 add 函数
 */

6.3 Doxyfile 配置要求

EXAMPLE_PATH = examples
EXAMPLE_RECURSIVE = YES

确保 INPUT 也包含 examples 目录。

6.4 常见问题

问题	解决方案
示例页面显示为空	检查文件是否位于 EXAMPLE_PATH 下，并重新执行 doxygen
修改未生效	确保已重新运行 doxygen
导航栏无 Examples	检查是否使用了 @example 标记

6.5 展示

---

7. 高级功能

7.1 类图和调用图

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

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

确保以下选项启用：

HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES

7.2 多语言支持

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

OPTIMIZE_OUTPUT_FOR_C = YES

---

8. 集成到项目

8.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 即可生成文档。

---

9. 常见问题

9.1 无法找到 dot 命令

• 确保安装了 Graphviz，并将其路径添加到环境变量中。
• 修改 Doxyfile 中的 DOT_PATH 选项。

9.2 中文字符显示问题

将 Doxyfile 中的编码设置为 UTF-8：

INPUT_ENCODING = UTF-8

---

10. 总结

Doxygen 是一个功能强大的文档生成工具，结合良好的代码注释，可以大大提高项目的可维护性。使用 Doxygen，您可以轻松生成包含类图、调用关系图的 HTML 和 PDF 文档，并将其集成到项目的 CI/CD 管道中。