轻松编写代码– Part 1

介绍

嵌入式软件开发中最重要但也是最被忽略的任务之一就是编写和维护文档。作为软件工程师,我们通常从记录所有内容开始做起,但是当压力加大时,老板会吐口气,客户很高兴看到一个功能性的原型,世界快要崩溃了,我们把头埋在代码中,然后尽快地把它搞清楚。我们欺骗自己,让我们相信只要在截止日期和时间到了,我们就会更新该软件文档。实际上,该代码要么没有文档记录,要么到处撒满了思想和胡言乱语,匆忙尝试为混乱中的事物提供照明。

文档是我们工作中乏味且无聊的一部分,我们谁都不想这样做,但是如果我们不这样做,维护和更新代码可能会成为同级开发人员的噩梦,甚至会成为我们自己遗忘的未来版本。挑战文档的开发人员已经摆在我们面前,并且有许多独特的工具可以减轻我们的负担。这些工具扫描我们的源代码,并允许我们通过将已经包含在代码中的注释转换为文档来自动生成文档。执行此功能的软件工具的几个示例包括JavaDocs,NaturalDocs和我一直以来最喜欢的文章,也是Doxygen。

“ Doxygen是一个用于C ++,C,Java,Objective-C,Python,IDL(Corba和Microsoft风格),Fortran,VHDL,PHP,C#和某种程度上D的文档系统。” [1] Doxygen提供了许多希望保持其文档与源代码实际工作保持一致并保持最新状态的软件开发人员的优势。除了其免费价格很难被击败(我还没有发现有人愿意付钱给我使用他们的软件),Doxygen允许我们使用标头,源文件和其他文本文件中的注释来生成HTML,RTF或PDF等常见格式的文档。Doxygen允许开发人员通过浏览文件,类,程序中使用的模块,变量和其他类型,以及生成图形以显示它们之间如何交互的图形。

您可以包含几乎所有类型的数据,包括图像和方程式。所有源代码均可用并托管在SourceForge上,这使我们(如果我们难以入睡或完全好奇)可以深入了解该软件的精髓更为重要的是,Doxygen已被各种软件学科广泛使用和提供支持,并且十多年来至少每年进行三次功能改进和更新,可以根据需要进行定制。通过支持多种平台和多种编程语言,几乎所有程序员都可以使用。

为了减少开发文档的时间,本文将引导开发人员逐步完成Doxygen的安装,配置和代码文档的基础知识,最终结果将是一系列可用的模板和配置文件,这些模板和配置文件可用于由开发人员快速启动几乎所有代码项目的文档。

安装

Doxygen的家位于 www.doxygen.org 可以从页面右侧的下载链接下载安装文件。虽然你们中的很多人都不愿意,但我还是在Windows平台上安装了我的Doxygen版本。这样做时,还有许多其他软件包需要如果要生成Pdf和更美观的图形,请同时进行安装。但是,首先,请下载并安装Doxygen作为您选择的操作系统。

接下来,从以下位置下载并安装Graphviz http://www.graphviz.org/。 Graphviz是AT提供的开源图形可视化资源&T研究。稍后,我们将通过在配置文件中启用HAVE_DOT函数来使用此软件包,以允许Graphviz生成图形。这导致更具视觉吸引力的结果。

最后,为了将我们的文档转换为Pdf,您将需要安装LaTex(对于Windows用户,我强烈建议使用MikTex)和Ghost Script。这两个软件包一起可以生成pdf。

在代码项目目录中为文档设置默认目录结构。例如C:ProjectDocsoutput,C:Project Docsimages和C:Project Docsconfig。 Docs文件夹将用于存储与doxygen相关的文件。可以在此文章文件中找到基准目录结构,可以从以下文件下载文件 www.beningo.com/resources/doxy-110123.zip。输出文件夹是我们生成的文档所在的位置。图像是我们将要存储在文档中的任何图像的位置(稍后将对此进行详细介绍),最后config文件夹将用于存储我们的项目配置文件。

基本配置文件设置

使用Windows的优点之一是命令提示和命令选项的陈旧乏味已经成为过去(好吧,我承认我仍然使用ipconfig之类的命令提示符,但我可以假装对吗?)。使用名为DoxyWizard的用户界面可用于设置Doxygen配置文件。DoxyWizard位于doxygen / bin目录中。

DoxyWizard分为一个选项卡式用户界面,每个选项卡都是设置项目的垫脚石。首先,我们有一个向导选项卡,对于配置初始项目设置(例如项目名称,徽标,源位置和位置)非常有用。接下来,在输入了基础知识的情况下,专家选项卡允许对Doxygen进行文件扩展名,消息,html和许多其他选项等参数的微调。最后,我们有运行选项卡,可以执行Doxygen根据配置文件参数并建立我们的文档。

使用Doxygen向导选项卡非常简单,在项目下输入项目名称,简短描述,然后输入版本或ID如果您的项目有徽标,则可以选择徽标文件,徽标将显示在html标头中的每个html文档页面。还可以输入文档的源代码和目标目录的主目录。设置页面的示例如图1所示。

强力蜥蜴

图1:DoxyWizard项目设置

在模式菜单中,我们可以选择提取模式和所使用的编程语言。对于此示例,我们将仅提取文档化的实体并优化C的输出。图2显示了一个示例,该示例显示了正确配置后模式页的外观。

图2:DoxyWizard模式设置

输出选项使我们能够选择要生成的文件类型的doxygen。对于此示例,我们将只生成html文档,但也可以生成LaTex或RTF文件。如果要更改html页面的颜色,则可以使用“更改颜色”按钮进行修改。输出配置示例如图3所示。

图3:DoxyWizard输出设置

最后,图表页面允许我们选择将要通过文档生成的图表。安装了GraphViz后,我们将选择使用点工具。我们可以选择要生成的图。为了更好地理解函数调用的深度,生成调用和由图形调用非常有用。配置的图部分可在图4中找到。

图4:DoxyWizard图设置

此时Doxygen有足够的配置信息供我们生成第一套文档。这可以通过简单地移至运行选项卡并按“ Run Doxygen”按钮来完成。Doxygen将在配置文件上咀嚼一会儿,然后开始处理整个源存储库。此外,它将生成我们要求其生成的任何图表。当状态窗口中显示“ *** Doxygen完成”时,按“显示HTML输出”按钮将打开HTML我们刚刚生成的文档。

恭喜!您只花了一步就减少了花在编写文档上的时间和更多的时间。

发表评论

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

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