doxygen 帮助手册生成使用心得

   程序员在写程序时经常需要在源程序里写一些注释，以备自己或他人以后再看时方便理解，程序的注释格式有多种，而 JavaDoc 的注释格式现在似乎更为流行，不仅 Java 语言在使用它，其它语言如：Javascript, C/C++, Php 等流程语言也越来多地采用 JavaDoc 注释方式。有了注释格式，当然需要有一个注释格式分析工具能够对注释内容进行清晰。Doxygen 便是这个方便的注释分析工具，它可以非常方便地将源程序里的按 JavaDoc 格式注释的内容提取出来，形成各种需要的帮助手册（如：Html格式，Man 格式，RTF格式等），因为doxygen是如此好用，以至于很多开源的软件都在用它，象比较著名的ACE项目的接口帮助手册就是由doxygen生成的，当然还有更多的使用doxygen工具的项目（你可以在　 http://www.stack.nl/~dimitri/doxygen/projects.html　上发现如此多的软件项目在使用它）。
　　因为本人开发了一套基于C语言的支持 Unix/Windows 的网络通信及服务器框架的函数库（名叫：ACL，http://acl.sourceforge.net/），有一些朋友和同事在用它，大家在使用ACL 库时既感到了它的强大、高效，同时又在不断地抱怨接口文档的缺乏及查找的不方便，本人对此也深感痛觉，于是痛下决心，经过相当一段时间的努力，终于在 ACL的所有对外头文件中添加了 JavaDoc 格式注释，于是非常高兴地从 doxygen 的主站(www.doxygen.org)下载了win32平台的安装程序（版本为：1.5.8),然后按使用说明（其实非常简单）将ACL的头文件生成了HTML格式帮助文档，但可惜的是，打开这些HTML页面时却发现是一大堆乱码，原因是doxygen生成的文档默认采用 utf-8编码，而我的文档注释采用的是GB2312的编码，于是修改 doxyen配置，将 INPUT_ENCODING 修改成 GB2312, 将 DOXYFILE_ENCODING 设置成　UTF-8，然后再生成时 doxygen 在分析头文件时报错说无法进行编码转换，既然 doxygen 无法进行编码转换，那只好自己写个转换器了，于是亲手写了个WINDOWS下的编码转换器，将GB2312直接转换成UTF-8, 再由 doxygen 从 UTF-8 的源文件生成UTF-8格式的HTML文档。
　　至于将ACL的头文件由GB2312转换成UTF-8的过程也是曲折的，开始本人用的转换器的库是 iconv.lib, 转换完发现文件的内容总是不全，不知是不是该库本身的问题还是本人使用不当造成的，于是一不做，二不休，编码转换库也用源代码进行编译运行（好在本人曾经做过邮件系统，在字符集编码方面不乏源代码，随手粘来一段代码贴在程序里），OK，转换成功，所有的头文件的中文注释均由原来的GB2312转换成 UTF-8了。当然在用 doxygen 生成HTML文档时，别忘了将 INPUT_ENCODING 设置成空，意思是说无需 doxygen进行字符集编码转换（通过跟踪 doxygen 的源代码，发现只要将 INPUT_ENCODING 设置为空，则它不会对注释文档进行字符集编码转换－－－这样也好，免得它总是转错，其实它的源程序里是用 iconv.lib 进行转换的，不知转换不成功的原因是否也与 iconv.lib 有关）。
　　其实， doxygen 在对中文的字符集转换时所出现的问题在以前的旧的版本并未出现过（那是因为原来还比较土，根本就不进行转换，哈，看来少做有时也有好处，至少还能用），只是在一些比较新的版本（包括当前的1.5.8）都存在这类问题（将中文由GB2312转换成UTF-8时会失败），本人本想采用旧的 doxygen 生成HTML帮助文档，但最终经不住新版的诱惑：更好的CSS控制，更优美的外观，更方便的索引方式，等等。于是自写了个工具软件，进行了字符集转换。（如哪位朋友需要，可以发邮件至 [e-mail] 索取这个小软件，等本人将其做完善后再放在网上）。
　　字符集转码工作做完了，但另一个问题又出现了，本人的函数库都是由C语言完成的，因为没有象C＋＋式的命名空间，所以为了防止与他人的代码冲突，所有的函数名前都加了前缀 acl_, 所有的结构前都加了前缀 ACL_, 这样问题就来了，本来用 doxygen 生成的HTML文档是有按字母索引、排序功能的，但因为我的函数前都有 acl_ 字样，这样所有的函数都堆在一个 a 开头的排序里，于是更加郁闷。怎么办？得，还得自己写工具进行转换，第一步：先用工具将所有中文注释的头文件转换成UTF-8格式的；第二步：将函数名前的前缀 acl_ 转换成后缀 _acl(如：原来的一个函数 acl_vstream_gets 前缀变后缀后应为 vstream_gets_acl, 结构：ACL_VSTREAM 则变为 VSTREAM_ACL)；第三步：用 doxygen 将第二步生成的头文件生成HTML文档；第四步：用自写工具将函数名、结构类型中的字符串由后缀转前缀（如：vstream_gets_acl->acl_vstream_gets, VSTREAM_ACL->ACL_VSTREAM)，这样就一切OK了，最终生成的HTML帮助文档都是UTF-8格式的，可以按字母序进行排列的函数接口帮助文档了。（题外话：象顶顶大名的 glib 库，虽然文档注释格式是 JavaDoc　格式的，但它并没有使用 doxygen 工具生成帮助手册，估计原因可能和我一样，它是一个C库，为了避免与别人冲突，都有前缀g-, 如果用 doxygen就无法按首字母进行排序查看，所以 glib 的开发小组自己开发文档生成工具）。
　　您可以参看 http://acl.sourceforge.net/ 看一下ACL库的在线帮助文档。
　　此外，此文档还有一个小小的缺陷，那就是在搜索栏里，如果你要查acl_vstream_xxx 类的函数时，需要输入 vstream_xxx, 而不是 acl_vstream_xxx, 并且查得的结果也是 vstream_xxx_acl 格式（当你点其链接时的结果是正确的），主要是因为 doxgen 生成ACL帮助文档的全文索引时的源文档都是 vstream_xxx_acl －－－即以 _acl/_ACL 为后缀的，目前主要是对其索引文档还不太熟悉，得有时间再完善这点吧。当然，希望 doxygen 能将我所遇到的问题都解决，这样也就不再需要那个转换工具了。
个人微博：http://weibo.com/zsxxsz