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”。