1. Doxygen 是什么Doxygen 是一个强大的、跨平台的文档生成工具。它能够从带有特殊格式注释的源代码中自动生成软件文档通常为 HTML、PDF、LaTeX、RTF 等格式。它的核心思想是“代码即文档”通过将文档与代码紧密关联极大提高了文档的准确性和可维护性。对于 C 这种复杂且充满各种语义类、模板、命名空间等的语言来说Doxygen 几乎是事实上的标准文档工具。2. 核心概念如何编写 Doxygen 注释Doxygen 注释的本质是带有特殊标记的、符合 Javadoc 风格的多行注释。2.1 注释风格Doxygen 支持多种注释风格最常见的有两种Javadoc 风格 (推荐) 使用/** ... *//** * 这是一个简短的描述。 * 这是一个更详细的多行描述 * 可以解释更多细节。 * * param x 参数的说明 * return 返回值的说明 */ void function(int x);Qt 风格 使用/*! ... */或//!/*! * 这是一个简短的描述。 * 这是一个更详细的多行描述。 * * \param x 参数的说明 * \return 返回值的说明 */ void function(int x); //! 这是一个非常简短的描述 //! //! 这是详细描述使用多个单行注释。 //! \param x 参数的说明 void anotherFunction(int x);最佳实践统一使用/** ... */风格因为它最通用也最容易被其他开发者识别。2.2 基本命令特殊标记命令以或\开头用于描述代码的特定部分。命令用途示例brief或\brief简要描述通常第一句就是可省略brief 计算两个数的和param或\param函数参数说明param a 第一个加数return或\return函数返回值说明return 两个参数的和details或\details详细描述如果简要描述后需要更多内容details 这个函数实现了...note或\note备注信息note 此函数非线程安全warning或\warning警告信息warning 参数不能为负数see或\see参考链接到其他函数/类see MyClass::anotherFunccode/endcode在文档中嵌入代码块见下文示例link/endlink创建自定义链接链接到特定锚点todo或\todo待办事项会汇总到单独的“Todo”列表todo 需要优化算法deprecated标记已弃用的函数/类deprecated 请使用 newFunc()3. 实战注释不同的 C 元素3.1 注释文件File Comment通常在.h或.cpp文件的开头添加。使用file命令。/** * file Calculator.h * brief 一个简单的计算器类头文件 * * 这个文件包含了 Calculator 类的声明该类提供了 * 基本的算术运算功能如加、减、乘、除。 * * author Your Name * date 2023-10-27 * version 1.0 */3.2 注释命名空间Namespace Comment/** * namespace MathUtils * brief 包含一系列数学工具函数和类 */ namespace MathUtils { // ... }3.3 注释类Class Comment/** * brief 一个简单的计算器类用于执行基本算术运算。 * * 这个类没有内部状态所有成员函数都是静态的。 * 它被设计为线程安全的。 * * see MathUtils */ class Calculator { public: /** * brief 计算两个整数的加法 * param a 第一个加数 * param b 第二个加数 * return a 和 b 的和 * note 注意整数溢出问题 */ static int add(int a, int b); /** * brief 计算两个整数的除法 * param dividend 被除数 * param divisor 除数 * return 除法运算的结果 (double) * warning 如果除数为0会抛出 std::invalid_argument 异常 * code{.cpp} * try { * double result Calculator::divide(10, 2); // result 5.0 * } catch (const std::exception e) { * // 处理异常 * } * endcode */ static double divide(int dividend, int divisor); /// brief 一个简短的注释使用三个斜杠也可以 static void shortComment(); };3.4 注释成员变量Member Variable Comment通常放在变量声明上方。class MyClass { private: int m_value; /// brief 内部存储的整数值行末注释使用 /// 或 /** /** * brief 代表用户状态的标志位 * - 0: 离线 * - 1: 在线 * - 2: 忙碌 */ int m_status; };3.5 注释枚举Enum Comment/** * brief 颜色枚举类 */ enum class Color { Red, /// 红色 Green, /// 绿色 Blue /// 蓝色 };4. 配置与生成Configuration Generation创建配置文件在项目根目录运行doxygen -g生成默认的配置文件Doxyfile。编辑Doxyfile用文本编辑器打开修改关键配置PROJECT_NAME My Awesome ProjectOUTPUT_DIRECTORY ./docs 输出目录INPUT ./src 源代码路径RECURSIVE YES 递归处理 INPUT 目录EXTRACT_ALL YES 为所有实体生成文档即使没有注释EXTRACT_PRIVATE YES 为私有成员也生成文档GENERATE_LATEX NO 如果你不需要 PDF/LaTeX 输出可以关闭HAVE_DOT YES,CALL_GRAPH YES,CALLER_GRAPH YES 生成函数调用关系图需要安装 Graphviz生成文档在终端运行doxygen Doxyfile。查看结果打开./docs/html/index.html即可浏览生成的 HTML 文档。5. 高级技巧与最佳实践使用 MarkdownDoxygen 支持 Markdown 语法可以让你的注释更丰富。/** * ## 这是一个二级标题 * 这是一个列表 * - 项1 * - 项2 * * **这是加粗文字** */分组Modules使用defgroup、addtogroup、ingroup将相关的函数/类分组让文档结构更清晰。/** defgroup MathCore 核心数学模块 * 提供最基础的数学运算功能。 */ /** * addtogroup MathCore * { */ int add(int, int); int subtract(int, int); /** } */ // 结束 MathCore 分组平衡细节与简洁公共API必须详细注释包括前置/后置条件、参数、返回值、异常、副作用。内部实现可以适当简洁但复杂的算法和逻辑仍需注释清楚。保持更新最糟糕的文档是过时的文档。将更新文档作为代码修改流程的必要一环。与 CI/CD 集成可以在 Jenkins、GitLab CI、GitHub Actions 等工具中集成 Doxygen 生成步骤实现文档的自动更新和部署。
