doxygen(帮助文档生成器) v1.8.13最新版 附使用教程

doxygen是一款专业的帮助文档生成器，主要用于生成英文文档，生成中文文档需要修改输入和输出的码制，支持多种语言的文档生成，小编提供的软件中还包含中文手册，不懂的朋友可以参考使用。

软件特色

它可以从一组文档化的源文件生成一个在线文档浏览器(HTML)和/或离线参考手册($ \ mbox {\ LaTeX} $)。 还支持在RTF(MS-Word)，PostScript，超链接PDF，压缩HTML和Unix手册页中生成输出。 文档直接从源中提取，这使得保持文档与源代码一致更容易。

您可以配置doxygen从未记录的源文件中提取代码结构。 这对于在大型源代码中快速找到方法非常有用。 Doxygen还可以通过包括依赖关系图，继承图和协作图来可视化各种元素之间的关系，这些都是自动生成的。

您也可以使用doxygen创建正常的文档(就像我对doxygen用户手册和网站一样)。

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>运行结束

doxygen注释规范

2.1> Doxygen注释种类

Doxygen注释的种类有多种

1.

/**

 * ....描述...

*/

2.

/*!

 * ....描述...

*/

或者

/*!

  ....描述...

*/

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

3

///

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

///

或者

//!

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

//!

4

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

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

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

2.2>Doxygen支持的指令

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

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

特别提示

1、doxygen的安装非常简单， linux下可以直接下载安装包运行即可，下载源代码编译安装也是比较通用的编译安装命令。

2、在生成文档时可以定义项目属性以及文档生成过程中的很多选项，使用下面命令能够产生一个缺省的配置文件：doxygen -g [配置文件名]

3、可以根据项目的具体需求修改配置文件中对应的项，修改过的配置文件可以作为以后项目的模板。

4、让软件自动产生文档，平常的注释风格可不行，需要遵循自己的格式。

5、OK，代码编完了，注释也按照格式写好了，最后的文档是如何的哪?非常简单，运行下面的命令，相应的文档就会产生在指定的目录中：doxygen [配置文件名]

6、需要注意的是doxygen并不处理所有的注释，重点关注与程序结构有关的注释，比如：文件、类、结构、函数、变量、宏等注释，而忽略函数内变量、代码等的注释。