作為一種iOS開發者，閱讀蘋果開發者文檔是一個優秀的習慣。Dash工具（無論Mac版還是移動版）的出現，都令這一切變得輸入此簡單。使用Dash查看文檔，每一個類的結構是如此的清晰。那我我們自己的項目如何能夠生成和蘋果開發者文檔一樣效果的文檔，并能夠使用Dash查看呢。還好有第三方工具AppleDoc。筆者無論開發還是寫作都推崇一種實用主義。AppleDoc的文檔一搜一大把，但是真正能實用的又有哪些？筆者現記錄下自己的使用始末，提供給大家參考。
1. 是什么？能干什么
弄清楚目的很重要。一個工具不要覺得不明覺厲就趕緊Down下來用，關鍵要能滿足自己的需求。AppleDoc就是一個文檔生成工具，能夠根據頭文件的注釋，公開的屬性，方法生成一份類似于蘋果開發者文檔的文檔。生成格式默認為Docset，直接Dash打開查看。
2. 安裝
cd "clone的path"
git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh
安裝好后象征性的查看版本
appleDoc --version
輸出
appledoc version: 2.2.1 (build 1334)
3. 文檔生成
進入項目的工程目錄：
appledoc --project-name="projectName" --project-version="3.1.0" --project-company="companyName" --company-id="companyID" --output="./" --docset-install-path="./" .
生成的信息如下：
如果設置設置companyID，則生成文件名為 companyID.projectName.docset
如果不設置則文件名為com.companyname.projectname.projectName.docset
--project-name，--project-company必須輸入
--output 為生成的txt文件的目錄，這里設置為當前目錄
--docset-install-path 為生成docket的目錄，這里設置為當前目錄。如果此目錄不設置，默認會在~/Library/Developer/Shared/Documentation/DocSets/目錄生成
就是這樣，沒有必要再建立一個腳本實現了。
4. 注釋
注釋使用HeaderDoc風格注釋就可以了,
單行注釋，只需要//雙斜杠注釋變成三斜杠注釋///就好。
多行注釋，加入一些HeaderDoc的標簽
- @brief: 簡單描述，往往設置為一行。
- @discussion: 詳細描述，它不是必須的，僅僅是為了使描述更清晰。
- @param: 描述方法、回調或函數的參數名稱。
- @return: 描述方法或函數的返回值。
- @warning 給出警告信息
- @see 參考某個類或者某個方法
- @since 從iOS7開始有效
- ……
注釋加入的標簽對應于文檔中的標簽。
下邊是一段示例代碼
#import <Foundation/Foundation.h>
/**
這是一個類注釋的實例
這個文檔包括了XXXX
這個注釋還支持MARKDOWN語法
###標題一
標題1的內容
###標題二
標題1的內容
下邊是一段示例代碼
NSURL *baseURL = [NSURL URLWithString:@"http://example.com/v1/"];
[NSURL URLWithString:@"foo" relativeToURL:baseURL]; // http://example.com/v1/foo
[NSURL URLWithString:@"foo?bar=baz" relativeToURL:baseURL]; // http://example.com/v1/foo?bar=baz
[NSURL URLWithString:@"/foo" relativeToURL:baseURL]; // http://example.com/foo
[NSURL URLWithString:@"foo/" relativeToURL:baseURL]; // http://example.com/v1/foo
[NSURL URLWithString:@"/foo/" relativeToURL:baseURL]; // http://example.com/foo/
[NSURL URLWithString:@"http://example2.com/" relativeToURL:baseURL]; // http://example2.com/
Also important to note is that a trailing slash will be added to any `baseURL` without one. This would otherwise cause unexpected behavior when constructing URLs using paths without a leading slash.
這是一個 `NSObject` 的子類
@warning 這只是一個測試
*/
@interface TestAppleDocComments : NSObject
/**
* 這是一個枚舉類型
*/
typedef NS_ENUM(NSUInteger, EnumType) {
/**
* 枚舉Type1
*/
Type1,
/**
* 枚舉Type2
*/
Type2,
/**
* 枚舉Type3
*/
Type3,
};
/**
* 枚舉類型屬性示例
*/
@property (nonatomic, assign) EnumType* myType;
///單行屬性注釋
@property (nonatomic, strong) NSString* testproperty;
/**
@brief 這是這個屬性的簡潔描述
@discussion 這是這個屬性的詳細描述
詳細信息的描述。如果不寫我，那我我和簡介描述一樣
@warning `testproperty2` must not be `nil`
*/
@property (nonatomic, strong) NSString* testproperty2;
/**
@brief 這是這個方法的簡潔描述，詳細信息的描述。如果不寫我，那我我和簡介描述一樣
@param para1 參數1，這個參數XXXX
@param para2 參數2 這個參數XXXX
@return 返回值為id類型
@warning 這是一個警告
@see AppDelegate
@since iOS9.0有效
*/
- (id)testMethordCommentsWithPara:(NSString*)para1 para:(NSInteger)para2;
/**
默認的全部都是詳細描述。
不寫brief
@discussion 這是這個方法的詳細描述
詳細信息的描述。如果不寫我，那我我和簡介描述一樣
@param para1 參數1，這個參數XXXX
@param para2 參數2 這個參數XXXX
@return 返回值為id類型
@warning 這是一個警告
@see AppDelegate
@since iOS9.0有效
*/
- (id)test2MethordCommentsWithPara:(NSString*)para1 para:(NSInteger)para2;
/**
默認的全部都是詳細描述。
不寫discussion
@brief 這是這個方法的簡潔描述
@param para1 參數1，這個參數XXXX
@param para2 參數2 這個參數XXXX
@return 返回值為id類型
@warning 這是一個警告
@see AppDelegate
@since iOS9.0有效
*/
- (id)test3MethordCommentsWithPara:(NSString*)para1 para:(NSInteger)para2;
/**
這是這個方法的簡潔描述
@discussion 這是這個方法的詳細描述
詳細信息的描述。如果不寫我，那我我和簡介描述一樣
@param para1 參數1，這個參數XXXX
@param para2 參數2 這個參數XXXX
@return 返回值為id類型
@warning 這是一個警告
@see AppDelegate
@since iOS9.0以上有效
*/
- (id)test4MethordCommentsWithPara:(NSString*)para1 para:(NSInteger)para2;
@end
生成文檔如下圖
