|
如果您这次还没来得及使用老式的Help Workshop为您的Web应用构建文档系统的话那么何不尝试一下Doxygen需知The proof of the pudding lies in the eating Doxygen是什么？Doxygen是一种开源跨平台的以类似JavaDoc风格描述的文档系统完全支持CC++JavaObjectiveC和IDL语言部分支持PHPC#注释的语法与QtDocKDoc和JavaDoc兼容Doxgen可以从一套归档源文件开始生成HTML格式的在线类浏览器或离线的LATEXRTF参考手册对于未归档的源文件也可以通过配置Doxygen来提取代码结构或者借助自动生成的包含依赖图（include dependency graphs）继承图（inheritance diagram）以及协作图（collaboration diagram）来可视化文档之间的关系Doxygen生成的帮助文档的格式可以是CHMRTFPostScriptPDFHTML和Unix man page等 Doxygen在Linux上开发但也可以在其它的Unix平台下运行而且Windows x/NT平台下也有对应的可执行版本 安装Doxygen首先去Doxygen网站上找到最新版本的Doxygen有二进制或源码两种版本如果不想重头编译下载二进制版本安装即可在Linux下源码编译需要perl和Gnu工具flexbisonmake的支持在Windows下二进制版本勿需安装而源码编译所需支持工具较多我们仅讲述Linux下的Doxygen的源码编译以及二进制版本安装过程 编译源码 gunzip doxygen$VERSIONsrctargztar xf doxygen$VERSIONsrctarsh /configure或者configure platform platformtype（略去直接使用configure需要平台检测的过程平台类型在PLATFORMS文件中列出）configure withdoxywizard（GUI前端选项）make或者make docs（创建HTML格式的手册）make pdf（创建PDF格式的手册） 安装二进制版本 /configuremake install 二进制文件安装目录是<prefix>/bin其中<prefix>缺省为/usr可以通过configure的参数prefix修改其值使用make install_docs可以把文档和例子安装在目录<docdir>/doxygen其中<docdir>缺省为<prefix>/share/doc/packages可以通过configure的参数docdir修改其值doxygen是bin目录下的一个命令行程序它是Doxygen的核心工具完成文档的转换和生成工作 Doxygen的处理流程图是Doxygen网站上给出的Doxygen处理工具以及它们之间的信息流 从图中可以看出Doxygen可执行程序位于正中所有的流程都围绕着它进行左侧图标表示Doxygen的输入可以是源文件或者是定制的头文件图像注解等Doxygen图标上部是配置文件由Doxywizard处理下部是Tag文件由Doxytag处理后面是Doxygen输出文件的类型依次是XMLLatexMan pagesRTF和HTML可处理类型图标之后是进行进一步转换所需的工具 图Doxygen网站上给出的Doxygen信息流图 配置文件每一个Doxygen工程都有一个后缀为cfg的配置文件用来保存所有的设置配置文件的格式与autoexecbatconfigsys等文件相似是由名称/值对组成的ASCII码会由doxygen命令来解析为了简化创建和修改配置文件Doxygen可以在命令行方式下加上参数g自动创建模板文件 doxygen g <configfile> 忽略<configfile>将会生成一个名为Doxyfile的缺省文件如果<configfile>已经存在会被Doxygen改名为<configfile>bak 实际上我们根本就不需要用一般的编辑器来编辑配置文件Doxygen提供了一个辅助工具DoxywizardDoxywizard是Doxygen的GUI前台用户可以能过它来读写配置文件省却了手工配置的麻烦基本上在Doxywizard中可以完成Doxygen的绝大多数工作而且Doxygen也可以在由Doxywizard启动这样就使得整个过程比较连贯 虽然如此我们还是要理解常见的各个Tag的含义在Doxywizard中可以看到这些Tag以自明的方式命名我们大致可以从名称中看出其作用这些Tag被Doxywizard大致分为几类其中HTML到PerlMod是输出文件种类设置Project是Doxygen工程设置Build是编译类选项Messages为出错或异常选项Input为输入源选项等等 图Doxywizard 注释Doxygen规定了进行注释的一些格式正确的注释才能使Doxygen生成文档第一个代码条目都有两种描述简要描述和详细描述两者都是可选的简要描述只有一行而详细描述则提供更长更仔细的描述Doxygen只允许有一个简要描述和详细描述 在Doxygen中一般只会处理与程序结构相关的注释函数内部的注释通常不做处理对于详细描述来说有下面几种表示方式 JavaDoc风格中间的*号可选/*** 注释*/Qt风格中间的*号可选/*!* 注释*/C++风格的变体或者最后一个/改为！也可以/// 单行注释/// 注释///更加显着的表示////////////////////////////////////////////// 注释///////////////////////////////////////////简要描述亦有多种表示方式在上述注释块中使用\brief命令详细注释在空行之后开始/*! \brief 简要描述* 继续** 详细注释*/JAVADOC_AUTOBRIEF设置为YES后在JavaDoc风格的注释中第一个点号之前的内容被自动设置为简要描述对于多行C++变体这个选项亦会起到相同的作用/** 简要描述详细描述* 注释*/C++变体风格/// 简要描述/* 详细描述 */ 命令Doxygen支持的指令非常多主要作用是控制输出文档的排版格式命令以\或@号开始 一些命令可以有多个参数一些命令只有一个参数参数周围的括号使用是有含义的 <>号表示参数是单个词 ()号表示参数一直会到行尾 {}号表示参数会扩展到下一段落 []号表示参数是可选的 下面章节中也涉及到一些命令的使用其它的命令可以查阅Doxygen用户手册 列表Doxygen有许多方法可以创建项目列表 使用在每行开始之前打头使用可以结束一个列表开始新的段落使用这种方法要严格对齐/*** 表项一* 子项一* 子项二* * */在文档块中使用HTML命令这种方法不需要严格对齐/*!* <ul>* <li> 表项一* <ol>* <li> 子项一* <li> 子项二* </ol>* <li> 表项二* </ul>*/ 分组Doxygen有两种分组机制第一种是全局地为每一个组创建一个网页此时分组被称为module第二种是用于复合实体中的成员列表此时分组被称为member groupModule是一种把内容在单个网页上分组的方法分组可以包括filesnamespaceclassesfunctionsvariablesenumstypedefs和defines也可以包含其它分组复合实体（compound entities）如类文件命名空间等可以分布在多个分组中而成员实体（member）如变量函数typedef等只能归属于一个分组 定义分组的方法是在特殊注释块中使用命令\defgroup和\addtogroup defgroup的格式如下 \defgroup <唯一标识名> （中间可以有空格的标题） 两次使用同一标识名在doxygen解析的时候会出现错误命令addtogroup与defgroup不同的地方在于如果使用了同一标识则会在改组中加入新的项如果标识不重复则会创建分组addtogroup中的标题是可选的 声明分组之后如果要使某个实体归属某一分组需要使用ingroup命令避免在每个成员之前都使用ingroup命令可以将member用@{和@}封装起来 /** * \ingroup A */extern int VarInA;/** * \defgroup IntVariables Global integer variables *//*@{*//** an integer variable */extern int IntegerVariable;/*@}*//** * \defgroup Variables Global variables *//*@{*//** a variable in group A */int VarInA;int IntegerVariable;/*@}*/ 上面这些命令都是有优先级的doxygen会根据优先级将实体放入具有最高优先级的分组之中它们的优先级顺序是ingroupdefgroupaddtogroupweakgroupweakgroup类似一个低优先级的addtogroup在h文件中可以使用高优先级的命令定义层次结构在c文件中\weakgroup就不需要准确遵循h文件中定义的层次结构 如果要把不同的类型归入同一分组内就要使用Member group它的定义方法如下 //@{ //@}或者/*@{*/ /*@}*/ Member group不可以嵌套 图表Doxygen里有内置生成C++类层次图的功能它使用贝尔实验室开发的graphviz 中的工具dot来生成更高级的图表使用这个工具时要将配置选项HAVE_DOT设为YES 当GRAPHICAL_HIERARCHY设置为YES时将会绘制一个图形表示的类图结构 当CLASS_GRAPH设置为YES时会为每个归档的类创建一张图表示其直接或间接的继承关系 当INCLUDE_GRAPH设置为YES时会为每个归档文件创建一幅包含依赖图此功能目前仅有HTML和RTF格式支持 当COLLABORATION_GRAPH设置为YES时会为每个归档类或结构绘制基类继承关系图和使用关系图 当CALL_GRAPH设置为YES时会为每个函数显示一幅直接或间接调用关系图 更具体的信息可以参考Doxygen的手册 公式Doxygen可以把LaTeX格式的公式输出出来要在HTML文档里包含公式需要安装下面的工具latex（LaTeX编译器）dvips（将DVI文件转换为PS文件）gs（将PS文件转换为位图） 包含公式的方法有两种 使用\f$命令对表示文本中间的公式遵循LaTeX格式\f$(x_ y_)\f$ (xy)位于独立一行上未编号的公式应放在命令\f[和\f]之间\f[ |I_|=\left| \psi(t) \right|\f]对应的输出是|I|=|ψ(t)| 中文文档Doxygen支持多种语言输出中文文档的时候只需要将配置文件中的OUTPUT_LANGUAGE标签设置为Chinese即可（用Doxywizard修改更方便） 有一个需要注意的问题是在Windows下的浏览器浏览中文HTML文档时英文字母会变得很难看解决的办法是将doxygen_cncss下载到本地硬盘并将配置文件中的HTML_STYLESHEET修改为这个文件的位置 HTML_STYLESHEET=c:\doxygen\doxygencss 运行doxygen在命令行下运行doxygen是很简单的只需要指定配置文件即可 doxygen projectcfg 或者也可以使用Doxywizard在配置完后直接运行doxygen 图doxygen的输出示例 |
