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就可以今夜做夢也會笑了。。。