當專案規模越來越大,程式碼註解若能被轉成可閱讀的文件,對團隊協作與交接都很有幫助。AppleDoc 就能依據原始碼中的註解,生成類似 Apple 官方風格的文件網站。
完成後,你可以得到類似官方文件的頁面結構,包含總目錄、類別展開、屬性與方法說明等。
AppleDoc 只支援部分註解格式,例如 ///、/** ... */、/*! ... */。它不會把一般註解全部視為文件內容,因此若希望某段說明被納入,建議使用支援的格式。
它也支援 Markdown 風格語法,例如標題、清單、表格、連結與程式碼區塊,讓文件表達更靈活。
可以透過原始碼安裝:
git clone git://github.com/tomaz/appledoc.git cd ./appledoc sudo sh install-appledoc.sh
安裝完成後,可以用 appledoc --version 確認是否可用。
進入專案目錄後,執行:
appledoc --project-name 你的專案名稱 --project-company 你的公司名稱 ./
完成後,專案資料夾中會出現文件產物。
若想讓文件生成更自動化,可以把 AppleDoc 加入 Xcode 的 Build Phase,透過 Run Script 執行。
在腳本中設定公司名稱、公司 ID、輸出位置與文件平台後,就可以在編譯時一併產出文件。
設定完成後,選擇對應 target 編譯即可。若第一次執行失敗,可以嘗試重新整理或重啟 Xcode 後再編譯。
整體來說,AppleDoc 最大的價值在於把註解轉成可閱讀的知識庫。對日常開發而言,註解仍然是最直接的說明;但若要產出給團隊、主管或外部合作夥伴的文件,這類工具就非常合適。