17370845950

Doxygen 是 C++ 项目主流文档生成工具，需安装工具、编写标准注释（如 ///@brief/@param）、生成配置文件（doxygen -g）并运行 doxygen Doxyfile 生成 HTML 等文档，配合小技巧可提升质量。

Doxygen 是 C++ 项目最主流的文档生成工具，它能从源码注释中自动提取结构化文档（HTML、LaTeX、XML 等），无需手写文档框架。关键在于写对注释格式，并配好配置文件。

1. 安装 Doxygen 工具

Windows 用户可直接下载官方安装包（doxygen.nl/download）；macOS 推荐用 Homebrew：brew install doxygen；Linux（如 Ubuntu）执行：sudo apt install doxygen。安装后终端运行 doxygen -v 验证是否成功。

2. 在代码中写标准 Doxygen 注释

Doxygen 不解析普通注释（// 或 /* */），必须使用特定标记开头：

• /// 或 /** 开头的行会被识别为文档块（推荐用 /// 写单行，/** */ 写多行）
• 函数前加注释，用 @param 描述参数，@return 说明返回值，@brief 给简短概述
• 类/结构体前用 @brief 和 @details 区分摘要与详细说明

示例：

/// @brief 计算两个整数的最大公约数
/// @details 使用欧几里得算法递归实现
/// @param a 第一个非负整数
/// @param b 第二个非负整数
/// @return 两数的最大公约数
int gcd(int a, int b);

3. 生成配置文件并运行

在项目根目录执行：doxygen -g Doxyfile，生成默认配置文件。常用修改项包括：

• PROJECT_NAME：设为你的项目名
• INPUT：指定源码路径，如 src/ include/
• FILE_PATTERNS：添加 *.h *.hpp *.cpp *.cc
• RECURSIVE：设为 YES 以递归扫描子目录
• GENERATE_HTML 和 GENERATE_XML：按需开启

保存后运行：doxygen Doxyfile，输出默认在 html/ 目录，直接打开 index.html 即可浏览。

4. 提升文档质量的小技巧

让生成结果更专业，可以：

• 在头文件顶部加 /** @mainpage 项目说明 */ 定义首页内容
• 用 @defgroup 和 @ingroup 对功能模块分组
• 用 @code ... @endcode 块插入代码片段
• 启用 EXTRACT_ALL = YES 可强制文档化未加注释的符号（调试阶段有用）
• 配合 DOT_PATH 和 Graphviz 生成类图、调用图（需额外安装）

不复杂但容易忽略：每次更新接口后，重新运行 doxygen 就能同步刷新文档，真正实现“代码即文档”。