Doxygen 實戰：從 C/C++ 專案自動生成專業文件

為什麼需要 Doxygen

維護大型 C/C++ 遺留系統時，理解類別階層、全域變數、函式呼叫關係極為耗時。Doxygen 能從原始碼自動萃取結構資訊，生成 HTML、LaTeX、RTF、CHM 等多種格式文件，並支援 C/C++、Java、Python、PHP 等語言。

安裝與建置

從原始碼編譯 (Linux/Unix)

svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn
cd doxygen-svn
./configure --prefix=/home/user1/bin
make && make install

指定 --prefix 避免需 root 權限寫入 /usr。

三步驟生成文件

1. 生成設定檔：doxygen -g 產生 Doxyfile。
2. 編輯關鍵標籤（Doxyfile 採 TAG = VALUE 格式）：
   • OUTPUT_DIRECTORY：輸出目錄（不存在會自動建立）。
   • INPUT：原始碼目錄列表，支援遞迴 (RECURSIVE = YES)。
   • FILE_PATTERNS：檔案副檔名過濾，預設涵蓋 .c/.cpp/.h 等。
   • EXTRACT_ALL、EXTRACT_PRIVATE、EXTRACT_STATIC：設為 YES 以提取無註解、私有、靜態成員。
3. 執行：doxygen Doxyfile，輸出目錄下將產生 html/ 與 latex/。

進階預處理控制

Doxygen 預設僅處理條件編譯 (#if)，不展開巨集。啟用完整預處理：

ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES

僅展開特定巨集：

EXPAND_ONLY_PREDEF = YES
EXPAND_AS_DEFINED = CONTAINER

預先定義巨集值（等同編譯器 -D）：

PREDEFINED = USE_ROPE= ALLOW_RANDOM_ACCESS=1

排除特定檔案/目錄

EXCLUDE = /home/user1/src_root/examples /home/user1/src_root/test/memoryleaks

圖表生成 (需 Graphviz dot)

HAVE_DOT = YES
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES

可生成繼承圖、協作圖，輔助理解類別關係。

原始碼標註風格

Doxygen 支援 JavaDoc (/** ... */) 與 Qt (/*! ... */) 風格。常用指令：

• \file、\class、\fn、\var、\def：標識程式元素。
• \brief：簡短說明。
• \param、\return、\warning：函式參數、回傳、警告。

/** \fn bool check_for_io_errors(FILE* fp)
 *  \brief 檢查檔案是否損毀
 *  \param fp 已開啟檔案指標
 *  \warning 非執行緒安全!
 */
bool check_for_io_errors(FILE* fp);

輸出格式選擇

在 Doxyfile 設定：

• GENERATE_HTML = YES (預設)
• GENERATE_LATEX = YES (預設，可生成 PDF)
• GENERATE_RTF = YES、RTF_HYPERLINKS = YES
• GENERATE_MAN = YES (Unix man page)
• GENERATE_HTMLHELP = YES (產生 .hhp，再用 HTML Help Workshop 生成 .chm)
• GENERATE_XML = YES (實驗性)