[Doxygen].Docygen使用

转自：http://www.javashuo.com/article/p-qztoywhr-kk.html

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

下载Doxygen + Graphviz

Doxygen能够生成动态文档

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

1、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注释的种类有多种

1.

/**

 * ....描述...

*/

2.

/*!

 * ....描述...

*/

或者

/*!

  ....描述...

*/

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

3

///

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

///

或者

//!

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

//!

4

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

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

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

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>全局和静态变量注释

例如：

1 2 3

/**  Description of global variable  */ int  g_xxx = 0; static  int  s_xxx = 0;  ///<  Description of static variable

使用文档详见：  Doxygen使用