doxygen的安装与使用
前言
大多数程序员讨厌的两件事，一是为代码写注， 二是维护代码文档。doxygen就能把遵守某种格式的注释自动转化为对应的文档， 从而提高程序员的工作效率。
Doxygen是基于GPL的开源项目，是一个非常优秀的文档系统，当前支持在大多数unix（包括linux），windows家族，Mac系统上运行，完全支持C++, C, Java, IDL（Corba和Microsoft 家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有很多开源项目（如log4cpp和CppUnit）都使用了doxygen文档系统。
安装
- 安装doxygen
sudo apt-get install doxygen
安装后可以使用命令行操作doxygen工具。
- 安装doxygen-gui
sudo apt-get install doxygen-gui
安装后可以通过指令doxywizard打开doxygen图形界面。
- 安装Graphviz
sudo apt-get install graphviz
安装后可以生成文件可视化图。
参数配置
doxygen的参数配置有两种方式， 一种是命令行方式，另一种是图形界面方式。对于第一次使用，推荐使用第二种方式设置好参数，设置好后保存参数文件供下次使用，以后只用手动修改少量设置即可使用。
命令行
一种是通过命令行生成配置文件，然后手动修改文件中的参数。
doxygen -g <doxygen-file> //生成doxygen配置文件
doxygen <doxygen-file> // 根据doxygen配置文件生成文档
图形界面
另一种是通过图形界面修改配置
- 设置Project
注： 设置好了doxygen工作目录后，源文件的目录和生成文档的存放目录请设置为工作目录的相对路径。
- 设置Mode
- 设置Output
- 设置Diagrams
- 生成文档
更多参数
在上述界面中点击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_DIAGRAMS> 标记就无效了 |
| CLASS_GRAPH | 如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes，就使用 dot 生成继承层次结构图 |
| GRAPHICAL_HIERARCHY | 设置为YES时，将会绘制一个图形表示的类图结构 |
上面的表格只是描述了一些常用的配置，需要更加详细的信息请参考Doxygen的帮助手册。
注释风格
在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed。 两种都是可选的，但不能同时没有。
顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。
Doxygen支持c风格注释、c++风格注释以及javaDoc风格注释等，下面将分别予以介绍。
若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：
- 文件头（包括.h和.cpp）：主要用于声明版权，描述本文件实现的功能，以及文件版本信息等
- 类的定义：主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述
- 类的成员变量定义：在类的成员变量上方，对该成员变量进行简要地描述
- 类的成员函数定义：在类定义的成员函数上方，对该成员函数功能进行简要描述
- 函数的实现：在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等
常用指令
可以在注释中加一些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 |
| @exception | 可能产生的异常描述eg:@exception 本函数执行可能会产生超出范围的异常 |
注释示例
文件头注释
/**
* @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
*/
类定义注释
/** 本类的功能：打印错误信息
*
* 本类是一个单件
* 在程序中需要进行错误信息打印的地方
*/
class CPrintError
{
……
}
类成员变量定义注释
（1）在成员变量上面加注释的格式
/** 成员变量描述 */
int m_Var;
（2）在成员变量后面加注释的格式
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;
vscode插件
vscode中有一款Doxygen Documentation Generator插件，可以快速补全doxygen的注释。
