前言
1.1 什么是 Doxygen？
Doxygen 是一个从源代码注释中提取信息并生成文档的工具。
这篇指南专为从事嵌入式开发的 C/C++ 程序员设计，目标是帮助你从零开始学会使用 Doxygen 工具生成代码文档。内容包括安装、功能介绍、配置、使用过程及生成 HTML、Markdown、PDF 等格式的文档。对于嵌入式开发者，Doxygen 可以帮助整理复杂的代码逻辑，生成清晰的 API 文档。
第 1 部分：Doxygen 工具安装
1.1 确定开发环境
嵌入式开发通常在 Windows、Linux 或 macOS 上进行。以下以常见操作系统为例，详细讲解如何安装 Doxygen。
Windows 安装步骤
访问 Doxygen 官方网站
打开浏览器，访问 Doxygen 官方下载页面。
在页面中找到 Binary distribution 部分，选择适合你的 Windows 版本（通常是 doxygen-x.y.z.windows.x64.bin.zip 或类似的压缩包）。
点击下载链接，保存压缩包到本地（如 C:Downloads）。
解压安装包
右键单击下载的 .zip 文件，选择“解压到当前文件夹”或使用解压工具（如 7-Zip、WinRAR）。
解压后得到一个文件夹（如 doxygen-x.y.z），里面包含 doxygen.exe 等文件。
添加 Doxygen 到系统环境变量（可选，推荐）
将解压后的文件夹移动到一个固定位置（如 C:Program FilesDoxygen）。
右键“此电脑” → “属性” → “高级系统设置” → “环境变量”。
在“系统变量”中找到 Path，点击“编辑”，添加 Doxygen 的 bin 目录路径（如 C:Program FilesDoxygenin）。
点击“确定”保存。
验证安装
示例输出：
Doxygen version 1.13.2 (2025-04-22)打开命令提示符（按 Win + R，输入 cmd，回车）。
输入以下命令：
doxygen --version如果显示版本号（如 1.13.2），说明安装成功。
安装 Graphviz（可选，用于生成类图和调用图）
Doxygen 使用 Graphviz 的 dot 工具生成图形。访问 Graphviz 官网，下载 Windows 版本的安装包。
运行安装程序，按照提示完成安装。
同样将 Graphviz 的 bin 目录（如 C:Program FilesGraphvizin）添加到系统环境变量 Path 中。
验证安装：
dot -V示例输出：
dot - graphviz version 12.2.1 (20250422.2002)安装 LaTeX（可选，用于生成 PDF 文档）
如果需要生成 PDF 格式文档，安装
MiKTeX: https://miktex.org/download
下载 MiKTeX 安装程序，运行并完成安装。安装过程中会自动配置环境。
Linux 安装（以 Ubuntu 为例）
打开终端，运行以下命令安装 Doxygen：
sudo apt update
sudo apt install doxygen安装 Graphviz（可选）：
sudo apt install graphviz安装 LaTeX（可选）：
sudo apt install texlive-full验证安装：
doxygen --version
dot -VmacOS 安装（使用 Homebrew）
安装 Homebrew（如果未安装）：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"安装 Doxygen：
brew install doxygen安装 Graphviz：
brew install graphviz安装 LaTeX：
brew install --cask mactex验证安装：
doxygen --version
dot -V1.2 安装辅助工具（可选）
生成 PDF 文档：需要安装 LaTeX（如 MiKTeX for Windows 或 TeX Live for Linux/macOS）。
Windows：访问 https://miktex.org/download，下载并安装 MiKTeX。
Linux：运行 sudo apt install texlive-full。
macOS：运行 brew install --cask mactex。
GUI 工具：Doxywizard 是 Doxygen 的图形界面，适合初学者。
Windows：下载时已包含在 Doxygen 安装包中，位于 bin 目录（doxywizard.exe）。
Linux/macOS：安装 Doxygen 时自动包含，运行 doxywizard 启动。
注意事项：
确保网络连接稳定，下载安装包时避免中断。
如果磁盘空间有限，LaTeX 安装包较大（几 GB），可以先跳过 PDF 相关步骤。
安装 Graphviz 是强烈推荐的，因为嵌入式开发中代码关系图非常有用。
第 2 部分 Doxygen 的功能介绍
Doxygen 提供了丰富的功能，适合从初学者到高级用户的需求。以下按 常用功能、进阶功能 和 高级功能 分类介绍。
2.1 常用功能
这些功能适合刚入门的开发者，易于上手：
自动提取注释：从代码中的特殊注释（如 /** ... */ 或 ///）生成文档。
支持多种语言：完美支持 C/C++，也支持 Python、Java 等。
生成 HTML 文档：生成带有导航栏、搜索功能的网页格式文档。
生成 Markdown 文档：生成简洁的 Markdown 文件，适合嵌入到 GitHub 或其他平台。
文件和函数文档：为源文件、函数、变量等生成详细说明。
生成函数和类列表
自动生成所有函数、类、结构等的列表。
配置：
ALPHABETICAL_INDEX = YES：生成按字母顺序排序的索引。
GENERATE_AUTOGEN_DEF = YES：包含自动生成的定义。
2.2 进阶功能
需要一定配置，适合有一定经验的开发者：
类图和调用图：结合 Graphviz，自动生成类继承关系图、函数调用关系图。
多语言支持：生成多语言文档（如中文、英文）。
自定义样式：修改 HTML 输出的 CSS 或添加自定义页眉页脚。
配置：
HTML_STYLESHEET = custom.css：指定自定义 CSS 文件。
HTML_HEADER = header.html：自定义页眉。
示例 CSS：
body { font-family: Arial, sans-serif; }
.memtitle { background-color: #007bff; color: white; }条件编译文档：根据宏定义（如 #ifdef）控制文档内容。
2.3 高级功能
需要深入理解 Doxygen 配置，适合复杂项目：
生成 XML/JSON 输出：用于与其他工具集成（如 CI/CD 管道）。
自定义标签：定义专属的注释标签（如 @my_tag），扩展 Doxygen 的功能。
多项目文档集成：通过 TAGFILES 整合多个项目的文档。
嵌入公式和图表：结合 LaTeX 或 Markdown，生成数学公式或复杂图表。
交互式文档：通过 JavaScript 增强 HTML 文档的交互性。
集成到 CI/CD：自动化生成文档并发布到网站。
配置（以 GitHub Actions 为例）：
name: GenerateDoxygenDocs
on: [push]
jobs:
docs:
runs-on:ubuntu-latest
steps:
-uses:actions/checkout@v3
-run:sudoaptinstalldoxygengraphviz
-run:doxygenDoxyfile
-uses:actions/upload-artifact@v3
with:
name:doxygen-docs
path: docs/html/嵌入式开发相关建议：
嵌入式项目通常代码量大、模块复杂，推荐重点掌握 类图和调用图，以可视化模块依赖关系。
使用 条件编译文档 功能，针对不同硬件平台生成特定文档。
第 3 部分：Doxygen 使用教学过程
以下是一个完整的 Doxygen 使用教学，基于一个简单的 C 语言嵌入式项目。我们会从零开始，逐步完成配置和文档生成。
3.1 示例项目准备
假设你有一个简单的嵌入式项目，目录结构如下：
my_project/
├── inc/
│ └── led.h
├── src/
│ └── led.c
└── main.cled.h（头文件）：
#ifndef LED_H
#define LED_H
/**
* @brief Initialize the LED module.
* @param pin The GPIO pin number connected to the LED.
* @return 0 on success, -1 on failure.
*/
int led_init(int pin);
/**
* @brief Turn the LED on or off.
* @param state 1 to turn on, 0 to turn off.
*/
void led_set_state(int state);
#endifled.c（源文件）：
#include "led.h"
int led_init(int pin) {
// Simulate GPIO initialization
if (pin < 0) return -1;
return 0;
}
void led_set_state(int state) {
// Simulate setting GPIO state
}main.c：
#include "led.h"
/**
* @brief Main entry point of the program.
*/
int main(void) {
led_init(5);
led_set_state(1);
return 0;
}注释说明：
使用 /** ... */ 格式的注释，包含 Doxygen 标签（如 @brief、@param、@return）。
这些注释会被 Doxygen 提取并生成文档。
3.2 生成 Doxygen 配置文件
创建 Doxygen 配置文件
打开命令提示符（Windows）或终端（Linux/macOS），进入项目目录：
cd path/to/my_project运行以下命令生成默认配置文件：
doxygen -g Doxyfile这会在项目目录下生成一个名为 Doxyfile 的配置文件。
编辑 Doxyfile
用文本编辑器（如 VS Code、Notepad++）打开 Doxyfile。
修改以下关键配置项（按需调整）：
# 项目信息
PROJECT_NAME = "Media Stream Project"
PROJECT_NUMBER = 1.0.0
OUTPUT_DIRECTORY = docs/
OUTPUT_LANGUAGE = Chinese
DOXYFILE_ENCODING = UTF-8
INPUT_ENCODING = UTF-8
# 输入设置
INPUT = ./
RECURSIVE = YES
FILE_PATTERNS = *.h
EXCLUDE = *.c *.cpp
# 输出格式
GENERATE_HTML = YES
GENERATE_MARKDOWN = YES # 需要 Doxygen 1.9.5+
GENERATE_LATEX = YES
# 提取所有实体
EXTRACT_ALL = YES # 如果注释不足，设置为 YES 可提取所有实体
EXTRACT_PRIVATE = NO # 私有函数等（默认不支持）
EXTRACT_STATIC = NO # 静态函数等（默认不支持）
EXTRACT_LOCAL_CLASSES = YES
# 类图和调用图（可选）
HAVE_DOT = YES
CLASS_DIAGRAMS = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
# 宏展开
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO保存文件。
修改 refman.tex（可选）：
如果不想使用自定义页眉，可以直接编辑 refman.tex。
打开 docs/latex/refman.tex，找到封面部分（通常在文件的开头）。
示例 refman.tex 的封面部分可能如下：
pdftitle={LED}
{Large LED}
{large 制作者 Doxygen 1.13.2}
fancyfoot[LO, RE]{fseriesscriptsize 制作者 Doxygen } 将 pdftitle={LED} 修改为：
pdftitle={主标题}例如：
pdftitle={LED设计使用指南} 将 {large 制作者 Doxygen 1.13.2} 修改为：
{large 你的名字}例如：
{large 制作者 张三} 在 {large 制作者 Doxygen 1.13.2} 下一行添加日期（生成文档的当天）：
{
ormalsize oday}\
将页脚 fancyfoot[LO, RE]{fseriesscriptsize 制作者 Doxygen } 修改为：：
fancyfoot[LO, RE]{fseriesscriptsize 作者 你的名字 }例如：
fancyfoot[LO, RE]{fseriesscriptsize 作者 张三 }注意事项：
INPUT 路径要包含所有需要生成文档的代码文件。
如果项目中有大量文件，使用 RECURSIVE = YES 自动扫描子目录。
确保 OUTPUT_DIRECTORY 是一个存在的目录，或留空（默认在当前目录生成）。
3.3 运行 Doxygen
在项目目录下运行以下命令：
doxygen DoxyfileDoxygen 会根据 Doxyfile 配置，扫描代码并生成文档。输出目录（docs/）将包含：
html/：HTML 格式文档。
markdown/：Markdown 格式文档（如果启用）。
latex/：LaTeX 格式文档（如果启用）。
注意事项：
如果报错“dot not found”，检查是否安装了 Graphviz 并添加到环境变量。
如果注释格式不正确，Doxygen 可能无法提取信息，确保使用 /** ... */ 或 ///。
4. 手把手生成 HTML、Markdown 和 PDF 文档
以下是生成不同格式文档的详细步骤，包含示例输出说明。
4.1 生成 HTML 文档
确保配置
在 Doxyfile 中，确认以下设置：
GENERATE_HTML = YES
OUTPUT_DIRECTORY = docs/运行 Doxygen
执行：
doxygen Doxyfile生成的 HTML 文件位于 docs/html/ 目录下。
查看结果
示例 HTML 输出（led_init 的文档）：
<h2>led_init</h2>
<p><b>int led_init (int pin)</b></p>
<p>Initialize the LED module.</p>
<dl>
<dt>Parameters</dt>
<dd><b>pin</b>: The GPIO pin number connected to the LED.</dd>
<dt>Returns</dt>
<dd>0 on success, -1 on failure.</dd>
</dl>打开 docs/html/index.html（用浏览器查看）。
界面示例（假设安装了 Graphviz）：
左侧导航栏：显示文件、函数、类等列表。
主页面：显示项目概述、函数 led_init 和 led_set_state 的详细说明。
调用图：显示 main 调用 led_init 和 led_set_state 的关系。
注意事项
如果需要自定义 HTML 样式，修改 Doxyfile 中的 HTML_STYLESHEET 或 HTML_EXTRA_FILES。
确保代码注释规范，否则生成的文档可能不完整。
4.2 生成 Markdown 文档
确保配置
在 Doxyfile 中，确认以下设置（Doxygen 1.9.5+ 支持）：
GENERATE_MARKDOWN = YES
OUTPUT_DIRECTORY = docs/运行 Doxygen
执行：
doxygen Doxyfile生成的 Markdown 文件位于 docs/markdown/ 目录下。
查看结果
打开 docs/markdown/ 下的 .md 文件（如 led_8h.md）。
示例 Markdown 输出（led.h 的文档）：
# led.h
## led_init
Initialize the LED module.
**Parameters**:
- `pin`: The GPIO pin number connected to the LED.
**Returns**:
- 0 on success, -1 on failure.
## led_set_state
Turn the LED on or off.
**Parameters**:
- `state`: 1 to turn on, 0 to turn off.注意事项
Markdown 文档适合嵌入到 GitHub 或 GitLab 的 README 中。
如果需要调整 Markdown 格式，需修改 Doxygen 源代码（较复杂，初学者可忽略）。
4.3 生成 PDF 文档
小贴士：
如果在执行
pdflatex refman.tex过程中有弹窗提示宏包安装。直接点安装即可（这是因为使用环境缺失对应的安装包，因此才会提示安装）。
确保配置
在 Doxyfile 中，确认以下设置：
GENERATE_LATEX = YES
OUTPUT_DIRECTORY = docs/确保已安装 MiKTeX 或 TeX Live。
运行 Doxygen
执行：
doxygen Doxyfile生成的 LaTeX 文件位于 docs/latex/ 目录下。
编译 LaTeX 生成 PDF
进入 docs/latex/ 目录：
cd docs/latex 运行以下命令（Windows 使用 MiKTeX 的 pdflatex）：
pdflatex refman.tex可能需要运行多次（通常 2-3 次）以生成完整的 PDF：
pdflatex refman.tex生成的 PDF 文件为 refman.pdf。
查看结果
打开 refman.pdf，内容与 HTML 文档类似，但格式更适合打印或正式发布。
示例 PDF 内容：
封面：显示项目名称和版本。
目录：列出所有文件和函数。
正文：详细描述 led_init 和 led_set_state，包含参数和返回值。
在 PDF 文档中添加水印：
详情请参考《在 Doxygen 生成的 PDF 添加水印》。
注意事项
LaTeX 编译可能因缺少字体或包而报错，使用 MiKTeX 的自动包管理功能可解决。
PDF 文件较大，适合正式文档，不建议频繁生成。
5. 总结与进阶建议
5.1 总结
通过以上步骤，你已经学会：
安装 Doxygen 和相关工具（Graphviz、LaTeX）。
配置 Doxygen 生成 HTML、Markdown 和 PDF 文档。
为 C/C++ 代码编写规范的 Doxygen 注释。
生成包含调用图的文档，适合嵌入式开发。
5.2 进阶建议
规范化注释：为所有函数、变量、宏添加 Doxygen 注释，Doxygen 官方手册。
自动化生成：将 Doxygen 集成到 CI/CD 流程（如 GitHub Actions），每次提交代码时自动更新文档。
学习高级标签：如 @ingroup（分组）、@todo（待办事项），提升文档组织性。
嵌入式特定优化：为硬件寄存器或驱动代码添加自定义标签，清晰描述硬件相关功能。
5.3 常见问题解答
Q：为什么生成的文档缺少某些函数？
A：检查函数是否添加了 Doxygen 注释（如 /** ... */），或 Doxyfile 中的 INPUT 是否包含相关文件。
Q：调用图没有生成？
A：确保安装了 Graphviz，并设置 HAVE_DOT = YES、CALL_GRAPH = YES。
Q：中文文档显示乱码？
A：设置 OUTPUT_LANGUAGE = Chinese，并确保代码文件使用 UTF-8 编码。
Q：中文文档显示乱码？
A：输出的文档内容仅包含原文（即头文件的原始代码），而未能生成类、宏、函数等的详细描述（如函数的 @brief 、@param 等注释内容）。 这通常是由于 Doxygen 的配置或注释格式问题导致的：
确保所有依赖文件在项目目录中，或在 INPUT 中指定其路径。
临时注释掉缺失的 #include（仅用于不想引入的头文件或测试）
📌 免费领取学习资源：进入公众号，点击【资源合集】-【电子书籍】即可领取！🚀🚀🚀
暂无评论内容