源代码文档生成工具----Doxygen

1. 简介

Doxygen是一种文档生成工具，可以抽取代码中的注释，生成类似JavaDoc的文档。

该工具支持的平台有Linux、Max OS X、Windows；支持的编程语言包括：C/C++、Java、Python、C#等数十种语言。

Doxygen是以GPL授权方式发布的开源软件，任何人都可以免费下载使用。

Doxygen的输出格式有html和tex，如果安装HTML HelpWorkshop和LaTeX，可以进一步分别编译成chm和pdf文档。

下文仅以前者为例。

2. 安装和配置

安装过程非常简单，运行安装文件即可。

安装好后运行Doxywizard，如下图所示：

Wizard页：

         设置工程路径，输出格式等选项，如果没有安装LaTeX软件，在output项中可以取消该选项。

Expert页：

高级选项设置。

以下为主要需要修改的项，其他的选项需要进一步探索

Topics	子选项	备注
Project	PROJECT_NAME	工程名称
	OUTPUT_DIRECTORY	生成文档的存放路径
	OUTPUT_LANGUAGE	输出语言，可以选择中文
Input	INPUT	输入目录，代码所在目录
	INPUT_ENCODING	代码文件的编码格式，如果填错会导致中文注释乱码， (Win 7中文版下VC采用GB2312)
	RECURSIVE	递归分析子目录
	EXCLUDE_SYMBOLS	将指定的符号(namespace，class，function)从输出文档中排除
HTML	GENERATE_HTMLHELP	生成额外的index文件，用于编译成chm；
	CHM_FILE	输出的chm文件名
	HHC_LOCATION	hhc.exe的路径，该文件在HTML Help Workshop安装后的目录中； 可选，如果不填则只生成html
	CHM_INDEX_ENCODING	Index文件的编码，hhc默认支持GB2312，所以这里指定为GB2312
Preprocessor	ENABLE_PREPROCESSING	启用预编译功能
	MACRO_EXPANSION	宏定义展开
	EXPAND_ONLY_PREDEF	展开指定的宏定义
	PREDEFINED	指定要展开的宏定义， 假如#define X Y 则语法为PREDEFINED = “X = Y”， 如有多个宏定义则添加"\", 并另起一行

Run页

运行doxygen，生成文档，可以点击show html output查看是否成功生成文档。

由于生成的html文档包含非常多的文件，因此最好还是编译成一份chm文档。

 

选择file->Save保存该配置文件。

对于其他工程的代码，需要再生成一份类似的配置文件。

3. 填写注释

到此，我们已经完成的doxygen的基本配置，但是生成的文档里并没有具体的内容。

为了使注释能够被doxygen识别，我们需要根据一定的格式来写注释，具体可参考doxygen的用户手册，该手册在doxygen的安装目录下。