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