嵌入式开发：使用Doxygen记录嵌入式代码的7个技巧

对于有纪律的嵌入式开发人员来说，Doxygen 是一个了不起的工具，他们希望快速生成与他们的代码保持同步的软件手册。它扫描您的代码，解析出开发人员的注释，并将注释与软件对象和功能相关联。结果输出可以是链接的HTML、rtf或LaTex文件，然后作为应用程序的知识主体。然而，为了充分利用Doxygen，开发人员在使用该工具时应该记住这七个关键技巧。

技巧1——优化C语言的输出

Doxygen支持许多不同的编程语言，它的默认值不一定能为C语言提供最好的输出。当使用Doxygen配置工具Doxywizard时，开发人员应该选择“为C优化输出”选项。选择按钮位于mode选项卡下。

技巧2——使用模块模板以获得一致的文档

Doxygen扫描代码库，寻找以/**开头的注释块，嵌入式开发人员可以通过在代码块中使用Doxygen标记来指定特定注释的特殊处理。(标签很容易被发现，因为它们以@开头。)例如,@file标签将通知Doxygen后面的注释提供了模块的文件名。图2展示了一个带有Doxygen标签的注释块的例子。

但是Doxygen支持100多种不同的标签，这意味着使用Doxygen编写软件文档可能会很快变得混乱。在嵌入式软件中使用Doxygen的最佳建议之一是为头文件和源文件创建一个模板。模板文件应该包含示例代码块和头文件，以便在实现阶段使用。

技巧3——创建主页

Doxygen将从配置文件中扫描嵌入式开发人员告诉它的任何文件类型，并能够解析一种称为主页的特殊类型的文件。主页是一个用户可配置的页面，默认情况下在加载HTML文档时显示，或者出现在生成的RTF文件的开头。对于开发人员来说，主页是描述项目、背景和任何可能对手册读者有用的编码约定的最佳地方。

主页通常会描述以下内容：

项目是什么，目的是什么

链接到编码标准

链接到项目的C风格指南

代码库中使用的任何缩写的概述

版本日志

使用的一般Doxygen惯例

可能有用的项目文档的链接

有用的工具以及它们如何在项目中使用

技巧4——使用GraphViz的点工具

从GraphViz包中启用点工具为Doxygen提供了一个非常强大的图形选项，允许嵌入式开发人员生成如下图形：

类图

依赖图

调用图

被调用图

点生成的图形可以使用图形表示向开发人员提供对软件的洞察力，允许快速浏览漂亮的图片以提供很好的洞察力。

技巧5——对于HTML，生成树形视图

默认情况下，Doxygen将在其HTML输出中生成一个顶部菜单，开发人员可以通过该菜单浏览代码库。顶部菜单很有帮助，但是生成树形视图是一种更有效的导航方法。可以通过expert HTML选项卡启用GENERATE_TREEVIEW选项来创建树视图。

技巧6——不将Doxygen添加到编译器命令行

一旦嵌入式开发人员开始使用Doxygen，每次编译代码库时，通过编译器命令行调用Doxygen会很有诱惑力。但是，每次编译时都解析文档的代码库是一个很大的错误，因为Doxygen可能需要“很长”时间来解析文件和生成文档。时间的冲击会大大降低开发速度。相反，开发人员应该在将任何新开发的软件添加到版本控制系统之前创建文档。

技巧7——做将Doxygen注释添加到C风格指南中

开发团队应该使用C风格指南，告诉工程师在开发过程中要使用的风格惯例。风格指南应该反映Doxygen模板和约定，以便为嵌入式开发人员提供如何在整个代码库中一致地编写注释的指导。采用Doxygen也应该导致对这个重要的开发团队文档的更新。