文档领域中的一阵清风

Doxygen:文档领域中的一阵清风

作者: BUILDER.COM
Monday, December 30 2002 12:14 PM 

Doxygen是一种适合C风格语言(如C++、C、IDL、Java甚至包括C#和PHP)的、开放源码的、基于命令行的文档产生器。除了是开放源码、可以公用这一特征外,Doxygen与其它商业软件,如JavaDoc,的区别还在于它广泛支持各种文档格式。它除了可以建立HTML文档外,还可以建立LATEX、PDF、RTF、PostScript、压缩HTML(微软HTML帮助文件兼容格式)、甚至还甚至包括*NIX man page格式。Doxygen的灵活性甚至可以用它来建立用户一级的文档文件:Doxyen的作者在用户手册说这么做是可行的,不过是“杀鸡用了宰牛刀”而已。Doxygen甚至包括了内建的C宏的预处理器。

灵活性与强大的功能

当第一次浏览用户手册时,你可能被Doxygen显示出来的复杂性吓倒。但是它并不一定复杂——你可以随心所欲的控制事情的复杂性。Doxygen的灵活性常常令人惊叹。

如果你想建立一个简单的文档,你只需要知道几个相关的注释风格,如果你曾经用过JavaDoc,那么其中某些风格你可能会觉得比较熟悉。如果你想使用更高级的功能,你可以利用特定的格式能力来在你的文档中使用特定格式列表、图表、甚至到源代码块的链接。如果你的同事需要审查你的代码或者你需要应用程序的内在结构进行文档整理,后者(到源代码块的链接)特别有用。

Doxygen使用了一个基于文本的配置文件,你可以在配置文件中设定大量的选项来控制Doxygen的行为。它支持文件和路径匹配的模式来控制Doxygen检测的是哪个文件,并递归扫描配置文件所设置的目录。由于Doxygen把它的配置文件名作为命令行的一个参数,所以你可以也最好为多个项目建立多个配置文件。如果你不喜欢手工编辑文本文件,Doxywizard工具可以提供一个GUI来修改配置文件。

用Doxygen建立文档的方法

启动Doxygen的最好方法就是在命令行中使用-g开关,这样它就会为你产生一个配置文件模板。或者你可以用Doxywizard工具代替手工来创建配置文件。在配置文件中,有许许多多选项需要你选择,很快就会让你不知所以然。综合手册有对全部选项都有解释。

默认情况下,Doxygen忽略常规(regular)注释,你可以通过修改配置文件中相关选项来强制Doxygen包括常规注释。Doxygen使用两种特殊注释类型:简洁的和详细的。简洁型的注释就是对代码结构进行简洁的、一行的描述,在C风格注释引导符后另加一个前向斜杠或者感叹号表示简洁型注释的开始,如下所示:

/// 这是一个简洁型的注释
//! 这也是一个简洁型的注释

详细型的注释,也就是多行注释,可以给出更深入详细的注释。这通过在C风格多行注释(块注释)引导符后加一个感叹号来实现,如下所示:

/*!
这是详细型的注释
...
...
*/

也可以使用JavaDoc的多行格式(/** … */)。这两种注释类型出现在所产生的文档的不同地方。在线用户手册中有一篇文章给出了C++编程方面的例子,所以我在这里就不重复了。尽管只用Doxygen的这两种基本注释类型就可以建立足以建立文档了,不过如果你需要更多复杂功能,Doxygen还可以提供高级格式如组(group)和列表。

反向工程文档

Doxygen的功能不会局限于简单的注释扩展,它还可以从源代码文件中创建继承关系图,并用不同的颜色表示不同的元素和元素间不同的关系。通过使用一个叫着dot的第三方文档工具,继承关系图可以变得相当复杂、详尽。如果你需要对现有的源代码进行反向工程,这个功能就显得特别重要了,它还可以帮助你分析其他人的没有很好文档组织的源文件——这原本是一件很可怕的任务。现在,让我们再次看看在线用户手册中关于Doxygen可建立的图表分类。

总结

Doxygen为C++和C#开发者提供了类似JavaDoc那样的高级文档产生功能。它易于使用且功能强大,而且有着极强的灵活性。

*译者注:反向工程意思与正向工程相反,意思是通过分析他人的设计资料来逆向获取原始设计,如通过分析印刷电路版图来获得电路原理图。这里的意思指的是分析他人的代码(没有注释或者注释很糟糕)来得到原作者的设计思路、实现方法,这样自己就可以根据需要进行相应的修改。


-- ZoomQuiet (2004-12-22)

DoxygenIntro (last edited 2009-12-25 07:16:17 by localhost)