body{ font-family: "Microsoft YaHei UI","Microsoft YaHei",SimSun,"Segoe UI",Tahoma,Helvetica,Sans-Serif,"Microsoft YaHei", Georgia,Helvetica,Arial,sans-serif,宋体, PMingLiU,serif; font-size: 10.5pt; line-height: 1.5;}html, body{ }h1 { font-size:1.5em; font-weight:bold;}h2 { font-size:1.4em; font-weight:bold;}h3 { font-size:1.3em; font-weight:bold;}h4 { font-size:1.2em; font-weight:bold;}h5 { font-size:1.1em; font-weight:bold;}h6 { font-size:1.0em; font-weight:bold;}img { border:0; max-width: 100%;}blockquote { margin-top:0px; margin-bottom:0px;}table { border-collapse:collapse; border:1px solid #bbbbbb;}td { border-collapse:collapse; border:1px solid #bbbbbb;}2013年12月26日 星期四 doxygen入门--很好 2013年12月26日 星期四 14:08:59 晴
一．什么是Doxygen?
Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，，Doxygen 工作目录，就是用来存放配置文件的目录。
2，递归搜索源文件目录需要选上。
选择wizard 标签下的 Output Topics
相关配置说明如下图 2 所示。
选择 wizard 标签下的 Diagrams Topics
相关配置说明如下图 3 所示。
说明：如果选择这个选项之前需要先安装了Graphviz 工具包。
选择 expert标签下的 Project Topics
相关配置说明如下图 4 所示。
说明：编码格式，UTF-8 是首选。如果需要显示中文则选择GB2313.
TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议设置成4。
OPTIMIZE_OUTPUT_FOR_C 这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果
是纯C代码，建议选择。
SUBGROUPING这个选项选择后，输出将会按类型分组。
选择 expert标签下的 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 ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。
选择 expert标签下的 Input Topics
相关配置说明如下图 5 所示。
说明：输入的源文件的编码，要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。
选择 expert标签下的 HTML Topics
相关配置说明如下图 6 所示。
说明：1，CHM_FILE文件名需要加上后缀（xx.chm）。
2，如果在 Wizard 的 Output Topics 中选择了 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 所示。
点击 Rundoxygen 按钮， Doxygen 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。
四．撰写正确格式的批注
并非所有程序代码中的批注都会被Doxygen 所处理。您必需依照正确的
格式撰写。原则上，Doxygen 仅处理与程序结构相关的批注，如
Function，Class ，档案的批注等。。
/**
* @brief Example class的简易说明
*
* 本范例说明Example class。
* 这是一个极为简单的范例。
*
*/
class Example {
private:
int var1 ;///< 这是一个private的变数
public:
int var2 ;///< 这是一个public的变数成员。
int var3 ;///< 这是另一个public的变数成员。
voidExFunc1(void);
intExFunc2(int a, char b);
char*ExFunc3(char *c) ;
};
example.cpp:
/**
* @file 本范例的程序代码档案。
*
* 这个档案用来定义example这个class的
* member function。
*
* @author garylee@localhost
*/
/**
* @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;
}