最新Doxygen使用教程个人总结资料文档格式.docx
《最新Doxygen使用教程个人总结资料文档格式.docx》由会员分享，可在线阅读，更多相关《最新Doxygen使用教程个人总结资料文档格式.docx（13页珍藏版）》请在冰豆网上搜索。
∙1.3安装WindowsHelpWorkshop1.32
Doxygen使用这个工具可以生成CHM格式的文档。
三．Doxygen的配置
Doxygen产生文档可以分为三个步骤。
一是在程序代码中加上符合Doxygen所定义批注格式。
二是使用Doxywizard进行配置。
三是使用Doxygen来产生批注文档。
Doxygen1.7.4主界面如下图1所示。
说明：
1，Doxygen工作目录，就是用来存放配置文件的目录。
2，递归搜索源文件目录需要选上。
选择wizard标签下的OutputTopics
相关配置说明如下图2所示。
选择wizard标签下的
DiagramsTopics
相关配置说明如下图
3所示。
如果选择这个选项之前需要先安装了Graphviz工具包。
选择
expert标签下的
ProjectTopics
4所示。
编码格式，UTF-8是首选。
如果需要显示中文则选择GB2313.
TAB_SIZE主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议设置成4。
OPTIMIZE_OUTPUT_FOR_C这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。
如果
是纯C代码，建议选择。
SUBGROUPING这个选项选择后，输出将会按类型分组。
Build
Build页面，这个页面是生成帮助信息中比较关键的配置页面：
EXTRACT_ALL表示：
输出所有的函数，但是private和static函数不属于其管制。
EXTRACT_PRIVATE表示：
输出private函数。
EXTRACT_STATIC表示：
输出static函数。
同时还有几个EXTRACT，相应查看文档即可。
HIDE_UNDOC_MEMBERS表示：
那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。
当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。
INTERNAL_DOCS主要指：
是否输出注解中的@internal部分。
如果没有被启动，那么注解中所有的@internal部分都
将在目标帮助中不可见。
CASE_SENSE_NAMES表示：
是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。
对于C/C++这种
字母相关的语言来说，建议永远不要开启。
HIDE_SCOPE_NAMES表示：
域隐藏，建议永远不要开启。
SHOW_INCLUDE_FILES表示：
是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列
表。
INLINE_INFO：
如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。
SORT_MEMBER_DOCS：
如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显
示。
GENERATE_TODOLIST：
是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显
示在一个页面中，其他的GENERATE选项同。
SHOW_USED_FILES：
是否在函数或类等的帮助中，最下面显示函数或类的来源文件。
SHOW_FILES：
是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。
InputTopics
5所示。
输入的源文件的编码，要与源文件的编码格式相同。
如果源文件不是UTF-8编码最好转一下。
HTMLTopics
6所示。
1，CHM_FILE文件名需要加上后缀（xx.chm）。
2，如果在Wizard的OutputTopics中选择了prepareforcompressedHTML（.chm）选项，此处就会要求选择hhc.exe程序的位置。
在windowshelpworkshop安装目录下可以找到hhc.exe。
3，为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。
4，GENERATE_CHI表示索引文件是否单独输出，建议关闭。
否则每次生成两个文件，比较麻烦。
5，TOC_EXPAND表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。
Run标签
7所示。
点击Rundoxygen按钮，Doxygen就会从源代码中抓取符合规范的注释生成你定制的格式的文档。
四．撰写正确格式的批注
（2）东西全并非所有程序代码中的批注都会被Doxygen所处理。
您必需依照正确的
格式撰写。
原则上，Doxygen仅处理与程序结构相关的批注，如
Function，Class，档案的批注等。
对于Function内部的批注则不做
处理。
Doxygen可处理下面几种类型的批注。
JavaDoc类型：
/**
*...批注...
*/
是□否□
Qt类型：
/*!
单行型式的批注：
附件
（一）：
///...批注...
或
（3）优惠多//!
...批注...
就算你买手工艺品来送给朋友也是一份意义非凡的绝佳礼品哦。
而这一份礼物于在工艺品店买的现成的礼品相比，就有价值意义，虽然它的成本比较低但它毕竟它是你花心血花时间去完成的。
就像现在最流行的针织围巾，为何会如此深得人心，更有人称它为温暖牌绝大部分多是因为这个原因哦。
而且还可以锻炼你的动手能力，不仅实用还有很大的装饰功用哦。
要使用哪种型态完全看自己的喜好。
以笔者自己来说，大范围的注
解我会使用JavaDoc型的。
单行的批注则使用"
///"
的类型。
此外，由于Doxygen对于批注是视为在解释后面的程序代码。
也就是
说，任何一个批注都是在说明其后的程序代码。
如果要批注前面的程
式码则需用下面格式的批注符号。
<
...批注...*/
/**<
//!
///<
（1）专业知识限制
上面这个方式并不适用于任何地方，只能用在class的member或是
function的参数上。
举例来说，若我们有下面这样的class。
classMyClass{
public:
intmember1;
intmember2:
voidmember_function（）;
};
加上批注后，就变成这样：
/**
*我的自订类别说明...
*/
///<
第一个member说明...
第二个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外，Doxygen也可针对档案做说明，条件
是该批注需置于档案的前面。
主要也是利用一些指令，通常这部分注
解都会放在档案的开始地方。
/*!
\filemyfile.h
\brief档案简易说明
详细说明.
\author作者信息
如您所见，档案批注约略格式如上，请别被"
\"
所搞混。
其实，"
与"
@"
都是一样的，都是告诉Doxygen后面是一个指令。
两种在
Doxygen都可使用。
笔者自己比较偏好使用"
。
接着我们来针对一些常用的指令做说明：
尽管售价不菲，但仍没挡住喜欢它的人来来往往。
这里有营业员们向顾客们示范着制作各种风格迥异的饰品，许多顾客也是学得不亦乐乎。
在现场，有上班族在里面精挑细选成品，有细心的小女孩在仔细盘算着用料和价钱，准备自己制作的原料。
可以想见，用本来稀奇的原料，加上别具匠心的制作，每一款成品都必是独一无二的。
而这也许正是自己制造所能带来最大的快乐吧。
@file
档案的批注说明。
（五）DIY手工艺品的“价格弹性化”@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的变数
intvar2;
这是一个public的变数成员。
intvar3;
这是另一个public的变数成员。
voidExFunc1（void）;
intExFunc2（inta,charb）;
char*ExFunc3（char*c）;
example.cpp:
*@file本范例的程序代码档案。
*这个档案用来定义example这个class的
*memberfunction。
*@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;
}
升级会员 