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控制，更优美的外观，更方便的索引方式，等等。因而自写了个工具软件，进行了字符集转换。（如哪位朋友须要，能够发邮件至 zhengshuxin@hexun.com 索取这个小软件，等本人将其作完善后再放在网上）。 　　字符集转码工做作完了，但另外一个问题又出现了，本人的函数库都是由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