Just a Computer Graphics Studio & My Life

[iOS] AppleDoc 文件生成工具

程式設計師軟體工程師最不想做的事情之一,就是根據程式碼來寫成文件,而這文件盡可能要讓不會寫程式的人也能看得懂,這就非常不容易了!而要面對的現實是,我們沒有太多時間去把程式碼轉換成一般話語,好在專案中我們或多或少寫有註解,若能直接將註解轉換成一般話語,那麼就能節省許多時間了!

以下是AppleDoc把code轉換成文件的結果,是不是跟Apple官方的文件很像呢?所以才叫做AppleDoc囉~

AppleDoc1 AppleDoc2

這麼棒的文件生成工具,之前就想要拿來使用,可是一直沒時間去嘗試,不然就是遇到編譯上的問題,如:

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 – 錯誤說明

AppleDoc Xcode

參考例子:


/**
 Theme: AppleDoc
 IDE: Xcode 5
 Language: Objective C
 Date: 103/06/13
 Author: HappyMan
 Blog: http://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 :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;

/**
 * @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顯示不出來,複製使用時請自行轉換。

執行後沒有出現任何錯誤,表示文件已成功生成到專案目錄中,去打開之後就如文章最上方的圖!其實有錯誤或警告訊息,文件也會生成。

AppleDoc

養成良好的寫註解習慣,從此可用在專案交接客戶需要的時候囉~

參考:

About these ads

發表留言

在下方填入你的資料或按右方圖示以社群網站登入:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / 變更 )

Twitter picture

You are commenting using your Twitter account. Log Out / 變更 )

Facebook照片

You are commenting using your Facebook account. Log Out / 變更 )

Google+ photo

You are commenting using your Google+ account. Log Out / 變更 )

連結到 %s

標籤雲

關注

Get every new post delivered to your Inbox.

Join 94 other followers

%d bloggers like this: