Doxygen 的使用教學

Doxygen 是一個程式的文件產生工具，可將程式中的特定註解轉換成為說明文件。通常我們在寫程式時，或多或少都會寫上註解，但是對於其他人而言，要直接探索程式裡的 註解，與打撈鐵達尼號同樣的辛苦。大部分有用的註解都是屬於針對函式，類別等等的說明。所以，如果能依據程式本身的結構，將註解經過處理重新整理成為一個 純粹的參考手冊，對於後面利用您的程式碼的人而言將會減少許多的負擔。不過，反過來說，整理文件的工作對於您來說，就是沈重的負擔。

一個好的程式設計師，在寫程式時，都會在適當的地方加上合適的註解。如果，能夠在撰寫註解時，稍微符合某種格式，接著就可以透過一個工具程式依據程式結構及您的註解產生出漂亮的文件。這將令許多工作繁重的程式設計師有時間多喝幾杯咖啡。

Doxygen 就是這樣的一個工具。在您寫註解時，稍微按照一些它所制訂的規則。接著，他就可以幫您產生出漂亮的文件了。因此，Doxygen 的使用可分為兩大部分。首先是特定格式的註解撰寫，第二便是利用Doxygen的工具來產生文件。

本篇以 解析 plog ( .php 檔)為範例做一步一步的解說，感謝 Mark 在 msn 上的耐心教學。

執行 doxygen

假設你的 plog source 放在 d:/plog

1. Project Name 打上 plog
2. Project Number 打上 0.31
3. 假設你的 document 輸出到 d:/plog/docs
4. create sub_dirs 不要勾，它有一點 bug
   (基本上，勾了，到時輸出會自動幫你分 folder，但最近的版本有) bug
5. output， lang 選 中文 ( Chinese_Traditiona)

切換 tab 到 build

基本上這是要選擇到時要輸出的 document 詳細程度
(我是全選啦！除了幾個 hide 開頭的，所以等一下你會看到很詳細的資料)

切換到 Input

1. 選擇 d:/plog 回我們的 input 目錄
2. 下面的 file pattern，是指定我們只分析 .php 還是 .html 還是 .c
   (基本上我都不選，反正先全部都分析)
3. 再來 recursive 一定要打勾
   (代表下面的每一個子目錄都要分析)

切換到 source browse

之前只是指定要產生 document, 但 doxygen 允許你將 doc & source 放在一起, 比較好看, 我的習慣是將他全部 include, 所以產生的文件比較大, 但好處是不用再去翻 source code.

切換到 index

• 決定要不要索引，你可以打勾
• 另外索引要顯示成幾欄, 基本上 3 欄就很大了, 5 欄會超出螢幕很多.

切換到 HTML

要選擇輸出的文件格式, 基本上只要 HTML , 看一看有什麼要改的, 原則上不動就可以了.

切換到 Latex

把latex 取消

跳到 dot

這個 tab, doxygen 會產生很詳細的 class digram & activity diagram, 但是要有一些 library support, 如果沒裝 library, 他只會產生 class diagram, 所以這一頁看看就好, 也不用去動他.

以上設定完成後, 按一下 save, 把現在的設定存下來.

然後按那個齒輪, 就會幫你產生文件了.

參考文件：
1. 簡介 doxygen
2. 與 Mark msn 上的交流記錄。

相關連結：
1. Doxygen 的使用方法，本篇以 解析 plog ( .php 檔)為範例做一步一步的解說