Xcode 內建 HeaderDoc 實戰：自動生成程式碼註解與開發文件

為什麼在 macOS 上選擇 HeaderDoc 而非 Doxygen？

許多開發者習慣使用 Doxygen 產生文件，但在 macOS 平台上，Doxygen 預設輸出的 CHM 格式並不理想。CHM 是微軟專有格式，在 Apple 系統上相容性差，常出現亂碼問題。相比之下，HTML、PDF 或 RTF 格式在 macOS 上的通用性與穩定性都高得多。

其實 Xcode 早就內建了強大的文件生成工具——HeaderDoc。它是開源專案，深度整合在 Xcode 中，不僅支援自訂註解格式與解析邏輯，還能透過腳本擴充功能，極大提升文件維護效率。

HeaderDoc 核心功能與操作流程

一鍵插入標準化註解

使用方式直覺：選取需加註的程式碼區塊（函數宣告建議在 +/- 號與函數名之間保留一個空格），再從選單選擇對應的註解類型即可自動產生模板。支援 Class、Protocol、Category 等所有 Objective-C 構造，連 Property 這類預設無模板的類型，也能透過撰寫腳本自行補齊，並可綁定自訂快捷鍵加速操作。

從原始碼生成專業級 HTML 文件

完成註解後，只需兩條終端指令即可產出類似 Apple 官方 Cocoa API 風格的文件：

headerdoc2html -o outputDir ExampleHeaders
gatherheaderdoc outputDir TOC.html

• outputDir：輸出 HTML 的資料夾名稱
• ExampleHeaders：存放標頭檔的目錄
• TOC.html：生成的目錄檔名（可自訂）

執行完成後，打開 TOC.html 即可瀏覽結構完整、樣式專業的 API 文件。

進階應用與官方資源

HeaderDoc 還支援 Man Page Generation Language (MPGL) 方言、自訂輸出樣板等進階功能。完整用法請參考 Apple 官方《HeaderDoc User Guide》，掌握更多客製化技巧，打造專屬團隊的文件規範。