Doxygen教程.docx
《Doxygen教程.docx》由会员分享，可在线阅读，更多相关《Doxygen教程.docx（14页珍藏版）》请在冰豆网上搜索。
Doxygen教程
简介Doxygen
简介Doxygen1
什么是Doxygen?
1
安装Doxygen2
设定Project的doxygen组态2
撰写正确格式的批注5
制作说明文件11
什么是Doxygen?
Doxygen是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。
通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。
大部分有用的批注都是属于针对函式，类别等等的说明。
所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。
不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。
一个好的程序设计师，在写程序时，都会在适当的地方加上合适的批注。
如果，能够在撰写批注时，稍微符合某种格式，接着就可以透过一个工具程序依据程序结构及您的批注产生出漂亮的檔。
这将令许多工作繁重的程序设计师有时间多喝几杯咖啡。
Doxygen就是这样的一个工具。
在您写批注时，稍微按照一些它所制订的规则。
接着，他就可以帮您产生出漂亮的檔了。
因此，Doxygen的使用可分为两大部分。
首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生檔。
目前Doxygen可处理的程序语言包含：
∙C/C++
∙Java
∙IDL（Corba,Microsoft及KDE-DCOP类型）
而可产生出来的檔格式有：
∙HTML
∙XML
∙LaTeX
∙RTF
∙UnixManPage
而其中还可衍生出不少其它格式。
如有了LaTeX档后，就可以透过一些工具产生出PS或是PDF档案。
在多国语言的支持方面，Doxygen目前可支持的约有2,30种。
自Doxygen1.2.16开始支持繁体中文（这正是小弟做的好事）。
所以在目前一些OpenSource的程序文件产生器中，Doxygen算是相当完整的一套。
在程序语言处理上面，Doxygen也算是少数在BorlandC++Builder的语法下还能够正常运作的工具之一（若非如此，小弟也不会推荐它）。
本文的目的是希望在经过仔细阅读本文之后能够给大家一个概略性的了解。
以便可以很容易的上手使用Doxygen。
至于Doxygen本身的详细使用，各位可以参考随着Doxygen所附的檔。
实际上，Doxygen自己的使用手册就是使用Doxygen产生的。
您可以看到他实际上能够产生远比ReferenceBook更复杂的文件。
安装Doxygen
Doxygen的安装可说十分的简单，本文仅介绍binary档案的安装，若您有兴趣从sourcecode重新compile起来，请自行查阅参考手册。
首先，请您先至doxygen的网站上面抓取最新版本的doxygen回来。
目前，只要您是Linux,Solaris,MacOSX,HP-UX,甚至是UnixWare，都有compile好的binary版本可以抓取。
如果是Windows95/98/ME/NT/2000/XP，甚至还有Setup的版本可以抓取。
所以安装过程可说十分简单。
只要给予正确的安装目录，相信一般在安装上是不会遇到什么问题的。
另外，如果您是Linux或是Windows，可以另外抓取DoxygenWizard的程序。
这是一个辅助工具，可以很快的帮您建立一个Doxygen的组态档案。
透过这个组态档案，您就可以很快的将檔产生出来。
另外，若没有使用DoxygenWizard，还是可以使用一般的文字编辑器将这个组态檔制作出来。
若安装成功，您应该可以看到doxygen这个执行文件出现在您的系统中。
若是Windows平台，则可看到在程序集中有Doxygen这个Folder出现。
设定Project的doxygen组态
Doxygen产生檔可以分为三个步骤。
一是为Project建立组态檔，二是在程序代码中加上符合Doxygen所定义批注格式。
三是使用Doxygen来产生批注。
因此，第一步就是为您的Project制作Doxygen的组态档案。
这个所谓的组态档案，格式其实与很简单。
就是一些Key与值的设定。
每个设定为一行。
若第一行开头为"#"表示该行为批注。
Doxygen会忽略它。
每个设定行的格式有两种，分别如下：
TAG=value[value,...]
及
TAG+=value[value,...]
第一种形式是最常见的，也就是要设定一个TAG（也就是一个Key），他的值为右边所定义的部分。
原则上每个值都是单一的英文字，如果您要定义的值有空格符包含在内，可使用双引号将它括住。
如果要定义的值超过一个以上，可使用逗号","予以分隔开来。
如果您要定义的TAG是属于表列型态的，也就是他会有很多的值分别以逗号隔开。
在Doxygen组态檔中允许您在不同的地方重复定义。
只是后面的定义应使用上面所说的第二种形式。
此种形式会将前后两个定义的值合并在一起。
知道这个基本格式后，剩下就是根据各个TAG的意义来进行设定。
关于TAG的定义很多，此处我们仅针对必要用到的TAG进行说明，剩下的部分请自行翻阅使用说明。
由于Doxygen的TAG还算不少，为了方便使用，Doxygen自身提供了一个方便的选项，可以帮您建立一份空白的Doxygen档案（Doxygen是Doxygen预设的组态檔名）。
>doxygenDoxygen
透过这个命令，您可以得到一个Doxygen档案，接下来就可使用一般的文字编辑器来进行编辑。
下面将针对几个必要的TAG进行说明：
PROJECT_NAME
Project的名字，以一个单字为主，多个单字请使用双引号括住。
PROJECT_VERSION
Project的版本号码。
OUTPUT_DIRECTORY
输出路径。
产生的文件会放在这个路径之下。
如果没有填这个路径，将会以目前所在路径来作为输出路径。
OUTPUT_LANGUAGE
输出语言。
预设为English。
1.2.16版后，您可以使用Chinese-Traditional来输出中文繁体的格式。
INPUT
指定加载或找寻要处理的程序代码档案路径。
这边是一个表列式的型态。
并且可指定档案及路径。
举例来说若您有a.c,b.c,c.c三个档案。
您可使用INPUT=a.c,b.c,c.c的方式。
若您给定一个目录，该目录下面所有档案都会被处理。
FILE_PATTERNS
如果您的INPUTTag中指定了目录。
您可以透过这个Tag来要求Doxygen在处理时，只针对特定的档案进行动作。
例如：
您希望对目录下的扩展名为.c,.cpp及.h的档案作处理。
您可设定FILE_PATTERNS=*.c,*.cpp,*.h。
RECURSIVE
这是一个布尔值的Tag，只接受YES或NO。
当设定为YES时，INPUT所指定目录的所有子目录都会被处理。
EXCLUDE
如果您有某几个特定档案或是目录，不希望经过Doxygen处理。
您可在这个Tag中指定。
EXCLUDE_PATTERNS
类似于FILE_PATTERNS的用法，只是这个Tag是供EXCLUDE所使用。
SOURCE_BROWSER
如果设定为YES，则Doxygen会产生出源文件的列表，以供查阅。
INLINE_SOURCES
如果设定为YES，则程序代码也会被嵌入于说明文件中。
ALPHABETICAL_INDEX
如果设定为YES，则一个依照字母排序的列表会加入在产生的文件中。
GENERATE_HTML
若设定为YES，就会产生HTML版本的说明檔。
HTML檔是Doxygen预设产生的格式之一。
HTML_OUTPUT
HTML文件的输出目录。
这是一个相对路径，所以实际的路径为OUTPUT_DIRECTORY加上HTML_OUTPUT。
这个设定预设为html。
HTML_FILE_EXTENSION
HTML文件的扩展名。
预设为.html。
HTML_HEADER
要使用在每一页HTML檔中的Header。
如果没有指定，Doxygen会使用自己预设的Header。
HTML_FOOTER
要使用在每一页HTML檔中的Footer。
如果没有指定，Doxygen会使用自己预设的Footer。
HTML_STYLESHEET
您可给定一个CSS的设定，让HTML的输出结果更完美。
GENERATE_HTMLHELP
如设定为YES，Doxygen会产生一个索引文件。
这个索引文件在您需要制作windows上的HTML格式的HELP档案时会用的上。
GENERATE_TREEVIEW
若设定为YES，Doxygen会帮您产生一个树状结构，在画面左侧。
这个树状结构是以JavaScript所写成。
所以需要新版的Browser才能正确显示。
TREEVIEW_WIDTH
用来设定树状结构在画面上的宽度。
GENERATE_LATEX
设定为YES时，会产生LaTeX的文件。
不过您的系统必需要有安装LaTeX的相关工具。
LATEX_OUTPUT
LaTeX文件的输出目录，与HTML_OUTPUT用法相同，一样是指在OUTPUT_DIRECTORY之下的路径。
预设为latex。
LATEX_CMD_NAME
LaTeX程序的命令名称及档案所在。
预设为latex。
GENERATE_RTF
若设定为YES，则会产生RTF格式的说明檔。
RTF_OUTPUT
与HTML_OUTPUT用法相同，用来指定RTF输出档案路径。
预设为rtf。
GENERATE_MAN
若设定为YES，则会产生UnixManPage格式的说明檔。
MAN_OUTPUT
与HTML_OUTPUT用法相同，用来指定ManPage的输出目录。
预设为man。
GENERATE_XML
若设定为YES，则会产生XML格式的说明檔。
ENABLE_PREPROCESSING
若设定为YES，则Doxygen会启动C的前置处理器来处理原始檔。
PREDEFINED
可以让您自行定义一些宏。
类似于gcc中的-D选项。
若上面这些基本的Tag都设定正确，接下来就是将您的SourceCode
批注修改成为正确的格式。
若您觉得用一般文字编辑器来编辑组态檔
很麻烦，建议您可以使用DoxygenWizard这个工具程序。
他可以很快
的建构出您所需要的Doxygen档案。
撰写正确格式的批注
并非所有程序代码中的批注都会被Doxygen所处理。
您必需依照正确的
格式撰写。
原则上，Doxygen仅处理与程序结构相关的批注，如
Function，Class，档案的批注等。
对于Function内部的批注则不做
处理。
Doxygen可处理下面几种类型的批注。
JavaDoc类型：
/**
*...批注...
*/
Qt类型：
/*!
*...批注...
*/
单行型式的批注：
///...批注...
或
//!
...批注...
要使用哪种型态完全看自己的喜好。
以笔者自己来说，大范围的注
解我会使用JavaDoc型的。
单行的批注则使用"///"的类型。
此外，由于Doxygen对于批注是视为在解释后面的程序代码。
也就是
说，任何一个批注都是在说明其后的程序代码。
如果要批注前面的程
式码则需用下面格式的批注符号。
/*!
<...批注...*/
/**<...批注...*/
//!
<...批注...
///<...批注...
上面这个方式并不适用于任何地方，只能用在class的member或是
function的参数上。
举例来说，若我们有下面这样的class。
classMyClass{
public:
intmember1;
intmember2:
voidmember_function（）;
};
加上批注后，就变成这样：
/**
*我的自订类别说明...
*/
classMyClass{
public:
intmember1;///<第一个member说明...
intmember2:
///<第二个member说明...
intmember_function（inta,intb）;
};
/**
*自订类别的member_funtion说明...
*
*@parama参数a的说明
*@paramb参数b的说明
*
*@return传回a+b。
*/
intMyClass:
:
member_function（inta,intb）
{
returna+b;
}
当您使用Doxygen产生说明檔时，Doxygen会帮您parsing您的程
式码。
并且依据程序结构建立对应的文件。
然后再将您的批注，依据
其位置套入于正确的地方。
您可能已经注意到，除了一般文字说明外
，还有一些其它特别的指令，像是@param及@return等。
这正是
Doxygen另外一个重要的部分，因为一个类别或是函式其实都有固定
几个要说明的部分。
为了让Doxygen能够判断，所有我们就必需使用
这些指令，来告诉Doxygen后面的批注是在说明什么东西。
Doxygen
在处理时，就会帮您把这些部分做特别的处理或是排版。
甚至是制作
参考连结。
首先，我们先说明在Doxygen中对于类别或是函数批注的一个特定格
式。
/**
*class或function的简易说明...
*
*class或function的详细说明...
*...
*/
上面这个例子要说的是，在Doxygen处理一个class或是function注
解时，会先判断第一行为简易说明。
这个简易说明将一直到空一行的
出现。
或是遇到第一个"."为止。
之后的批注将会被视为详细说明。
两者的差异在于Doxygen在某些地方只会显示简易说明，而不显示详
细说明。
如：
class或function的列表。
另一种比较清楚的方式是指定@brief的指令。
这将会明确的告诉
Doxygen，何者是简易说明。
例如：
/**
*@briefclass或function的简易说明...
*
*class或function的详细说明...
*...
*/
除了这个class及function外，Doxygen也可针对档案做说明，条件
是该批注需置于档案的前面。
主要也是利用一些指令，通常这部分注
解都会放在档案的开始地方。
如：
/*!
\filemyfile.h
\brief档案简易说明
详细说明.
\author作者信息
*/
如您所见，档案批注约略格式如上，请别被"\"所搞混。
其实，"\"
与"@"都是一样的，都是告诉Doxygen后面是一个指令。
两种在
Doxygen都可使用。
笔者自己比较偏好使用"@"。
接着我们来针对一些常用的指令做说明：
@file
档案的批注说明。
@author
作者的信息
@brief
用于class或function的批注中，后面为class或function的简易说明。
@param
格式为
@paramarg_name参数说明
主要用于函式说明中，后面接参数的名字，然后再接关于该参数的说明。
@return
后面接函数传回值的说明。
用于function的批注中。
说明该函数的传回值。
@retval
格式为
@retvalvalue传回值说明
主要用于函式说明中，说明特定传回值的意义。
所以后面要先接一个传回值。
然后在放该传回值的说明。
Doxygen所支持的指令很多，有些甚至是关于输出排版的控制。
您可从Doxygen的使用说明中找到详尽的说明。
下面我们准备一组example.h及example.cpp来说明Doxygen批注的使用方式：
example.h:
/**
*@file本范例的include档案。
*
*这个档案只定义example这个class。
*
*@authorgarylee@localhost
*/
#defineEXAMPLE_OK 0 ///<定义EXAMPLE_OK的宏为0。
/**
*@briefExampleclass的简易说明
*
*本范例说明Exampleclass。
*这是一个极为简单的范例。
*
*/
classExample{
private:
intvar1;///<这是一个private的变数
public:
intvar2;///<这是一个public的变数成员。
intvar3;///<这是另一个public的变数成员。
voidExFunc1（void）;
intExFunc2（inta,charb）;
char*ExFunc3（char*c）;
};
example.cpp:
/**
*@file本范例的程序代码档案。
*
*这个档案用来定义example这个class的
*memberfunction。
*
*@authorgarylee@localhost
*/
/**
*@briefExFunc1的简易说明
*
*ExFunc1没有任何参数及传回值。
*/
voidExample:
:
ExFunc1（void）
{
//emptyfuncion.
}
/**
*@briefExFunc2的简易说明
*
*ExFunc3（）传回两个参数相加的值。
*
*@parama用来相加的参数。
*@paramb用来相加的参数。
*@return传回两个参数相加的结果。
*/
intExFunc2（inta,charb）
{
return（a+b）;
}
/**
*@briefExFunc3的简易说明
*
*ExFunc3（）只传回参数输入的指标。
*
*@paramc传进的字符指针。
*@retvalNULL空字符串。
*@retval!
NULL非空字符串。
*/
char*ExFunc2（char*c）
{
returnc;
}
上面这两个档案很简单的说明了Doxygen批注的使用方式。
您可依照此要领在你自己的程序代码中加上对应的批注。
其实，无论您有无使用Doxygen，都不妨依照他的格式将批注写入，一方面是依照他的格式，并不会干扰您程序的运作。
另一方面，Doxygen所定义的都是基本程序批注应当要有的东西。
撰写清楚的批注是好的程序设计师应当的工作。
制作说明文件
当您前面所有的步骤都正确无误执行后，只需要执行下面的命令就可建立出您要的文件了：
>doxygenDoxygen
如果有错误产生，请检查您的Doxygen组态檔设定是否有误，目录的存取权限是否足够。
如果输出的结果不正确，请检查您的批注是否符合格式。
批注的位置是否正确。
举例来说，您不可在说明class的批注与class本身插入其它的程序代码或宣告。
否则Doxygen就无法将批注与该class对应起来。
如果您使用DoxygenWizard，可直接使用上面的Run的按钮或选单项目来制作说明文件。
如果是产生HTML檔，在HTML_OUTPUT所指定的目录中的index.html将是您说明文件的首页。
在中文繁体方面，目前我仅成功制作出HTML与RTF格式的说明檔。
其它格式的过程比较复杂，需要搭配其它工具，有待各位自行尝试。
升级会员 