1、 1.3 安装 Windows Help Workshop 1.32Doxygen 使用这个工具可以生成 CHM 格式的文档。三Doxygen的配置Doxygen 产生文档可以分为三个步骤。一是在程序代码中加上符合Doxygen所定义批注格式。二是使用Doxywizard进行配置。三是使用Doxygen来产生批注文档。Doxygen 1.7.4 主界面如下图 1 所示。说明:1,Doxygen 工作目录,就是用来存放配置文件的目录。 2,递归搜索源文件目录需要选上。选择 wizard 标签下的 Output Topics相关配置说明如下图 2 所示。选择 wizard 标签下的Diagrams
2、 Topics相关配置说明如下图3 所示。如果选择这个选项之前需要先安装了 Graphviz 工具包。选择expert 标签下的Project Topics4 所示。编码格式,UTF-8 是首选。如果需要显示中文则选择GB2313.TAB_SIZE 主要是帮助文件中代码的缩进尺寸,譬如code和endcode段中代码的排版,建议设置成4。OPTIMIZE_OUTPUT_FOR_C 这个选项选择后,生成文档的一些描述性名称会发生变化,主要是符合C习惯。如果是纯C代码,建议选择。SUBGROUPING这个选项选择后,输出将会按类型分组。BuildBuild页面,这个页面是生成帮助信息中比较关键的配
3、置页面:EXTRACT_ALL 表示:输出所有的函数,但是private和static函数不属于其管制。EXTRACT_PRIVATE 表示:输出private函数。EXTRACT_STATIC 表示:输出static函数。同时还有几个EXTRACT,相应查看文档即可。HIDE_UNDOC_MEMBERS 表示:那些没有使用doxygen格式描述的文档(函数或类等)就不显示了。当然,如果EXTRACT_ALL被启用,那么这个标志其实是被忽略的。INTERNAL_DOCS 主要指:是否输出注解中的internal部分。如果没有被启动,那么注解中所有的internal部分都将在目标帮助中不可见。C
4、ASE_SENSE_NAMES 表示:是否关注大小写名称,注意,如果开启了,那么所有的名称都将被小写。对于C/C+这种字母相关的语言来说,建议永远不要开启。HIDE_SCOPE_NAMES 表示:域隐藏,建议永远不要开启。SHOW_INCLUDE_FILES 表示:是否显示包含文件,如果开启,帮助中会专门生成一个页面,里面包含所有包含文件的列表。INLINE_INFO :如果开启,那么在帮助文档中,inline函数前面会有一个inline修饰词来标明。SORT_MEMBER_DOCS :如果开启,那么在帮助文档列表显示的时候,函数名称会排序,否则按照解释的顺序显示。GENERATE_TODOL
5、IST :是否生成TODOLIST页面,如果开启,那么包含在todo注解中的内容将会单独生成并显示在一个页面中,其他的GENERATE选项同。SHOW_USED_FILES :是否在函数或类等的帮助中,最下面显示函数或类的来源文件。SHOW_FILES :是否显示文件列表页面,如果开启,那么帮助中会存在一个一个文件列表索引页面。Input Topics5 所示。输入的源文件的编码,要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。HTML Topics6 所示。1,CHM_FILE文件名需要加上后缀(xx.chm)。2,如果在 Wizard 的 Output Topics 中选
6、择了 prepare for compressed HTML (.chm)选项,此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe。3,为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码,CHM_INDEX_ENCODING中输入GB2312即可。4,GENERATE_CHI 表示索引文件是否单独输出,建议关闭。否则每次生成两个文件,比较麻烦。5,TOC_EXPAND 表示是否在索引中列举成员名称以及分组(譬如函数,枚举)名称。Run 标签7 所示。 点击 Run doxygen 按钮, Doxyge
7、n 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。四撰写正确格式的批注 (2)东西全并非所有程序代码中的批注都会被Doxygen 所处理。您必需依照正确的格式撰写。原则上,Doxygen 仅处理与程序结构相关的批注,如Function,Class ,档案的批注等。对于Function内部的批注则不做处理。Doxygen可处理下面几种类型的批注。JavaDoc类型:/* . 批注 .*/是 否Qt类型:/*!单行型式的批注:附件(一):/ . 批注 .或(3)优惠多/! . 批注 .就算你买手工艺品来送给朋友也是一份意义非凡的绝佳礼品哦。而这一份礼物于在工艺品店买的现成的礼品相比,就有
8、价值意义,虽然它的成本比较低但它毕竟它是你花心血花时间去完成的。就像现在最流行的针织围巾,为何会如此深得人心,更有人称它为温暖牌绝大部分多是因为这个原因哦。而且还可以锻炼你的动手能力,不仅实用还有很大的装饰功用哦。要使用哪种型态完全看自己的喜好。以笔者自己来说,大范围的注解我会使用JavaDoc 型的。单行的批注则使用/ 的类型。此外,由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说,任何一个批注都是在说明其后的程序代码。如果要批注前面的程式码则需用下面格式的批注符号。 . 批注 . */*/!/(1) 专业知识限制上面这个方式并不适用于任何地方,只能用在class 的memb
9、er或是function的参数上。举例来说,若我们有下面这样的class。 class MyClass public: int member1 ; int member2: void member_function(); ;加上批注后,就变成这样: /* * 我的自订类别说明 . */ / 第一个member说明 . 第二个member说明 . int member_function(int a, int b); * 自订类别的member_funtion说明 . * * param a 参数a的说明 * param b 参数b的说明 * return 传回a+b。 */ int MyClas
10、s:member_function( int a, int b ) return a+b ; 当您使用Doxygen 产生说明文档时,Doxygen 会帮您parsing 您的程式码。并且依据程序结构建立对应的文件。然后再将您的批注,依据其位置套入于正确的地方。您可能已经注意到,除了一般文字说明外,还有一些其它特别的指令,像是param及return 等。这正是Doxygen 另外一个重要的部分,因为一个类别或是函式其实都有固定几个要说明的部分。为了让Doxygen 能够判断,所有我们就必需使用这些指令,来告诉Doxygen 后面的批注是在说明什么东西。Doxygen 在处理时,就会帮您把这些
11、部分做特别的处理或是排版。甚至是制作参考连结。首先,我们先说明在Doxygen 中对于类别或是函数批注的一个特定格式。 * class或function的简易说明. * class或function的详细说明. * .上面这个例子要说的是,在Doxygen 处理一个class 或是function注解时,会先判断第一行为简易说明。这个简易说明将一直到空一行的出现。或是遇到第一个. 为止。之后的批注将会被视为详细说明。两者的差异在于Doxygen 在某些地方只会显示简易说明,而不显示详细说明。如:class 或function的列表。另一种比较清楚的方式是指定brief的指令。这将会明确的告诉D
12、oxygen,何者是简易说明。例如: * brief class或function的简易说明.除了这个class 及function外,Doxygen 也可针对档案做说明,条件是该批注需置于档案的前面。主要也是利用一些指令,通常这部分注解都会放在档案的开始地方。 /*! file myfile.h brief 档案简易说明 详细说明. author 作者信息如您所见,档案批注约略格式如上,请别被 所搞混。其实,与 都是一样的,都是告诉Doxygen 后面是一个指令。两种在Doxygen 都可使用。笔者自己比较偏好使用。接着我们来针对一些常用的指令做说明:尽管售价不菲,但仍没挡住喜欢它的人来来往
13、往。这里有营业员们向顾客们示范着制作各种风格迥异的饰品,许多顾客也是学得不亦乐乎。在现场,有上班族在里面精挑细选成品,有细心的小女孩在仔细盘算着用料和价钱,准备自己制作的原料。可以想见,用本来稀奇的原料,加上别具匠心的制作,每一款成品都必是独一无二的。而这也许正是自己制造所能带来最大的快乐吧。file档案的批注说明。(五)DIY手工艺品的“价格弹性化”author作者的信息我们长期呆在校园里,没有工作收入一直都是靠父母生活,在资金方面会表现的比较棘手。不过,对我们的小店来说还好,因为我们不需要太多的投资。brief四、影响的宏观环境分析用于class 或function的批注中,后面为clas
14、s 或function的简易说明。param格式为param arg_name 参数说明主要用于函式说明中,后面接参数的名字,然后再接关于该参数的说明。return后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。retvalretval value 传回值说明主要用于函式说明中,说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。Doxygen 所支持的指令很多,有些甚至是关于输出排版的控制。您可从Doxygen的使用说明中找到详尽的说明。下面我们准备一组example.h 及example.cpp 来说明Doxygen 批注的使用方式:examp
15、le.h: * file 本范例的include档案。 * 这个档案只定义example这个class。 * author garyleelocalhost #define EXAMPLE_OK 0 定义EXAMPLE_OK的宏为0。 * brief Example class的简易说明 * 本范例说明Example class。 * 这是一个极为简单的范例。 * class Example private: int var1 ; 这是一个private的变数 int var2 ; 这是一个public的变数成员。 int var3 ; 这是另一个public的变数成员。 void ExFun
16、c1(void); int ExFunc2(int a, char b); char *ExFunc3(char *c) ;example.cpp: * file 本范例的程序代码档案。 * 这个档案用来定义example这个class的 * member function。 * brief ExFunc1的简易说明 * ExFunc1没有任何参数及传回值。 void Example:ExFunc1(void) / empty funcion. * brief ExFunc2的简易说明 * ExFunc3()传回两个参数相加的值。 * param a 用来相加的参数。 * param b 用来相加的参数。 * return 传回两个参数相加的结果。 int ExFunc2(int a, char b) return (a+b); * brief ExFunc3的简易说明 * ExFunc3()只传回参数输入的指标。 * param c 传进的字符指针。 * retval NULL 空字符串。 * retval !NULL 非空字符串。 char * ExFunc2(char * c) return c;
copyright@ 2008-2022 冰豆网网站版权所有
经营许可证编号:鄂ICP备2022015515号-1