使用doxygen为C/C++程序生成中文文档

文章来自:http://www.fmddlmyy.cn/text21.html

依照约定的格式凝视源码，用工具处理凝视过的源码产生文档。经过这样的方式产生文档至少有下面优势：

• 便于代码和文档保持同步。
• 可以对文档作版本号管理。

很是多编程语言都有相似的文档工具，好比：Java有javadoc，Ruby有rdoc。对于C/C++程序，咱们可以用Doxygen生成文档。本文经过为一个C++程序“谁养鱼”创建文档，介绍了如何在Windows平台使用Doxygen。

Doxygen比較适合制做API的接口文档，CHM是这类文档的常见格式。

最新版本号的Doxygen（眼下是1.5.2）统一採用UTF-8做为输出文件的编码格式，但微软的CHM编译工具不支持UTF-8。这就为制做中文CHM文档带来麻烦。

本文提出了解决问题的方法。

1 Doxygen简单介绍

1.1 要作什么

使用Doxygen生成文档。主要是两件事：

1. 写一个配置文件（Doxyfile）。通常用Doxywizard生成后。再手工改动。

2. 依照Doxygen的约定，将代码“文档化”。

而后仅仅要运行命令：

doxygen Doxyfile

就可以了。输入文件、输出文件夹、參数等都是在Doxyfile中配置的。

1.2 获得什么

Doxygen的输出格式主要有HTML、LATEX、RTF等：

• Doxygen在输出HTML文档时，可以本身主动准备用于制做CHM的项目文件（.hhp）、文件夹文件（.hhc）和索引文件（.hhk）。

  用HTML Help Workshop中的CHM编译器（hhc.exe）编译后生成CHM文件。

• Doxygen在输出LATEX文档的同一时候准备了转换到pdf格式的makefile。仅仅要系统安装了合适的TEX工具，就可以从LATEX文档生成pdf文档。

• Doxygen输出的RTF格式，已经针对Word做了优化。可以较好地转换到Word文档。

1.3 需要什么

完毕本文的范例需要下面工具：

1. Doxygen的最新版本号。可以从Doxygen的站点下载。
2. Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各类图形，好比类的继承关系图、合做图，头文件包括关系图等。可以从Graphviz的站点下载Graphviz的最新版本号。Doxygen使用了Graphviz的布局引擎dot，因此在文档中将其称做dot。
3. 为解决中文问题。需要使用Cygwin的iconv程序做编码转换。
4. 为解决中文问题，需要一个命令行的查找替换工具。

   我选择了白杨创做的工具fr。

可以从个人主页http://www.fmddlmyy.cn下载这些工具：Doxygen 1.5.2、Graphviz 2.12、iconv (GNU libiconv 1.9)和fr 2.1.1.120。

2 CHM格式的中文问题

前面说过：眼下，Doxygen统一採用UTF-8做为输出文件的编码格式。但微软的CHM编译工具（hhc.exe）不支持UTF-8。假设直接用hhc.exe编译，中文不能正确显示。解决问题的思路很是easy：

• 将Doxygen输出的html文件以及CHM的项目文件（.hhp）、文件夹文件（.hhc）和索引文件（.hhk）全部转换到GBK编码后，再用hhc.exe编译就能够。

可以用iconv对文件做编码转换。对于html文件。除了文件内容的编码转换外，还要将

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

中的“UTF-8”替换成“gb2312”。

2.1 用批处理简化操做

我写了一些批处理文件（.bat）用于简化处理过程。包含：

2.1.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.1.2 build.bat —— 调用doxygen生成文档

@echo off
echo 生成文档
doxygen Doxyfile


2.1.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.1.4 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.1.5 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\HTML Help Workshop\hhc.exe" index.hhp

if exist index.chm copy index.chm ..\..\refman.chm
del /f /q *.chm
cd ..\..


这个批处理文件若是系统在文件夹“C:\Program Files\HTML Help Workshop\”安装了“HTML Help Workshop”。并若是输出文件夹是Doxyfile所在文件夹的子文件夹output。

2.1.6 rebuild.bat —— 又一次生成chm文件

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


2.2 小结

了解DOS命令的朋友应该很是easy看懂这些批处理吧。将这些批处理文件放在工做文件夹（即Doxyfile所在文件夹）后。每次仅仅要键入rebuild就可以又一次生成chm文件。必要时可以单独使用clean、build、makechm命令。utf82gbk和html-utf82gbk命令也可以单独使用。

读者可以从个人主页www.fmddlmyy.cn下载这些批处理文件。

3 建立配置文件

3.1 准备工做

“谁养鱼”是我近期写的一个小程序，它用推理法求解爱因斯坦谜题——“谁养鱼”。读者可从《穷举和推理：用C++程序求解“谁养鱼”》下载未文档化的程序。

制做文档前。咱们要完毕下面准备工做：

1. 安装Doxygen、Graphviz和“HTML Help Workshop”。我使用的HTML Help Workshop版本号是4.74.8702.0。英文版。网上有汉化版本号，但执行时会出错。
2. 将iconv和fr程序放到系统路径包括的文件夹。好比c:\windows\system32。
3. 创建一个空文件夹fish。放入要凝视的程序（fish\src），创建制做文档的工做文件夹（fish\doc），将前面介绍的批处理文件放到doc文件夹。

好了。现在可以执行Doxywizard建立配置文件。

可以直接点“Save...”button，将配置保存在doc\Doxyfile。这时，Doxyfile的内容是Doxygen的默认设置。Doxyfile是普通文本文件。咱们可以直接打开编辑。只是在Doxywizard的界面上填写也很是方便，每个參数都有具体提示。建议用Doxywizard完毕第一次设置。之后假设需要调整个别參数，可以直接编辑Doxyfile。

3.2 填写參数

点“Expert...”button后，開始填写配置參数。

:)，Doxygen是否是有很是多參数？事实上大多数參数都有缺省值。需要填写的不算多，如下分页介绍：

3.2.1 Project页

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

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

Doxywizard的中文支持不无缺，中文字符会被存为乱码。咱们直接编辑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，内容为：

<p align="right"><A HREF="http://www.fmddlmyy.cn/text20.html" target="_top">穷举和推理：用C++程序求解“谁养鱼”</A></p>
</BODY>
</HTML>

而后将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文件夹后（參见附录1）执行rebuild.bat，就可以产生refman.chm。这时，咱们尚未对程序做不论什么文档化。输出仅包括Doxygen经过Dot生成的示意图。

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

仅仅想看看结果的朋友可以下载这个chm文件。Doxygen配置文件里所有參数的具体參考可以查阅Doxygen手冊中的“Configuration”页。上篇到此结束。下篇将介绍文档化程序的方法。

后记（2007/7/15）

很多朋友说依照个人说明不能产生期待的结果。这必定是个人文章表述不清了，很差意思。近期，我手头事情比較多，这几个月恐怕没时间写本文的下篇了。

好在网上介绍Doxygen文档化的文章仍是很多的，少我这篇应该也没什么。

事实上，这篇文章的目的仅仅是让不熟悉doxygen的朋友可以高速地了解这个工具。你们假设真的要使用doxygen，仍是应该多花些时间看看它的文档。我把本文范例的工做文件夹打包放在个人主页www.fmddlmyy.cn上，需要的朋友可以下载。

这是个未完毕的版本号，我去掉了EXTRACT_ALL。凝视了几个函数。因为凝视不完整，编译（在doc文件夹rebuild）时还会产生非空的build.log。

log是善意的提示，可以帮助咱们无缺文档。

附录1 高速进入命令行并转到指定文件夹

假设经常用到命令行，可以在注冊表的“HKEY_CLASSES_ROOT\Folder\shell”下创建“Command Prompt Here”项及其子项“command”。将“command”项的默认值设为字符串值“cmd.exe”。这时，仅仅要在资源管理器的随意文件夹上点击右键并选择“Command Prompt Here”就可以高速进入命令行并转到指定文件夹。

我将这个注冊表项保存成reg文件：

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\Folder\shell\Command Prompt Here]

[HKEY_CLASSES_ROOT\Folder\shell\Command Prompt Here\command]
@="cmd.exe"




需要的朋友可以下载后双击导入注冊表就能够。

在vista上。这样操做不能进入指定文件夹，也没有必要这样作。在vista中：仅仅要在资源管理器中先按下shift键。再用右键点击文件夹，就会出现“在此处打开命令窗体”的菜单项，选择就能够。在左側的文件夹树上。这样操做无效。