Doxygen的使用，配置及实例

Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，可以从一套归档源文件开始，生成文档

下载Doxygen + Graphviz

Doxygen可以生成动态文档

Graphviz可以生成视图连接将.c文件中所用到的函数、头文件生成一个树状结构并且设置之后可以生成相对应的函数的跳转，方便查询函数。

一、Doxygen的使用步骤

1.1Doxygen配置方法

1.1.1>Doxygen的主页面

首先修改Project name，选择扫描源代码的目录，Source code directory：勾选Scan recursively：

1.2>在Wizard的Topics下的Mode，选择All Entities，可以输出相对完整的功能，是否包含源代码看自身情况，在下面选择好自己的语言。这里得是C所以选择C or PHP

1.3>在Output中，如果你需要输出chm格式，勾选chm,没有要求的话html就可以了

1.4>在Diagrams中选择使用GraphViz包，来输出UML，GraphViz包可以帮助建立一些树状视图。

1.5>Expert中，你需要首选确定你所输出的语言，个人使用中文在Expert的Input中，很重要的是INPUT_ENCODING项，如果使用的为微软默认字符集请填写GBK，不然目录乱码,当前选择UTF-8，输出语言选择的是Chinese.

1.6>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 ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

1.7>Expert>Input页按照下图进行设置调整参数。

1.8>

1.如果在 Wizard 的 Output Topics 中选择了 prepare for compressed HTML (.chm)选项，此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe。

2.为了解决Doxygen生成的CHM文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。

3.GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。

4.TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。

1.8>运行doxygen

1.9>运行结束

二.注释规范

2.1> Doxygen注释种类

Doxygen注释的种类有多种

/**

 * ....描述...

*/

/*!

 * ....描述...

*/

或者

/*!

  ....描述...

*/

注：注释块中的星号(*)是可选的，可写可不写。

///

///....描述...

///

或者

//!

//!....描述...

//!

////////////////////////

///....描述...

//////////////////////////

2.2>Doxygen支持的指令

可以在注释中加一些Doxygen支持的指令，主要作用是控制输出文档的排版格式，使用这些指令时需要在前面加上“\”或者“@”（JavaDoc风格）符号，告诉Doxygen这些是一些特殊的指令，通过加入这些指令以及配备相应的文字，可以生成更加丰富的文档，下面对比较常用的指令做一下简单介绍。

@file	档案的批注说明。
@author	作者的信息
@brief	用于class或function的简易说明 eg：@brief本函数负责打印错误信息串
@param	主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@return	描述该函数的返回值情况 eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval	描述返回值类型 eg:@retval NULL 空字符串。 @retval !NULL 非空字符串。
@note	注解
@attention	注意
@warning	警告信息
@enum	引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg：@enum CTest::MyEnum
@var	引用了某个变量，Doxygen会在该枚举处产生一个链接 eg：@var CTest::m_FileKey
@class	引用某个类，格式：@class <name> [<header-file>] [<header-name>] eg: @class CTest "inc/class.h"
@exception	可能产生的异常描述 eg:@exception 本函数执行可能会产生超出范围的异常

2.3>文件注释

放于文件的开头，例如：

/**

* @file       filename

* @brief      This is a brief description.

* @details This is the detail description.

* @author     author

* @date       date

* @version A001

* @par Copyright (c):

*      XXX公司

* @par History:        

*   version: author, date, desc\n

*/

2.3>函数注释

放于函数声明前，例如：

/** 下面是一个含有两个参数的函数的注释说明（简述） 

 * 

 *     这里写该函数的详述信息 

 *     @param a 被测试的变量（param描述参数） 

 *     @param s 指向描述测试信息的字符串 

 *     @return    测试结果 （return描述返回值） 

 *     @see    Test()    （本函数参考其它的相关的函数，这里作一个链接） 

 *     @note    (note描述需要注意的问题) 

 */
int testMe(int a,const char *s);

2.4>数据结构注释

应放于函数声明前，例如：

/**

 * The brief description.

 * The detail description.

 */

typedef struct

{

    int var1;///<Description of the member variable

}XXXX;

或者

typedef struct box {

    成员变量注释（enum的各个值也如此注释）：

    double length; ///< The length of the box

    double width; ///< The width of the box

    double height; ///< The height of the box

};

2.5>宏定义注释

放于宏定义上方或者右侧，例如：

/** Description of the macro */

#define XXXX_XXX_XX      ox7fffffff

或者

#define XXXX_XXX_XX      0 ///< Description of the macro.

2.6>全局和静态变量注释

例如：

/**  Description of global variable  */

int g_xxx = 0;

static int s_xxx = 0; ///<  Description of static variable

使用文档详见： Doxygen使用