方法一：使用doxygen为C/C++程序生成中文文档
转自www.fmddlmyy
按照约定的格式注释源代码，用工具处理注释过的源代码产生文档。通过这种方式产生文档至少有以下好处：
∙ 便于代码和文档保持同步。
∙ 可以对文档做版本管理。
很多编程语言都有类似的文档工具，例如：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编译器（）编译后生成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。
可以从我的主页www.fmddlmyy下载这些工具：Doxygen 1.5.2、Graphviz 2.12、iconv (GNU libiconv 1.9)和fr 2.1.1.120。
2 CHM格式的中文问题
前面说过：目前，Doxygen统一采用UTF-8作为输出文件的编码格式，但微软的CHM编译工具（）不支持UTF-8。如果直接用编译，中文不能正确显示。解决这个问题的思路很简单：
∙ 将Doxygen输出的html文件以及CHM的项目文件（.hhp）、目录文件（.hhc）和索引文件（.hhk）全部转换到GBK编码后，再用编译即可。
可以用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时，使用-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
这个批处理文件要求系统当前路径上有和白杨的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 " 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命令的朋友应该很容易看懂这些批处理吧。将这些批处理文件放在工作目录（即Doxyfile所在目录）后，每次只要键入rebuild就可以重新生成chm文件。必要时可以单独使用clean、build、makechm命令。utf82gbk和html-utf82gbk命令也可以单独使用。读者可以从我的主页www.fmddlmyy下载这些批处理文件。
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创建配置文件。
可以直接点“”按钮，将配置保存在doc\Doxyfile。这时，Doxyfile的内容是Doxygen的默认设置。Doxyfile是普通文本文件，我们可以直接打开编辑。不过在Doxywizard的界面上填写也很方便，每个参数都有详细提示。建议用Doxywizard完成第一次设置。以后如果需要调整个别参数，可以直接编辑Doxyfile。
3.2 填写参数
点“”按钮后，开始填写配置参数。
:)，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，在文档中包含源代码。

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。