程式設計師或軟體工程師最不想做的事情之一，就是根據程式碼來寫成文件，而這文件盡可能要讓不會寫程式的人也能看得懂，這就非常不容易了！而要面對的現實是，我們沒有太多時間去把程式碼轉換成一般話語，好在專案中我們或多或少寫有註解，若能直接將註解轉換成一般話語，那麼就能節省許多時間了！
以下是AppleDoc把code轉換成文件的結果，是不是跟Apple官方的文件很像呢？所以才叫做AppleDoc囉～
這麼棒的文件生成工具，之前就想要拿來使用，可是一直沒時間去嘗試，不然就是遇到編譯上的問題，如：
error: garbage collection is no longer supported
只好找作者已經編譯好的程式來安裝！AppleDoc下載點。
下載appledoc.zip，解壓縮appledoc.zip。開啟終端機進入appledoc，安裝的時候輸入：
cp appledoc /usr/local/bin
cp -Rf Templates/ ~/.appledoc
必要時後面兩個指令前面要加sudo，完成後可輸入指令：
appledoc –help
若有出現指令集說明，表示安裝成功！
接下來就是在.h中寫註解，註解的幾個關鍵字與規則：
@brief (建議必寫) – 大綱簡易說明
@param (建議必寫) – 參數說明
@return (建議必寫) – 回傳說明
@exception – 例外說明
@see – 參考
@warning – 警告說明
@bug – 錯誤說明
參考例子：
/** Theme: AppleDoc IDE: Xcode 5 Language: Objective C Date: 103/06/13 Author: HappyMan Blog: https://cg2010studio.wordpress.com/ */ // // HTViewController.h // HappyTest3 // // Created by Jason on 2014/6/12. // Copyright (c) 2014年 HappyMan's Studio. All rights reserved. // #import <UIKit/UIKit.h> /**這是測試view controller 解釋你如何使用AppleDoc 😀 */ @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; /** * @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
最後在專案目錄底下，輸入指令：
appledoc -o ./doc –project-name HappyTest3 –project-company “HappyMan’s Studio" –company-id Jason –no-warn-undocumented-object –keep-intermediate-files .
需注意「2個-號」與「1個-號」的差異喔！
即可在該目錄底下看到doc目錄了，其中規則：
appledoc –output [輸出目錄] –project-name [專案名稱] –project-company [公司名稱] –company-id [公司app id] –no-warn-undocumented-object –keep-intermediate-files [專案目錄]
需注意關鍵字（如output）前面是2個-號，由於WordPress顯示不出來，複製使用時請自行轉換。
執行後沒有出現任何錯誤，表示文件已成功生成到專案目錄中，去打開之後就如文章最上方的圖！其實有錯誤或警告訊息，文件也會生成。
養成良好的寫註解習慣，從此可用在專案交接或客戶需要的時候囉～
參考：
逍遙文工作室 
Comments on: "[iOS] AppleDoc 文件生成工具" (2)
[…] 最近同事需要匯出開發文件，我在寶寶App也因應客戶需求，以Apple Doc的格式釋出，多虧一年半前我有記錄下來，直接貼連結給同事參考，節省不少學習時間。 […]
讚讚
[…] 最近同事需要匯出開發文件，我在寶寶App也因應客戶需求，以Apple Doc的格式釋出，多虧一年半前我有記錄下來，直接貼連結給同事參考，節省不少學習時間。 […]
讚讚