帮助文档.doc

简介Doxygen
简介Doxygen 1
什么是Doxygen? 1
安装Doxygen 2
设定Project的doxygen组态 2
撰写正确格式的批注 5
制作说明文件 11
什么是Doxygen?
Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用您的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于您来说,就是沉重的负担。
一个好的程序设计师,在写程序时,都会在适当的地方加上合适的批注。如果,能够在撰写批注时,稍微符合某种格式,接着就可以透过一个工具程序依据程序结构及您的批注产生出漂亮的檔。这将令许多工作繁重的程序设计师有时间多喝几杯咖啡。
Doxygen 就是这样的一个工具。在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的檔了。因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生檔。
目前Doxygen可处理的程序语言包含:
C/C++
Java
IDL (Corba, Microsoft及KDE-DCOP类型)  
而可产生出来的檔格式有:
HTML
XML
LaTeX
RTF
Unix Man Page
而其中还可衍生出不少其它格式。如有了LaTeX 档后,就可以透过一些工具产生出PS或是PDF档案。
在多国语言的支持方面,Doxygen 目前可支持的约有2,30种。自Doxygen (这正是小弟做的好事)。所以在目前一些Open Source 的程序文件产生器中,Doxygen 算是相当完整的一套。在程序语言处理上面,Doxygen也算是少数在Borland C++ Builder 的语法下还能够正常运作的工具之一(若非如此,小弟也不
会推荐它)。
本文的目的是希望在经过仔细阅读本文之后能够给大家一个概略性的了解。以便可以很容易的上手使用Doxygen。至于Doxygen本身的详细使用,各位可以参考随着Doxygen 所附的檔。实际上,Doxygen 自己的使用手册就是使用Doxygen 产生的。您可以看到他实际上能够产生远比Reference Book更复杂的文件。
安装Doxygen
Doxygen 的安装可说十分的简单,本文仅介绍binary档案的安装,若您有兴趣从source pile起来,请自行查阅参考手册。
首先,请您先至doxygen 的网站上面抓取最新版本的doxygen 回来。目前,只要您是Linux, Solaris, Mac OS X, HP-UX, 甚至是UnixWare,pile好的binary版本可以抓取。如果是Windows 95/98/ME/NT/2000/XP,甚至还有Setup的版本可以抓取。所以安装过程可说十分简单。只要给予正确的安装目录,相信一般在安装上是不会遇到什么问题的。
另外,如果您是Linux或是Windows,可以另外抓取Doxygen Wizard的程序。这是一个辅助工具,可以很快的帮您建立一个Doxygen 的组态档案。透过这个组态档案,您就可以很快的将檔产生出来。另外,若没有使用Doxygen Wizard,还是可以使用一般的文字编辑器将这个组态檔制作出来。
若安装成功,您应该可以看到doxygen 这个执行文件出现在您的系统中。若是Windows 平台,则可看到在程序集中有Doxygen 这个Folder出现。
设定Project的doxygen组态
Doxygen 产生檔可以分为三个步骤。一是为Project 建立组态檔,二是在程序代码中加上符合Doxygen所定义批注格式。三是使用Doxygen来产生批注。
因此,第一步就是为您的Project 制作Doxygen 的组态档案。这个所谓的组态档案,格式其实与很简单。就是一些Key 与值的设定。每个设定为一行。若第一行开头为"#" 表示该行为批注。Doxygen 会忽略它。每个设定行的格式有两种,分别如下:
TAG = value [value, ...]
及
TAG += value [value, ...]
第一种形式是最常见的,也就是要设定一个TAG (也就是一个Key ),他的值为右边所定义的部分。原则上每个值都是单一的英文字,如果您要定义的值有空格符包含在内,可使用双引号将它括住。如果要定义的值超过一个以上,可使用