轻松编写代码– Part 2

高级配置文件设置

DoxyWizard中的向导选项卡使我们能够快速启动和运行Doxygen,但是只有在Expert选项卡中可以使用许多可自定义的选项,因此在开始详细讨论如何使用源代码之前文件,我们将首先探讨专家用户可用的一些非常有用的选项。

项目主题下的JAVADOC_AUTOBRIEF选项使Doxygen能够将注释的第一行识别为简短描述。这可以通过不在命令中明确指定简短命令来节省时间。因此,我们始终假定语句的第一行是简要概述。

专家输入主题具有一些非常有用的功能,这些功能使我们可以覆盖由向导生成的默认输入。除了指定文件模式(例如* .c),设置映像目录以及开发人员可能会觉得有用的其他选项外,我们还可以指定单个源目录。我们还可以排除文件和目录,并指定Doxygen应该在输入中使用的过滤方案。

默认情况下,Doxygen不会生成导航框架。该导航框架显示在HTML页面的左侧,并且使我们能够导航html文档中的任何位置而不必在顶部菜单中跳转。 ,在DoxyWizard中的HTML主题下,必须选择GENERATE_TREEVIEW选项。

最后,点主题允许我们对图进行详细控制,我们可以指定点字体,使用DOT_IMAGE_FORMAT控制图像格式,指定目录,外观以及可在图中生成的最大节点数。

通过对配置文件的这些更新,Doxygen生成的输出将得到更完善。在这一点上,我们可以开始开发代码,但首先,我们将为我们的文档构建一个MainPage,该文档将为阅读文档的任何人提供概述和有关如何使用文档的说明。这将概述一些有用的标记,这些标记可在我们记录代码时使用。

PDF文件

不能使用Doxygen直接生成PDF文档。但是,有一种简单的方法可以在生成LaTex文档后创建一个。在命令窗口中(如我所说,我假装没有使用命令提示符)导航到/ latex文件夹并键入$ make。是位于/ latex文件夹中的名为refman.pdf的PDF文档。

生成主页

当有人打开我们的文档时,我们希望他们看到带有一系列Web链接的目录,然后他们可以用来导航到有关项目和源代码的有用信息。总的来说,有人希望在主页上看到什么类型的东西?经过一番思考和一些安息的睡眠后(幸运的是,这个问题并没有引起我失去足够的睡眠),我决定在主页上添加以下内容

–简介(整个内容是关于什么的?)

–版本日志(这是什么版本,以及版本之间的变化如何)

–首字母缩写词(所有这些有趣的术语是什么意思?)

–API(需要说明驱动程序的API吗?)

–编码标准(我们的代码约定是什么?我们如何命名事物)

–文档(我们如何记录事物)

–项目需求(我们必须做的事情的简要概述)

–测试和验证(我们如何证明该版本确实有效)

–工具(我们用来开发项目的工具,例如编译器,ide,lint,svn等)

要创建主页,我们将命名为文本文件Overview .txt,并将我们需要的所有内容放入主页中,我们必须确保将概述文档放置在源文件的doxygen路径中的任何位置我们将查看此处使用的主要标签,但请参见示例模板以获取完整功能的版本。

在开发主页时,可以使用两种主要方法来创建目录的效果:一种是将整个目录数据集中到一个文件中(overview.txt);第二种是创建子页面在第二个选项中,Doxygen将其合并在一起。第二个选项主要是因为它允许一个漂亮的模块化目录结构,但是它也增加了目录的复杂性,可能超出基本用户的范围。在这一点上,我已经决定保持简单并使用单文件方法。但是,如果我创建本文的后续解释如何创建分页目录,请不要感到惊讶。

我们只需要在overview.txt顶部的注释块中使用mainpage命令来开始主页,在HTML文档中我们可以使用任何HTML标记,出于我们的目的,表1列出了其中最有用的标记。锚命令可在目录列表的每个部分上方直接创建锚,然后将创建指向目录中每个锚的链接。单击链接时,文档将跳至该锚。为使文档保持整洁,我们还希望使用水平规则标签在每个部分之间创建一条水平线。有时也可能需要在文档中强制使用回车符。<br> tag.

HTML命令

描述

<A NAME=”Contents”></A>

创建一个锚点

<A HREF=”#Introduction”>Introduction</A>

创建指向锚点的链接

<br>

在html页面上创建回车符

<hr>

创建一条水平线

表1:HTML命令

为了创建目录列表,我们将使用Doxygen的section命令。如果发现我们的一个部分应该分成较小的部分,我们也可以使用subsection命令。这将使我们能够组织主页并适当控制信息流。

与任何文档一样,我们希望在整个文档中包含图像,因为图像值1000字。只要我们想在其中包含图像,我们要做的就是使用doxygen image标签。此标记由命令图像,类型(例如html,rtf或乳胶)和文件名(例如image.jpg)组成。重要的是要注意,乳胶图像必须是封装的PostScript(eps)。如果不是,那么祝您好运,但很可能根本不会显示,或者显示错误。这确实意味着,如果您要插入图像并想要生成html,rtf和Latex文件,则需要三个单独的图像标签才能以所有三种格式显示图像。

最后,最有用的命令之一是创建项目符号列表。要在项目符号列表中的项目之前创建项目符号,只需在其前面放置一个–。有关目录模板的完整列表,请参阅相关的资源文件,从下载 www.beningo.com/resources/doxy-110123.zip.

记录代码

经过Doxygen的所有努力之后,我们终于准备好了解如何记录我们的代码了。为了快速开始这一工作和以后的工作,我在本文的资源中提供了两个模块模板。 * .h模板包含用于记录C头文件的常用类型。第二个** c模板包含用于记录C源文件的常用类型。这些文件中的一般原理通常可以继承到其他语言,但它们已创建并经过测试可在嵌入式C环境中使用。

在编写模块文档时,我们要做的第一件事就是包括file命令,以便Doxygen可以知道这是什么文件模块。如果您还记得我们的配置文件,我们还添加了JAVADOCS_BRIEF,以便在第一行注释一个文件将作为文件的概述。以下注释可以放在模块的顶部,以生成文件和简要信息。请记住,简短语句要求第一个语句以句点(。)结尾。

/ **文件physics.h

*此文件包含物理应用程序的标题定义。

*

在大多数模块中,我们有通用的“对象”类型,例如标签,宏和变量。每种类型都很容易记录,而所有三个都以完全相同的方式记录。关键是简单地输入/ **,然后输入任何内容之后将自动记录该变量。例如,以下代码段记录了一个名为METRIC_G的标签。

/ **

*用于定义重力加速度,单位为m / s ^ 2

* /

#定义METRIC_G 9.81

记录枚举,typedef,结构并不复杂。该描述与标签中的定义相同。但是,只需添加/ **即可添加成员的详细说明<Description * /之后,其中description是成员的描述。的<字符用于告诉doxygen该注释与该注释之前声明的变量相关联。如果确实需要,可以通过在定义的前面放置一个enum orstruct命令来明确指定枚举和结构之间的区别,但是Doxygen在知道它确实是不必要的且不推荐使用的文档方面做得很好。可以在下面找到记录结构的示例:

/ **

*定义两个指定航天器结构的变量。

* /

类型定义结构

{

uint8加速; / **<航天器加速的速率* /

uint8质量; / **<当前航天器的质量* /

} SpaceCraft_Type;

要记录的最复杂的嵌入式类型是函数。这是因为可以与它们关联的相对复杂性。除了引用与之关联的其他功能外,它们还具有输入和返回参数。这就是为什么创建一个可以针对每个开发的新功能进行复制,粘贴和修改的功能模板非常有用的原因。

在记录功能时,使用section标签将其分为两个部分非常有用,第一部分是Description部分,它概述了该功能的含义,功能以及使用的原因。使用return和return命令可以指定传入和传出该函数的所有参数。第二部分是示例部分。在此部分中,我们使用命令代码在doxygen中创建代码块,然后可以键入有关在应用程序中如何使用该函数的示例代码。完成示例后,我们使用endcode命令退出代码块模式。最后,如果此函数是功能模块中的单个功能,则创建链接很有用。到所有其他相关函数。这可以通过使用see命令,然后加上我们希望链接的函数的名称来完成。在本文的资源以及下面。

/ ***************************************************** *****************************

*功能:Sys_Init

* // **

*部分说明说明:

*

*此功能用于初始化系统。

*

*参数无。

*

*返回无。

*

*部分示例示例:

*代码

*

*结束码

*

*请参阅App_Init

****************************************************** ******************************** /

除了记录变量和函数外,Doxygen还可以在代码中记录待办事项。这可以通过以下格式来完成:

/ **
*这里的待办事项说明。
*
* /

结论:

在当今缩短的开发周期中,保持文档的最新性和准确性非常具有挑战性。经理们希望软件工程师能够快速,无错误且有大量文档来开发代码,但不幸的是,这三件事相互矛盾。

Doxygen使我们能够专注于手头的工作并自动生成文档,以便当老板站在我们上方时,我们不再担心稍后会被文档咬伤。

在本文中,我们回顾了Doxygen并逐步进行了设置和配置过程,其结果是开发了许多模板和项目目录,可用于快速启动下一个软件项目。

发表评论

您的电子邮件地址不会被公开。 必需的地方已做标记 *

该网站使用Akismet减少垃圾邮件。 了解如何处理您的评论数据.