1. AppleDoc 使用教學
將程式碼註解轉為文件
2014/06/13
HappyMan

2. 目的
• 工程師最不想要做的事情之一，就是將程
式碼內容邏輯寫成文件
• 不過我們總養成習慣會寫註解，幫助未來
開發維護的自己或他人能快速回顧
• 於是我們使用工具將這些註解給轉成技術
文件
• 做到這兒，我們算是仁至義盡啦：Ｐ～

3. 遇到瓶頸
• 遇到編譯上的問題，如：
– error: garbage collection is no longer supported
• 只好找作者已經編譯好的程式來安裝！
• AppleDoc下載點：
– https://github.com/tomaz/appledoc/releas
es/tag/v2.2-963

4. 安裝流程
• 下載appledoc.zip，解壓縮appledoc.zip。
開啟終端機進入appledoc，安裝的時候輸
入：
– cp appledoc /usr/local/bin
– cp -Rf Templates/ ~/.appledoc
• 必要時後面兩個指令前面要加sudo，完成
後可輸入指令：
– appledoc –help
• 若有出現指令集說明，表示安裝成功！

5. 在.h檔中寫註解
• 註解的關鍵字與規則：
– @brief (建議必寫) -- 大綱簡易說明
– @param (建議必寫) -- 參數說明
– @return (建議必寫) -- 回傳說明
– @exception -- 例外說明
– @see -- 參考
– @warning -- 警告說明
– @bug -- 錯誤說明

6. 在程式碼中加入註解

7. 參考例子
• #import <UIKit/UIKit.h>
• /**這是測試view controller
•
• 解釋你如何使用AppleDoc :D
•
• */
• @interface HTViewController : UIViewController
• /**
• * @brief This a full version of comment description.
• * @param value The vale of integer.
• * @return Return a result Object.
• * @exception NSException Put exception message here.
• * @see beHappy
• * @see doMyBestWithValue1:andValue2:
• * @warning You can write some message about some warning things.
• * @bug If this method has any bug, please write here.
• */
• - (BOOL)doYourBest:(int)value;

8. 承上
• /**
• * @brief doMyBest
• * @param value1 The vale of integer
• * @param value2 The vale of integer
• * @return Return BOOL value.
• */
• - (BOOL)doMyBestWithValue1:(int)value1 andValue2:(int)value2;
• /**
• * @brief beHappy
• * @return Return BOOL value.
• */
• - (BOOL)beHappy;
• @end

9. 輸出文件
• 從終端機進入專案母目錄
• 範例指令
– appledoc -o ./doc --project-name HappyTest3 --
project-company “HappyMan" --company-id
Jason --no-warn-undocumented-object --keep-
intermediate-files .
• 格式
– appledoc --output [輸出目錄] --project-name [專案
名稱] --project-company [公司名稱] --company-id
[公司app id] --no-warn-undocumented-object --
keep-intermediate-files [專案目錄]

10. 輸出路徑

11. 輸出成果

12. 輸出成果（續）

13. 參考
• 在 iOS 專案中寫註解與文件生成的技巧
• Amazing Apple-like Documentation
• 使用Objective-C語言的文檔生成工具：
appledoc
• Objective-C規範註釋心得——同時兼容
appledoc（docset、html）與doxygen
（html、pdf）的文檔生成
• GitHub - appledoc