Doxygen简介及使用说明

一、 Doxygen简介

Doxygen是一个程序的文档产生工具，可以将程序中的注释转换成说明文档或者说是API参考手册，从而减少程序员整理文档的时间。当然这里程序中的注释需要遵循一定的规则书写，才能让Doxygen识别和转化。

目前Doxygen可处理的程序语言包含C/C++、Java、Objective-C、IDL等，可产生出来的文档格式有HTML、XML、LaTeX、RTF等，此外还可衍生出不少其它格式，如HTML可以打包成CHM格式，而LaTeX可以通过一些工具产生出PS或是PDF文档等。

二、下载及安装

Doxygen官网分别提供Linux和Windows下的源代码编译安装包和二进制安装包。方便起见，我们选择二进制包进行下载和安装。下载路径为：http://www.stack.nl/~dimitri/doxygen/download.html。

Windows平台下，下载完成后，直接按照对话框提示安装即可。

Linux平台下，下载完成后，输入：

./configure

Make install

可执行的二进制文件将被安装到<prefix>/bin 目录下。<prefix>默认路径为/usr/local，可使用配置脚本的--prefix选项来修改安装的默认路径。

另外，也可以安装一些辅助工具来生成更加漂亮的文档。如可以使用graphviz中的dot工具来渲染出效果更好的图表，因此，如果需要在注释中加入图表可以下载并安装GraphViz(http://www.graphviz.org/Download..php)； Windows平台下还可以安装 Windows Help Workshop来生成 CHM 格式的文档等等。

三、代码的注释格式

并非所有程序代码中的注释都会被Doxygen所处理，而是必须依照正确的格式撰写。原则上，Doxygen仅处理与程序结构相关的注释，如Function，Class等。对于Function内部的注释则不做处理。Doxygen可处理下面几种类型的注释。

JavaDoc类型：

/*

 * ... 注释 ...

 */

Qt类型的注释：

/*!

 * ... 注释 ...

 */

单行类型的注释：

/// ... 注释 ...

或   

//! ... 注释 ...

备注：不同类型的注释可以混合使用。

由于Doxygen 对于注释是视为在解释后面的程序代码。也就是说，任何一个注释都是在说明其后的程序代码。如果要注释前面的程序代码则需用下面格式的注释符号。

/*!< ... 注释前面的代码 ... */
/**< ... 注释前面的代码... */
//!< ... 注释前面的代码...
///< ... 注释前面的代码...

Doxygen产生说明文档时，Doxygen会首先解析程序源代码，并且依据程序的结构建立对应的文档，然后再将代码中的注释依据其在程序中的位置放在文档中正确的地方。除了一般文字说明外，Doxygen中还有一些其它特别的指令，如@param及@return等。Doxygen根据这些指令判断注释的是函数参数还是返回值。例如Doxygen中对文件的注释如下所示：

  /**  
     *\file myfile.c
     *
     *\brief 文件简易说明
     *
     *   详细说明
     *
     *\author 作者信息
     */

\file会告诉Doxygen此处是源码文件的注释，\brief表明此处是文件的简易说明，\author表示的是作者信息。

对函数说明的注释如下所示：

/**
 * Function 的简易说明…
 * Function的详细说明…
 * @param a 用来相加的参数
 * @param b 用来相加的参数
 * @return 传回两个参数相加的结果
 */
int Function(int a, char b)
{
    return (a+b);
}

上面这个例子要说的是，在Doxygen处理一个函数注释时，会先判断第一行为简易说明。这个简易说明将一直到空一行的出现，或是遇到第一个 "." 为止。之后的注释将会被视为详细说明。@param表示是函数参数说明。在上面两个例子中"@"和"\"在Doxygen 中是一样的，都是告诉Doxygen后面是一个指令。

Doxygen中常用指令的说明如下表所示：

@file	源码文件的注释说明。
@author	作者的信息
@brief	用于class 或function的注释中，后面为class 或function的简易说明。
@param	格式为@param arg_name 参数说明主要用于函式说明中，后面接参数的名字，然后再接关于该参数的说明。
@return	后面接函数传回值的说明。用于function的注释中。说明该函数的传回值。
@retval	格式为@retval value 传回值说明主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。

下面给一个注释举例

/**
 * @file example.c
 * @brief 文件简要说明
 *
 * 详细说明
 *
 * @author 作者信息
 */
 
 #define EXAMPLE_OK  0   /**< 注释EXAMPLE_OK*/

/**
 * @brief 结构体简要说明
 */
typedef struct
{
    int member1 ;  /**< 注释member1*/
    ...
}STRUCT_T;
    
/**
 * Function1() 的简易说明...
 * Function1()的详细说明...
 * @param a 用来相加的参数
 * @param b 用来相加的参数
 * @return 传回两个参数相加的结果
 */
int Function1(int a, char b)
{
    return (a+b);
}

/**
 * Function2()的简易说明
 *
 * @param c 传进的字符指针
 * @retval NULL 空字符串
 * @retval !NULL 非空字符串
*/ 
char *Function2(char *c) 
{
    return c;
}

四、 Doxygen配置

Doxygen产生文档可以分为三个步骤，一是在程序代码中加上符合Doxygen所定义注释格式；二是使用Doxywizard进行配置；三是使用Doxygen来产生注释文档。现在我们假定电脑中已经安装了Doxygen并且代码中的注释已经符合Doxygen规范，下面我们来通过设置配置来生成注释文档。

1. 图4.1是Doxygen的主界面，按照界面提示，填写Doxygen的工作目录、项目名称、源文件目录、生成文档的存放目录，同时递归搜索源文件目录的选项也要勾选。其中，Doxygen的工作目录是指用来存放配置文件的目录。

图4.1 Doxygen主界面

2. 选择Wizard标签下的Output项，如图4.2所示

图4.2Wizard标签下的Output项的设置

3. 选择Expert标签下的Project项，如图4.3所示。其中，编码格式，UTF-8是首选。如果需要显示中文则选择GB2313。OPTIMIZE_OUTPUT_FOR_C 这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果是纯C代码，建议选择。SUBGROUPING这个选项选择后，输出将会按类型分组。

图4.3Expert标签下的Project项的设置

4. 选择Expert标签下的Build项，如图4.4所示。这个页面是生成帮助信息中比较关键的配置页面：

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

图4.4 Expert标签下的Build项的设置

5. 选择Expert标签下的Input项，如图4.5所示。其中输入的源文件的编码，要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。

图4.5Expert标签下的Input项的设置

6. 选择Expert标签下的HTML项，如图4.6所示。为了解决DoxyGen生成的文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。

图4.6Expert标签下的HTML项的配置

7. 选择 Run 标签，如图4.7所示。点Run doxygen按钮，Doxygen 就会从源代码中抓取符合规范的注释生成定制的格式的文档。

图4.7 选择Run标签下的Rundoxygen按钮

Doxygen简介及使用说明

猜你喜欢