【2】Qt5.12.6和Doxygen生成chm开发手册教程

简介

快速阅读

​ 搭建好整个环境后，稍微浏览一下注释规范选择一种喜欢的风格，然后按照简单配置指南配置好测试一下效果。更详细的内容可根据需求在使用中学习、查阅。

​ 其实在熟悉了Doxygen使用方法后，不再限于某种编程平台的代码比如Qt、VS等，也不限于某种编程语言C、C++、Java等，不限于在windows还是在linux上使用。Doxygen关注的是代码文件中的文档注释（希望在文档中出现的注释，遵循doxygen规定的注释格式即可），只要有项目文件夹就可以使用了。

Linux有自己的安装、配置、使用的方法，暂时还没用到，就不介绍了。

用途

规范注释

​ 为代码写注释一直是大多数程序员有些困扰的事情。当前程序员都能接受为了程序的可维护性、可读性编码的同时写注释的说法，但对哪些地方应该写注释，注释如何写，写多少等这些问题，很多程序员仍然没有答案。而doxygen就提供了一几种参考的注释风格。

生成开发文档

​ 更头痛的是写文档，以及维护文档的问题。 开发人员通常可以忍受编写或者改动代码时编写或者修改对应的注释，但之后需要修正相应的文档却比较困难。

​ 如果能从注释直接转化成文档，对开发人员无疑是一种福音。而doxygen就能把遵守某种格式的注释自动转化为对应的文档。

分析代码

​ 当分析一个很复杂的项目源代码时，如何有效的分析函数间的调用关系呢？可以使用doxygen和graphviz来自动分析函数间的调用关系。

Doxygen简介

​ Doxygen 是基于GPL的开源项目，是一个非常优秀的文档系统，初始版本的Doxygen借鉴了一些老版本DOC++的代码；随后，Doxygen源代码由Dimitri van Heesch重写。

​ 这个软件包包括了一个GUI界面的前端工具，可以帮助我们方便创建Doxygen配置文件和生成目标文档。

详细请看http://www.oschina.net/p/doxygen

功能

1．Doxygen 可以根据代码注释生成文档的工具，因此比较容易保持更新。

2．Doxygen 可以交叉引用文档和代码，使文件的读者可以很容易地引用实际的代码。

运行环境

在大多数unix（包括linux），windows家族，Mac系统上运行，

支持语言

C++, C, Java,Objective-C, IDL（Corba和Microsoft 家族）语言，Fortran,VHDL,部分支持PHP和C#语言和D语言，

输出格式

包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。

doxygen使用步骤

​ 由于只是工具的使用，这里只介绍使用步骤。

主要可以分为：

1）第一次使用需要安装doxygen的程序和插件

2）生成doxygen配置文件

3）编码时，按照某种格式编写注释

4）生成对应文档

Html Help Work Shop简介

微软的chm文件编译器。

Graphviz简介

​ 是一种开源的将结构化信息展示成抽象图和网络的工具，用于网络，生物信息，软件工程，数据库和网站设计，机器学习以及其他技术领域的可视性接口。

windows10下Qt+Doxygen环境搭建

全部资源：

doxygen的安装包及插件：

在准备好所有资源后建立如下文件夹，以D盘为例：

版本不相同应该同样可以搭建成功

Doxygen下载及安装

下载

下载地址

安装

1.双击doxygen-1.8.20-setup

2.选择“I accept the agreement”–>Next

3.点击Browse…–>选择安装目录即D:\Doxygen\doxygen1.8.20–>OK–>Next

4.一路Next–>Install–>Next–>Finish

5.完成

Graphviz下载安装

下载

下载地址

安装

1.双击graphviz-2.38

2.点击–>Next

3.点击Browse…–>选择安装目录即D:\Doxygen\graphviz2.38–>OK–>Next

4.一路Next–>Close

5.完成

补充

​ 如果mac安装过程中弹出“打不开 XXX，因为它来自身份不明的开发者”请进入如下网址寻找解决办法：

百度方法

Html Help Work Shop下载安装

下载和安装 chm 编译器，我们使用微软古老的 HTML Help Workshop 1.3，这个软件N久没更新了

下载

下载地址

安装

1.双击htmlhelp1.3

2.点击–>Yes–>是

3.点击Browse…–>选择安装目录即D:\Doxygen\htmlhelp1.3–>OK

4.一路Next–>Close

5.完成

补充

​ 计算机中一般自带了一个htmlhelp，也可以直接使用这个自带的。一般安装htmlhelp1.3不会出现任何问题，只会提示计算机中已经有htmlhelp的新版本了。

​ 本次安装时遇到一个问题：

error creating process <C:\Users\楸\AppData\Local\Temp\IXP000\setup.exe>.Reason:系统找不到指定文件

​ 解决方法：将用户变量的TEMP/TMP变量改为和系统变量一样的值就可以正常安装了。

Qt Doxygen插件下载及配置

查看QtCreator版本

帮助–>About Qt Creator

下载适配的Qt Doxygen版本

下载地址

Qt配置Doxygen插件

将动态库复制到Qt安装目录下：

验证是否成功

重启QtCreator，中才会出现插件Doxygen的选项：

打开Qtcreator–>帮助–>关于插件–>确认Doxygen已勾选

Qtcreator–>工具–>选项–>查看左侧有没有Doxygen

doxygen注释规范

一般代码注释

注释的书写总原则

注释应该怎么写，写多还是写少。过多的注释甚至会干扰对代码的阅读。

写注释的一个总的原则就是注释应该尽量用来表明作者的意图

• 从解决问题的层次上进行注释
• 从问题的解答的层次上进行注释
• 至少也应该是对一部分代码的总结

​ 而不应该是对代码的重复或者解释，看代码可能更容易理解。

注释过程

推荐的写注释的过程是**首先使用注释勾勒出代码的主要框架 **，然后根据注释撰写相应的代码。

注意点

下面是一些写注释时需要注意的要点：

1．通过注释解释为什么这么做、或者要做什么，使代码的读者可以只阅读注释理解代码；

2．对读者可能会有疑问的地方进行注释；

3．对关键的控制结构进行注释，单一目的的语句集进行注释；

4．对于难于理解的代码，进行改写，而不要试图通过注释加以说明；

5．避免对单独语句进行注释；

6．对数据定义进行注释，而不是对其使用过程进行注释；

7．多个函数公用的变量进行详细地注释。

8．对各种主要的数据结构进行详细地注释。

9．输出的函数进行详细地注释。

10．对数据和函数的边界、使用前提等进行注释；

Doxygen文档化的注释

Doxygen的处理的注释简介

允许注释在源文档

​ 与其他大多数文档系统不同，doxygen 允许你在定义的前端放置文档成员（包括全局函数），这种方法使得文档能放在源文件而不是头文件中，它保持了头文件的兼容性，允许成员的执行者直接访问文档。

​ 折中的方法是简明描述放在声明之前，而细节描述放在成员定义之前。

注释关注点

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

​ 若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：

• 文件头（包括.h和.cpp）

​ 主要用于声明版权，描述本文件实现的功能，以及文件版本信息等

• 类的定义

​ 主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述

• 类的成员变量定义

​ 在类的成员变量上方，对该成员变量进行简要地描述

• 类的成员函数定义

​ 在类定义的成员函数上方，对该成员函数功能进行简要描述

• 函数实现

​ 在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等

通用注释规则

​ 对于任何一行代码来说，会有两种（也可能是三种）注释方式，并且会一同放置到文档中，一种是简明描述，另一种是细节描述。而方法和函数也可能使用第三种描述的方式，它被称为“in body”描述，并包含方法和函数内所有注释块之间的联系。

• 简述和详述都是可选的，但不能同时没有。
• 多于一个的简明或者细节描述是能被接受的（不推荐，将会无法判定描述的顺序）

详述

​ 详细描述(detailed description)：要提供足够的长度以包容更多的细节文档。

QT 风格

​ 可使用 QT 风格，即在 C 注释风格基础上添加一个！字符，例子如下：

/*! 
 * ... text ... 
*/ 

JavaDoc 风格

可使用 JavaDoc 风格，包含两个“*”开头的 C 注释风格，如同：

/**
 * ... text ... 
*/ 

C++风格

​ 第三种替代方式则使用至少两行的 C++注释块，在每行开始出添加一个斜杠或者惊叹号，这有两个例子：

/// 
/// ... text ... 
/// 

//!
//!... text ... 
//! 

​ 这种情况下，请使用一条空行作为文档块的结尾。

注释块

​ 有些人喜欢在文档中使用他们自己的注释块，感觉更清晰。基于这样的目的，可能会用到以下的方式： （注意前两条斜杠结束普通注释块，后两条开始一个特殊注释块）

/********************************************//**
 * ... text 
***********************************************/ 

/ 
/// ... text ... 
/ 

简述

简述(brief)：建议简明描述使用一个短小的单行方式。以 HTML 方式输出的简明描述可在文档行引用之处支持冒泡提示 。

类，名字空间或文件的成员概述中会包含简明描述，可使用 small italic 字体打印（这类描述能被隐藏，设置 BRIEF_MEMBER_DESC为 NO）。

/// Brief description. 

简述加详述

通常一行注释只会有一个简明描述，而多行注释块会包含一个更详细的描述。

多个细节描述被组合在一起，请注意假如这些细节描述被放置到代码的不同地方，那么能否找到只能取决于doxygen 对代码的解析程度而定。

​ 默认情况下简明描述作为细节描述的第一条句子（可通过设定 REPEAT_BRIEF为 NO 改变），在 QT 风格中简明描述和细节描述都是可选的。

空行分隔简述和详述

​ 不超过一行的 C++注释块,此类情况下将 JAVADOC_AUTOBRIEF设置为 NO。空行用于分隔注释块中简明描述和细节描述:

/// Brief description. 

/** Detailed description. */ 

//! Brief descripion. 

//! Detailed description 
//! starts here. 

.+空格/空白行分隔简述和详述

在出现第一个“.” 后跟一个空格或空白行处结束，可在之后紧跟细节描述。 可参考以下的例子：

//! Brief description, which is 
//! really a detailed description since it spans multiple lines. 
/*
*!Another detailed description! 
*/ 

QT风格

​ 如果希望 QT 文档块自动将第一条句子作为简明描述，设置 QT_AUTOBRIEF为 YES。

​ 如果在配置文件中将QT_AUTOBRIEF设置为 YES，同一个块中，在出现第一个“.” 后跟一个空格或空白行处结束，可在之后紧跟细节描述：

/*! \brief Brief description. 
 * Brief description continued. 
 *
 * Detailed description starts here. 
 */ 

JavaDoc 风格

​ JavaDoc 文档块与 QT 文档块规则类似，JavaDoc 不同的地方是，它会将文档块的第一句自动当成是简明描述。

可通过设置 JAVADOC_AUTOBRIEF为 YES 使能此动作。如果你有效了此选项，需要在句子中放置一个“.”（点）来结束句子，并在点之后放置一个反斜杠或空格：

/** Brief description which ends at this dot. Details follow 
 * here. 
*/ 

C++风格

​ 如果在配置文件中将 JAVADOC_AUTOBRIEF设置为 YES，在出现第一个“.” 后跟一个空格或空白行处结束，可在之后紧跟细节描述：

/// Brief description which ends at this dot. Details follow 
/// here. 

注释写在成员之后

​ 如果你希望文档化一个文件、结构、联合、类以及枚举的成员，需要为复合体中的这些成员放置文档。有时希望放置在成员之后的文档块，可以替换掉原有的块，如同前面所介绍的特殊注释块。

在注释块中加入“<” 标记（只使用“<”），将前一个注释块替换后一个注释块。这些块都有相同的结构和意义

警告：

• 这些块只能用于文档化成员和参数，无法用于文件，类，联合，结构，组，名字空间以及枚举
• 下面提到的结构化命令（比如\class）是不允许在这些注释块中出现的。

注释在其余位置

​ Doxygen 允许你将文档块放到任何位置（一个函数或一个 C 注释块的主体，是一个例外）。

到目前为止，我们假定文档块总是位于文件，类，名字空间的声明或定义的前端，或者处于它们成员的前后注释块中，尽管大多数时间这个约束是合适的。

有时出于别的原因要将文档放到其他位置，因为文件中不存在“文件前端”的位置而需要对文件进行文档化。

结构化命令

​ 使用结构化命令在不影响生成文档的情况下，所有的注释块将被移动到另一个位置或者是输入文件（例如源文件）。在实际中你最好避免使用结构化命令，除非其他的需求迫使你这样做。

缺点：

• 在文本行的前后端不能直接放置文档块，因为它有可能携带一些信息的副本。
• 所有的原型都要复制，那么所有的变更都需要执行两次！正因为如此你首先考虑上述的方式是否真的需要，和避免可能出现结构化命令。

​ 我经常收到一些例子，注释块中包含\fn 命令并放置在函数前端。很明显\fn 命令字是多余的，而它只会带来问题。

结构化命令字

结构化命令（和其他所有的命令一样）由一个反斜杠或“@”开始，如果你喜欢 JavaDoc风格，紧跟一个命令字和若干参数。如：

/*! \class Test 
\brief A test class. 

A more detailed class description. 
*/ 

这有一个特殊命令 \class 用于指示注释块包括类 Test 的文档。

其它特殊命令字

\struct 文档化一个 C 结构 
\union 文档化一个联合 
\enum 文档化一个枚举
\fn 文档化一个函数
\var 文档化一个变量，类型转换，枚举值其中之一 
\def 文档化一个#define 
\typedef 文档化一个类型转换\file 文档化一个文件 
\namespace 文档化一个名字空间 
\package 文档化一个 Java 包 
\interface 文档化一个 IDL 接口

文档化C++类

文档化一个 C++类成员，你必须先文档化 C++类，这同样适用于名字空间。

文档化全局对象头文件

​ 文档化全局对象（函数，类型转换，枚举，预处理定义宏，等等），你必须先文档化包含它们的文件。

文档化头文件

换句话说，必须在文件至少有一行以下内容：

/*! \file */ 

或

/** @file */ 

举例

这有一个使用结构化命令进行文档化的 C 头文件 structcmd.h：

/*! \file structcmd.h
 \brief A Documented file.
 
 Details.
*/

/*! \def MAX(a,b)
 \brief A macro that returns the maximum of \a a and \a b.
 
 Details.
*/

/*! \var typedef unsigned int UINT32
 \brief A type definition for a .
 
 Details.
*/

/*! \var int errno
 	\brief Contains the last error code. 
 	\warning Not thread safe! 
*/

/*! \fn int open(const char *pathname,int flags)
 	\brief Opens a file descriptor.
 	
 	\param pathname The name of the descriptor.
 	\param flags Opening flags.
*/

/*! \fn int close(int fd)
 	\brief Closes the file descriptor \a fd.
 	\param fd The descriptor to close.
*/

/*! \fn size_t write(int fd,const char *buf, size_t count)
 	\brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
 	\param fd The descriptor to write to.
 	\param buf The data buffer to write.
 	\param count The number of bytes to write.
*/

/*! \fn int read(int fd,char *buf,size_t count)
 	\brief Read bytes from a file descriptor.
 	\param fd The descriptor to read from.
 	\param buf The buffer to read into.
 	\param count The number of bytes to read.
*/

#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);

in body

in body描述:可看成一个细节描述，或者是执行细节的集合。

简述详述注释举例

变量详细描述

QT 风格:

int var; /*!< Detailed description after the member */ 

JavaDoc 风格:

 int var; /**< Detailed description after the member */ 

C++风格

int var; //!< Detailed description after the member 		 //!< 

int var; ///< Detailed description after the member  		 ///< 

变量简要描述

大多数时候也需要在一个成员之后，放置一个简明描述，如下：

C++风格

int var; //!< Brief description after the member 

int var; ///< Brief description after the member 

变量在函数中

​ 函数中可用“@param”来文档化它的参数，使用“[in], [out], [in,out]”文档化它的执行方向。内联文档则可能从方向属性开始记录

void foo(int v /**< [in] docs for input parameter v. */);

注意“<”作为一个函数参数值是有效的。

综合举例

/*! A test class */ 

class Test 
{
     

 public: 
 /** An enum type. 
  * The documentation block cannot be put after the enum!
 */

 enum EnumType 
 {
     
     int EVal1, /**< enum value 1 */
     int EVal2  /**< enum value 2 */
 };

 void member(); //!< a member function.

 protected:
    
    int value; /*!< an integer value */
};

不同语言的注释示例

​ Doxygen支持c风格注释、c++风格注释以及javaDoc风格注释等，下面将分别予以举例。

​ 由于Doxygen支持 javadoc的格式，但还有部分区别，按照如下方式可以作为注释的模板，可以参考Doxygen的具体文档，形成你自己的风格。

JavaDoc风格的注释

概述

JavaDoc 风格的注释风格主要使用下面这种样式： 即在注释块开始使用两个星号‘*‘

/**
 * description
 * description
 * description    
 */

简述与详述

​ Doxygen 支持的块（类、函数、结构体等）的注释描述分为两种：简述和详述，一般注释的描述由简述开始，经过特殊分隔方式后，后面紧跟详述的内容，javaDoc风格可以使用的分隔方法有以下两种：

使用\brief参数标识，空行作为简述和详述的间隔标识:

/**   @brief  Brief description.  
*   description continued.  
* 
*   Detailed description starts here. 
*/

​ 直接使用javaDoc风格，javaDoc风格自动以简述开头，以空行（或者小数点加空格）作为简述与详述的分割

/**     Brief description  
*     description continued . (注意:这里有一个小数点,加上一个空格)  
*     Detailed description starts here.  
*/

文件头注释示例

文件的开头必须有文件注释，否则该文件不会被识别：

/** \file math.h */
/**
 * @brief 说明内容
 * @param void
 * @return void
 * @author 123
 * @version v1.0.0.0
 * @date 2013
 * @since Keil uVision4
 * @bug 
 * @warning 
*/

类定义注释示例

/**   本类的功能：打印错误信息    *    *   本类是一个单件    *   在程序中需要进行错误信息打印的地方  */ class CPrintError  {
            ……  }

类成员变量定义示例

在成员变量上面加注释的格式

/** 成员变量描述 */int  m_Var;

在成员变量后面加注释的格式

int  m_color;   /**< 颜色变量 */

成员函数的注释示例

/** 下面是一个含有两个参数的函数的注释说明（简述）    *    *   这里写该函数的详述信息    *   @param a 被测试的变量（param描述参数）    *   @param s 指向描述测试信息的字符串    *   @return   测试结果 （return描述返回值）    *   @see   Test()（本函数参考其它的相关的函数，这里作一个链接）    *   @note   (note描述需要注意的问题)  */ int testMe(int a,const char *s);

枚举变量的注释示例

/**   颜色的枚举定义  
  *  
  *   该枚举定义了系统中需要用到的颜色\n  
  *   可以使用该枚举作为系统中颜色的标识  
*/ 
enum TEnum  
{
       
   RED,      /**< 枚举，标识红色   */    
   BLUE,      /**< 枚举，标志蓝色   */    
   YELLOW     /**< 枚举，标志黄色. */    
}enumVar;

使用 JavaDoc 风格

/**
 * A test class. A more elaborate class description.
*/ 

class Test 
{
     

 public: 

 /**
  * An enum. * More detailed enum description.
 */

 enum TEnum {
      
     TVal1, /**< enum value TVal1. */ 
     TVal2, /**< enum value TVal2. */ 
     TVal3  /**< enum value TVal3. */ 
 } 

 	*enumPtr, /**< enum pointer. Details. */
 	enumVar; /**< enum variable. Details. */

 

 /**
  * A constructor.
  * A more elaborate description of the constructor.
 */
 Test();

 /**
  * A destructor.
  * A more elaborate description of the destructor.
 */
 ~Test();

 /**
  * a normal member taking two arguments and returning an integer value.
  * @param a an integer argument.
  * @param s a constant character pointer.
  * @see Test()
  * @see ~Test()
  * @see testMeToo()
  * @see publicVar()
  * @return The test results
 */
 int testMe(int a,const char *s);

 /**
  * A pure virtual member. * @see testMe()
  * @param c1 the first argument.
  * @param c2 the second argument.
 */
 virtual void testMeToo(char c1,char c2) = 0;

 /**
  * a public variable.
  * Details.
 */
 int publicVar; 

 /**
  * a function variable.
  * Details.
 */
 int (*handler)(int a,int b);

};

C++风格的注释

概述

​ C++的注释风格主要使用下面这种样式：即在注释块开始使用三个反斜杠‘/’其他地方其实与JavaDoc的风格类似，只是C++风格不用“*”罢了。

注释风格约定

1. 一个代码块（类、函数、结构等）的概述采用单行的///加一个空格开头的注释，并写在该代码块声明的前面；
2. 一个代码块的详述采用至少两行的///加一个空格开头的注释，若不足两行第二行的开头也要写出来，并且放在代码块定义的前面；如果某代码没有声明只有定义或者相反，则在定义或者声明前面写上单行的概述+一个空行+多行的详述；
3. 枚举值列表的各项、结构域的各项等采用在本行最后添加///加一个空格开头的注释；
4. 对变量的定义采用在变量上面加单行///加一个空格开头的注释（相当于是给改变量一个概述）；
5. 函数的参数用/// @param+一个空格开头的行描述在函数的详述里面；
6. 函数的返回值用/// @return”+一个空格开头的行描述在函数的详述里面；
7. 函数之间的参考用/// @see+一个空格开头的行描述在函数的详述里面；
8. 文件头的版权以及文件描述的注释参见例代码。

简述与详述

C++风格的简述与详述方式与javaDoc类似。

一般注释的描述由简述开始，经过特殊分隔方式后，后面紧跟详述的内容，C++风格可以使用的分隔方法有以下两种：

使用\brief参数标识，空行作为简述和详述的间隔标识

///   \brief  Brief description. 
///  
///   description continued.  
///  
///   Detailed description starts here.  
///

使用以空行作为简述与详述的分割

///  Brief description  ///  ///  description continued ///   ///  Detailed description starts here.

以小数点加空格作为分隔如下：

///     Brief description  ///     description continued . （注意:这里有一个小数点,加上一个空格）  ///     Detailed description starts here.  

文件头注释示例

文件的开头必须有文件注释，否则该文件不会被识别：

/// \file math.h // @brief 说明内容// @param void/// @return void/// @author 123/// @version v1.0.0.0/// @date 2013/// @since Keil uVision4/// @bug /// @warning 

类定义注释示例

///   本类的功能：打印错误信息  ///  ///   本类是一个单件  ///   在程序中需要进行错误信息打印的地方  class CPrintError  {      ……  }

类成员变量定义示例

在成员变量上面加注释的格式

/// 成员变量描述 int  m_Var;

在成员变量后面加注释的格式

int  m_color;   /// 颜色变量

成员函数的注释示例

/// 下面是一个含有两个参数的函数的注释说明（简述）  
///   
///   这里写该函数的详述信息   
///   @param a 被测试的变量（param描述参数）   
///   @param s 指向描述测试信息的字符串   
///   @return   测试结果 （return描述返回值）  
///   @see   Test()   （本函数参考其它的相关的函数，这里作一个链接）  
///   @note   (note描述需要注意的问题)   
int testMe(int a,const char *s);

枚举变量的注释示例

///   颜色的枚举定义  
///  
///   该枚举定义了系统中需要用到的颜色  
///   可以使用该枚举作为系统中颜色的标识  
enum TEnum  
{
       
  RED,       ///< 枚举，标识红色    
  BLUE,      ///< 枚举，标志蓝色    
  YELLOW     ///< 枚举，标志黄色.    
}enumVar;

C++代码块使用 QT 注释风格的例子

//! A test class. 
/*!
 A more elaborate class description.
*/

class Test 
{
     

 public: 

 //! An enum.
 /*! More detailed enum description. */
 enum TEnum {
      
             TVal1, /*!< Enum value TVal1. */  
             TVal2, /*!< Enum value TVal2. */ 
             TVal3  /*!< Enum value TVal3. */ 
 } 

 //! Enum pointer.
 /*! Details. */
 *enumPtr, 

 //! Enum variable.
 /*! Details. */
 enumVar; 

 //! A constructor.
 /*!
 	A more elaborate description of the constructor.
 */
 Test();

 //! A destructor.
 /*!
 	A more elaborate description of the destructor.
 */
 ~Test();

 

 //! A normal member taking two arguments and returning an integer value.
 /*!
 	\param a an integer argument.
 	\param s a constant character pointer.
 	\return The test results
 	\sa Test(), ~Test(), testMeToo() and publicVar()
 */
 int testMe(int a,const char *s);


 //! A pure virtual member.
 /*!
 	\sa testMe()
 	\param c1 the first argument.
 	\param c2 the second argument.
 */ 
  virtual void testMeToo(char c1,char c2) = 0;

 

 //! A public variable.
 /*!
 	Details.
 */
 int publicVar;

 

 //! A function variable.
 /*!
 	Details.
 */
 int (*handler)(int a,int b);

};

Python 中的特殊文档块

Python 文档化代码的标准方式，调用文档字串来完成。字串可以保存在__doc__中，并能实时检索。Doxygen 能引用这些注释，并假定他们在预定义格式中可以被描述。

使用“”开始

"""@package docstring
Documentation for this module.

More details.
"""

def func(): 
 """Documentation for a function.

 More details.
 """
 pass

class PyClass: 
 """Documentation for a class.

 More details.
 """

 def __init__(self): 
 """The constructor."""
 self._memVar = 0;
    
 def PyMethod(self): 
 """Documentation for a method."""
 pass

注意，在此模式下 doxygen 的特殊命令字是不支持的。

使用##开始

​ 另一种文档化 Python 代码的方法使用“##”开始，这种注释块类型与其他 doxygen 支持语言的文档块比较一致， 在这种模式下允许使用特殊命令字 这是使用 doxygen 风格注释的同一个例子：

## @package pyexample
# Documentation for this module.
#
# More details.

## Documentation for a function.
#
# More details.
def func(): 
 	pass

## Documentation for a class.
#
# More details.
class PyClass: 
 

 ## The constructor.
 def __init__(self): 
 	self._memVar = 0;


 ## Documentation for a method.
 # @param self The object pointer.
 def PyMethod(self): 
 pass

 ## A class variable.
 classVar = 0;
 
 ## @var _memVar
 # a member variable

因为 Python 看上去越来越象 Java 而不是 C/C++，所以需要设置OPTMIZE_OUTPUT_JAVA 为 YES。

VHDL 中的特殊文档块

​ VHDL 的注释通常从“–”开始，doxygen 的注释从“–！”开始。在 VHDL 中只有这两种注释类型，“–！”开头的注释表明它是一个简明描述，而一个多行“–！”开头（每一行开始都会有“–！”符号）的注释则表明它是一个细节描述。

​ 注释总是处于将被文档化的文本行前端，并存在一个例外：端口的注释处于文本行的后端，并被当作端口的一个简明描述。

这有一个使用 doxygen 注释的 VHDL 文件的例子：

-------------------------------------------------------
--! @file
--! @brief 2:1 Mux using with-select 
-------------------------------------------------------

--! Use standard library
library ieee;

--! Use logic elements
 use ieee.std_logic_1164.all;

--! Mux entity brief description

--! Detailed description of this 
--! mux design element.
entity mux_using_with is  port (
     din_0 : in std_logic; --! Mux first input
     din_1 : in std_logic; --! Mux Second input
     sel : in std_logic; --! Select input
     mux_out : out std_logic --! Mux output
 );
end entity;

--! @brief Architure definition of the MUX
--! @details More details about this mux element.
architecture behavior of mux_using_with is 
begin 
     with (sel) select 
     mux_out <= din_0 when '0',
     din_1 when others;
end architecture;

​ 为获得合适的输出，需要设定 OPTIMIZE_OUTPUT_VHDL 为 YES，这个设置将会影响其他的一些设置。当他们没有被正确设定时，doxygen 也能发出一个警示，告知在哪里如何更改设置。

列表注释

Doxygen 支持创建文本行列表的多种方法。

使用破折号

​ 在每一行的开始处放置列对齐的多个减号“-”，一个 bullet 列表将自动生成。使用“-”紧跟“#”，也能生成一个带编号的列表。

这有一个例子：

/*! 
   * A list of events: 
   * 	- mouse events 
   * 		-# mouse move event 
   * 		-# mouse click event\n 
   * 			More info about the click event. 
   * 		-# mouse double click event 
   * 	- keyboard events 
   *		 	-# key down event 
   * 		-# key up event 
   *
   * More text here. 
   */ 

最终结果是：

A list of events: 
	● mouse events 
		a. mouse move event 
		b. mouse click event 
			More info about the click event. 
		c. mouse double click event 
	● keyboard events 
		a. key down event 
		b. key up event 
More text here. 

使用TAB

如果在列表中使用 tabs 进行缩排，请确认配置文件中 TAB_SIZE 选项是否设置了正确的 tab 尺寸。 可在列表结束的缩排层级的空白处放置一个点“.”或者开始一个新的段落，即可结束一个列表。

这有一个不言自明的例子：

/**
 * Text before the list 
 * - list item 1 
 * 	- sub item 1 
 * 		- sub sub item 1 
 * 		- sub sub item 2 
 * 		. 
 * 		The dot above ends the sub sub item list. 
 * 		More text for the first sub item 
 * 	. 
 * 	The dot above ends the first sub item. 
 * 	More text for the first list item 
 * 	- sub item 2 
 * 	- sub item 3 
 * 	- list item 2 
 * . 
 * More text in the same paragraph. 
 *
 * More text in a new paragraph. 
*/ 

使用HTML 命令

​ 如果你喜欢也可以在文档块中使用 HTML 命令。使用这些命令的优点在于，列表行中包含的多个段落看起来更自然。

这有一个运用 HTML 命令的例子：

 /*! 
  * A list of events: 
  * <ul>
  * 	<li> mouse events 
  * 	<ol>
  * 	<li>mouse move event 
  * 	<li>mouse click event\n 
  * 		More info about the click event. 
  *		 <li>mouse double click event 
  * 	ol>
  * <li> keyboard events 
  * 	<ol> 
  * 	<li>key down event 
  * 	<li>key up event 
  * 	ol>
  * ul>
  * More text here. 
  */ 

注意：在 HTML 模式下缩排的层级并不重要。

使用\arg 或者@li

​ 为兼容 QT 的内部文档工具 qdoc 和 kDoc，doxygen 有两个可用于创建简单的无嵌套列表的命令。

组合注释

Doxygen 一共有三种组合的机制

• 一种工作于全局级别，为每一个组创建一个新页面。在文档中这些组被称为“模块”，
• 第二种工作在一些复合体的成员列表中，参考“成员组”。
• 第三种工作于页面，参考“子页面”。

模块

​ 进行设计时，通常有模块的概念，**一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。 **如何对这个概念进行注释？doxygen提供了group的概念，生成的模块的注释会单独放在一个模块的页面中。

​ 模块是在一个独立页面中进行组合的方法，你可以文档化整个组以及所有单独的成员，一个组的成员可以是文件，名字空间，类，函数，变量，枚举，类型转换以及定义，但也可以是其他的组。

定义一个组

​ 定义一个组，你需要在特殊注释块中放置\defgroup或@ defgroup命令，\和@等同。命令的第一个参数是一个组的 uid（uniquely identify唯一表示）label，第二个参数是将出现在文档中的组的名称或标题。

​ 在组之前使用打开标记“@{ ”，或在组之后使用关闭标记“@}”，将每一个成员组合在一起，并在文档中避免放 置\ingroup 命令。这些标记可放置在组定义的文档或一个独立的文档块中。

使用下面的格式定义一个group

/**
 * \defgroup [A] [brief group description ] 
 */

/*@{*/ 

    /** a variable in group A */
    int VarInA;

/*@}*/ 

​ group中的代码可以有自己的注释。

单纯定义一个模块，去除{ 和}命令即可。

组命名

​ 对这种组进行命名可以使用name命令。此时中间代码可以有自己的注释。如：

/** @name group_name
 * description for group.
 */
//@{
     

	code…
        
//@}

组引用名称

​ \ref 命令定义组的引用名称，第一个参数\ref 命令将用到组 label，如果要用自定义链接名称，可在 label之 后可放置使用双引号修饰的链接名称，如下面的例子所示：

This is the \ref group_label "link" to this group. 

添加一个组中的成员个体

​ 任何其他代码项（比如类、函数、组甚至文件）如果要加入到某个模块，可以在其doxygen注释中使用ingroup命令即可。

变量

/**
 * \ingroup A 
 */ 
extern int VarInA;

组

Group之间使用ingroup命令，可以组成树状关系。

/**@file util.cpp
 * @ingroup [group_name]
 * @brief files brief info.
*/

添加多个组中成员个体

​ 把多个代码项一起添加到某个模块中可以使用addtogroup命令，格式和defgroup相似。

​ 组可以使用自身的组标记实现嵌套。 当使用相同的组 label 超过一次，你将得到一个错误消息。

​ 如果你不希望 doxygen 强制组 label 的唯一性，可用\addtogroup 替换掉\defgroup，当组已经被定义，它可以合并到一个已经存在的文档中，形成一个新组。组标题 对于这个命令来说是可选的。所以你可以使用

/** \addtogroup  */ 
/*\@{*/ 
/*\@}*/ 

注意：

复合体（比如类，文件，名字空间）可放到多个组中

成员（比如变量，函数，类型转换，枚举）只能是一个组中的组成员（这种位置上的限制，是为了当一个成员在它的类，名字空间，文件的正文中无法被文档化而在组中却是可见的情况下，避免链接组目标时产生二义性 ）

组成员优先级

​ Doxygen 放置组成员时，会将其定义为最高的“优先级”：

覆盖

​ 例如一个直接\ingroup 命令可通过“@{ @}”覆盖掉一个意义含混的组定义。相同优先级下的组定义冲突将触发一个警告，除非一个成员定义并未出现在其他直接的文档中。

​ 以下的例子是放置 VarInA 到组中，解决 IntegerVariable 放置IntVariables 组的冲突，因为 extern int IntegerVariable 无法不被文档化的：

/**
 * \ingroup A 
*/ 
extern int VarInA;

/**
 * \defgroup IntVariables Global integer variables 
*/ 
/*@{*/ 

/** an integer variable */ 
extern int IntegerVariable; 

/*@}*/ 

.... 

/**
 * \defgroup Variables Global variables 
*/ 
/*@{*/ 

/** a variable in group A */ 
int VarInA;

int IntegerVariable; 

/*@}*/ 

组定义的优先级

组定义的优先级（从最高到最低）：\ingroup,\defgroup,\addtogroup,\weakgroup。最后的命令\addtogroup想比有一个更低的优先级（？），但\weakgroup 允许你添加“松散”的组定义：你能在.h 文件中使用更高级别的命令来定义层次结构，而在.c 文件中的\weakgroup 无须完全复制这种层次结构。

例子：

/** @defgroup group1 The First Group 
 * This is the first group 
 * @{ 
*/ 

    /** @brief class C1 in group 1 */ 
    class C1 {
     };

    /** @brief class C2 in group 1 */ 
    class C2 {
     };

    /** function in group 1 */ 
    void func() {
     }

/** @} */ // end of group1 


/**
 * @defgroup group2 The Second Group 
 * This is the second group 
*/ 

/** @defgroup group3 The Third Group 
 * This is the third group 
*/ 

/** @defgroup group4 The Fourth Group 
 * @ingroup group3 
 * Group 4 is a subgroup of group 3 */ 
/**

 * @ingroup group2 
 * @brief class C3 in group 2 
*/ 
class C3 {
     };

/** @ingroup group2 
 * @brief class C4 in group 2 
*/ 
class C4 {
     };

/** @ingroup group3 
 * @brief class C5 in @link group3 the third group@endlink. 
*/ 
class C5 {
     };

/** @ingroup group1 group2 group3 group4 
 * namespace N1 is in four groups 
 * @sa @link group1 The first group@endlink, group2, group3, group4 
*
 * Also see @ref mypage2 
*/ 
namespace N1 {
     };

/** @file 
 * @ingroup group3 
 * @brief this file in group 3 
*/ 

/** @defgroup group5 The Fifth Group 
 * This is the fifth group 
 * @{ 
*/ 

/** @page mypage1 This is a section in group 5 
* Text of the first section 
*/ 

/** @page mypage2 This is another section in group 5 
 * Text of the second section 
*/ 

/** @} */ // end of group5 
/** @addtogroup group1 
 * 
 * More documentation for the first group. 
 * @{ 
*/ 

/** another function in group 1 */ 
void func2() {
     }

/** yet another function in group 1 */ 
void func3() {
     }

/** @} */ // end of group1 

成员组

​ 如果一个复合体（比如一个类或文件）有很多成员，通常希望能将成员们一同合并到组中，doxygen 在类型 和保护层级之上，已经能够自动组合， 但是你也许感觉有这些还不够或是认为缺省的组合操作将会出错，例如 你觉得存在类型差异（语法的）的成员属于相同（语义上的）的组。

​ 如果你喜欢 C 风格注释，用以下两种块模板来定义一个成员组，注意成员组内部的组成员都必须是确实存在。

//@{ 
 ...
 //@} 

或

/*@{*/ 
 ... 
/*@}*/ 

​ 在一个块开始标记“@{”之前可以放置一个单独的注释块，而此块必须包含@name (或 \name)命令，用于指定组的头部，也可选择让注释块包含更多的组信息。

*** *对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念， ****可以通过下面的方式：

//@{
     
/** Comments for all below code. */
code…
//@}

成员组的嵌套是不被允许的。

组保护级别

​ 如果一个类的成员组中的全部组成员都有相同的类型和保护级别（比如全是静态公有成员），那么整个成员组被当成类型/保护级别组的一个子分组（例如成员组将被看\“静态公有成员\”节点的子节点），假如两个或多个成员有不同的类型，那么组会将它们置于相同的层级上自动生成一个组，假如你希望强制类的全部组成员在顶层，你需要在类文档中加入\nosubgrouping 命令。

例子：

/** A class. Details */ 

class Test 
{
     

 public: 

//@{
     
    /** Same documentation for both members. Details */ 
    void func1InGroup1();
    void func2InGroup1();
//@}

 /** Function without group. Details. */ 
     void ungroupedFunction();
     void func1InGroup2();
protected: 
     void func2InGroup2();

};

void Test::func1InGroup1() {
     }
void Test::func2InGroup1() {
     }

/** @name Group2 
 * Description of group 2. 
*/ 
//@{ 
    /** Function 2 in group 2. Details. */ 
    void Test::func2InGroup2() {
     }
    /** Function 1 in group 2. Details. */ 
    void Test::func1InGroup2() {
     }
//@} 

/*! \file 
 * docs for this file 
*/ 

//@{
     
//! one description for all members of this group 
//! (because DISTRIBUTE_GROUP_DOC is YES in the config file)
    \#define A 1 
    \#define B 2 
    void glob_func();
//@}

​ Group1 看成公有成员的子节点，而 Group2 则是一个独立节点，因为它包含成员中存在不同保护级别（即公有和保护）。

子页面

​ 信息可用\page 和\mainpage 命令合并到页面中，正常情况下，结果将置于页面的平直（无缩排）列表中，列表的起始端即为\“主\”页面。

​ 在“模块”章节中简述添加结构的替代方法，为了更自然和方便地增加额外结构到页面中，可以使用\subpage命令。

​ A 页面用\subpage 命令增加一个链接到 B 页面，同时将 B 页面变成 A 页面的一个子页。这对于 GA，GB 两个组同 样有影响，使得 GB 变为 GA 一部分的方法，将 A 页面置于 GA 组内，而将 B 页面置于 GB 组内即可。

包含公式

​ Doxygen 允许你放置 Latex 公式在输出中（只能支持 HTML，Latex 的输出，无法用于 RTF 和 man 页面输出），在 HTML 文档中可以包含公式（可看成图片），你需要安装以下工具：

• Latex：latex 编译器，解析公式时需要它，我使用 teTex 1.0 发行版本做测试
• dvips：转换 DVI 文件为 PostScript 文件的工具，我使用 Radical Eye 5.92 版本做测试
• gs：Ghostscript 解释器，用于转换 PostScript 文件为位图，我使用 Aladdin Ghostscript 8.0 做测试

在文档中包含公式的若干方法：

文本公式

​ 在运行的文本中使用文本公式，这些公式可以放置在一对 \f$ 命令之间，如：

The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$. 

结果为：

集中于单独一行的非数字公式

​ 集中于单独一行的非数字公式，这些公式可放置在 \f[ 和 \f]命令之间，一个例子：

\f[
    |I_2|=\left| \int_{0}^T \psi(t) 
             \left\{ 
                u(a,t)- 
                \int_{\gamma(t)}^a 
                \frac{d\theta}{k(\theta,t)}
                \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi 
              \right\} dt 
          \right| 
\f]

结果为：

对于非数学领域的公式或

Latex 元件可用\f{environment}命令说明, environment 是 Latex 所支持的environment 名称，配合\f}终止命令，这有一个等式计算的例子：

\f{eqnarray*}{
 		g &=& \frac{Gm_2}{r^2} \\ 
 		&=& \frac{(6.673 \times 10^{-11}\,\mbox{m}^3\,\mbox{kg}^{-1}\,
 \mbox{s}^{-2})(5.9736 \times 
10^{24}\,\mbox{kg})}{(6371.01\,\mbox{km})^2} \\ 
 &=& 9.82066032\,\mbox{m/s}^2 

\f}

结果为：

​ 前两个命令都能确定公式包含有 [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-CLbJVs39-1631945542641)(Qt5.12.6+Doxygen生成chm开发手册教程.assets/image-20210616154519974.jpg)]数学模式下的有效命令，第三个命令包含特殊环境下的有效命令。

警告：

​ 当前 doxygen 的公式从错误中自动修正的容错能力，还不能令人满意。它可能会成功删除已写入 html 目 录的 formula.repository 文件，以丢弃一个出错的公式。

生成chm开发文档配置

提供三种方式：

Wizard方式指简约方式：在其中只提供一些重要的参数设置，其余的均为默认值；

Expert方式为详细方式：通过该选项可以详细地配置Doxygen的各个配置项；

Doxyfile Load方式：用于导入以前生成的Doxyfile配置文件，导入后可以再点击Expert进行修改。

简单配置指南

打开doxywizard

开始–>所有程序–>Doxygen–>doxywizard

简单使用举例

代码举例

工作目录如下：

.

├── out

└── src

└── math.h

/*! \file math.h 中的一个函数*/

/*!

  用于求一个角度的sin值，输入是字符串以便同时支持弧度制和角度制表示

  \li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角
  \li 角度制用d结尾，例如：360d表示一圈、90d表示直角
  \li 输入也可以是数值，例如：输入3.14159大约表示180度


  \param a 用弧度制或角度制表示都行，字符串必须用'\0'表示结束
  \param[out] res 是输出参数，用于保存sin运算的结果

  \return 错误码，0表示成功，其它表示失败

  \todo 在xxx的情况下存在BUG，预计下一版本修复

*/

int sin(char *a, double *res);

简单配置

​ 这里我们只填入必要的配置，其它配置都用默认值。

生成HTML文档

位置

文档位置在之前的out目录下。

函数注释

默认页面样式

Doxygen输出的默认HTML比较难看，如图

默认主色调

Doxygen默认的页面主色调大约是天蓝色的。

默认导航栏

Doxygen中「导航栏」有两种展示方式：Treeview和Index，分别是竖向和横向的

可以配置DISABLE_INDEX和GENERATE_TREEVIEW来控制是否显示它们，如图。

详细配置指南

Step 1:Specify the working directory from which doxygen will run：步骤1：指定运行 doxygen 的工作目录

Step 2: Configure doxygen using the Wizard and/or Expert tab,then switch to the Run tab to generate the documenting 步骤 2：使用向导和/或专家选项卡配置 doxygen，然后切换到运行选项卡以生成文档

Wizard

Project

名称说明：

Project name ：项目名称，将在最新的文档首页中显示

Project synopsis：项目概要

Project version or id：项目版本和ID

Project logo：项目图标

Source code directory： 源码目录，选择要生成文档的源代码或目录，可以有多个文件或目录形成一个列表。（建议使用相对路径，相对当前配置文件所在的目录）

Scan recursively ：递归扫描*，*如果需要对整个源码目录下的所有子目录及文件生成文档，请勾选本项。

Destination directory：输出目录：设置最终生成的帮助文档的存储路径，建议使用相对路径

示例：

Mode

名称说明：

select the desired extraction mode ：选择所需的提取模式

Documented entities only：只生成文档

All Entities：所有实体，图片、html等，可以输出相对完整的功能。

Include cross-referenced source code in the output：是否包含源代码看你自身情况

select programming language to optimize the results for：选择被注释的编程语言以优化结果

Optimize for C++ output：优化C++语言的注释

Optimize for C++ /CLI output：优化 C++ /CLI 语言的注释

Optimize for Java/C# output：优化Java/C#语言的注释

Optimize for C++/PHP output：优化C++/PHP语言的注释

Optimize for Fortran output：优化Fortran语言的注释

Optimize for VHDL output：优化VHDL语言的注释

示例：

Output

​ 如果你需要输出chm格式，请在Output中勾选。

名称说明：

select the output format to generate：选择要生成的输出格式

HTML：html格式

Plain HTML:优化HTML

With navigation panel:带有导航窗格

***prepare for compressed HTML（.chm）***：准备压缩的HTML

With search function:具有搜索功能

Change color…:调整html页面的外观风格

LaTeX：数学公式

Man pages：主页

Rich Text Format(RTF)：富文本格式

XML：xml格式

示例：

Diagrams

​ 在Diagrams中可以选择使用GraphViz插件包，来将代码结构输出UML图.

名称说明：

Diagrams to generate：生成图片

No diagrams：无图表

Use built-in class diagram generator：使用内置的类图生成器

Use dot tool from the GraphViz package：使用GraphViz软件包中的点工具

dot graphs to generate点图生成

class diagrams：类图

collaboration diagrams：协作图

overall class hierarcy graphs：整体类层次图

include dependency graphs：包括依赖图

included by dependency graphs：依赖图包含

call graphs：调用图

called by graphs：由图调用

示例：

Expert

所有高级设置（包括编码设置）都在“Expert”标签

Project

名称说明：

DOXYFILE_ENCODING：当前 Doxygen 配置文件本身的字符编码，默认为UTF-8，一般不需要修改

**OUTPUT_LANGUAGE&：输出语言。这里是指Doxygen自己生成的导航、提示、帮助等文本的文字采用的语言。我们希望帮助文档是全中文的，所以选择Chinese

示例：

Build

名称说明：

EXTRACT_PACKAGE：提取包

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

示例：

Messages

无手动修改

Input

INPUT_ENCODING：输入文件的编码，指我们的源代码文件本身的编码。在Windows平台一般是系统编码（GBK），而Linux平台一般是UTF-8。请用文本编辑器查看源文件的编码。这里如果设置的不一致，源码文件的注释中所有非ASCII字符将在生成的文档中变成乱码。

Source Browser

无手动修改

Index

无手动修改

HTML

名称说明：

GENERATE_HTMLHELP：确保已经勾选了

CHM_FILE：最终生成的.chm的文件名，默认为“index.chm”.如“HkcProj。ctHelp.chm”,方便寻找。可以使用路径，也可以使用相对路径，相对于上面设置的输出目录的html目录（建设使用上一级目录，如“…\MyDoc.chm”）

HHC_LOCATION：chm 编译器（hhc.exe）的全路径。请指到 HTML Help Workshop 的安装目录的 hhc.exe 程序 。

CHM_INDEX_ENCODING*：*这里设置Doxygen生成的CHM索引文件的编码，以前是不能设置的，默认为UTF-8，而微软的编译器不能识别UTF-8编码的索引文件，所以最终造成左边目录导航栏乱码。我们设置它为GBK，这样Doxygen将为我们生成GBK编码的索引文件（.hhc、.hhk、.hhp）

示例：

LateX

无手动修改

RTF

无手动修改

Man

无手动修改

XML

无手动修改

Docbook

无手动修改

AutoGen

无手动修改

Sqlite3

无手动修改

PerlMod

无手动修改

Preprocessor

无手动修改

External

无手动修改

Dot

在Expert的Dot中勾选CLASS_DIAGRAMS,UML_LOOK

CLASS_DIAGRAMS：类图表

UML_LOOK：uml视图，根据需求。

DOT_IMAGE_FORMAT：为了减少chm体积，在中选择gif或者jpg，均可。

DOT_PATH：下面填入graphiv的bin目录绝对路径。

Run

点击Run doxygen

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-pJyUlFGu-1631945542650)(https://ossimg.weixinzeng.cn/%E5%8D%9A%E5%AE%A2%E5%9B%BE%E7%89%87/Typora%E4%BD%BF%E7%94%A8%E6%95%99%E7%A8%8B/20210619145539.jpg)]

点击Show HTML output

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-SSurUCDI-1631945542651)(https://ossimg.weixinzeng.cn/%E5%8D%9A%E5%AE%A2%E5%9B%BE%E7%89%87/Typora%E4%BD%BF%E7%94%A8%E6%95%99%E7%A8%8B/20210619145607.jpg)]

生成的参考手册网页版，在目标目录下会生成一个文件夹，如果生成成功会找到一个xxx.chm文件。

导入配置文件

配置文件介绍

​ 配置文件是一个开放的 ASCII 文本文件，且包含一个类似于 Makefile 的文件结构，它的默认名称是 doxyfile，并能被 doxygen 解析。

制表和换行

​ 这个文件可以包含若干的制表符和换行符，用于格式化的目的。

大小写敏感

​ 文件中语句对大小写敏感，能在文件的任何位置放置注释（除了引号之间）。从“#”字符开始的一行内容将被当成注释。

赋值语句

格式：该文件主要包括一个赋值语句列表，每条语句的首部都包括一个TAG_NAME，并跟随一个“=”符号，以及一个或多个值。

赋值：如果同一个选项被多次赋值，那么最后的赋值将覆盖掉之前的。

参数列表：对于能附带参数列表的选项，可以使用“+=”操作符来替代“=”，它能将新值添加到参数列表中，而其中的值是一个无空格的连接序列，如果这些值包含一个或多个空格，它必须使用引号（“…”）。

连接多个行：在一行的最后一个字符后插入一个反斜杠“\”，可将多个行连接在一起。

包含其它配置文件

环境变量使用$(ENV_VARIABLE_NAME)来扩展。

你也能使用@INCLUDE 标记包含其他的配置文件，如下：

@INCLUDE = config_file_name Doxygen 将会在当前工作目录下搜索被包含的配置文件，你也能指定一个目录列表，用于在查找当前工作目录之前进行配置文件的搜索。在@INCLUDE 标记之前放置一个@INCLUDE_PATH 标记，如： @INCLUDE_PATH = my_config_dir

配置文件例子

最小配置文件

假定你已有了一个包含两个文件的简单项目：一个 example.cc 源文件和一个 example.h 头文件，以及一个同样

简单的最小配置文件：

INPUT = example.cc example.h 

假定例子使用 Qt 类，perl 位于/usr/bin，一个更实用的配置文件，如下：

PROJECT_NAME = Example 
INPUT = example.cc example.h 
WARNINGS = YES 
TAGFILES = qt.tag 
PERL_PATH = /usr/bin/perl
SEARCHENGINE = NO 

QdbtTabular配置文件

以下是为生成 QdbtTabular程序包文档所用的配置文件：

参考

PROJECT_NAME = QdbtTabular OUTPUT_DIRECTORY = htmlWARNINGS = YES INPUT = examples/examples.doc src FILE_PATTERNS = *.cc *.h INCLUDE_PATH = examples TAGFILES = qt.tag PERL_PATH = /usr/local/bin/perlSEARCHENGINE = YES 

Qt-1.44 源码文档配置文件

以下是为重新生成 Qt-1.44 源码文档所用的配置文件：

PROJECT_NAME = Qt OUTPUT_DIRECTORY = qt_docs HIDE_UNDOC_MEMBERS = YES HIDE_UNDOC_CLASSES = YES ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES SEARCH_INCLUDES = YES FULL_PATH_NAMES = YES STRIP_FROM_PATH = $(QTDIR)/PREDEFINED = USE_TEMPLATECLASS Q_EXPORT= \ QArrayT:=QArray \ QListT:=QList \ QDictT:=QDict \ QQueueT:=QQueue \ QVectorT:=QVector \ QPtrDictT:=QPtrDict \ QIntDictT:=QIntDict \ QStackT:=QStack \ QDictIteratorT:=QDictIterator \ QListIteratorT:=QListIterator \ QCacheT:=QCache \ QCacheIteratorT:=QCacheIterator \ QIntCacheT:=QIntCache \ QIntCacheIteratorT:=QIntCacheIterator \ QIntDictIteratorT:=QIntDictIterator \ QPtrDictIteratorT:=QPtrDictIterator INPUT = $(QTDIR)/doc \ $(QTDIR)/src/widgets \ $(QTDIR)/src/kernel \ $(QTDIR)/src/dialogs \ $(QTDIR)/src/tools FILE_PATTERNS = *.cpp *.h q*.doc INCLUDE_PATH = $(QTDIR)/include RECURSIVE = YES 

Qt-2.1 源码文档配置文件

以下是用于 Qt-2.1 的推荐设置： PROJECT_NAME = Qt

PROJECT_NUMBER = 2.1HIDE_UNDOC_MEMBERS = YES HIDE_UNDOC_CLASSES = YES SOURCE_BROWSER = YES INPUT = $(QTDIR)/src FILE_PATTERNS = *.cpp *.h q*.doc RECURSIVE = YES EXCLUDE_PATTERNS = *codec.cpp moc_* */compat/* */3rdparty/*ALPHABETICAL_INDEX = YES COLS_IN_ALPHA_INDEX = 3 IGNORE_PREFIX = Q ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES INCLUDE_PATH = $(QTDIR)/include PREDEFINED = Q_PROPERTY(x)= \ Q_OVERRIDE(x)= \ Q_EXPORT= \ Q_ENUMS(x)= \ "QT_STATIC_CONST=static const " \ _WS_X11_ \ INCLUDE_MENUITEM_DEFEXPAND_ONLY_PREDEF = YES EXPAND_AS_DEFINED = Q_OBJECT_FAKE Q_OBJECT ACTIVATE_SIGNAL_WITH_PARAM \ Q_VARIANT_AS 

doxygen 预处理可代用通常情况下的 C 预处理器，但无法实现宏的完全展开。

制作配置文件Doxyfile

​ 如果我们希望下次代码改动后能够继续沿用上次配置，那么我们可以把上面两种方式的配置保存成Doxyfile文件。

导入配置文件Doxyfile

通过界面的Open导入

高级配置

不同编程语言的扩展名配置

文件名符合FILE_PATTERNS都会被处理。

默认扩展名

其中包括了.c、.h、.py等等

自定义扩展名

​ 如果我们的扩展名并不在FILE_PATTERNS内，那么可以加上去。例如我们项目下的所有.ccc文件，其实是C语言代码（这很奇葩，举个例子而已）。那我们可以编辑Doxyfile配置文件满足这一需求，需要2个步骤。

​ 在EXTENSION_MAPPING中添加映射规则ccc=C，如图3-3。语法是ext=language，其中language可以取的值有：IDL、Java、Javascript、C#、C、C++、D、PHP、Objective-C、Python、Fortran、VHDL。

个性化样式设置

如果嫌生成的HTML不好看，可以自定义HTML页面头部、尾部以及页面整体CSS样式表。

修改HTML头尾

配置HTML_HEADER、HTML_FOOTER、HTML_STYLESHEET指向修改后的文件，如图。

修改主色调

可以通过HTML_COLORSTYLE_HUE、HTML_COLORSTYLE_SAT、HTML_COLORSTYLE_GAMMA修改主色调，这3个配置分别对应色相、饱和度、Gamma校正，见图。如果不太懂色相、饱和度是啥意思，请自行百度「色彩模式」或参考Photoshop相关教程。

修改导航栏目录结构

我们已经知道Doxygen中「导航栏」有Treeview和Index两种了。这节介绍如何定制导航栏的目录结构。这需要三个步骤。

1. 编辑DoxygenLayout.xml文件，修改其中的布局

2. 修改LAYOUT_FILE配置，使其指向DoxygenLayout.xml文件，如图

3. 运行Doxygen

那么如何修改XML文件呢？默认的DoxygenLayout.xml代码如下：

<doxygenlayout version="1.0"> <navindex>  <tab type="mainpage" visible="yes" title=""/>  <tab type="pages" visible="yes" title="" intro=""/>  <tab type="modules" visible="yes" title="" intro=""/>  <tab type="namespaces" visible="yes" title="">   <tab type="namespacelist" visible="yes" title="" intro=""/>   <tab type="namespacemembers" visible="yes" title="" intro=""/>  tab>  <tab type="classes" visible="yes" title="">   <tab type="classlist" visible="yes" title="" intro=""/>   <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>    <tab type="hierarchy" visible="yes" title="" intro=""/>   <tab type="classmembers" visible="yes" title="" intro=""/>  tab>  <tab type="files" visible="yes" title="">   <tab type="filelist" visible="yes" title="" intro=""/>   <tab type="globals" visible="yes" title="" intro=""/>  tab>  <tab type="examples" visible="yes" title="" intro=""/>   navindex> doxygenlayout>

​ XML对应了导航栏的目录树结构，我们通过该文件改变布局。标签的type属性取值除了上面列出的这些预定义值以外，还可以是type="user"或type=“usergroup”，我们只能通过这两个type自定义布局，例如下面这段代码，生成的效果如图

<doxygenlayout version="1.0"> <navindex>  <tab type="usergroup" visible="yes" title="友情链接（演示如何外链）">   <tab type="user" visible="yes" title="百度" url="http://www.baidu.com" />   <tab type="user" visible="yes" title="163" url="http://www.163.com" />  tab>  <tab type="usergroup" visible="yes" title="数学库（演示如何链接文件）">   <tab type="user" visible="yes" url="@ref math.h" title="math" />   <tab type="user" visible="yes" url="@ref math2.h" title="math2" />  tab>  <tab type="usergroup" visible="yes" title="三角函数（演示链接函数、结构体）">   <tab type="user" visible="yes" url="@ref sin" title="sin" />   <tab type="user" visible="yes" url="@ref sin2" title="sin2" />  tab>  navindex> doxygenlayout>

完全自定义

​ 如果Doxygen输出的界面实在不入你的法眼，以上介绍的定制化功能也不能彻底满足你的需求。那么你需要根据Doxygen输出的XML数据自行生成界面了。

1. 将GENERATE_XML配置为YES
2. 去输出目录寻找生成的XML文件，XML文件包括了函数信息、注释信息等
3. 自己写程序读取XML文件，并生成漂亮的文档

常见问题

输出chm的问题

如何输出.chm文件

1. 你必须安装微软或其相兼容的chm编译系统。通常为HTML Help Workshop。Microsoft网站
2. 在[Wizard…]的Output页面中，选择HTML，然后选择到prepare for compressed HTML(.chm)。
3. 在[Expert…]的HTML页面中，将HHC_LOCATION指向微软的hhc工具。通常为C:/Program Files/HTML Help Workshop/hhc.exe。
4. 点击OK，保存，编译即可。

生成了chm，但是无内容

1. 你必须安装微软或其相兼容的chm编译系统。通常为HTML Help Workshop。
2. 在[Wizard…]的Output页面中，选择HTML，然后选择到prepare for compressed HTML(.chm)。
3. 在[Expert…]的HTML页面中，将HHC_LOCATION指向微软的hhc工具。通常为C:/Program Files/HTML Help Workshop/hhc.exe。
4. 点击OK，保存，编译即可。

如何去掉CHM附带的CHI文件？

​ 注意在默认情况下，CHM会有一个CHI文件，似乎是用来加速索引的。我本人也遇到过很多用户仅仅上传了CHM，**而没有上传CHI文件，导致无法正常显示的情况。我不知道是否可以通过工具重建CHI文件，但是我觉得关闭这个功能即可。 **

​ 打开[Expert…]的HTML页面，取消GENERATE_CHI即可。

error:failed to run html help compiler on index.hhp

小故事：我可以用Doxygen生成一个CHM文件。启动CHM文件，我发现内容和索引选项卡确实列出了这些类的页面，名称空间，类和成员。但是，单击这些内容和索引列表中的项目不会显示任何内容。如何使用Doxygen和HTML帮助编译器生成CHM？

我在使用Windows 7 Professional SP1（64位）的计算机上。

我使用Doxywizard在我的代码上运行Doxygen版本1.8.9.1。它正确地生成HTML输出;页面，命名空间，类和成员出现在文档中。

然后我又想将HTML转换成压缩的HTML（CHM）文件。

我从Microsoft网站下载了Microsoft HTML Help Workshop 1.31版（即htmlhelp.exe版本4.74.8703）。我运行了安装程序。当安装程序正在进行时，出现弹出消息：

This computer already has a newer version of HTML Help.

但是，安装已成功完成。而且，hhc.exe程序就在那里，我告诉它安装。

我现在指定这些相关Doxygen的设置：

向导 - >输出：

HTML检查

“压缩HTML（的.chm）准备” 选项被选中。

专家 - > HTML：

GENERATE_HTMLHELP = YES

CHM_FILE = Foo.chm

HHC_LOCATION = C：\ Program Files文件（x86）的\微软\的HTML Help Workshop的\ hhc.exe

当我再次运行Doxygen的，它会报告错误：

error: failed to run html help compiler on index.hhp

在预期的位置生成Foo.chm文件。但是，如上所述，它缺少很多内容。

我试着在Doxygen生成的HHP文件上手动运行hhc.exe。它不表示任何错误。

C:\Program Files (x86)\Microsoft\HTML Help Workshop>hhc c:\test\html\index.hhp

Microsoft HTML Help Compiler 4.74.8702

Compiling c:\test\html\Foo.chm

Compile time: 0 minutes, 3 seconds 292 Topics 3,855 Local links 83 Internet links 0 Graphics

Created c:\test\html\Foo.chm, 259,580 bytes

Compression decreased file by 1,077,915 bytes.

然而，结果是一样的：一个Foo.chm文件缺少内容。

我后来发现我在我的电脑上安装了另一个HTML Help Workshop。但是，hhc.exe是完全相同的版本。所以，这可能不是问题。

你能否建议我还可以尝试获取所有文档内容以显示在CHM文件中？

参考

回答

当我看到这个问题（html存在和chm有内容但内容不可见）时，这是因为Windows安全已经“阻止”了chm文件。要查看这是你遇到的问题，请尝试以下操作：

在Windows资源管理器中，右键单击生成的.chm文件并选择属性。

在“常规”选项卡上，如果看到“解除阻止”按钮，请单击它。

关闭对话框并打开.chm文件。

（我还没有遇到这个问题，doxygen的.chm文件本地产生的，但我从你的描述希望，这可能会解决你的问题。）

我没有看到“阻止”按钮点击。但是，这让我想到了正确的道路。我已经简化了我的上述问题描述，说“Foo.chm”文件在’c：'驱动器上。但是，它实际上位于映射的网络驱动器上。当我将CHM文件复制到计算机上的物理驱动器时，显示的所有内容。问题解决了。谢谢。

中文问题

如何彻底解决DoxyGen的输出中文chm的乱码问题？

DoxyGen的实现中大概有三处编码的设置。

首先是，doxyfile，也就是配置文件。

其次，INPUT_ENCODING，也就是DoxyGen需要解析的输入文件的编码*

最后，**就是输出的编码。**譬如CHM左边的索引编码。

chm的标题乱码

首先是chm的标题乱码，这个比较好解决，因为DoxyWizard使用QT做的界面，它内部做了转换，所以在DoxyWizard中输入中文，在保存的时候，他自己做了转码，导致doxyfile中的最终的保存信息不正确。这个时候只需要用记事本打开doxyfile配置文件，输入相应中文即可。注意保存的时候保存成ANSI编码即可。保存成其他格式的话可能需要去掉BOM，比较麻烦，没研究了。这个相应的编码设置在[Expert…]中，页Project 的 DOXYFILE_ENCODING，不输入或者默认为UTF-8都行。

右边内容乱码

​ 其次是右边内容乱码，这个多半是因为你没有配置好输入的文件编码类型造成的。

​ 在[Expert…]的Input页面中，有一个INPUT_ENCODING，这个选项表示输入文件的编码方式，这要和你处理的源文件格式一致。对于我们来说（使用vs的人），一般设置为GB2312。当然，再次声明，编码方式取决于源文件的编码方式。如果文件编码已经是UTF-8了，然而你还将其设置成GB2312，那么DoxyGen会将UTF-8当成ANSI再进行一次UTF-8转换，自然会出错了。

左边树目录的中文变成了乱码

​ 最后也是经常遇到的问题就是DoxyGen生成的CHM文件的左边树目录的中文变成了乱码。

​ 这个只需要将chm索引的编码类型修改为GB2312即可。在HTML的CHM_INDEX_ENCODING中输入GB2312即可。然而这种方法下，还有一个瑕疵之处，就是chm的搜索页的搜索结果中显示的中文文字却变成乱码了*。这是因为DoxyGen默认开启了HTML Help Workshop的Full-textsearch全文搜索选项，他在进行全文搜索的时候，应该是打开文件然后按照ANSI进行搜索的，（资料表示HHW不支持UTF-8，仅支持ISO-8859-1或者windows-1252编码。）而Doxygen生成的右边界面统一是UTF-8，这自然出现了问题。而在这种情况下做全文搜索，理论上只能搜索英文。

​ 无奈，我们的解决方案只能是**重新编译DoxyGen代码，为了满足搜索，只要保证右边的页面文件不是UTF-8即可。我们首先修改writeDefaultHeaderFile这个函数的代码，将其charset=GB2312。然后在TranslatorDecoder的构造函数中修改m_toUtf8 =(void )-1;即屏蔽文本写入时最终的转换函数。**最后删除INPUT_ENCODING的设置或者输入UTF-8。**这样会使DoxyGen认为我们的文本是UTF-8的，从而不用进行转换。生成替换原始的DoxyGen即可。

另外需要补充的是，还有一种方案是不用修改作者的源代码，但是需要将DoxyGen生成的右边的HTML文件使用工具（如iconv）手工转换成GB2312，然后再使用HTML Help Workshop生成，网上有篇文章介绍过，我测试一下，也是没有问题的。

最后，doxygen是一个开源项目，并且支持vs2005项目，这样一来，如果你觉得哪里不顺手，完全可以把代码下载后自行编译。虽然我感觉doxygen的代码写的不能算是perfect，但是对于一个这样的工程，我们无论如何都需要一种敬意。祝好运~

这样，基本上就能够用doxygen生成漂亮的文档了。代码方面，doxygen支持多种格式的注释风格，根据manual选择自己喜欢的就好。

图形问题

无法绘制类图协作图等图形

首先确保安装了graphviz forwin，注意不是wingraphviz，后者是一个graphviz的com封装，但是doxygen并不是基于它开发的，所以装了也没用。

然后在expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。

如果出现无法包含.map文件的错误，可以将工作目录设置成html，并将html中所有文件都清除再试。这个问题的原因还不太确定。

风格问题

如何像MSDN那样在左边的树中显示函数列表？

​ 这个问题其实比较棘手，在[Expert…]中的Project页面，下面有一个选项叫做SEPARATE_MEMBER_PAGES，把这个选项选中，这样每个函数就是一个页。但是会有一个问题，那就是右边页面的旁边多了所有函数的列表**。很遗憾，经过研究，这个确实无法去掉。**

​ 我的解决方法就是自己编译一下doxygen，在memberlist.cpp的writeDocumentationPage函数中将container->writeQuickMemberLinks(ol,md);连同附近几行屏蔽掉即可

打开[Expert…]的HTML页面，然后选中TOC_EXPAND即可。

如何修改或者去掉右下脚Generated at …的文字？

打开[Expert…]的HTML页面，然后在HTML_FOOTER中指定相应的HTML文件即可。注意HTML_FOOTER中至少包含BODY和HTML结束标记。即一个最小的尾部HTML至少是这样

BODY>HTML>

同理，如果你要指定了HTML_HEADER，他至少包含

<HTML><HEAD>HEAD><BODY>

如何生成组？

​ 组就是可以把同类的函数放到一个根下的显示方式。doxygen支持grouping，即你可以把相关的代码通过标志，放到同一个组中，便于查看。这主要是通过几个内置语法命令。首先通过@defgroup定义一个组，然后要把分组的函数或者类等，通过标志@ingroup加入相应的组。这样，相应的函数就被放置在同一个组中。

如何在CHM中去掉当选择SUBGROUPING后去掉分组的组信息？

这个功能就是在chm的左边树中直接列出函数列表，而不用点击看右边页面了。**这个功能需要修改源代码。在index.cpp中，屏蔽writeGroupIndexItem函数的Doxygen::indexList.addContentsItem，Doxygen::indexList.incContentsDepth和Doxygen::indexList.decContentsDepth();即可，具体不解释了，一看便知 **。

注释问题

去掉不想添加到文档的的doxygen风格注释

这对我来说很有用，可以隐藏大块的代码和文档：

/*! \cond PRIVATE */ 
 
/*! \endcond */ 
注意：留一个空行，否则类的生成会丢失

使用ENABLED_SECTIONS = PRIVATE

运行以创建文档的内部版本。

您可以有多个条件，并根据受众启用/禁用它们。

要隐藏文档块的一部分，请使用\internal（除非找到\endinternal，否则将隐藏到块结束）

注意：如果您不喜欢反斜杠，可以使用@表示法。

Doxygen手册提供了一些可能性： HIDE_UNDOC_MEMBERS，HIDE_UNDOC_CLASSES：显然只有在您只记录公共成员时才有效。 INTERNAL_DOCS：允许您使用\ internal标记从文档的“公共”版本中排除注释。 ENABLED_SECTIONS：是INTERNAL_DOCS的更通用版本

附录

常用指令介绍

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

注释指令

名称	含义
@file	文件名
@mainpage	工程概览
@author	作者的信息
@email	邮箱
@date	年-月-日
@version	版本号
@license	版权
@brief	用于class 或function的简易说明
@details	用于class 或function的详细说明
@param	主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@param [in]	输入参数说明
@param [out]	输出参数说明
@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 [] []eg:@class CTest “inc/class.h”
@exception	可能产生的异常描述eg:@exception 本函数执行可能会产生超出范围的异常
@todo	对将要做的事情进行注释
@see	一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。
relates	通常用做把非成员函数的注释文档包含在类的说明文档中
deprecated
@pre	用来说明代码项的前提条件。
@post	用来说明代码项之后的使用条件。
@code	在注释中开始说明一段代码，直到@endcode命令。
@endcode	注释中代码段的结束。

常用配置选项含义

​ 在上述界面中点击Expert按钮，或者用文本方式打开Doxyfile文件，可以看到Doxygen的参数配置项特别多，各个参数的含义其实也并不难掌握，在Doxygen的帮助手册中有详细的介绍，下面我介绍一些常用的参数含义，其余的参数大多可以设置为默认值。

名称	含义
DOXYFILE_ENCODING	Doxygen文件的编码方式，默认为UTF-8，若希望支持中文，最好设置为 GB2312
PROJECT_NAME	Project 的名字，以一个单词为主，多个单词请使用双引号括住。
PROJECT_VERSION	Project的版本号码。
OUTPUT_DIRECTORY	输出路径。产生的文件会放在这个路径之下。如果没有填这个路径，将会以目前所在路径作为输出路径。
OUTPUT_LANGUAGE	输出语言, 默认为English 。
EXTRACT_ALL	为NO，只解释有doxygen格式注释的代码；为YES，解析所有代码，即使没有注释
EXTRACT_PRIVATE	是否解析类的私有成员
EXTRACT_STATIC	是否解析静态项
EXTRACT_LOCAL_CLASSES	是否解析源文件（cpp文件）中定义的类
INPUT	指定加载或找寻要处理的程序代码文件路径。这边是一个表列式的型态。并且可指定档案及路径。
FILE_PATTERNS	如果您的INPUT Tag 中指定了目录。您可以透过这个Tag来要求Doxygen在处理时，只针对特定的档案进行动作。例如：您希望对目录下的扩展名为.c, .cpp及.h的档案作处理。您可设定FILE_PATTERNS = *.c, *.cpp, *.h。
RECURSIVE	这是一个布尔值的Tag，只接受YES或NO。当设定为YES时，INPUT所指定目录的所有子目录都会被处理.
EXCLUDE	如果您有某几个特定档案或是目录，不希望经过Doxygen处理。您可在这个Tag中指定。
EXCLUDE_PATTERNS	类似于FILE_PATTERNS的用法，只是这个Tag是供EXCLUDE所使用。
SOURCE_BROWSER	如果设定为YES，则Doxygen会产生出源文件的列表，以供查阅。
INLINE_SOURCES	如果设定为YES ，则函数和类的实现代码被包含在文档中
ALPHABETICAL_INDEX	如果设定为YES，则一个依照字母排序的列表会加入在产生的文件中。（有很多类、结构等项时建议设为YES）
GENERATE_HTML	若设定为YES ，就会产生HTML版本的说明文件。HTML文件是Doxygen预设产生的格式之一。
HTML_OUTPUT	HTML文件的输出目录。这是一个相对路径，所以实际的路径为OUTPUT_DIRECTORY加上HTML_OUTPUT。这个设定预设为html。
GENERATE_HTMLHELP	是否生成压缩HTML格式文档（.chm）
HTML_FILE_EXTENSION	HTML文件的扩展名。预设为.html。
HTML_HEADER	要使用在每一页HTML文件中的Header。如果没有指定，Doxygen会使用自己预设的Header。
HTML_FOOTER	要使用在每一页HTML文件中的Footer。如果没有指定，Doxygen会使用自己预设的Footer。
HTML_STYLESHEET	您可给定一个CSS 的设定，让HTML的输出结果更完美。
GENERATE_HTMLHELP	如设定为YES，Doxygen会产生一个索引文件。这个索引文件在您需要制作windows 上的HTML格式的HELP档案时会用的上。
GENERATE_TREEVIEW	若设定为YES，Doxygen会帮您产生一个树状结构，在画面左侧。这个树状结构是以JavaScript所写成。所以需要新版的Browser才能正确显示。
TREEVIEW_WIDTH	用来设定树状结构在画面上的宽度。
GENERATE_LATEX	设定为YES 时，会产生LaTeX 的文件。不过您的系统必需要有安装LaTeX 的相关工具。
LATEX_OUTPUT	LaTeX文件的输出目录，与HTML_OUTPUT用法相同，一样是指在OUTPUT_DIRECTORY之下的路径。预设为latex。
LATEX_CMD_NAME	LaTeX程序的命令名称及档案所在。预设为latex。
GENERATE_RTF	若设定为YES ，则会产生RTF 格式的说明档。
RTF_OUTPUT	与HTML_OUTPUT 用法相同，用来指定RTF 输出档案路径。预设为rtf。
GENERATE_MAN	若设定为YES ，则会产生Unix Man Page 格式的说明文件。
MAN_OUTPUT	与HTML_OUTPUT 用法相同，用来指定Man Page的输出目录。预设为man。
GENERATE_XML	若设定为YES ，则会产生XML 格式的说明文件。
ENABLE_PREPROCESSING	若设定为YES ，则Doxygen 会激活C 的前置处理器来处理原始档。
PREDEFINED	可以让您自行定义一些宏。类似于gcc 中的-D选项。
CLASS_DIAGRAMS	这个标记用来生成类继承层次结构图。要想生成更好的视图，可以从 Graphviz 下载站点 下载 dot 工具。Doxyfile 中的以下标记用来生成图表：
HAVE_DOT	如果这个标记设置为 Yes，doxygen 就使用 dot 工具生成更强大的图形，比如帮助理解类成员及其数据结构的协作图。注意，如果这个标记设置为 Yes， 标记就无效了
CLASS_GRAPH	如果 标记和这个标记同时设置为 Yes，就使用 dot 生成继承层次结构图
GRAPHICAL_HIERARCHY	设置为YES时，将会绘制一个图形表示的类图结构

上面的表格只是描述了一些常用的配置，需要更加详细的信息请参考Doxygen的帮助手册。

配置文件参数详细含义

与项目有关的选项

DOXYFILE_ENCODING

指定文件中所有字符的编码格式。在此标记出现之前默认使用 UTF-8。Doxygen 可以使用 libiconv（或在 libc中创建 iconv）实现编码转换。查阅 中列出的编码格式。

PROJECT_NAME

此标记是一个单词（或者使用双引号可包含一个字串），用于标识生成的文档项目，这个名称可用于大多数生成页面的标题或某些地方。

PROJECT_NUMBER

此标记能用于记录一个项目或是修订版本号，能非常容易地将生成的文档进行归类，或是被一些版本控制系统所使用。

OUTPUT_DIRECTORY

指定一个（相对或绝对）的路径，用于生成文档的写入点。如果是一个相对路径，它将会关联到启动 doxygen 的位置。如果留空则表示当前目录将被使用。

CREATE_SUBDIRS

如果此标记设定为 YES，在每种输出格式的输出目录下，doxygen 将创建 4096 个子目录（主输出目录的下 2 层中），并分发生成文件到这些目录中。当提供了一个数量巨大的源码文件集给 doxygen 时，如果将所有的生成文件都放置到同一目录下，这将导致文件系统的性能问题，而此时有效 CREATE_SUBDIRS 选项将非常有益处。

OUTPUT_LANGUAGE

用于指定所有生成文档的语言，doxygen 将使用此信息，生成指定语言的所有常规输出。默认语言是英语，其他支持的语言有：南非荷兰语，阿拉伯语，巴西语，加泰罗尼亚语，汉语，克罗地亚语，捷克语，丹麦语，荷兰语，芬兰语，法语，德语，希腊语，匈牙利语，意大利语，日语，韩语，立陶宛语，挪威语，波斯语，波兰语，葡萄牙语，罗马尼亚语，俄语，塞尔维亚语，斯洛伐克语，斯洛文尼亚语，西班牙语，瑞典语，乌克兰语。

BRIEF_MEMBER_DESC

假如此标记设为 YES（默认值），doxygen 将在文件和类文档（类似于 JavaDoc）中列出的成员之后加入简明的成员描述，若设为 NO 则无效。

REPEAT_BRIEF

如果此标记设为 YES（默认值），doxygen 将会在详细描述之前加入一个成员或函数的简明描述。 注意，若 HIDE_UNDOC_MEMBERS 和 BRIEF_MEMBER_DESC 都设为 NO，简明描述将被完全隐藏。

ABBREVIATE_BRIEF

这个标记采用了一种仿智能的简明描述的缩写工具，用于多个列表中的文本。在列表的每个字串中，如果查找到简明描述的首位字符，会在整个列表处理之后的结果和文本中剔除，可看成为附加说明的文本。否则将维持原状。

如果标记之后留空，下面的值将被使用（“$name”自动替换某些实体的名称）：$name类，$name 部件，以及$name

文件。If left blank, the following values are used ("$name" is automatically replaced with the name of the entity): “The $name class” “The $name widget” “The $name file” “is” “provides” “specifies” “contains” “represents” “a” “an” “the”.

ALWAYS_DETAILED_SEC

如果 ALWAYS_DETAILED_SEC 和 REPEAT_BRIEF 都设为 YES，在只有一个简明描述的地方 doxygen 将生成一个详细的小节。

INLINE_INHERITED_MEMB若设为 YES，doxygen 将在类文档中显示类的所有派生成员。并假定这些成员均为普通类成员。基类的构造器，析构器以及赋值操作符将不会显示。

FULL_PATH_NAMES

若设为 YES，doxygen 将在文件列表和头文件中的文件名之前加入完整路径。若设为 NO，将使用能保证文件名唯 一性的最短路径。

STRIP_FROM_PATH

若 FULL_PATH_NAMES 设为 YES，STRIP_FROM_PATH 用于去除路径中用户自定义的部分，且只会去除与路径左起匹配的多个指定字串，此标记能够显示文件列表中相关的路径，假如标记后留白此标记无效。

STRIP_FROM_INC_PATH

从类文档内所涉及的路径中，去除用户自定义的部分，它将告知阅读者一个类将包含那些头文件。假如标记后留 白，只会使用类定义中的头文件名。否则将会在正常编译时使用-I 参数指定，此标记之后的包含路径。

CASE_SENSE_NAMES

若设为 NO，doxygen 将只生成小写字母的文件名，若设为 YES，允许使用大写字母。如果你的类或文件名之间存在同名但有大小写的差异，以及你的文件系统支持大小写敏感的文件名，那么这个标记是非常有用的。Windows用户可设为 NO 忽略它。

SHORT_NAMES

若设为 YES，doxygen 将生成最短（但可读）的文件名。当你的文件系统不支持长文件名，如 DOS，Mac，CD-ROM时，这个标记是非常有用的。

JAVADOC_AUTOBRIEF

若设为 YES，doxygen 将会使用一个 JavaDoc 风格的注释，作为简明描述来表述第一行（直到第一行结束）。若设为 NO（默认值），JavaDoc 风格看上去更象是一个标准的 Qt 注释（这里需要一个@brief 命令来生成一个简明描述）。

QT_AUTOBRIEF

若设为 YES，doxygen 将会使用一个 Qt 风格的注释，作为简明描述来表述第一行（直到第一行结束）。若设为 NO （默认值），Qt 风格看上去更象是一个标准的 Qt 注释（这里需要一个\brief 命令来生成一个简明描述）。

BUILTIN_STL_SUPPORT

如果你使用了 STL 类（如 std：：string，std：：vector 等等），但又不希望包含（在一个标记中）STL 库，那么可将此标记设为 YES，使得 doxygen 能够匹配包含 STL 类的函数声明和定义（例如 func（std：：string）等同于func（std：：string） {}），这也使得继承和协作图中，涉及到 STL 类的部分更加完整和准确。

CPP_CLI_SUPPORT

假如你使用了微软的 C++/CLI 语言，可设为 YES 使能解析支持。

SIP_SUPPORT

如果你的项目中只包含 SIP 源码可设为 YES，doxygen 解析时会将其看成一般的 C++代码，但是当 protection 关 键字没有出现时，会假定所有的类都使用了公有继承而不是私有继承。

** SIP 是一个自动生成 C/C++库的 Python 绑定端的工具，原本是为了 PyQt（Qt GUI 工具包的绑定端）而开发的，时间始于 1998 年。但它更适合生成任意 C/C++库的绑定端。参考页面

IDL_PROPERTY_SUPPORT

微软 IDL 的获取和设定特性，用于表示一个属性获取和设定的方法。设置这个选项为 YES（默认），使得 doxygen在文档中覆盖掉属性的获取和设定方法，这只能工作在这些方法获取和设定简单类型时。如果不是这种情况，而 总是希望显示这些方法，那么将此选项设为 NO。

DISTRIBUTE_GROUP_DOC

如果在文档中使用了成员组，以及此选项设为 YES，为了组中的其他成员，doxygen 将会重复使用用文档中组的第一个成员（如果有），then doxygen will reuse the documentation of the first member in the group (ifany) for the other members of the group 组默认情况下，所有的组成员必须被显示文档化。

MULTILINE_CPP_IS_BRIEF

若设为 YES，doxygen 需要处理一个多行的 C++特殊注释块（如，//!或///的注释块），类似于一个简明描述。 这是一个默认状态。最新修订后的默认状态则是将上述的特殊注释块看作一个细节描述。如果你接受修改后的默 认状态，可将此标记设为 YES，注意，此标记设为 YES，也就意味着 rational rose 的注释无法被完全辨别。

INHERIT_DOCS

若设为 YES（默认值），那么一个未文档化成员继承于其他文档化成员，它将重新执行文档化。If the INHERIT_DOCS tag is set to YES (the default) then an undocumented member inherits the documentation from any documented member that it re-implements

SEPARATE_MEMBER_PAGES

若设为 YES，doxygen 将为每一个成员建立一个新页，若设为 NO，成员文档将成为文件/类/名字空间文档中的一部分。

TAB_SIZE

设置制表符的大小，doxygen 使用这个数值替换掉代码段中的空格数。

ALIASES

在文档中用于指定一定数量的 alias，等同于命令。一个 alias 有以下的式，

name=value

这里增加一个例子：

“sideeffect=\par Side Effects:\n”

它允许你放置\sideeffect（或@sideeffect）命令在文档中，这将导致在用户定义的段落标题为“Side Effects:”，

你可放置\Side Effects:插入换行符。You can put \n’s in the value part of an alias to insert newlines.

OPTIMIZE_OUTPUT_FOR_C

若设为 YES，如果你的项目中只包含 C 源码，doxygen 将为 C 生成更适合的输出，比如，使用一些不同的名称，忽略所有成员的列表，等等。

OPTIMIZE_OUTPUT_JAVA

若设为 YES，如果你的项目中只包含 Java 或 Python 的源码，doxygen 将为这些语言生成更适合的输出，比如出 现的名字空间将被看做包，获取认证的范围将会有差异，等等。

OPTIMIZE_FOR_FORTRAN

若设为 YES，如果你的项目中只包含 Fortran 的源码，doxygen 将为它生成更适合的输出。

OPTIMIZE_OUTPUT_VHDL

若设为 YES，如果你的项目中只包含 VHDL 的源码，doxygen 将为它生成更适合的输出。

EXTENSION_MAPPING

Doxygen 使用它能够解析的文件扩展名，来选择解析器， 此标记能为解析器分配一个给定的扩展名，doxygen 有一个内建的映射，但你可以使用此标记覆盖或扩展它。格式为 ext=language，ext 即文件的扩展名，language则为 doxygen 所支持的解析器中的一个：IDL, Java, Javascript, C#, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++。比如使得 doxygen 将.inc 看做 Fortran 文件（默认为 PHP 文件），.f 看做 C 文件（默认为 Fortran 文件），可以使用：inc=Fortran，f=C。

SUBGROUPING

若设为 YES（默认），允许相同类型的类成员组（比如一个公有函数组）被放置到此类型的子分组中（如在 Public Functions 小节下），设为 NO 禁用子分组。另外，对每个类使用\nosubgrouping 命令同样可禁用子分组。

TYPEDEF_HIDES_STRUCT

若设为YES，文档化的结构，联合或枚举的类型定义，将被看做它们类型的名称。如typedef struct TypeS {} TypeT， 那么文档中就存在一个名为 TypeT 的结构，当无效这个类型定义时，它有可能是文件，名字空间或类的成员，而 这个结构将被命令为 TypeS，这对于 C 代码是非常有价值的，可在编码约定中指定所有的混合类型的定义，以及只对此类型定义进行引用，而不需要标记名称。

SYMBOL_CACHE_SIZE

它会决定内部缓存的大小，以此来确定那些符号应保存在内存，而那些应更新到磁盘中。当缓存已满不经常被使用的符号将被写入到磁盘中。对于小中型项目（小于 1000 个输入文件）来说，默认值已经能满足你的要求。对于大型项目来说，缓存过小，有可能导致 doxygen 频繁与磁盘交换符号而花费大量的时间，而造成性能的下降。

如果系统中有足够的物理内存，可增加缓冲来保存更多的符号以改善性能。注意,缓存实际大小在一个对数范围内变化，所以增加的缓存大小应该会超过原来的一倍。缓冲大小的计算公式： 有效的范围是 0~9，默认为 0，相应缓存的大小为 。

与创建有关的选项

EXTRACT_ALL

若设为 YES, doxygen 会假定文档中的所有主体将被文档化，即使在未提供文档的情况下。私有类成员和文件静 态成员将隐藏，直到 EXTRACT_PRIVATE 和 EXTRACT_STATIC 标记设为 YES。

注意： 当 WARNINGS 设为 YES 时，将无效生成过程中未文档化成员发出的警告。

EXTRACT_PRIVATE

若设为 YES，在文档中将包含所有类私有成员。

EXTRACT_STATIC

若设为 YES，在文档中将包含所有文件的静态成员。

EXTRACT_LOCAL_CLASSES

若设为 YES，在文档中将包含在源文件中定义的类（和结构），若设为 NO，只包含在头文件中定义的类。对于 Java源码无任何影响。

EXTRACT_ANON_NSPACES

若设为 YES，匿名空间的成员将被提取到文档中，并被称为anonymous_namespace{file}的名字空间，file 可使用匿名空间包含的文件基类名进行替换。默认情况下，匿名空间将被隐藏。

EXTRACT_LOCAL_METHODS

这个标记只对 Object-C 代码有效，当设为 YES 时，在文档中包含的局部方法将在执行部分被定义，而不会在接 口中。若设为 NO（默认），只有在接口中的方法才会被包含到文档。

HIDE_UNDOC_MEMBERS

若设为 YES，doxygen 将隐藏在文档化的类或文件中的所有未文档化的成员，若设为 NO（默认），这些成员将包含在一些预览中，但不会有文档小节生成，如果 EXTRACT_ALL 为 YES，此选项无效。

HIDE_UNDOC_CLASSES

若设为 YES，doxygen 将隐藏所有未文档化的类，若设为 NO（默认），这些类将被包含在一些预览中，但不会有文档小节生成，如果 EXTRACT_ALL 为 YES，此选项无效。

HIDE_FRIEND_COMPOUNDS

若设为 YES，doxygen 将隐藏所有友元（类|结构|联合）声明，若设为 NO（默认），这些声明将包含在文档中。

HIDE_IN_BODY_DOCS

若设为 YES，doxygen 将隐藏函数主体中的一些文档块，若设为 NO（默认），这些块将出现在函数的细节文档块中。

INTERNAL_DOCS

用于确认在一个\internal 命令之后能否包含文档。若设为 NO（默认），那么文档将被移除，如设为 YES，将包含内部文档。

HIDE_SCOPE_NAMES

若设为 NO（默认），doxygen 将显示文档中类成员和名字空间的作用域，若设为 YES，此作用域将被隐藏。

SHOW_INCLUDE_FILES

若设为 YES（默认），doxygen 将在文件的文档中放置它所包含文件的列表。

FORCE_LOCAL_INCLUDES

若设为 YES，doxygen 将会在文档中使用双引号列出所包含的文件，而不是尖括号。

INLINE_INFO

若设为 YES（默认），将在文档中插入 inline 标记来指示 inline 成员。

SORT_MEMBER_DOCS

若设为 YES（默认），doxygen 将按英文字母的顺序对文件和类的成员名字进行文档排序，若设为 NO，成员将按声明的顺序出现。

SORT_BRIEF_DOCS

若设为 YES，doxygen 会按英文字母的顺序将文件，名字空间和类的成员名字，作为它们简明描述的排序依据，若设为 NO（默认），成员将按声明的顺序出现。

SORT_GROUP_NAMES

若设为 YES，doxygen 会按英文字母的顺序对组名的层级进行排序。若设为 NO（默认），组名将按定义的顺序出现。

SORT_BY_SCOPE_NAME

若设为 YES，将由类的全称（即包含名字空间）对类列表进行排序。若设为 NO（默认），类列表排序只能由不包含名字空间的类名决定。

注意：

如果 HIDE_SCOPE_NAMES 设为 YES，这个选项不太有价值。

此选项只适用于类列表，且不是按字母排序的列表。

SORT_MEMBERS_CTORS_1 ST

若设为 YES，doxygen 将对类成员的（简明和细节描述）文档进行排序，且构造器和析构器将位于列表首部。若 设为 NO（默认），构造器将出现在 SORT_MEMBER_DOCS，SORT_BRIEF_DOCS 所设定的各自定义的位置。

注意：

若 SORT_BRIEF_DOCS 设为 NO，此选项将忽略成员简明描述的排序。 若 SORT_MEMBER_DOCS 设为 NO，此选项将忽略成员细节描述的排序。

GENERATE_DEPRECATEDLIST

用于有效（YES）或失效（NO）废弃列表（主要针对类和类方法），通过放置\deprecated 命令来创建废弃列表。

GENERATE_TESTLIST

用于有效（YES）或失效（NO）测试列表，通过放置\test 命令来创建测试列表。

GENERATE_BUGLIST

用于有效（YES）或失效（NO）bug 列表，通过放置\bug 命令来创建 bug 列表。

ENABLED_SECTIONS

用于有效某些条件化文档小节，可使用标记，\if <小节标号> … \endif 和\cond <小节标号> … \endcond 的块结构。

MAX_INITIALIZER_LINES

用于确定一个变量或定义初始化时能使用的最大文本行数，如果初始化时的行数超过最大值，那么它将被隐藏。将最大值设为 0 将完全隐藏初始化的文本。可在文档中使用\showinitializer 和\hideinitializer 命令，来控 制个别变量和定义的初始化文本。

SHOW_USED_FILES

若设为 NO，在类和结构文档的底部无效文件列表的生成。若设为 YES，列表将会提取那些已被用于生成文档的文件。

SHOW_DIRECTORIES

如果你项目中源码分布在多个目录下，可设定此选项为 YES，在文档中显示出源码目录的层级。

SHOW_FILES

若设为 NO，将无效文件页面的生成，并将文件从快速索引和文件树浏览（如果指定）中移除。默认设定为 YES。

SHOW_NAMESPACES

若设定为 NO，将无效名字空间页面的生成，并将名字空间从快速索引和文件树浏览（如果指定）中移除。默认设定为 YES。

与警告和处理消息相关的选项

QUIET

用于打开或关闭 doxygen 生成输出时的消息，若设定 YES 表明关闭消息，若留白则设定为 NO。

WARNINGS

用于打开或关闭 doxygen 生成错误记录时的警告消息，若设定 YES 表明打开警告消息，若留白则设定为 NO。

技巧：当写文档时应打开警告消息。

WARN_IF_UNDOCUMENTED

若设为 YES，doxygen 将为未文档化的成员生成警告消息，如果 EXTRACT_ALL 设为 YES，那么该标记将自动失效。

WARN_IF_DOC_ERROR

若设为 YES，doxygen 将为文档中潜在的错误生成警告消息，例如在一个文档化函数中并没有文档化一些参数，或文档化的参数并不存在，又或者使用了错误的标记命令。

WARN_NO_PARAMDOC

用于获得文档化函数所生成警告消息，但不能兼顾到它的参数和返回值。若设为 NO（默认）doxygen 只能生成错 误或参数文档不完整的警告，而不能监控文档的缺失。

WARN_FORMAT

确定 doxygen 所生成警告消息的格式，消息字串会包含$file, $line, $text 标记，并且这些标记将被发出警告的文件名，行号，以及相应的文本所替换。

WARN_LOGFILE

用于指定一个警告和错误消息写入的日志文件，如果留空表示将消息写入 stderr。

与输入相关的选项

INPUT

用于指定将被文档化的源文件和目录，你可以输入 myfile.cpp 文件名或/usr/src/myproject 目录名，多个文件名或目录名可用空格进行分离。

注意：如果此标记留空，那么将搜索当前目录。

INPUT_ENCODING

用于指定 doxygen解析源文件所使用字符编码，doxygen 内部使用 UTF-8 编码，同样也是默认的输入编码。 Doxygen可使用 libiconv（或者在 libc 中创建 iconv）进行编码转换。查看编码列表。

FILE_PATTERNS

如果 INPUT 包含有目录，可用此选项指定一个或多个通配符（如*.cpp 和*.h）在目录过滤源文件。假如选项后留空，以下的扩展名将用于过滤：.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp .h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm 。

FILE_VERSION_FILTER

用于指定一个程序或脚本，使得 doxygen 能调用每个文件以获得当前版本（一般通过 CVS 版本控制系统获取），且 doxygen 将会执行（使用 popen（）） command input-file 命令来调用该程序，其中 command 为FILE_VERSION_FILTER 后跟的设定名称，input-file 则为 doxygen 所支持的输入文件名。无论该程序向标准输出写入任何内容，都将被用做文件版本。

Unix 下使用一个 shell 脚本过滤器的例子:

FILE_VERSION_FILTER = "/bin/sh versionfilter.sh" 

CVS 的脚本例子：

#!/bin/sh cvs status $1 | sed -n 's/^[ \]*Working revision:[ \t]*\([0-9][0-9\.]*\).*/\1/p' 

SVN 的脚本例子：

#!/bin/sh svn stat -v $1 | sed -n 's/^[ A-Z?\*|!]\{1,15\}/r/;s/ \{1,15\}/\/r/;s/ .*//p' 

ClearCase 过滤器的例子：

 FILE_VERSION_INFO = "cleartool desc -fmt \%Vn"

LAYOUT_FILE

用于指定一个能被 doxygen 解析的布局文件。在一种独立的输出格式中，此布局文件可以控制所生成的输出文件的全局结构。创建默认的布局文件可运行 doxygen 附带-l 选项，并且可选择在选项之后是否指定一个文件名，如 果文件名被忽略将使用 DoxygenLayout.xml，注意，如果你运行 doxygen 的目录中已经包含了一个名为DoxygenLayout.xml 的文件时，倘若 LAYOUT_FILE 之后留空 doxygen 将自动解析该文件。

RECURSIVE

用于是否在子目录中搜索可用的输入文件，如果选项之后留空则设为 NO。

EXCLUDE

用于指定那些文件和目录将从 INPUT 选项中将被移除。这种方式使你很容易得从 INPUT 选项设定根目录树中，移 除一个子目录。

EXCLUDE_SYMLINKS

用于选择是否从输出中移除文件或者目录的符号链接（一个 Unix 文件系统的特性）。

EXCLUDE_PATTERNS

在 INPUT 选项设定的目录中，使用该选项指定的一个或多个通配符来移除匹配的文件。

注意，通配符将对文件的绝对路径进行匹配，如移除所有的测试目录，可使用*/test/*的样式。

EXAMPLE_PATH

指定一个或多个包含例子代码段的文件或包含例子文件的目录。（在\include 小节中查看\include 命令）

EXAMPLE_RECURSIVE

若设为 YES，将在子目录中搜索输入例子文件，可使用\include 或\dontinclude 命令，它与 RECURSIVE 无关，如 果选项之后留空则设为 NO。

EXAMPLE_PATTERNS

若 EXAMPLE_PATH 选项之后含有目录，可用此标记指定一个或多个通配符（如*.cpp 和*.h），从上述目录中过滤掉匹配的文件，如果选项后留空则设为 NO。

IMAGE_PATH

用于在文档中指定一个或多个包含图片的文件或是包含图片文件的目录。（查看\image 命令）

INPUT_FILTER

指定一个程序，使得 doxygen 对每一个输入文件进行过滤，doxygen 调用过滤程序可以执行（使用 popen()）这个命令：

则为 INPUT_FILTER 的设定值，则为输入文件名，doxygen 会将过滤程序的输出写入到标准输

出中。

FILTER_PATTERNS

用于在每种文件样式的基础上指定过滤规则。Doxygen 将会比较文件名和每一种样式，并检查是否与过滤规则匹配。这些过滤规则来自一个列表：pattern=filter（如*.cpp=my_cpp_filter），查看 INPUT_FILTER 进一步获得如何使用过滤器的信息，假设选项后留空，INPUT_FILTER 将用于全部文件。

FILTER_SOURCE_FILES

若设为 YES，输入过滤器（可使用 INPUT_FILTER 设定）既可过滤输入文件，也可用于生成源文件的浏览（当SOURCE_BROWSER 设为 YES 时）。

与源码浏览相关的选项

SOURCE_BROWSER

若设为 YES，将生成一个源码文件的列表。文档主体部分将对这些源码进行交叉引用。 注意，在生成输出的过程中与所有源码的关联有可能失效，因此要确认 VERBATIM_HEADERS 是否设为 NO。

INLINE_SOURCES

若设为 YES，在文档中将直接包含函数，类，枚举的代码段。

STRIP_CODE_COMMENTS

若为 YES（默认），告知 doxygen 隐藏一些来自源码段中特殊的注释块，正常情况下 C 和 C++的注释始终可见。

REFERENCED_BY_RELATION

若为 YES，所有的文档化函数都将会列出其引用过的函数。

REFERENCES_RELATION

若为 YES，所有的文档化实体都将会列出其调用或使用过的函数。

REFERENCES_LINK_SOURCE

若为 YES（默认），且 SOURCE_BROWSER 也为 YES，那么 REFERENCES_RELATION，REFERENCED_BY_RELATION 所生成列表中函数的超链接将指向源码，否则将指向该函数的文档。

VERBATIM_HEADERS

若为 YES（默认），doxygen 将为类所指定的头文件，生成一个相同的副本，doxygen will generate a verbatim copy of the header file for each class for which an include is specified 若为 NO 则无效。 也可查看\class 小节。

USE_HTAGS

若为 YES，对于源码的引用，将指向由 htags 工具而非 doxygen 内建的源码浏览器生成的 HTML。Htags 工具是 GNU 全局源码标签系统 GNU’s global source tagging system 的一部分（参看）。按以下步骤使用 htags 工具：

1. 安装最新的版本（如 4.8.6 或更新的）

2. 有效 SOURCE_BROWSER，USE_HTAGS

3. 确认 INPUT 指向的是源码树的根目录

4. 正常运行 doxygen

Doxygen 将调用 htags（依次调用 gtags），这些工具只有在命令行下才有效（并存在于系统的检索路径中）。

得到的结果，可替代 doxygen 所生成的源码浏览器，指向源码的链接将会指向 htags 的输出。

与字母索引相关的选项

ALPHABETICAL_INDEX

若为 YES，将会生成一个所有合成部分的字母索引。如果项目中包含一些类，结构，联合和接口时，应有效此标记。

COLS_IN_ALPHA_INDEX

如果 ALPHABETICAL_INDEX 有效，那么此标记可用于指定每列的间距（间距的范围是 1~20）。

IGNORE_PREFIX

项目中所有的类都是由一个公共的前缀开始，那么所有的类也将被放置到字母索引中相同的首部之下。此标记可指定一个特殊的前缀（或是一个前缀列表），当生成索引首部时却可以忽略掉。

HTML 相关的选项

GENERATE_HTML

若为 YES（默认），doxygen 将生成 HTML 输出。

HTML_OUTPUT

指定 HTML 文档所存放的位置。如果此标记后为一相对路径，则 OUTPUT_DIRECTORY

的值将被放置到它之前。如果标记后留空，则将 html 作为默认路径。

HTML_FILE_EXTENSION

指定生成的 HTML 页面文件的扩展名（例如：.htm，.php，.asp），如果标记后留空，doxygen 将生成 .html 文件。

HTML_HEADER

指定生成的 HTML 页面中用户自定义的页头。为获得有效 HTML 页头至少要包含一个和一个```标记，但 更好的办法是，包含 doxygen 生成的样式表。最小化的例子:

<HTML> <HEAD> <TITLE>My titleTITLE> <LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css"> HEAD> <BODY BGCOLOR="#FFFFFF">

如果选项后留空，doxygen 将生成一个标准页头。

以下是包含在页头和页脚中具有特定意义的标识：

$title 替换页面的标题

$datetime

替换当前的日期和时间

$date

替换当前的日期

$year

替换当前的年份

$doxygenversion 替换 doxygen 的版本

$projectname

替换项目的名称（查看 PROJECT_NAME）

$projectnumber 替换项目的编号（查看 PROJECT_NUMBER）

$relpath$ 如果 CREATE_SUBDIRS 有效，$relpath$命令将生成一个关联到 HTML 输出目录的相对路

径，如使用$relpath$doxygen.css,来引用一个标准的样式表。

查看“doxygen 用法”小节获得如何使用 doxygen 生成默认页头的信息。

HTML_FOOTER

指定生成的 HTML 页面中用户自定义的页脚，为获得有效 HTML 页脚至少要包含一个和一个标记，

一个最小化的例子：

BODY>HTML>

如果选项后留空，doxygen 将生成一个标准页脚。

在页脚中具有特定意义的命令有：$title, $datetime, $date, $doxygenversion, $projectname, $projectnumber

Doxygen 将分别用页标题，当前日期和时间，当前日期，doxygen 的版本号，项目名（查看 PROJECT_NAME），项目编号（查看 PROJECT_NUMBER）来替换这些命令。 查看“doxygen 用法”小节获得如何使用 doxygen 生成默认页脚的信息。

HTML_STYLESHEET

为 HTML 页面指定一个用户自定义的样式表，它可用于 HTML 输出观感的微调。如果标记后留空，doxygen 将生成默认的样式表。 查看“doxygen 用法”小节获得如何使用 doxygen 生成默认样式表的信息。

HTML_TIMESTAMP

若为 YES，生成的 HTML 页面的页脚中将包含页面生成的日期和时间。设为 NO，当比较多次运行后生成的输出时可提供帮助。

HTML_ALIGN_MEMBERS

若为 YES，HTML 的类，文件或名字空间的成员使用表格对齐，若为 NO 将使用一个无序列表。

注意：此标记设为 NO 在未来将被废弃，目前我只关注于支持和测试那些已对齐的文本描述。

HTML_DYNAMIC_SECTIONS

若为 YES，在生成的 HTML 文档装载之后，它将会包含可隐藏和显示的动态部分。这一特性需要浏览器支持JavaScript 和 DHTML（例如 Mozilla 1.0+, Firefox Netscape 6.0+, Internet explorer 5.0+, Konqueror,

Safari）。

GENERATE_DOCSET

若为 YES，将为运行于 OSX 10.5 (Leopard)上的 Apple Xcode 3集成开发环境生成可用的索引文件，创建一个文档集，doxygen 将在 HTML 输出目录中生成一个 Makefile，并在目录中运行 make 创建 docset，然后运行 make intall 将 docset 安装到~/Library/Developer/Shared/Documentation/DocSets 下，使得 Xcode 在启动时能够找到它。查看获得更多的信息。

DOCSET_FEEDNAME

若为 YES，确认 feed 的名称，一个文档 feed 支持将多个来自一个提供者的文档组合成一个整体。（如同一间公司或一组产品套件）A documentation feed provides an umbrella under which multiple documentation sets from a single provider (such as a company or product suite) can be grouped

DOCSET_BUNDLE_ID

若 GENERATE_DOCSET 为 YES，此标记将指定一个字串，用于文档集被捆绑后的唯一标识。this tag specifies a string that should uniquely identify the documentation set bundle 而它是一个将域名颠倒的字串，比如com.mycompany.MyDocSet。doxygen 将附加.docset 到字串后。

DOCSET_PUBLISHER_ID

当 GENERATE_PUBLISHER_ID 指定一个字串，用于文档提供者的唯一标识。而它是一个将域名颠倒的字串，比com.mycompany.MyDocSet.documentation

DOCSET_PUBLISHER_NAME

GENERATE_PUBLISHER_NAME

将标识文档的提供者。

GENERATE_HTMLHELP

若为 YES，doxygen 将生成三个附带的 HTML 索引文件：index.hhp, index.hhc, index.hhk。index.hhp 是一个可被微软 HTML Help Workshop 读取的项目文件。

HTML Help Workshop 包含一个编译器，它可转换所有 doxygen 生成的 HTML 输出文件，成为一个单一的已编译的HTML 文件（.chm）。目前使用的已编译 HTML 文件被当作 windwos98 帮助文件的格式，在将来的 windows 所有平台上，将会替代老的 windows 帮助文件格式（.hlp）。已压缩的 HTML 文件包含一个索引，一个目录，并且你可以在文档中检索关键字。HTML Help Workshop 也包括了一个已压缩 HTML 文件的查看器。

CHM_FILE

若 GENERATE_HTMLHELP 为 YES，此选项用于指定.chm 输出文件的名称，如果该文件无法写入 html 输出目录，可在文件前加入一个路径。

HHC_LOCATION

若 GENERATE_HTMLHELP 为 YES，该标记用于指定 HTML 帮助文件编译器（hhc.exe）的本地位置（包含文件名的绝对路径），如果标记后不为空，在生成 index.hhp 时 doxygen 将尝试运行 HTML 帮助文件编译器。

GENERATE_CHI

若 GENERATE_HTMLHELP 为 YES，该标记为 YES，将生成一个单独的.chi 索引文件，若为 NO，.chi 文件将被包含在一个.chm 文件中。

BINARY_TOC

若 GENERATE_HTMLHELP 为 YES，该标记为 YES，将生成一个二进制的目录，若为 NO，将在.chm 文件中生成一个正常的目录。

TOC_EXPAND

若为 YES，可在 HTML 帮助文档的目录和树型查看器中增加额外组成员的条目。

GENERATE_QHP

若为 YES，并且 QHP_NAMESPACE，QHP_VIRTUAL_FOLDER 都已设定，将生成一个附加的索引文件，可使得 Qt qhelpgenerator 从已生成的 HTML 文档中生成一个 Qt 压缩帮助文件（.qch）。

QHP_NAMESPACE

当生成 Qt 帮助文件输出时，指定名字空间，为获得更多信息，

请查看

QHP_VIRTUAL_FOLDER

当生成 Qt 帮助文件输出时，指定名字空间，为获得更多信息，

请查看

QHP_CUST_FILTER_NAME

指定增加的一个自定义过滤器的名称，为获得更多信息，

请查看

QHP_CUST_FILTER_ATTRS

指定增加的自定义过滤器的属性列表，为获得更多信息，

请查看

QHP_SECT_FILTER_ATTRS

指定与项目过滤器匹配的属性列表，为获得更多信息，

请查看

QHG_LOCATION

若 GENERATE_QHP 为 YES，此标记用于指定 Qt qhelpgenerator 的本地位置，如果标记后不为空，doxygen 在生成.qhp文件时将尝试运行 qhelpgenerator。 GENERATE_ECLIPSEHELP 若为 YES，将生成附加的索引文件，并与 HTML 文件一同打包成一个 Eclipse 的帮助插件。 在 Eclipse 的帮助菜单下可安装和有效此插件，目录中包含的 HTML 和 XML 文件需要复制到 Eclipse 的插件目录中，且插件目录中的目录名要与ECLIPSE_DOC_ID 相同。 复制文件之后将要重启 Eclipse 才能使帮助插件出现在开发环境中。

ECLIPSE_DOC_ID

指定 Eclipse 帮助插件的唯一标识。当安装的插件中含有 HTML 和 XML 文件的目录名称将与此标识相同，每一个文档集都必须有它自己的标识。

SEARCHENGINE

若此标记有效，doxygen 将为 HTML 输出生成一个搜索工具。底层的搜索引擎会使用 JavaScript 和 DHTML，且能工作在一些主流的浏览器中。注意，当使用 HTML 帮助文件（GENERATE_HTMLHELP），Qt 帮助文件（GENERATE_QHP），或者 docset（GENERATE_DOCSET）时，这些文件都已经附带有一个搜索功能，所以通常情况下此标记将无效。对于大型项目，基于 JavaScript 搜索引擎的检索速度将会很慢，可以使能SERVER_BASED_SEARCH，它可以提供一种更好的解决方法。

可以使用键盘进行检索，使用功能键 + S 可直接调用搜索工具（具体使用那一个功能键，与操作系统和浏览器有 关，通常是 CTRL，或 ALT，或者二者皆可）。在搜索工具中使用光标下键，可跳至搜索结果窗口，并使用光标键

查看搜索结果。按 Enter 键可选中一栏，使用 Esc 可取消搜索。当光标处于搜索工具内并按下 Shift + 光标下键，可选择过滤器参数，使用光标键选定一个过滤器之后，可按下 Enter 和 Esc 激活或者取消过滤器选项。

SERVER_BASED_SEARCH

若此标记有效，搜索引擎将使用基于 PHP 的 web 服务器模式来替代基于 JavaScript 的 web 客户端模式，doxygen将在 web 服务器上放置已生成的 PHP 搜索脚本和索引文件。服务器模式的优点在于，对于大型项目的良好表现，以及文本检索。而缺点是安装比较有难度，并且还不具备智能搜索的能力。

DISABLE_INDEX

如果你希望完全掌控已生成 HTML 的页面布局，就必须用自定义的设置替换原有的索引。此标记可用于打开或取消每个页面顶端的精简索引。若为 NO（默认）将使能该索引，若为 YES 则取消。

ENUM_VALUES_PER_LINE

用于设定 doxygen 在一行中可排列多少个枚举值（范围是 1~20 个）。

GENERATE_TREEVIEW

在显示生成的层次信息时，是否采用树型结构。若为 YES，一侧的面板将包含一个树型结构（如同一个生成的 HTML帮助文件），此类特性需要浏览器支持 JavaScript，DHTML，CSS，frames（如一些主流的浏览器），windows 用户使用 HTML 帮助文件可能是更好的选择。 通过自定义样式表（查看 HTML_STYLESHEET）能进一步微调索引的观感， doxygen 生成的默认样式表中有一个例 子，它将显示如何在索引树的根节点放置一副图片来替换 PROJECT_NAMEUSE_INLINE_TREES 有效该标记，doxygen 将使用树型视图来生成组，目录，类的层次页面，用以替代一个顺序列表。

TREEVIEW_WIDTH

如果树型视图有效（查看 GENERATE_TREEVIEW），该标记用于设定在树型索引显示的框体的初始宽度（像素值）。

EXT_LINKS_IN_WINDOW

若为 YES，doxygen 将通过导入标记文件，开放指向一个独立窗口的外部符号链接。

FORMULA_FONTSIZE

用于改变 HTML 文档中包含的如同图片一样的 Latex 公式的字体大小。默认为 10，你希望在 doxygen 运行之后成 功更改字体的大小，你必须从 HTML 输出目录中手动删除一些 form_*.jpg 图片，并确认它们被重新生成。

FORMULA_TRANSPARENT

为了显示公式，用于确认是否将图片生成为背景透明的 PNG 文件，透明的 PNG 有可能不被 IE6.0 所支持，但其他所有的主流浏览器都支持。注意，当你更改了此选项，你必须在更改生效之前，在 HTML 输出目录中删除一些

form_*.jpg 文件。

与LaTex 相关的选项

GENERATE_LATEX

若为 YES（默认），doxygen 将生成 LaTex 输出。

LATEX_OUTPUT

指定 LaTex 文档放置的位置，如果键入的是一个相对路径，那么 OUTPUT_DIRECTORY 设定值将放置它之前。若标 记后留空，将使用默认路径 latex。

LATEX_CMD_NAME

指定将被调用的 LaTex 命令字，若标记后留空，将使用默认命令字 latex。注意，当有效 USE_PDFLATEX 选项只能在 HTML 输出中用于生成位图公式，无法在 Makefile 中使用并写入输出目录。

MAKEINDEX_CMD_NAME

指定生成 latex 索引的命令字，如果标记后留空，将使用默认命令字 makeindex。

COMPACT_LATEX

若为 YES，doxygen 将生成压缩的 latex 文档，这对于小型项目非常有用，以及在通常情况下保存一些树也是非常有帮助的。

PAPER_TYPE

用于指定打印机所使用页面类型，以下是一些标准值：

• a4 (210 x 297 毫米).

• a4wide (大小与 a4 相同, 但包含 a4wide 包).

• letter (8.5 x 11 英寸).

• legal (8.5 x 14 英寸).

• executive (7.25 x 10.5 英寸)

若标记后留空将使用 a4wide。

EXTRA_PACKAGES

指定在 latex 输出中包含一个或多个 latex 包的名称，为获得 times 字体你可以设定 EXTRA_PACKAGES = times*若标记后留空将不包含额外的包。

LATEX_HEADER

指定在生成 latex 文档中包含一个个人风格的 latex 头，在第一章开始之前此头可包含任何内容。 如果标记后留空，doxygen 将生成一个标准头，查看“doxygen 用法”小节，获得如何让 doxygen 写入一个默认头到单独文件的信息。

注意：

如果你知道自己在做什么的话，可以只使用一个用户自定义的头。 之 后 是 头 中 一 些 有 特 殊 意 义 的 命 令 ： $title, $datetime, $date, $doxygenversion, $projectname, $projectnumber。Doxygen 可分别使用页标题，当前日期和时间，当前日期，doxygen 版本号，项目名（查看PROJECT_NAME），项目编号（查看 PROJECT_NUMBER）来替换这些命令。

PDF_HYPERLINKS

若为 YES，latex 将转换生成的文档为 PDF 文件（使用 ps2pdf 或者pdflatex），PDF 文件将包含链接（如同 HTML输出）而非页面引用。这使得用 PDF 浏览器作为在线浏览器变得更适合。

USE_PDFLATEX

若为 YES，doxygen 将使用 pdflatex 直接从 latex 文件生成 PDF 文件。

LATEX_BATCHMODE

若为 YES，doxygen 将已生成的 latex 文件中添加\batchmode 命令，它将指示 latex 在出现错误时继续运行，而 不是询问用户以获得帮助。此选项也可用于 HTML 中生成公式。

LATEX_HIDE_INDICES

若为 YES，doxygen 将不会在输出中包含索引部分（比如文件索引，复合索引等等）。

与 RTF 相关的选项

GENERATE_RTF

若为 YES，doxygen 将生成 RTF 输出。此 RTF 只针对 Word97 进行了优化，但在其他阅读和编辑器中未必表现良好。

RTF_OUTPUT

指定 RTF 文档放置的位置，如果它是一个相对路径，那么OUTPUT_DIRECTORY 设定值将放置它之前。若标记后留

空，将使用默认路径 rtf。

COMPACT_RTF

若为 YES，doxygen 将生成压缩的 RTF 文档，这对于小型项目非常有用，以及在通常情况下保存一些树也是非常有帮助的。

RTF_HYPERLINKS

若为 YES，生成的 RTF 将包括超链接的区域，RTF 文件将会包含链接（如同 HTML 输出）而非页面引用。这使得用Word 或是其他一些与 Word 兼容并支持超链接的阅读器，作为在线浏览器变得更适合。

注意：WordPad 和其他兼容的工具都不支持超链接。

RTF_STYLESHEET_FILE

从文件中装载样式表定义，风格与 doxygen 配置文件类似，如同一个配置序列。你只需要提供代换值，缺省的定义将会使用它们的默认值。 查看“doxygen 用法”小节获得如何在 doxygen 正常使用时生成默认样式表的信息。

RTF_EXTENSIONS_FILE

将在 RTF 文档的生成过程中使用该选项的设定值。风格与 doxygen 配置文件类似，一个模板扩展文件可使用doxygen -e rtf extensionFile 来生成。

与Man 页面相关的选项

GENERATE_MAN

若为 YES（默认），doxygen 将为类和文件生成 man 页面。

MAN_OUTPUT

指定 man 页面放置的位置。如果它是一个相对路径，那么OUTPUT_DIRECTORY 设定值将放置它之前。若标记后留空，将使用默认路径 man。使用此选项可在目录中创建一个 man3 目录。

MAN_EXTENSION

确认添加到已生成 man 页面的扩展部分（默认为程序的第三小节）。

MAN_LINKS 若为 YES，doxygen 会生成 man 输出，它将为 man 页面中的文档主体，生成一个附带的 man 文件，这些附带文件来自实际的 man 页面，但没有它们 man 将无法查找到正确的页面。默认为 NO。

与 XML 相关的选项

GENERATE_XML

若为 YES，doxygen 将生成一个 XML 文件，用于表述所有文档中包含的代码结构。

XML_OUTPUT

指定 XML 页面放置的位置。如果它是一个相对路径，那么OUTPUT_DIRECTORY 设定值将放置它之前。若标记后留

空，将使用默认路径 xml。

XML_SCHEMA

用于指定一个 XML 例表 schema，XML 解析器可用其检查 XML 文件的语法。

XML_DTD

用于指定一个 XML DTD，XML 解析器可用其检查 XML 文件的语法。

XML_PROGRAMLISTING

若为 YES，doxygen 会将程序列表（包含高亮语法和交叉引用的信息）转存到 XML 的输出。注意，此标记有效将会显著增加 XML 输出的大小。

与 AUTOGEN_DEF 相关的选项

GENERATE_AUTOGEN_DEF

若为 YES，doxygen 将会生成一个 AutoGen 的定义（查看）文件，用于表述所有文档中包含的代码结构。注意，此特性一直在试验中，目前还不完善。

与PERLMOD 相关的选项

GENERATE_PERLMOD

若为 YES，doxygen 将生成一个 Perl 模块，用于表述所有文档中包含的代码结构。注意，此特性一直在试验中，目前还不完善。

PERLMOD_LATEX 若为 YES，doxygen 将生成必要的 Makefile 规则，以使 Perl 脚本和 latex 代码可从 Perl 模块的输出中生成 PDF或 DVI 文件。

PERLMOD_PRETTY

若为 YES，Perl 模块的输出将具有良好的格式，以方便使用者阅读。对于你理解它的操作过程也是非常有价值的。另类情况下，若为 NO，Perl 模块的输出规模将非常小，但对 Perl 来说是可解析的。

PERLMOD_MAKEVAR_PREFIX

在已生成 doxyrules.make 文件中的 make 变量名，将被加入到此选项所设定的字串之前。The names of the make variables in the generated doxyrules.make file are prefixed with the string contained in

PERLMOD_MAKEVAR_PREFIX.这对于在同一 Makefile 中包含有若干个不同的 doxyrules.make，且相互存在不能覆盖的变量名时，这个选项将非常有用。

与预处理有关的选项

ENABLE_PREPROCESSING

若为 YES（默认），doxygen 将在源文件和头文件中，判别所有的 C 预处理指令。

MACRO_EXPANSION

若为 YES，doxygen 将在源代码中展开所有的宏定义。若为 NO（默认），只会执行条件编译。宏展开的另一种控制 方法是将 EXPAND_ONLY_PREDEF 设为 YES。

EXPAND_ONLY_PREDEF

若此标记和 MACRO_EXPANSION 均设为 YES，宏展开将受限于宏所指定的 PREDEFINED，EXPAND_AS_DEFINED 标记。

SEARCH_INCLUDES

若为 YES（默认），如果#include 被找到，那么将搜索INCLUDE_PATH（下一条）中的头文件。

INCLUDE_PATH

指定一个或多个目录，用于预处理在输入文件未找到包含的头文件时将搜索的其他位置。

PREDEFINED

在预处理运行之前，指定一个或多个宏定义名（类似于运行 gcc –D）。此标记的参数是一个宏列表，如下：name 或者 name=definition (无空格)。如果 definition 和“=”被省略，则假定“=1”.用来防止一个宏定义来自于，使用了#undef 的非受限标识 undefined，或是在递归展开使用：=操作符而不是=操作符。

EXPAND_AS_DEFINED

若 MACRO_EXPANSION， EXPAND_ONLY_PREDEF 均为 YES，此标记用于指定一个将被展开的宏名列表。并将源码中查 询列表中的宏定义。如果你想使用一个不同的宏定义，可用 PREDEFINED 标记。

SKIP_FUNCTION_MACROS 若为 YES（默认），所有风格类似于函数，且处于单独的一行内使用一个全部大写的名字并没有以分号结束的宏，将被 doxygen 的预处理删除。为了代码的风格一致，通常会使用函数宏，如果不将其移除，将会引起解析器的混 乱。

与外部引用相关的选项

TAGFILES

用于指定一个或多个 tag 文件。 查看“doxytag 用法”小节以获得 tag 文件用法的更多信息。 可每一个 tag 文件选定一个将添加的外部文档的初始位置，tag 文件的格式中不附带位置信息的方式，如下：

TAGFILES = file1 file2 …

在 tag 文件添加位置信息方式，如下：

TAGFILES = file1=loc1 “file2 = loc2” …

loc1，loc2 可以是相对路径，绝对路径或者 URL，如果 tag 文件出现一个位置信息，Installdox 工具（查看

“Installdox 用法”小节获得更多信息）无需运行来修正这个链接。

注意：每个 tag 文件都有一个唯一的名称（此名称不包含路径），当 doxygen 运行后在目录无法定位一个 tag 文件时，你必须指定一个路径给这个 tag 文件。

GENERATE_TAGFILE

当在此标记后指定一个文件名时，doxygen 将创建一个 tag 文件，基于 doxygen 所读取的输入文件。查看“doxytag用法”小节以获得 tag 文件用法的更多信息。

ALLEXTERNALS

若为 YES，在类的索引中将列表所有的外部类，若为 NO，只会列表外部继承类。

EXTERNAL_GROUPS

若为 YES，在模块索引中将列表所有的外部组，若为 NO，只会列表当前项目的组。

PERL_PATH

指定 perl 脚本翻译器的绝对路径和程序名（等同于 which perl 的运行结果）。

与 Dot 相关的选项

CLASS_DIAGRAMS

若为 YES（默认），doxygen 将为基类或超类生成一个类图表（在 HTML 和 latex 中）。若为 NO 将取消类图表。注意，此选项将被下面的 HAVE_DOT 选项所取代，它只是一个备用选择。推荐安装 dot，因为使用它能产生更丰富的图形效果。

MSCGEN_PATH

可使用\msc命令在 doxygen的注释中定义消息序列图。

Doxygen将运行mscgen工具生成此图并插入到文档中。此选项允许你指定 mscgen 工具的保存目录，若选项后留空，将在默认搜索路径中查找该工具。

HAVE_DOT

若为 YES，doxygen 将假定在系统路径中 dot 工具是有效的，此工具是 GraphViz（一个来自 AT＆T 和朗讯贝尔实验室的图形可视化工具包）的一部分，若此选项为 NO（默认），那么该小节中其他选项将全部失效。

DOT_NUM_THREADS

指定 doxygen 能允许并行调用 dot 的线程数。当设为 0（默认）doxygen 将依据系统中有效的处理器个数设定 dot的线程数。你可以设定一个大于 0 的值，用于控制 CPU 载荷和处理速度之间的平衡。

DOT_FONTNAME

默认情况下，doxygen 将写入一个名为 FreeSans.ttf 字体文件到输出目录中，并在 doxygen 生成的所有 dot 文件中引用。但这个字体并不包含一切可能的 unicode 字符，所以当你需要这些无法显示的字符时（或者更换一种不同的字体），你可以用 DOT_FONTNAME 指定字体的名称。你需要确认 dot 能否找到指定的字体，可将字体放置到一个标准的位置，或是配置 DOTFONTPATH 环境变量，又或者在 DOT_FONTPATH 指定的目录中包含该字体。

DOT_FONTSIZE

设定 dot 图表中字体的尺寸，默认为 10pt。

DOT_FONTPATH

默认情况下，doxygen 将告知 dot 从输出目录查找 FreeSans.ttf 字体文件（或是其他 doxygen 放置字体文件的目录），如果使用 DOT_FONTNAME 指定了一个特殊字体，你要在此选项后设定相应的路径使得 dot 能够找到。

CLASS_GRAPH

若 CLASS_GRAPH，HAVE_DOT 都为 YES，doxygen 将为每个文档化的类生成一个类图，显示直接和间接的继承关系。

设定该标记为 YES 后将导致 CLASS_DIAGRAMS 标记为 NO。

COLLABORATION_GRAPH

若 COLLABORATION_GRAPH，HAVE_DOT 都为 YES，doxygen 将为每个文档化的类生成一个协作图，显示直接和间接的类与其他文档化类的执行依赖关系（继承，包容，类引用变量）。

GROUP_GRAPHS

若 GROUP_GRAPHS，HAVE_DOT 都为 YES，doxygen 将成一个组图，显示直接的组的依赖关系。

UML_LOOK

若为 YES，doxygen 将生成继承和协作的图表，在样式类似于 OMG 的统一建模语言。

TEMPLATE_RELATIONS

若 TEMPLATE_RELATIONS，HAVE_DOT 都为 YES，doxygen 将显示出模板和它的实例化之间的关系。

HIDE_UNDOC_RELATIONS

若为 YES，如果目标未被文档化或者不是一个类，那么继承和协作图中将隐藏继承和调用的关系。

INCLUDE_GRAPH

若 ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_ GRAPH，HAVE_DOT 都为 YES，doxygen 将为每个文档化文件生成一个包容图，显示与其他文件的直接和间接的包容依赖关系。

INCLUDED_BY_GRAPH

若 ENABLE_PREPROCESSING, SEARCH_INCLUDES,INCLUDED_BY_GRAPH，HAVE_DOT 都为 YES，doxygen 将为每个文档化的头文件，生成一个包容图以显示那些文件直接或间接包含过此头文件。

CALL_GRAPH

若 CALL_GRAPH，HAVE_DOT 都为 YES，doxygen 将被每一个全局函数或类方法生成一个调用依赖图，注意，有效该选项将会显著增加运行的时间，但大多数情况下，它优于只在所选函数中使用\callgraph 命令来有效调用图的生成。

CALLER_GRAPH

若 CALLER_GRAPH，HAVE_DOT 都为 YES，doxygen 将被每一个全局函数或类方法生成一个被调用的依赖图，注意，有效该选项将会显著增加运行的时间，但大多数情况下，它优于只在所选函数中使用\callergraph 命令来有效被调用图的生成。

GRAPHICAL_HIERARCHY

若 GRAPHICAL_HIERARCHY，HAVE_DOT 都为 YES，doxygen 将为所有的类生成层次图，以替换原有的纯文字描述。

DIRECTORY_GRAPH

若 DIRECTORY_GRAPH，HAVE_DOT 都为 YES，doxygen 将使用图形的方式展现出目录之间的依赖关系，这种依赖关 系可以确定目录中文件之间的包含关系。

DOT_GRAPH_MAX_NODES

用于设定在图中将显示的最大节点数。若图中的节点数大于该值，doxygen 将对图进行处理，多余的节点将被放 置到图中可见的类似于一个红盒子的节点内。注意，如果图中根节点的下级子节点数已经超过该选项的设定值，

doxygen 将无法显示所有的节点，图的尺寸也能通过 MAX_DOT_GRAPH_DEPTH 进行限定。

MAX_DOT_GRAPH_DEPTH

用于设定 dot 工具生成的图中显示的最大深度，深度值为 3，意味着根结点下的每条路径上最多只能获得 3 层节点的显示。根结点的索引值为 0，即计算深度值时它将被忽略。注意，对于大型代码库来说，设定此选项为 1 或 2 能大大减稍所需的计算时间，图的尺寸也能通过 DOT_GRAPH_MAX_NODES 进行限定，选定深度值为 0（默认）则 表示无深度限制。

DOT_IMAGE_FORMAT

用于设定 dot 工具生成的图片格式，它有可能是 gif, jpg, jpg，如果选项后留空则使用 jpg 格式。 DOT_PATH 指定 dot 工具放置的位置，若选项后留空，则假定 dot 工具处于能被查找到的路径之下。

DOTFILE_DIRS

用于指定文档中包含一个或多个保存有 dot 文件的目录（查看\dotfile 命令）

DOT_TRANSPARENT

若为 YES，将生成背景透明的图片。该选项默认状态下是无效的，因为在 windows 中 dot 并不支持这个功能。警 告：与使用的平台有关，有效该选项可能会导致在图形的边沿出现抗锯齿的印记（它们将变得难以阅读）。

DOT_MULTI_TARGETS

若为 YES，允许 dot 在一次运行中生成多个输出文件（在命令行中使用 -o 和 –T 的选项），这将使得 dot 运行得更快，但只有 dot 新版本（>1.8.10）才支持，此特性在默认情况下是禁用的。

GENERATE_LEGEND

若为 YES（默认），doxygen 将生成一个说明页面，用于解释在 dot 生成的图中多种方框和箭头的所表达的意义。

DOT_CLEANUP

若为 YES（默认），doxygen 将删除在生成多种图时使用的 dot 临时文件。