11、使用 Doxygen 进行固件文档编写指南

使用 Doxygen 进行固件文档编写指南

1. 生成文档

当 Doxygen 拥有足够的配置信息后，就可以生成文档了。具体操作步骤如下：
1. 切换到“Run”选项卡。
2. 点击“Run Doxygen”按钮。
3. Doxygen 会对配置文件进行处理，随后开始处理源代码。
4. 当状态窗口显示“*** Doxygen has finished”时，点击“Show HTML Output”按钮，即可打开刚刚生成的 HTML 文档。

生成的文档是基于代码中的函数和变量，而非开发者编写的注释。接下来，我们将探讨开发者如何为 Doxygen 编写和定制软件文档。

2. Doxygen 注释基础

在解析源文件时，Doxygen 会寻找特定的字符集，以识别为其编写的注释。所选语言将决定使用哪种字符集。对于使用 C 语言编程的开发者，可以使用标准的注释块 /* Comment */ ，但需要稍作改动。Doxygen 注释以在注释块前添加第二个 * 字符开始。例如，以下是为 Doxygen 注释宏或变量的示例：

/**
 * 注释内容
 */

当 Doxygen 解析源文件时，会识别 /** 注释块，并将整个注释与相应的宏或变量关联起来。所有 Doxygen 块都以 /** 开头，但并非每个 C 语言结构的注释方式都完全相同。下面我们来看看一些常见声明的注释块应如何正确格式化。