需求

一個公司隨著時間的推移會慢慢的成長起來田藐，這也就意味著公司的隊伍也會不斷的壯大缆八。在壯大的同時需要保證團隊開發(fā)的規(guī)范性铺罢。這樣有益于后期維護卖氨，同時也能夠培養(yǎng)團隊的協(xié)作能力会烙。軟件開發(fā)一直是公司的核心部門，那么作為 iOS開發(fā)部 的成員之一筒捺，就更應(yīng)該積極做好各項工作柏腻。這次我就啰里啰嗦的整理一下網(wǎng)上的關(guān)于 AppleDoc 生成開發(fā)文檔的相關(guān)知識點。此文章需要有一定的指令基礎(chǔ)的童鞋學(xué)習(xí)系吭，不然看了會比較吃力五嫂。有不懂的需要自行腦補一下，這里就不再累贅。

安裝

打開終端沃缘，執(zhí)行指令進行下載安裝

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

當(dāng)出現(xiàn) INSTALL SUCCEEDED 時說明成功了躯枢，你也可以用appledoc --version查看驗證下。如果可以正常執(zhí)行下面指令則證明安裝成功槐臀，否則需要查看報錯說明锄蹂。

# 查看版本號
$ appledoc --version
# 查看更多文檔信息
$ appledoc --help

查看版本號

使用

1. 使用終端進入代碼目錄

直接拖拽我們的工程文件夾到終端，然后按回車鍵
或者使用 cd+"項目名字目錄"水慨，然后按回車鍵
以上兩種方法都可以進入到我們的工程根目錄

2. 指令用法及參數(shù)說明

# 參考指令寫法1(不生成docset文件)
$ appledoc --no-create-docset --output ./doc --project-name "QQ" --company-id "com.tencent.QQ" --project-company "Tencent Inc." /Users/superdanny/Desktop/QQ-Project/QQ/Views

# 參考指令寫法2(不生成docset文件得糜，參數(shù)使用“=”等號寫法)
$ appledoc --no-create-docset --output="./doc" --project-name="QQ" --company-id="com.tencent.QQ" --project-company="Tencent Inc." /Users/superdanny/Desktop/QQ-Project/QQ/Views

# 參考指令寫法3(生成docset文件并指定生成路徑)
$ appledoc --output ./doc --project-name "QQ" --company-id "com.tencent.QQ" --project-company "Tencent Inc." /Users/superdanny/Desktop/QQ-Project/QQ/Views --docset-install-path ./doc

參數(shù)說明

如果是生成docset文件按傅，則--output參數(shù)對應(yīng)的目錄會生成一個 docset-installed.txt 文件，里面記錄docset存放的目錄胧卤。
如果是不生成docset文件唯绍，則--output參數(shù)對應(yīng)的目錄會生成html文件。直接打開 index.html 文件即可查看枝誊。

支持的注釋

下面是一些常用的語法示意:

單行注釋

/// 這是單行注釋况芒。

/** 這也是單行注釋 */

/*! 同樣是單行注釋 */

/** 這也是單行注釋，
*  第二行會接上第一行叶撒。
*/

多行注釋

/** 
 @brief 這里是方法的簡介绝骚。僅對屬性、方法有效祠够，對類压汪、協(xié)議 無效，會造成后續(xù)內(nèi)容解析失敗古瓤。所以該指令不能放到類注釋里止剖。
 @param string 參數(shù)描述腺阳。
 @return 返回值描述。
 @exception NSException 可能拋出的異常穿香。
 @warning 這里是警告描述亭引。
 @bug 這里是缺陷描述。
 @see 用它來指明其他相關(guān)的method或function皮获。你可以使用多個這種標簽焙蚓。
 @sa 同@see。
 */

注意事項

@brief洒宝、@see主届、@sa僅對屬性、方法有效待德，對類、協(xié)議 無效枫夺，會造成后續(xù)內(nèi)容解析失敗将宪。所以該指令不能放到類注釋里。

@see <name>
@sa <name>
其中<name>為：
1) 當(dāng)前類（或協(xié)議）中的屬性或方法橡庞。（注意Objective-C方法簽名的寫法较坛，一般為“方法名:參數(shù)1:參數(shù)2:??”的格式）
2) 類（或協(xié)議）名。（注意AppleDoc不支持當(dāng)前類）
3) 將@see或@sa指令放在注釋的最后面扒最，避免內(nèi)容丟失

類注釋

 /** 第一行是類的簡介

 在簡介的下面,就是類的詳細介紹了丑勤。
 沒有間隔換行會被消除，就像HTML那樣吧趣。
 
 下面是常用的markdown語法
 
 分割線：
 
 - - -
 
 無序列表: (每行以 '*'法竞、'-'、'+' 開頭):
 
 * this is the first line
 * this is the second line
 * this is the third line
 
 有序列表: (每行以 1.2.3强挫、a.b.c 開頭):
 
 a. this is the first line
 b. this is the secode line
 
 多級列表:
 
 * this is the first line
 a. this is line a
 b. this is line b
 * this is the second line
 1. this in line 1
 2. this is line 2
 
 標題:
 
 # This is an H1
 ## This is an H2
 ### This is an H3
 #### This is an h4
 ##### This is an h5
 ###### This is an H6
 
 鏈接:
 
 普通URL直接寫上岔霸，appledoc會自動翻譯成鏈接: http://superdanny.link
 
 這個 [鏈接](http://example.net/) 會隱藏實際URL.

 表格:
 
 | header1(默認) | header2(居中) | header3(左對齊) | header4(右對齊) |
 |---------|:-------:|:--------|--------:|
 | normal  |  center |  left  |  right  |
 | cell    | cell    | cell    | cell    |
 
 引用:
 
 這里會引用到方法 `pinyinFromChiniseString:`，這里會引用到類 `AreaListViewController`
 
 這里會引用到一個代碼塊俯渤。具體辦法是在每行內(nèi)容的前面按tab鍵進行縮進呆细，不然會無法正常識別。
 
    void CMYK2RGB(float c, float m, float y, float k, float *r, float *g, float *b) {
        *r = (1 - c) * (1 - k);
        *g = (1 - m) * (1 - k);
        *b = (1 - y) * (1 - k);
    }
 */

最后我們來看看效果怎么樣吧??

主頁效果

類說明詳情

注釋

再一次感謝您花費時間閱讀這篇文章八匠！

微博： @Danny_呂昌輝
博客： SuperDanny