小攻城師的戰場筆記

一個專案的生命很長，因此程式開發者之間常有需要交接程式碼的需求，免費的 Doxygen 與 GNU Global 可以幫助我們更瞭解接手的程式碼概觀。

Ubuntu 中要安裝 Doxygen，可以直接從應用程式中勾選 doxygen 與 graphviz，後者可以協助 doxygen 產生 UML圖、流程圖等。其他的 Linux distribution 則視實際情況下指令或勾選安裝 doxygen 與 graphviz 套件。

以 nmap-4.65 為例，當我們想要產生其相關文件，可以先進入這個程式專案的目錄，產生其 doxygen config 檔。（角括號內的文字表示依實際情況填寫）
　　$ cd <nmap_path>
　　$ doxygen -g <config.conf>

產生 config 檔後，可視自己需求修改這個設定檔內容（也可以全不修改），之後即可執行這個設定檔產生文件。
　　$ doxygen <config.conf>

產生出的文件有 HTML 與 LATEX 兩種格式，若程式碼已依照 doxygen 的規範撰寫，就會產生出我們所需要的說明文件來。

由於有一些 config 檔的預設設定是不太符合一般需求的，因此通常需要先編輯 config 檔，例如將 RECURSIVE 的值設為 YES，才會搜尋子目錄程式碼，通常我們也會希望可以一口氣得到程式碼全觀的說明文件。

Doxygen 的註解格式支援兩種格式，一種是 Java style、一種是 QT style，一般都是使用前者，格式如下：

/**
 * ... 這裡寫注解 ...
 */

若編輯器使用 VIM，會以星號為基準自動幫忙對齊排好。



/** \brief 這裡寫簡要註解.
 *         簡要注解可以繼續寫在這裡，不要有空行就好。
 *
 *  這裡寫詳細的註解，上面要空一行。
 */

以上範例中，可以寫成 @brief 也可以寫成 \brief。

如果設定檔中 JAVA_AUTOBRIEF = YES ，則簡要註解和詳細註解可以不用空一行，程式會自動將第一個句點後的句子視為詳細註解區塊。



變數的說明可以撰寫如下：

void test(void){
    int a = 0;   /**< 可以撰寫多行註解的寫法*/
    int b = 0;  ///< 用來撰寫單行註解的寫法
}



完整一點的說明可以撰寫如下：

/** @brief
 *  @param p1 可以用來說明第一個回傳值的意義
 *  @param p2 可以用來說明第二個回傳值的意義
 * @return 可以用來說明該函式 return 的意義
 */

int test (int p1, int p2) {
    int a = 0;
    int b = 1;
}


trace code 時可以使用 Doxygen 產生的文件、搭配 GNU Global　追蹤，可以使得追蹤工程事半功倍。