appledoc 是一個命令行工具,能幫助 Objective-C 開發者從源代碼中特定格式的註釋裡提取內容,生成外觀接近 Apple 官方開發者文檔的 API 文檔。對於要對外交付 SDK 或維護大型項目的團隊來說,它能把「寫註釋」直接變成「出版文檔」。
安裝非常簡單,克隆倉庫後執行安裝腳本即可:
git clone git://github.com/tomaz/appledoc.git cd appledoc sudo sh install-appledoc.sh
腳本會把 appledoc 安裝到系統路徑下,之後就能在任意目錄直接調用 appledoc 命令。
打開終端,用 cd 進入項目所在文件夾,執行:
appledoc --output ./doc \
--project-name SD4iPhone \
--project-company "sammydress" \
--company-id "com.zyl910" \
.
參數含義逐項說明:
· --output ./doc:設置輸出目錄為 ./doc,生成的 HTML 文檔會放在這裡。
· --project-name SD4iPhone:設置項目名稱。
· --project-company "sammydress":設置公司名稱。
· --company-id "com.zyl910":設置公司標識,通常用於生成文檔中的相關鏈接與標識信息。
· .:最後這個點表示掃描當前目錄下的源碼。
命令執行完畢後,進入 ./doc 打開 index.html,就能看到一份帶側邊導航、類別索引和方法列表的完整文檔站點。
appledoc 依賴的是 Appledoc 風格的註釋標記,主要包括:
· /** ... */ 或 ///:文檔註釋的基本形式。
· @brief:一句話摘要。
· @param:參數說明。
· @return:返回值說明。
· @see / @warning / @note:交叉引用、警告與補充說明。
寫好註釋後重新執行一次命令,文檔就會自動更新。配合腳本或 Xcode 的 Build Phase,可以把文檔生成接入持續集成流程,做到代碼提交即文檔同步。
值得一提的是,appledoc 也能生成 install-docset 形式的文檔集,安裝後可以直接在 Xcode 的文檔窗口或 Dash 中離線查閱,日常開發體驗會好很多。