使用doxygen生成代码工程文档并显示相关注释

1 环境准备

工具链接地址：

 

链接：http://pan.baidu.com/s/1slowLaP 密码：d7j5 

 

说明：

 

工具文件	使用说明
doxygen-1.5.2-setup.exe	Doxyge，安装即可。
graphviz-2.12.exe	图形可视化软件，安装即可。
htmlhelp.exe	用于生成CHM文件，安装即可
iconv.rar	编码转换，按后文说明使用。
fr.rar	命令行查找替换工具，按后文说明使用。
doxybat.zip	批处理文件，解压后按后文说明使用。

 

建立一个空目录xxx，放入要注释的程序（xxx\src），建立制作文档的工作目录（xxx\doc），将前面介绍的批处理文件放到doc目录。

2 批处理文件使用说明

说明：将批处理文件放在工作目录（doc目录：即Doxyfile所在目录）后，每次只要键入rebuild就可以重新生成chm文件。必要时可以单独使用clean、build、makechm命令。utf82gbk和html-utf82gbk命令也可以单独使用。

2.1 clean.bat

作用：清空之前的输出文件

 

@echo off echo 清空以前输出 if exist refman.chm del /f /q refman.chm if exist output\html del /f /q output\html\*.* if exist output\latex del /f /q output\latex\*.* if exist output\rtf del /f /q output\rtf\*.* if exist output del /f /q output\*.*

2.2 build.bat

作用：调用doxygen生成文档

 

@echo off echo 生成文档 doxygen Doxyfile

2.3 utf82gbk.bat

作用：将指定文件（支持通配符）从utf-8编码转换到gbk编码

 

@echo off echo 将%1从utf-8编码转换到gbk编码 for %%f in (%1) do copy %%f %%f.utf8 for %%f in (%1) do iconv -c -f utf-8 -t gbk %%f.utf8 > %%f

 

这个批处理文件要求系统当前路径上有iconv.exe。执行iconv时，使用-c参数忽略无法转换的字符。否则如果输入文件包含无法转换的字符，转换会失败。输入文件被备份到加过.utf8后缀的文件。

2.4 make_utf82gbk.bat

作用：将指定路径（默认输入：..\src）下的所有文件从utf-8编码转换到gbk编码格式

 

@echo off echo 将%1目录下的所有文件从utf-8转换到gbk cd %1   echo 处理chm输入文件 for %%f in (*.c *.h) do call utf82gbk.bat %%f   cd ..\doc\

 

2.5 html-utf82gbk.bat

作用：将指定html文件（支持通配符）从utf-8编码转换到gbk编码

 

@echo off call utf82gbk %1 echo 将%1中的charset从UTF-8改为gb2312 fr %1 -f:charset=UTF-8 -t:charset=gb2312

 

这个批处理文件要求系统当前路径上有iconv.exe和白杨的fr.exe。

2.6 makechm.bat

作用：用Doxygen的输出制作chm文件

 

@echo off echo 将Doxygen输出文件编码从utf-8转换到gbk set path=%path%;%cd% cd output\html echo 处理chm输入文件 call utf82gbk.bat index.hhp call utf82gbk.bat index.hhc call utf82gbk.bat index.hhk call html-utf82gbk *.html echo 生成chm文件 "C:\Program Files (x86)\HTML Help Workshop\hhc.exe" index.hhp if exist index.chm copy index.chm ..\..\refman.chm del /f /q *.chm cd ..\..

 

这个批处理文件假设系统在目录“C:\Program Files (x86)\HTML Help Workshop\”安装了“HTML Help Workshop”。并假设输出目录是Doxyfile所在目录的子目录output。

2.7 rebuild.bat 

作用：重新生成chm文件

 

@echo off call clean.bat call build.bat call makechm.bat

 

3 创建配置文件

3.1 准备工作

安装Doxygen、Graphviz和“HTML Help Workshop”。

 

将iconv和fr程序放到系统路径包含的目录（区分系统位数）：

32位系统 c:\windows\system32

64位系统 c:\windows\SysWOW64

 

运行Doxywizard (安装Doxygen后的根目录下的bin文件中)创建配置文件：

 

 

直接点“Save...”按钮，将配置保存在doc\Doxyfile。这时，Doxyfile的内容是Doxygen的默认设置，我们可以直接打开编辑。不过在Doxywizard的界面上填写也很方便，每个参数都有详细提示。建议用Doxywizard完成第一次设置，以后如果需要调整个别参数，可以直接编辑Doxyfile。

 

3.2 填写参数

点击“Expert...”按钮后，开始填写配置参数。

 

 

下面是Doxygen配置参数介绍：

3.2.1 Project页

DOXYFILE_ENCODING是Doxyfile的文本编码。如果文件中有中文字符，可以填写GBK。

 

填写项目名（PROJECT_NAME）、项目版本（PROJECT_NUMBER）、输出目录（OUTPUT_DIRECTORY）和输出语言（OUTPUT_LANGUAGE）。输出目录可以按Doxyfile的相对目录填写。输出语言相当于程序资源，选择Chinese。

 

Doxywizard的中文支持不完善，所以在Doxywizard中使用中文后需要使用utf82gbk.bat对其进行转码。我们直接编辑Doxyfile，例如填写：

 

PROJECT_NAME = 微信宠物屋

 

取消FULL_PATH_NAMES。我们修改了以下参数：

 

DOXYFILE_ENCODING	GBK
PROJECT_NAME	微信宠物屋
PROJECT_NUMBER	1.0
OUTPUT_DIRECTORY	output
OUTPUT_LANGUAGE	Chinese
FULL_PATH_NAMES	NO

3.2.2 Messages页

在Messages页将WARN_LOGFILE填写为build.log。这样，Doxygen会将编译时出现的警告和错误保存在build.log，我们可以对照修改。

 

WARN_LOGFILE

build.log

3.2.3 Input页

指定输入源文件目录（INPUT），将输入文件编码（INPUT_ENCODING）改为GBK。

 

INPUT	..\src
INPUT_ENCODING	GBK

 

FILE_PATTERNS参数是Doxygen要处理的文件类型，缺省值包括Doxygen支持的所有文件类型。不能用Doxygen文档化任意文件类型。例如Doxygen不支持汇编程序。

3.2.4 Source Browser页

选择SOURCE_BROWSER，在文档中包含源代码。

 

SOURCE_BROWSER

YES

3.2.5 Html页

选择GENERATE_HTMLHELP后，Doxygen会准备生成chm文件需要的项目文件、目录文件和索引文件。可以通过参数HTML_HEADER和HTML_FOOTER定制页面，参数值是包含定制内容的文件名。例如，我们可以建立文件html_foot，内容为：

 

穷举和推理：用C++程序求解“谁养鱼”

 

然后将HTML_FOOTER的值设为html_foot。

 

GENERATE_HTMLHELP	YES
HTML_FOOTER	html_foot

3.2.6 LaTex页

取消GENERATE_LATEX，不产生LaTex输出。

 

GENERATE_LATEX

NO

3.2.7 Dot页

在Dot页，可以选上UML_LOOK、CALL_GRAPH和CALLER_GRAPH。CALL_GRAPH是本函数调用其它函数的示意图，例如：

 

 

CALLER_GRAPH是本函数调用者的示意图，例如：

 

 

UML_LOOK	YES
CALL_GRAPH	YES
CALLER_GRAPH	YES

3.3 运行Doxygen

其它参数都可以使用缺省值。从命令行进入doc目录后运行rebuild.bat，就可以产生网页版文档(doc\output\html\index.html )以及chm版文档(doc\refman.chm)。这时，我们还没有对程序作任何文档化，输出仅包含Doxygen通过Dot生成的示意图。

我们可以编辑Doxyfile，将EXTRACT_ALL设为YES，再rebuild。这时，Doxygen会自动提取程序的所有要素，包括文件、函数、变量、类型定义、枚举、枚举值、宏定义等。

 

 

4. 编写Doxygen可识别的注释

说明：Doxygen可识别Javadoc风格的注释，注释模板如下：

 

4.1 文件注释

 

/** * @file  CommonType.h   * @brief 常见类型定义 * @author       Vincent * @date     2015-5-24 * @version  A001 * @copyright Vincent                                                               */

 

4.2 函数注释

 

/**  * 读取文件  * @param[in]    fileNameLen    文件名长度  * @param[in]   fileName    文件名  * @param[in]    dataLen        数据长度  * @param[out]  fileData    输出数据  * @return        0，执行成功，非0，失败，详见  * @ref            RetCode.h  * @see  * @note  */ UINT ReadFile(UINT fileNameLen, BYTE *fileName, UINT dataLen, BYTE *fileData);

 

4.3 类型/宏定义注释

 

/** * 2字节字符类型                                                                  */ typedef unsigned short WORD;

 

4.4 枚举/结构注释

 

/**  枚举类型*/   enum COLOR{     RED=0,    ///<  红色     GREEN=1,///<  绿色     YELLOW=2///<  黄色 };

 

4.5 全局和静态变量注释

 

/**  Description of global variable  */   int g_xxx = 0;   static int s_xxx = 0; ///<  Description of static variable

 

4.6举例说明（函数注释）：

 

代码中如下：

 

 

 

生成文档中显示如下：