您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 程式開發 >> iOS 開發綜合

appledoc:為 Objective-C 生成蘋果風格的 API 文檔

編輯:iOS 開發綜合

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 中離線查閱,日常開發體驗會好很多。

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved