资源描述
单击此处编辑母版标题样式,单击此处编辑母版文本样式,第二级,第三级,第四级,第五级,0,使用,Doxygen,的目的,生成模块文档，方便以后维护模块代码。,提高代码可读性。,提高项目代码的管理。,省略了自己写,readme,文件（或文档）。,第1页/共38页,使用Doxygen的目的第1页/共38页,1,安装,Doxygen,所需工具,Doxygen(,版本,:1.5.2),Graphviz(,版本,:2.12),iconv(GNU libiconv 1.9),fr(,版本,:2.1.1.120),HTML Help Workshop(,版本,:4.74.8702.0),(,注,:,这些工具放在,dataserver,开发二部,开发二部,_,公共盘,白盒测试相关,生成文档工具,),第2页/共38页,安装Doxygen所需工具第2页/共38页,2,安装,Doxygen,工具,1.,先解压,doxygen.rar;,2.,双击运行,doxygen-1.5.2-setup.exe;,3.,安装软件提示语操作即可,;,4.,把,create_chm.bat,、,html_foot,拷贝到,Doxygen,安装目录的,bin,文件夹里,.,5.,把,Doxygen,安装目录的,bin,路径放在系统环境变量里,;,6.Doxygen,安装完成,;,第3页/共38页,安装Doxygen工具第3页/共38页,3,安装,Graphviz,工具,1.,先解压,graphviz.rar,；,2.,双击运行,graphviz-2.12.exe,；,3.,安装软件提示语操作即可；,4.,Graphviz,安装完成；,第4页/共38页,安装Graphviz工具第4页/共38页,4,安装,iconv,、,fr,工具,1.,先解压,iconv.rar,和,fr.rar,；,2.,将,iconv.rar,和,fr.rar,分别解压出来的,cygiconv-2.dll,、,cygintl-2.dll,、,cygwin1.dll,、,iconv.exe,和,fr.exe,拷到“,C:WINDOWSsystem32,”,；,3.,安装完成；,注,:,上面安装能够运行成功,但是出现一个问题,.,就是我们编译下载环境模块时,iconv,的,cygwin1.dll,文件名明与,cygwin,的,cygwin1.dll,文件名相同导致的,.,所以编译不通过,.,解决方法,:,在下页,.,第5页/共38页,安装iconv、fr工具1.先解压iconv.rar和fr,5,安装,iconv,、,fr,工具解决方案,新建一个系统变量名为”,GBK”,这我固定了,.,所以都以这个名字,.,这个就是要放置,iconv,、,fr,工具里文件的路径,.(,这个路径随自己编写,),、,第6页/共38页,安装iconv、fr工具解决方案新建一个系统变量名为”GB,6,安装,HTML Help Workshop,工具,1.,双击运行,htmlhelp.exe;,2.,安装软件提示语操作即可,;,3.HTML Help Workshop,安装完成,;,注：,HTML Help Workshop,工具要安装在这个路径“,X:Program FilesHTML Help Workshop”,（,X,：自己指定）,.,第7页/共38页,安装HTML Help Workshop工具第7页/共38页,7,附带操作,为了方便运行,Doxygen,工具与管理,.,为每个模块创建一文件夹,(,如：,“,TEST,”,),在,TEST,文件夹里再创建,src,、,doc,文件夹。,Src,文件夹存放源文件，,doc,文件夹存放,Doxygen,输出文件。顺便把,doxygenWD.bat,和,Doxygen,配置文件,“,Doxyfile,”,拷贝到,doc,文件夹下，如果要生成,文档就双击,doxygenWD.bat,即可。（模块的目录结构如下）,注,:Doxygen,不支持,中问路径,不要创建,中文路径,.,TEST,|-src,|,|-test.c,|-test.h,|,|-doc,|,|-Doxyfile,|-doxygenWD.bat,第8页/共38页,附带操作 为了方便运行Doxygen工具与管,8,配置,Doxygen,分为两种,:,向导,(Wizard),模式：将快速配置大多数重要设定,其他选项保持默认值。,专家,(Expert),模式：进入全部的配置选项。,第9页/共38页,配置Doxygen分为两种:第9页/共38页,9,向导,(Wizard),模式,向导,(Wizard),对话框,-Project,相关选项,项目名称，将作为于所生成的程序文档首页标题,.,文档版本号，可对应于项目版本号,.,存放要生成项目文档的项目源文件路径,.,如果选上，就会连子文件夹的文件一起生成文当。没选，就只会生成本文件夹的文件文档,.,这里填入生成文档文件输出路径,这里只填文件夹名字就可以了,.,为了大家工作方便,就规定统一写,output,文件夹,第10页/共38页,向导(Wizard)模式向导(Wizard)对话框-P,10,向导,(Wizard),模式,向导,(Wizard),对话框,-Mode,相关选项,选择这个,只生成文档实体,不会生成源文件文档,.,选择这个,会生成全部实体,.,因此,要选择这个,.,选择这个,把源文件内容导入到项目文档里,.(,建议选择,),选择项目文档输出格式,测试,C,语言,就选择个,.,第11页/共38页,向导(Wizard)模式向导(Wizard)对话框-M,11,向导,(Wizard),模式,向导,(Wizard),对话框,-Output,相关选项,生成普通模式的,HTML,生成文件列表格的,HTML,生成,chm,文件格式的,HTML,因此,就选这个,.,附带查找功能,一般不选择,.,这项没用到,因此把它选择取消,.,这三项不要选择,第12页/共38页,向导(Wizard)模式向导(Wizard)对话框-O,12,向导,(Wizard),模式,向导,(Wizard),对话框,-Diagrams,相关选项,这两个不选择,.,全选择,.,通过这个,GraphViz,工具生成图表,:,(1).,类的图表,.,(2).,协作图表,.,(3).,包含文件图表,(,调用图表,).,(4).,被包含文件图表,(,被调用图表,).,(5).,整个类层次结构图表,.,(6).,调用图表,(,函数,文件,).,第13页/共38页,向导(Wizard)模式向导(Wizard)对话框-D,13,专家,(Expert),模式,由于经过向导,(Wizard),模式快速的配置，,所以,专家,(Expert),模式大部分也相应配置好了。,那么，下面主要配置细节问题，其他就不详细介绍都保持默认选择就可以。,第14页/共38页,专家(Expert)模式第14页/共38页,14,专家,(Expert),模式,专家,(Expert),对话框,-Project,相关选项,DOXYFILE_ENCODING,是,Doxyfile,的文本编码。如果文件中有中文字符，可以填写,GBK,。把,UTF-8,改为,GBK,。,输出语言相当于程序资源，选择Chinese,。,第15页/共38页,专家(Expert)模式专家(Expert)对话框-P,15,专家,(Expert),模式,专家,(Expert),对话框,-Project,相关选项,取消选项,不然会显示全路径,:,如图,1.,图,1,第16页/共38页,专家(Expert)模式专家(Expert)对话框-P,16,专家,(Expert),模式,专家,(Expert),对话框,-,Messages,相关选项,将,WARN_LOGFILE,填写为,error.txt,。这样，,Doxygen,会将编译时出现的警告和错误保存在,error.txt,，这样可以对照修改。,让,doxygen,静悄悄地为你生成文档，只有出现警告或错误时，才在终端输出提示信息,(,不选择,).,第17页/共38页,专家(Expert)模式专家(Expert)对话框-M,17,专家,(Expert),模式,专家,(Expert),对话框,-Input,相关选项,指定输入源文件目录（,INPUT,）,.,输入文件编码（,INPUT_ENCODING,）改为,GBK.,对文件过滤选项,我们这里只填*,.c*.h.,第18页/共38页,专家(Expert)模式专家(Expert)对话框-I,18,专家,(Expert),模式,专家,(Expert),对话框,-,Messages,相关选项,可以通过参数,HTML_HEADER,和,HTML_FOOTER,定制页面，参数值是包含定制内容的文件名,.,这里我填了,html_foot,文件,内可以打开,html_foot,文件看,.,这里只看效果图,:,如图,2.,选择,GENERATE_HTMLHELP,后，,Doxygen,会准备生成,chm,文件需要的项目文件、目录文件和索引文件,。,图,2,第19页/共38页,专家(Expert)模式专家(Expert)对话框-M,19,专家,(Expert),模式,专家,(Expert),对话框,-Dot,相关选项,可以选上,UML_LOOK,、,CALL_GRAPH,和,CALLER_GRAPH,。,CALL_GRAPH,是本函数调用其它函数的示意图,.,效果如,:,图,3.,图,3,第20页/共38页,专家(Expert)模式专家(Expert)对话框-D,20,Doxygen,注释风格,Doxygen,指令目的为了生成更丰富与可读性更强的文档。所以总结,5,类常用的注释风格说明,。,变量、宏定义、类型定义。,枚举类型定义、结构体类型定义类似。,函数定义。,模块定义（单独显示一页）。,分组定义（在一页内分组显示）。,第21页/共38页,Doxygen注释风格 Doxygen指令,21,变量、宏定义、类型定义简要说明,变量、宏定义、类型定义注释风格类似。,格式：,/*,简要说明文字*,/,变量（宏定义或类型定义）,如：,/*,简要说明文字*,/,#define FLOAT float,/*brief,简要说明文字（在前面加,brief,是标准格式）*,/,#define MIN_UINT 0,/*,*,分行的简要说明,n*,这是第二行的简要说明*,/int b;,注：不文档化局部变量，只文档化全局变量。,/*,*/,这是固定格式，还要注意,/*,这,2,个,“,*,”,不能少也不能多。其他注释风格也是这样的。,“,n,”,作用是回车换行,.,“,brief,”,是注释指令,“,”,也可以用,”,”,.,第22页/共38页,变量、宏定义、类型定义简要说明 变量、宏定义、类型定义注释风,22,枚举类型定义、结构体类型定义,枚举类型定义、结构体类型定义注释风格类似。,格式：,/*,简要说明文字*,/,typedef,类型 结构体名字,成员,1,/*,简要说明文字*,/,成员,2,/*,简要说明文字*,/,成员,3,/*,简要说明文字*,/,结构体别名；,注：所有的结构体类型定义要放在枚举类型定义前面。,类型：,enum,，,struct,注意，要以,“,”,小于号开头，如过不用,“,”,，那这行的注释就会被,Doxygen,认为是成员,2,的注释。,第23页/共38页,枚举类型定义、结构体类型定义枚举类型定义、结构体类型定义注释,23,函数定义,指令格式,:,执行符指令操作符,执行符：,或,两个。,指令操作符：,param,、,return,、,retval,、,note,、,pre,、,par,、,code,、,endcode,、,see,、,deprecated,。（其实还有很多，这里的指令操作符已经够我们函数用了，所以不再列举。）,特殊符号指令符：,-,、,#,、,:,。（这三符号对于我们也够用了）,
展开阅读全文