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

转自：http://hi.baidu.com/seest/blog/item/9f1d73c268b81636e4dd3b4f.html

 

详细见：http://blog.csdn.net/fmddlmyy/archive/2007/06/23/1663898.aspx

按照约定的格式注释源代码，用工具处理注释过的源代码产生文档。通过这种方式产生文档至少有以下好处：

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

很多编程语言都有类似的文档工具，例如：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。

下载这些工具：Doxygen 1.5.2、Graphviz 2.12、iconv (GNU libiconv 1.9)和fr 2.1.1.120。