通过Doxygen生成代码仓文档资料（类图、依赖图、调用图等）
目录
1. Doxygen基本介绍
1.1 什么是Doxygen
Doxygen是一款开源、跨平台的自动化文档生成工具，广泛用于从源代码中提取注释并生成结构化的技术文档。它能够：
- 自动提取代码结构：从源代码中提取类、函数、变量、命名空间等结构信息
- 生成多种格式文档：支持HTML、LaTeX（用于PDF）、RTF、Man页等多种输出格式
- 支持多种编程语言：支持C、C++、Java、Objective-C和IDL语言，对PHP、C#、Python、Fortran、VHDL等语言也提供部分支持
- 提供图形化展示：工具可自动生成类继承图、协作图与包含依赖图，增强代码结构的可视化表达
- 支持跨平台工作：支持Windows、Linux、macOS等操作系统
1.2 Doxygen的优势
- 自动化程度高：只需在代码中添加注释，即可自动生成文档
- 与代码同步：文档与代码在同一位置，便于维护
- 标准化格式：使用统一的注释格式，提高代码可读性
- 丰富的输出：支持多种输出格式，满足不同需求
- 图形化展示：自动生成类图和依赖关系图，可视化效果好
1.3 Doxygen注释格式
Doxygen支持多种注释风格：
/**
* @brief 简要描述
* @details 详细描述
* @param param1 参数1说明
* @return 返回值说明
*/
int function(int param1);
//! 单行注释风格
//! @brief 简要描述
class MyClass {
//! 成员变量说明
int m_member;
};
2. 工具安装
2.1 Linux系统安装
Ubuntu/Debian系统
# 使用apt包管理器安装
sudo apt-get update
sudo apt-get install doxygen
sudo apt-get install Graphviz
# 安装LaTeX支持（用于生成PDF）
sudo apt-get install texlive-full
CentOS/RHEL系统
# 使用yum包管理器安装
sudo yum install doxygen
sudo yum install Graphviz
# 安装LaTeX支持
sudo yum install texlive-scheme-full
2.2 Windows系统安装
- 下载安装包：从 Doxygen官网 下载Windows安装包
- 运行安装程序：双击安装包，按照向导完成安装
- 添加到PATH：安装完成后，确保Doxygen可执行文件在系统PATH中
2.4 验证安装
安装完成后，可以通过以下命令验证：
# 查看版本信息
doxygen --version
# 查看帮助信息
doxygen --help
3. 参数配置
3.1 生成配置文件
首次使用Doxygen时，需要生成配置文件：
# 生成默认配置文件Doxyfile
doxygen -g
# 或者指定配置文件名称
doxygen -g MyDoxyfile
3.2 关键配置参数说明
3.2.1 项目基本信息
# 项目名称
PROJECT_NAME = "My Project"
# 项目版本号
PROJECT_NUMBER = "1.0.0"
# 项目简要描述
PROJECT_BRIEF = "项目简要说明"
# 输出目录
OUTPUT_DIRECTORY = ./docs
# 输出语言
OUTPUT_LANGUAGE = Chinese
3.2.2 输入文件配置
# 源代码目录（多个目录用空格分隔）
INPUT = ./src ./include
# 文件编码
INPUT_ENCODING = UTF-8
# 递归搜索子目录
RECURSIVE = YES
# 文件模式（支持通配符）
FILE_PATTERNS = *.cpp \
*.h \
*.hpp \
*.c \
*.cc \
*.cxx \
*.c++ \
# 排除的文件和目录
EXCLUDE =
EXCLUDE_PATTERNS =
3.2.3 提取配置
# 提取所有成员（包括未文档化的）
EXTRACT_ALL = YES
# 提取静态成员
EXTRACT_STATIC = YES
# 提取私有成员
EXTRACT_PRIVATE = YES
# 提取本地类
EXTRACT_LOCAL_CLASSES = YES
# 提取本地方法
EXTRACT_LOCAL_METHODS = YES
3.2.4 HTML输出配置
# 生成HTML文档
GENERATE_HTML = YES
# HTML输出目录
HTML_OUTPUT = html
# HTML文件头
HTML_HEADER =
# HTML文件尾
HTML_FOOTER =
# HTML样式表
HTML_STYLESHEET =
# HTML额外文件
HTML_EXTRA_FILES =
# HTML搜索功能
SEARCHENGINE = YES
# 服务器端搜索（需要JavaScript）
SERVER_BASED_SEARCH = NO
3.2.5 LaTeX/PDF输出配置
# 生成LaTeX文档
GENERATE_LATEX = YES
# LaTeX输出目录
LATEX_OUTPUT = latex
# LaTeX命名名称（推荐xelatex）
LATEX_CMD_NAME = xelatex
# PDF超链接
PDF_HYPERLINKS = YES
# PDF书签
USE_PDFLATEX = YES
# PDF文档标题
LATEX_HEADER =
3.2.6 图形配置
# 生成类图
HAVE_DOT = YES
# DOT工具路径（需要安装Graphviz）
DOT_PATH =
# 生成调用关系图
CALL_GRAPH = NO
# 生成调用者关系图
CALLER_GRAPH = NO
# 生成协作图
COLLABORATION_GRAPH = YES
# 生成包含依赖图
INCLUDE_GRAPH = YES
# 生成包含依赖者图
INCLUDED_BY_GRAPH = YES
3.2.7 其他重要配置
# 显示未文档化的文件
SHOW_FILES = YES
# 显示未文档化的成员
SHOW_UNDOCUMENTED = YES
# 成员简要描述
BRIEF_MEMBER_DESC = YES
# 重复简要描述
REPEAT_BRIEF = YES
# 完整路径名称
FULL_PATH_NAMES = YES
# 从路径中剥离的前缀
STRIP_FROM_PATH =
# 从包含路径中剥离的前缀
STRIP_FROM_INC_PATH =
4. HTML和PDF生成操作流程
4.1 HTML文档生成
4.1.1 基本生成流程
# 1. 进入项目根目录
cd /path/to/project
# 2. 生成或修改配置文件（如果还没有）
doxygen -g Doxyfile
# 3. 编辑配置文件，设置必要的参数
vim Doxyfile # 或使用其他编辑器
# 4. 运行Doxygen生成HTML文档
doxygen Doxyfile
# 5. 查看生成的HTML文档
# 默认输出目录为 html/index.html
4.1.3 HTML文档结构
生成的HTML文档通常包含以下页面：
- index.html：文档首页，包含项目概述和导航
- pages.html：相关页面索引
- namespaces.html：命名空间列表
- classes.html：类列表
- files.html：文件列表
- functions.html：函数列表
- variables.html：变量列表
- namespace_*.html：各命名空间的详细文档
- class_*.html：各类的详细文档
- *.html：各文件的详细文档
4.2 PDF文档生成
4.2.1 生成LaTeX文件
# 1. 确保Doxyfile中启用了LaTeX生成
GENERATE_LATEX = YES
# 2. 运行Doxygen生成LaTeX文件
doxygen Doxyfile
# 3. 进入LaTeX输出目录
cd latex
4.2.2 编译LaTeX生成PDF
# 方法1：使用make命令（推荐）
make
5. 常见问题解决
5.1 安装相关问题
问题1：找不到doxygen命令
症状：运行doxygen --version提示命令未找到
解决方案：
# 检查是否已安装
which doxygen
# 如果未安装，按照第2节的方法安装
# 如果已安装但不在PATH中，添加到PATH
export PATH=$PATH:/usr/local/bin
问题2：缺少Graphviz导致无法生成图形
症状：配置HAVE_DOT = YES后，生成文档时提示找不到dot命令
解决方案：
# Ubuntu/Debian
sudo apt-get install graphviz
# CentOS/RHEL
sudo yum install graphviz
# macOS
brew install graphviz
# 验证安装
dot -V
5.2 配置相关问题
问题3：中文注释显示乱码
症状：生成的文档中中文注释显示为乱码
解决方案：
# 在Doxyfile中设置正确的编码
DOXYFILE_ENCODING = UTF-8
INPUT_ENCODING = UTF-8
OUTPUT_LANGUAGE = Chinese
# 确保源代码文件也是UTF-8编码
# 可以使用file命令检查
file source.cpp
问题4：某些文件未被包含
症状：部分源文件没有出现在生成的文档中
解决方案：
# 检查INPUT配置
INPUT = ./src ./include
# 检查FILE_PATTERNS配置
FILE_PATTERNS = *.cpp *.h *.hpp *.c *.cc
# 检查EXCLUDE配置，确保没有意外排除
EXCLUDE =
# 检查EXCLUDE_PATTERNS
EXCLUDE_PATTERNS =
# 启用递归搜索
RECURSIVE = YES
问题5：私有成员未显示
症状：类的私有成员没有出现在文档中
解决方案：
# 在Doxyfile中启用私有成员提取
EXTRACT_PRIVATE = YES
EXTRACT_ALL = YES
5.3 生成相关问题
问题6：PDF生成失败
症状：运行pdflatex时出现错误
解决方案：
# 1. 确保安装了完整的LaTeX发行版
# Ubuntu/Debian
sudo apt-get install texlive-full
# 2. 查看详细错误信息
cat refman.log
问题7：类图或依赖图未生成
症状：配置了图形选项但未生成图形
解决方案：
# 1. 确保安装了Graphviz
dot -V
# 2. 检查Doxyfile配置
HAVE_DOT = YES
DOT_PATH = /usr/bin # 或实际dot命令所在路径
# 3. 检查具体图形选项
CALL_GRAPH = YES
CALLER_GRAPH = YES
COLLABORATION_GRAPH = YES
INCLUDE_GRAPH = YES
# 4. 检查DOT工具版本（需要2.38或更高版本）
dot -V
问题8：生成速度慢
症状：文档生成耗时过长
解决方案：
# 1. 排除不必要的文件
EXCLUDE = test/ examples/ build/
# 2. 限制文件模式
FILE_PATTERNS = *.cpp *.h *.hpp
# 3. 禁用不必要的图形生成
HAVE_DOT = NO
# 4. 使用子目录（对于大型项目）
CREATE_SUBDIRS = YES
5.4 文档质量问题
问题9：函数参数说明缺失
症状：函数文档中没有参数说明
解决方案：
在源代码中添加正确的注释：
/**
* @brief 函数简要说明
* @param param1 参数1的说明
* @param param2 参数2的说明
* @return 返回值的说明
*/
int function(int param1, const std::string& param2);
问题10：类继承关系不清晰
症状：类的继承关系在文档中显示不清晰
解决方案：
# 启用继承图
HAVE_DOT = YES
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
# 在源代码中添加继承关系注释
/**
* @brief 基类说明
*/
class Base {
};
/**
* @brief 派生类说明
* @extends Base
*/
class Derived : public Base {
};
5.5 调试技巧
调试配置文件
# 检查配置文件语法
doxygen -s Doxyfile
# 查看实际使用的配置（展开所有变量）
doxygen -x Doxyfile
# 查看配置与模板的差异
doxygen -x_noenv Doxyfile
查看详细输出
# 运行doxygen时显示详细信息
doxygen -v Doxyfile
# 或者重定向输出到文件
doxygen Doxyfile 2>&1 | tee doxygen.log
6. 生成文档内容介绍
6.1 文档结构概览
生成的Doxygen文档通常包含以下几个主要部分：
- 首页（Main Page）：项目概述和导航
- 命名空间（Namespaces）：所有命名空间的列表和详细说明
- 类（Classes）：所有类的列表和详细说明
- 文件（Files）：所有源文件的列表和详细说明
6.2 命名空间文档
6.2.1 命名空间列表页面
在namespaces.html页面中，可以看到：
- 所有命名空间的列表：按字母顺序排列
- 命名空间层次结构：显示命名空间的嵌套关系
- 命名空间简要描述：每个命名空间的简要说明
6.2.2 命名空间详细页面
点击某个命名空间，进入详细页面（如namespace_mc.html），包含：
- 命名空间概述：完整描述和简要说明
- 命名空间成员列表：
- 类型定义（Typedefs）
- 枚举（Enums）
- 函数（Functions）
- 变量（Variables）
- 命名空间成员详细说明：每个成员的详细文档
- 相关文件：该命名空间相关的源文件
6.3 类文档
6.3.1 类列表页面
在classes.html页面中，可以看到：
- 所有类的列表：按字母顺序或层次结构排列
- 类继承层次：显示类的继承关系树
- 类简要描述：每个类的简要说明
6.3.2 类详细页面
点击某个类，进入详细页面（如class_mc_1_1variant.html），包含：
- 类概述：
- 完整描述
- 继承关系图
- 协作图（如果启用）
- 成员概览：
- 公共类型（Public Types）
- 公共成员函数（Public Member Functions）
- 公共属性（Public Attributes）
- 受保护成员（Protected Members）
- 私有成员（Private Members，如果EXTRACT_PRIVATE=YES）
- 成员详细说明：
- 每个成员的完整文档
- 参数说明
- 返回值说明
- 异常说明
- 使用示例（如果有）
- 相关文件：类定义所在的头文件
6.4 文件文档
6.4.1 文件列表页面
在files.html页面中，可以看到：
- 所有文件的列表：按目录结构组织
- 文件类型分类：
- 头文件（Header Files）
- 源文件（Source Files）
- 文件简要描述：每个文件的简要说明
6.4.2 文件详细页面
点击某个文件，进入详细页面（如variant_8h.html），包含：
- 文件概述：
- 文件路径
- 文件描述
- 包含关系图（如果启用）
- 文件内容：
- 包含的头文件列表
- 定义的类列表
- 定义的函数列表
- 定义的变量列表
- 定义的宏列表
- 源代码：文件的完整源代码（如果SOURCE_BROWSER=YES）
6.5 依赖关系图
6.5.1 包含依赖图（Include Dependency Graph）
如果启用了INCLUDE_GRAPH = YES，文档中会显示：
- 文件包含关系：显示哪些文件包含了哪些文件
- 依赖方向：箭头指向被包含的文件
- 依赖层次：显示文件的包含层次结构
6.5.2 类协作图（Collaboration Diagram）
如果启用了COLLABORATION_GRAPH = YES，文档中会显示：
- 类之间的关系：显示类之间的使用关系
- 成员关系：显示类的成员变量类型
- 函数调用关系：显示类方法调用的其他类
6.5.3 调用关系图（Call Graph）
如果启用了CALL_GRAPH = YES，文档中会显示：
- 函数调用关系：显示函数之间的调用关系
- 调用层次：显示函数的调用层次结构
- 调用方向：箭头指向被调用的函数
6.5.4 继承关系图（Inheritance Diagram）
文档中会自动显示：
- 类继承层次：显示类的继承关系
- 基类和派生类：清晰标识基类和派生类
- 多重继承：支持显示多重继承关系
6.6 搜索功能
6.6.1 客户端搜索
如果启用了SEARCHENGINE = YES，文档提供：
- 全文搜索：可以搜索所有文档内容
- 符号搜索：可以搜索类名、函数名等符号
- 快速导航：输入关键词快速定位
6.7 文档示例
以下是一个完整的文档结构示例：
libmcpp文档
├── 首页 (index.html)
│ ├── 项目概述
│ ├── 快速开始
│ └── 导航链接
│
├── 命名空间 (namespaces.html)
│ ├── mc (namespace_mc.html)
│ │ ├── 概述
│ │ ├── 类型定义
│ │ ├── 类列表
│ │ └── 函数列表
│ └── mc::log (namespace_mc_1_1log.html)
│ └── ...
│
├── 类 (classes.html)
│ ├── variant (class_mc_1_1variant.html)
│ │ ├── 类概述
│ │ ├── 继承关系图
│ │ ├── 成员概览
│ │ ├── 成员详细说明
│ │ └── 相关文件
│ ├── dict (class_mc_1_1dict.html)
│ └── ...
│
├── 文件 (files.html)
│ ├── variant.h (variant_8h.html)
│ │ ├── 文件概述
│ │ ├── 包含关系图
│ │ ├── 定义的符号
│ │ └── 源代码
│ └── ...
│
└── 其他页面
├── 函数列表 (functions.html)
├── 变量列表 (variables.html)
└── 页面列表 (pages.html)
7. 最佳实践
7.1 注释规范
7.1.1 文件头注释
每个文件应该包含文件头注释：
/**
* @file filename.h
* @brief 文件的简要描述
* @details 文件的详细描述
* @author 作者名
* @date 创建日期
* @copyright 版权信息
*/
7.1.2 类注释
每个类应该包含类注释：
/**
* @class ClassName
* @brief 类的简要描述
*
* 类的详细描述，可以包含多行。
*
* 使用示例：
* @code
* ClassName obj;
* obj.method();
* @endcode
*/
class ClassName {
// ...
};
7.1.3 函数注释
每个公共函数应该包含函数注释：
/**
* @brief 函数的简要描述
*
* 函数的详细描述。
*
* @param param1 参数1的说明
* @param param2 参数2的说明
* @return 返回值的说明
* @throws ExceptionType 异常说明
*
* @note 注意事项
* @warning 警告信息
* @see 相关函数或类
*
* @par 示例:
* @code
* int result = function(1, "test");
* @endcode
*/
int function(int param1, const std::string& param2);
7.2 配置优化
7.2.1 性能优化
对于大型项目，可以：
# 使用子目录分散文件
CREATE_SUBDIRS = YES
# 排除测试和示例代码
EXCLUDE = test/ examples/ build/
# 禁用不必要的图形生成
HAVE_DOT = NO # 如果不需要图形
7.2.2 质量优化
提高文档质量：
# 提取所有成员
EXTRACT_ALL = YES
# 显示未文档化的成员
SHOW_UNDOCUMENTED = YES
# 启用源代码浏览
SOURCE_BROWSER = YES
# 启用交叉引用
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
7.3 版本控制
7.3.1 忽略生成的文件
在.gitignore中添加：
# Doxygen生成的文件
html/
latex/
rtf/
man/
xml/
7.3.2 自动化生成
在CI/CD中集成文档生成：
# .github/workflows/docs.yml
name: Generate Documentation
on:
push:
branches: [ main ]
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install Doxygen
run: sudo apt-get install -y doxygen graphviz
- name: Generate Documentation
run: doxygen Doxyfile
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./html