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（可选）

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 创建配置文件

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
     

---

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);
   

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(docCOMMAND doxygen ${DOXYGEN_CONFIG_FILE}WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}COMMENT "Generating API documentation with Doxygen"VERBATIM)

运行 make doc 即可生成文档。

---

8. 常见问题

8.1 无法找到 dot 命令

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

8.2 中文字符显示问题

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

INPUT_ENCODING = UTF-8

---

9. 总结

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