使用Doxygen工具时的七个关键提示

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

Doxygen支持许多不同的编程语言，其默认值不一定能为C语言提供最佳输出。当使用Doxygen配置工具Doxywizard时，开发人员应选择“优化C输出”选项。选择按钮位于模式选项卡下，如图1所示。如果正在使用C ++，请选择其中一个选项来优化C ++的输出。

图1 - 设置“优化C输出”选项

提示2 -使用模块模板一致的文档

Doxygen扫描代码库，寻找以/**开头的注释块，开发人员可以通过在代码块中使用Doxygen标记来指定对特定注释的专门处理。 （标签很容易被发现，因为它们以@开头。）例如，@ file标签将通知Doxygen，后面的注释提供了模块的文件名。图2显示了带有Doxygen标记的注释块的示例。

图2 - Doxygen注释块

但Doxygen支持100多个不同的标签，这意味着使用Doxygen记录软件具有潜力很快就搞砸了。将Doxygen与嵌入式软件一起使用的最佳建议之一是为头文件和源文件创建模板。模板文件应包含示例代码块和标头，然后可以在实现阶段使用它们。可以在此处找到模板外观的示例。

提示3 -创建主页

Doxygen将扫描开发人员在配置文件中发出的任何文件类型，并具有能够解析称为主页的特殊类型的文件。主页面是一个用户可配置的页面，默认情况下在加载HTML文档时显示，或者出现在生成的RTF文件的开头。主页面是开发人员描述项目，背景和任何可能对手册读者有用的编码约定的理想场所。

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

项目是什么以及它的目的是什么

编码标准的链接

指向项目的C样式指南的链接

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

版本日志

使用的常规Doxygen约定

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

有用的工具以及它们在项目中的使用方式

提示4 -使用GraphViz中的点工具

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

类图

依赖关系图表

调用图表

调用图表

点生成的图表可以使用图形表示为开发人员提供对软件的深入了解，允许快速浏览漂亮的图片以提供深刻见解。

提示5 -对于HTML，生成树视图

默认情况下，Doxygen会生成一个HTML输出中的顶级菜单，开发人员可以从中导航代码库。顶部菜单很有用，但生成树视图是一种更有效的导航方法。可以通过专家HTML选项卡启用选项GENERATE_TREEVIEW来创建树视图。

提示6 -不要将Doxygen添加到编译器命令行

一旦开发人员开始使用Doxygen它就可以了每次编译代码库时，都很想通过编译器命令行调用Doxygen。但是，在每个编译时解析文档的代码库是一个很大的错误，因为Doxygen可能需要“很长”的时间来解析文件并生成文档。时间的流逝可能会大大减缓开发速度。相反，开发人员应该在将任何新开发的软件添加到版本控制系统之前创建文档。

提示7 -做将Doxygen评论添加到C风格指南中

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