Doxygen详细使用指南

Doxygen 详细使用指南

Doxygen 是一个用于生成代码文档的工具，支持 C++, C, Java, Python 等多种语言。它通过解析代码中的注释和结构，生成 HTML、LaTeX、PDF 等格式的文档。

一、官网地址

• 官网地址：https://www.doxygen.nl/
• 下载地址：https://www.doxygen.nl/download.html
• 官方文档：Doxygen Manual

二、安装与配置

1. 安装

   • Linux:

     sudo apt-get update && sudo apt-get install doxygen graphviz
     

   • macOS (Homebrew):

     brew install doxygen graphviz
     

   • Windows:
     • 从 官网 下载安装包，安装时勾选 Graphviz 支持图表生成。
     • 将 Doxygen 和 Graphviz 的 bin 目录添加到系统 PATH 环境变量。

2. 初始化配置文件
   生成默认配置文件 Doxyfile：

   doxygen -g
   

3. 关键配置参数详解
   修改 Doxyfile 中的以下参数：

   # 输入目录（代码路径）
   INPUT                  = ./src
   # 递归扫描子目录
   RECURSIVE              = YES
   # 输出目录（文档生成路径）
   OUTPUT_DIRECTORY       = ./docs
   # 提取未注释的代码
   EXTRACT_ALL            = YES
   # 生成 HTML 文档
   GENERATE_HTML          = YES
   # 启用 Graphviz 图表
   HAVE_DOT               = YES
   # 生成调用关系图
   CALL_GRAPH             = YES
   # 生成被调用关系图
   CALLER_GRAPH           = YES
   # 输出语言（支持中文）
   OUTPUT_LANGUAGE        = Chinese
   # 输入文件编码
   INPUT_ENCODING         = UTF-8
   

三、注释语法规范

1. 注释风格

   • 单行注释：

     /// 简要描述
     //! 另一种单行风格
     

   • 多行注释：

     /**
      * 多行描述
      * @param 参数说明
      */
     /*!
      * 另一种多行风格
      */
     

2. 常用标签

   标签	用途	示例
   @brief	简要说明	@brief 计算两数之和
   @param	函数参数说明	@param a 第一个整数
   @return	返回值说明	@return 两数之和
   @details	详细描述	@details 支持整数和浮点数运算
   @code/@endcode	插入代码示例	见下方示例
   @note	注意事项	@note 输入必须为非负数
   @see	参考链接	@see Calculator::multiply
   @class	类说明	@class Calculator
   @file	文件说明	@file math_utils.h

3. 示例代码

   • 函数注释（C++）：

     /**
      * @brief 计算两个整数的乘积
      * @param x 第一个整数
      * @param y 第二个整数
      * @return 乘积结果
      * @note 如果结果为负数，返回 -1
      * @code
      * int result = multiply(3, 4); // 返回 12
      * @endcode
      */
     int multiply(int x, int y);
     

   • 类注释（Python）：

     ## @class DataProcessor
     ## @brief 数据处理工具类
     class DataProcessor:
         ## @brief 清洗数据
         ## @param data 原始数据（列表格式）
         ## @return 清洗后的数据
         def clean_data(self, data):
             pass
     

四、集成到开发工具

1. CMake 集成

   • 步骤：
     1. 在 CMakeLists.txt 中添加以下内容：

        find_package(Doxygen REQUIRED)
        if(DOXYGEN_FOUND)
            set(DOXYGEN_INPUT "${PROJECT_SOURCE_DIR}/src")
            set(DOXYGEN_OUTPUT "${PROJECT_BINARY_DIR}/docs")
            configure_file(
                "${PROJECT_SOURCE_DIR}/Doxyfile.in"
                "${PROJECT_BINARY_DIR}/Doxyfile"
                @ONLY
            )
            add_custom_target(docs
                COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile
                WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
                COMMENT "生成文档中..."
            )
        endif()
        

     2. 创建模板文件 Doxyfile.in：

        INPUT          = @DOXYGEN_INPUT@
        OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT@
        RECURSIVE      = YES
        HAVE_DOT       = YES
        

   • 生成文档：

     cmake -B build && cmake --build build --target docs
     

2. IDE 插件

   • VS Code：
     • 安装插件 Doxygen Documentation Generator。
     • 在函数上方输入 /** + Enter，自动生成注释模板。
     • 配置模板：

       "doxdocgen.generic.paramTemplate": "@param {param} - ",
       "doxdocgen.generic.returnTemplate": "@return {type} - "
       

   • Visual Studio：
     • 安装插件 Doxygen Comments。
     • 使用快捷键 Ctrl+Shift+D 生成注释块。

3. CI/CD 集成

   • GitHub Actions 示例：

     name: Docs
     on: [push]
     jobs:
       build-docs:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - name: Install Doxygen
             run: sudo apt-get install -y doxygen graphviz
           - name: Generate Docs
             run: doxygen Doxyfile
           - name: Deploy to GitHub Pages
             uses: peaceiris/actions-gh-pages@v3
             with:
               github_token: ${{ secrets.GITHUB_TOKEN }}
               publish_dir: ./docs/html
     

五、高级功能

1. 结合 Sphinx + Breathe

   • 步骤：
     1. 安装依赖：

        pip install sphinx breathe exhale
        

     2. 创建 Sphinx 项目：

        sphinx-quickstart --sep -p "MyProject" -a "John Doe" -v 1.0
        

     3. 修改 conf.py：

        extensions = ["breathe"]
        breathe_projects = {"MyProject": "../doxygen/xml/"}
        breathe_default_project = "MyProject"
        

     4. 生成文档：

        doxygen Doxyfile                # 生成 XML
        sphinx-build -b html . ./build  # 生成 Sphinx HTML
        

2. 自定义模板

   • 修改 Doxygen 的布局文件 layout.xml：

     <navindex>
         <tab type="mainpage" visible="yes" title="Overview"/>
         <tab type="classes" visible="yes" title="API Reference"/>
     </navindex>
     

   • 在 Doxyfile 中指定布局文件：

     LAYOUT_FILE = ./custom_layout.xml
     

3. 过滤私有成员

   EXTRACT_PRIVATE = NO     # 不提取私有成员
   EXTRACT_STATIC  = NO     # 不提取静态成员
   HIDE_UNDOC_MEMBERS = YES # 隐藏未注释的成员
   

六、调试与问题解决

1. 查看生成日志

   doxygen Doxyfile 2>&1 | tee doxygen.log
   

2. 常见问题

   • 问题1：图表未生成
     • 确保 Graphviz 已安装且 dot 命令可用。
     • 检查 Doxyfile 中配置：

       HAVE_DOT = YES
       DOT_PATH = "C:/Program Files/Graphviz/bin"  # Windows 需指定路径
       

   • 问题2：中文乱码
     • 确保源代码文件编码为 UTF-8。
     • 设置 Doxyfile：

       INPUT_ENCODING = UTF-8
       DOXYFILE_ENCODING = UTF-8
       

   • 问题3：文档未更新
     • 清理输出目录：

       rm -rf docs/html/*
       

七、扩展资源

• 示例项目：Doxygen Examples
• 图表定制：Graphviz 文档

通过本指南，您可以从零开始配置 Doxygen，并实现与开发工具、自动化流程的深度集成，生成专业级的代码文档。