Xcode4自動生成註釋和開發文件
阿新 • • 發佈：2019-02-06
在寫程式碼的時候，如果按照一定的規範在標頭檔案裡寫上註釋的話，
就可以利用Xcode的文件自動輸出功能生成一份完整的HTML專案文件。
生成的格式和Apple Developer網站上的API文件幾乎是一樣的。
我們來看看如何利用Xcode生成專案文件。
步驟:
1. 在XCode裡點選Project,然後點Add Target給專案新增一個TARGET
2. 在新增Target的彈出對話方塊裡，選擇Aggregate,點選Next,輸入一個你喜歡的名字,點選Finish
3. 你會發現TARGETS下面多了一個專案，點選它，然後在右邊點選BuildPhases標籤，然後點選Add Build Phase並選擇Add Run Script
4. Run Script新增成功後，點選它的下拉選單，把以下程式碼拷貝到程式碼對話方塊裡。
# shell script goes here
mkdir -p headerDoc
find ./HelloPhoneGap/Classes -name \*.h -print | xargs headerdoc2html -o headerDoc
gatherheaderdoc headerDoc
exit 0
注意：程式碼裡的./HelloPhoneGap/Classes是你的類檔案的儲存的路徑，請根據各自情況修改。
5. 在XCode左上角的Scheme裡選定剛才生成的Target,然後點Run。
執行以後，在你的專案資料夾裡，就會生成一個文件檔案夾了。
這些自動生成的文件都是根據你在原始碼裡寫的註釋生成的。
下面就詳細介紹一下各種能自動生成文件的註釋
■ header : 標頭檔案基本資訊。這個用在每個原始碼檔案的標頭檔案的最開頭。
例如:
/*!
@header 這裡的資訊應該與該原始碼檔案的名字一致
@abstract 關於這個原始碼檔案的一些基本描述
@author Kevin Wu (作者資訊)
@version 1.00 2012/01/20 Creation (此文件的版本資訊)
*/
■ class: 類資訊。此註釋用在類宣告的開頭。
例如:
/*!
@class
@abstract 這裡可以寫關於這個類的一些描述。
*/
@interface MyClass : NSObject {
}
■ property: property的相關注釋。
/*!
@property
@abstract 這裡可以寫關於這個Property的一些基本描述。
*/
@property (nonatomic,readonly) NSString *helloDocText_;
■ method: 函式(方法)的相關注釋。
/*!
@method
@abstract 這裡可以寫一些關於這個方法的一些簡要描述
@discussion 這裡可以具體寫寫這個方法如何使用，注意點之類的。如果你是設計一個抽象類或者一個
共通類給給其他類繼承的話，建議在這裡具體描述一下怎樣使用這個方法。
@param text 文字 (這裡把這個方法需要的引數列出來)
@param error 錯誤參照
@result 返回結果
*/
- (BOOL)showText:(NSString *)text
error:(NSError **)error;
■ enum: enum的相關注釋。
/*!
@enum
@abstract 關於這個enum的一些基本資訊
@constant HelloDocEnumDocDemoTagNumberPopupView PopupView的Tag
@constant HelloDocEnumDocDemoTagNumberOKButton OK按鈕的Tag
*/
typedef enum HelloDocEnumDocDemo_{
HelloDocEnumDocDemoTagNumberPopupView = 100,
HelloDocEnumDocDemoTagNumberOKButton,
}HelloDocEnumDocDemo;
■ category: category的相關注釋。
/*!
@category
@abstract NSString的Category
*/
@interface KevinNSString (NSString)
■ protocol: protocol的相關注釋
/*!
@protocol
@abstract 這個HelloDoc類的一個protocol
@discussion 具體描述資訊可以寫在這裡
*/
@protocol HelloDocDelegate ＜NSObject＞
以上列舉的標準註釋也許並不完善。
具體請參考蘋果的developer網站的API文件。
以上列舉的標準註釋全都在下面的標頭檔案裡，僅供參考。
HelloDoc.h
就可以利用Xcode的文件自動輸出功能生成一份完整的HTML專案文件。
生成的格式和Apple Developer網站上的API文件幾乎是一樣的。
我們來看看如何利用Xcode生成專案文件。
步驟:
1. 在XCode裡點選Project,然後點Add Target給專案新增一個TARGET
2. 在新增Target的彈出對話方塊裡，選擇Aggregate,點選Next,輸入一個你喜歡的名字,點選Finish
3. 你會發現TARGETS下面多了一個專案，點選它，然後在右邊點選BuildPhases標籤，然後點選Add Build Phase並選擇Add Run Script
4. Run Script新增成功後，點選它的下拉選單，把以下程式碼拷貝到程式碼對話方塊裡。
# shell script goes here
mkdir -p headerDoc
find ./HelloPhoneGap/Classes -name \*.h -print | xargs headerdoc2html -o headerDoc
gatherheaderdoc headerDoc
exit 0
注意：程式碼裡的./HelloPhoneGap/Classes是你的類檔案的儲存的路徑，請根據各自情況修改。
5. 在XCode左上角的Scheme裡選定剛才生成的Target,然後點Run。
執行以後，在你的專案資料夾裡，就會生成一個文件檔案夾了。
這些自動生成的文件都是根據你在原始碼裡寫的註釋生成的。
下面就詳細介紹一下各種能自動生成文件的註釋
■ header : 標頭檔案基本資訊。這個用在每個原始碼檔案的標頭檔案的最開頭。
例如:
/*!
@header 這裡的資訊應該與該原始碼檔案的名字一致
@abstract 關於這個原始碼檔案的一些基本描述
@author Kevin Wu (作者資訊)
@version 1.00 2012/01/20 Creation (此文件的版本資訊)
*/
■ class: 類資訊。此註釋用在類宣告的開頭。
例如:
/*!
@class
@abstract 這裡可以寫關於這個類的一些描述。
*/
@interface MyClass : NSObject {
}
■ property: property的相關注釋。
/*!
@property
@abstract 這裡可以寫關於這個Property的一些基本描述。
*/
@property (nonatomic,readonly) NSString *helloDocText_;
■ method: 函式(方法)的相關注釋。
/*!
@method
@abstract 這裡可以寫一些關於這個方法的一些簡要描述
@discussion 這裡可以具體寫寫這個方法如何使用，注意點之類的。如果你是設計一個抽象類或者一個
共通類給給其他類繼承的話，建議在這裡具體描述一下怎樣使用這個方法。
@param text 文字 (這裡把這個方法需要的引數列出來)
@param error 錯誤參照
@result 返回結果
*/
- (BOOL)showText:(NSString *)text
error:(NSError **)error;
■ enum: enum的相關注釋。
/*!
@enum
@abstract 關於這個enum的一些基本資訊
@constant HelloDocEnumDocDemoTagNumberPopupView PopupView的Tag
@constant HelloDocEnumDocDemoTagNumberOKButton OK按鈕的Tag
*/
typedef enum HelloDocEnumDocDemo_{
HelloDocEnumDocDemoTagNumberPopupView = 100,
HelloDocEnumDocDemoTagNumberOKButton,
}HelloDocEnumDocDemo;
■ category: category的相關注釋。
/*!
@category
@abstract NSString的Category
*/
@interface KevinNSString (NSString)
■ protocol: protocol的相關注釋
/*!
@protocol
@abstract 這個HelloDoc類的一個protocol
@discussion 具體描述資訊可以寫在這裡
*/
@protocol HelloDocDelegate ＜NSObject＞
以上列舉的標準註釋也許並不完善。
具體請參考蘋果的developer網站的API文件。
以上列舉的標準註釋全都在下面的標頭檔案裡，僅供參考。
HelloDoc.h