在 iOS 專案中寫註解與文件生成的技巧

Document

寫 Code 最害怕的就是過了兩星期後你已經忘記你曾經寫過什麼,或是這段程式在代表什麼,所以註解與文件就相對顯得重要了,但是有寫過程式的工程師應該沒有一個喜歡寫文件的,那是一個又麻煩有沒有創造力的工作,所以這次我們要示範如何透過  appledoc 這個工具來自動產生文件,簡單的來說就是你寫註解他寫文件啦。

要能讓工具能自動產生文件出來,就必須要有標準的註解寫法規則,我幫大家整理一些簡單的規則給大家,相信你只要遵守這幾個簡單的規則,就能產生精美且實用的文件。

註解的幾個關鍵字與規則:
@brief (建議必寫)  – 大綱簡易說明
@param <name> <description> (建議必寫) – 參數說明
@return <description> (建議必寫) – 回傳說明
@exception <name> <description> – 例外說明
@see <name> – 參考
@warning <text> – 警告說明
@bug <text> – 錯誤說明

這邊我們示範幾個例子給大家看,你可以稍微斟酌一下你的文件要提供到多細的說明。

單行簡易註解

/// This a simple method with out return any result.
- (void)simpleMethod;

多行簡易註解

/**
 * @brief This a complex method with two parameters.
 * More detail descriptions can write below "@" sign...
 *
 * @param value1 The value of integer.
 * More detail description for value1...
 *
 * @param value2 The value of CGFloat.
 * More detail description for value2...
 *
 * @return Retrun a result Object.
 * More detail descroption for return value...
 */
- (NSObject *)complexMethodWithParam1:(int)value1 param2:(CGFloat)value2;

多行完整註解

/**
 * @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 simpleMethod
 * @see complexMethodWithParam1:param2:
 *
 * @warning You can write some message about some warning things.
 *
 * @bug If this method has any bug, please write here.
 */
- (NSObject *)DetailComplexMethodWithParam:(int)value;

恭喜你,這樣就能將註解的標準規則建立了,應該對身為程式設計師的你不會太難,接下來就教你如何安裝 appledoc 這個工具。

首先先到 Terminal 終端機中敲入以下指令:

git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh

若是你有遇到 could not stat active Xcode path ‘/Volumes/Xcode/Xcode.app/Contents/Developer’. (No such file or directory) 這個錯誤訊息,那你可以嘗試執行這段,之後再執行 install:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

都安裝好後就可以執行這段指令來生成文件了:

appledoc --output [輸出目錄] --project-name [專案名稱] --project-company [公司名稱] --company-id [公司app id] --no-warn-undocumented-object --keep-intermediate-files [專案目錄]
例如: appledoc --output ~/Desktop/doc --project-name "appledocDemo" --project-company "Anistar Studio" --company-id "com.riaproject" --no-warn-undocumented-object --keep-intermediate-files ~/Documents/iOS_Project/AppleDocDemo/

 

執行完後你就能得到一個 HTML 的文件,如下圖所示

html docset

除此之外會自動的安裝在  Xcode 中的文件,你可以在 Xcode 中隨意地調閱:

docsetxcode docset
是不是很棒很方便呢?希望這可以讓你有點喜歡上在寫程式的同時加上註解。

本篇發表於 Objective C 與標籤於 anistar固定網址書籤。
本文引用:
文章內容為ANISTAR BLOG所有,引用分享請以鏈結形式註明出處與原始作者。

關於 anistar

現任:台灣區 Yahoo! 專長: Objective C、iOS SDK、Android SDK、Flex 4、RIA、ActrionScript 3、HTML5、CSS3、JQuery、JQuery Mobile、C++、PHP、MySQL...等整合運用。 著作:《Run!PC雜誌》專欄作家、《CADesigner雜誌》專欄作家、《Flash CS3 Professional ActionScript 3.0 打造互動設計力與美》、《新一代互動體驗Flex+AIR程式開發》。 認證:Macromedia Certified Instructor in ColdFusion    Adobe Certified Expert in Photoshop    Adobe Certified Instructor in Flex

發表迴響

你的電子郵件位址並不會被公開。 必要欄位標記為 *