Doxygen简单经验谈。。。
Doxygen，大名鼎鼎的文档生成工具，被Boost、OpenCasCade等诸多项目作为文档生成的不二人选。人说，才华横溢往往是高深莫测，这句话放在 Doxygen这里显然是不适用的。十八般武艺样样精通的Doxygen，却十分的简单易用，从头到尾看一下它随机的文档，想不会用都难。。。
嫌看英文麻烦的，这里有一篇中文的入门介绍。简单的说，如果你准备在项目中采用Doxygen作为文档生成的工具，首先，你需要了解，Doxygen需要什么样的代码结构才能够生产文档。 Doxygen基本上对光秃秃的代码不感兴趣，你需要在所有的类、函数、成员函数、公共变量、名字空间等代码已有表示的结构上方添加上指定格式的注释，Doxygen才能识别出来。此外，你还可以按照指定格式的注释添加附加的信息，用以生成模块的分类，架构图之类的信息。Doxygen支持的注释格式多种多样，强烈建议制定一个统一的标准，否则会给项目中其他的人员或者后来的人员带来很多的困扰。。。
按照指定的格式书写了注释之后，就需要写一个Doxygen的配置文件，依照此配置文件，Doxygen可以生产HTML、Tex、XML等多种格式输出文档。Doxygen的配置文件，有辅助的GUI工具帮助书写，你只需要改几个选项，点几下按钮就信手拈来了。但在此强烈建议，你应该把Doxygen每一个配置值的含义都了解一下，写一些简单的例子实践一下，这样一则你可以清楚的明白你需要的格式该如何配置出来，二则你可以充分了解Doxygen可以做到什么程度，以备不时之需。。。
Doxygen通常是用作生成英文文档的，生成中文文档需要修改输入和输出的码制，这样可以改变解析方式，生成中文文档。但是，你必须意识到，Doxygen在从注释中抽取信息是需要做语法解析的，这些解析都是基于英文的基础，不可能在这个层面上支持中文。比如，一个类的简明信息和详细信息的分隔，是通过英文的句号“.”来识别的，如果你用中文的句号“。”，Doxygen就分辨不出来了。再比如，在某个类的注释中，你写 Created by xxx function，其中xxx是某个方法名，Doxygen会在生成的文档中，自动为该函数添加上链接。当如果你用中文：该类是被xxx方法构造出来的。 Doxygen就无法抽取出该信息并添上链接。你要按如下格式来写：该类是被 xxx 方法构造出来的。用强行的人肉空格帮助Doxygen。所有类似的问题都可以以此类推。。。
我们说，Doxygen无法识别光秃秃的代码信息，这并不意味着代码结构对Doxygen来说不重要。Doxygen可以对各种语言书写的代码进行优化，比如你开启C++代码优化后，Doxygen会解析你写的C++代码，添加更多更具体的信息，并依照之间联系为你添加链接。这也就是说，Doxygen会产生真实的代码结构表示出来的东西，你在写注释的时候也应该按照严谨的代码结构去写。比如，你在某个类A的注释中写道：此类用到了 B 类中的方法。假设B这个类，在名字空间N1内，如果，你的A类同样也是在N1内，这个链接Doxygen会为你自动添加，但是，如果B这个类在名字空间 N2内，Doxygen会无视你的请求。你必须严格的写它的全名 N2::A，Doxygen才会欣然接受这个娃。。。
我在做的项目比较小，因此我利用Doxygen的ToDo-List和Bug列表对项目进行简单的管理。比如，有一个类你有一些后续的工作没有完成，你可以在其注释中加上@todo xxx，（这只是其中一种语法，不是唯一的规范...）Doxygen会将其链接添加到一个to do list中，并为该to do list生成一个页面，查看起来颇为方便。同样，Bug标记也是这么用这么看的，举一反三大家都会，我就不多磨叽了。。。
Doxygen中利用到很多第三方的基于编译的信息生成工具，辅助生成更为炫目的文档。比如，你可以在注释中嵌入符合tex标准的公式，Doxygen帮助你把这些显示到你的文档中来；你还可以为你的文档自动生成继承图，组合图，UML格式的图，等品种齐全的图，只要你把Graphviz装上，并打开相关参数即可。更漂亮的是，利用Graphviz的dot方法，你可以将符合其格式的画图指令写在注释中，场景图，架构图，流图，交互图，隔壁校长含泪跳楼图，只要你能用Graphviz画出，Doxygen都能给你用上，图例想改就改想变就变，幸福生活，不过尔尔。而关于Graphviz，g9老大已经推荐过了，再多的好话也就显得苍白。这东西无疑是好东西，方便的一塌糊涂，对于常年和代码打交道对直观之物缺失判断的程序员而言，这无疑是居家旅行杀人必备的水果刀。但要把水果刀玩的和关公大刀似的，是需要不俗功力的，像我这样三脚猫的功夫，就只能关注功能而无法挑战美观了。。。
其他的信息，比如author，date，group，之类的，我都会要求写注释的时候加上，举手之劳，可以方便很多后续可能出现的问题。每一个简单到无需注释的函数，也要加一个空的注释头，以便生成文档的时候，所有的方法都齐备；如果有需要，你可以修改配置文件的设置，把代码也绑定进文档，这样别人只要拿着文档一看，几乎就完全不用在添一份代码放在手上了。。。
把文档与代码绑定在一起，这是用Doxygen之类工具的一个好处，它至少可以产生两个方面的生产力。一方面，它可以帮助你构建结构良好的文档，生成真正可看好看的文档来；另一方面，它可以刺激你更新文档，把文档工具当作项目管理工具用起来。当然，如果文档就在你写的代码上面两行你都懒的看一眼，那么，啥工具也挽救不了了。用这类工具，必须要文档代码配合着写，配合着看，把它提升到和写单元测试一个习惯级别来，看一眼注释，写一段代码，然后测一测，改改过期注释，就像蘸酱卷饼吃黄瓜一样一气呵成，那么，Doxygen就可以今夜做梦也会笑了。。。
使用doxygen为C/C++程序生成中文文档（上）
按照约定的格式注释源代码，用工具处理注释过的源代码产生文档。通过这种方式产生文档至少有以下好处：
- 便于代码和文档保持同步。
- 可以对文档做版本管理。
很多编程语言都有类似的文档工具，例如：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生成文档，主要是两件事：
- 写一个配置文件（Doxyfile）。一般用Doxywizard生成后，再手工修改。
- 按照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 需要什么
完成本文的范例需要以下工具：
- Doxygen的最新版本，可以从Doxygen的网站下载。
- Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各种图形，例如类的继承关系图、合作图，头文件包含关系图等。可以从Graphviz的网站下载Graphviz的最新版本。Doxygen使用了Graphviz的布局引擎dot，所以在文档中将其称作dot。
- 为解决中文问题，需要使用Cygwin的iconv程序作编码转换。
- 为解决中文问题，需要一个命令行的查找替换工具。我选择了白杨创作的工具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编译，中文不能正确显示。解决这个问题的思路很简单：
- 将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”。