Xcode自帶的導(dǎo)出API文檔的方法遭笋。但作為崇拜貓神的一員的我，使用的是貓神的VVDocumenter插件，驚訝的發(fā)現(xiàn)這個插件生成的注釋并不能支持導(dǎo)出正確的文檔。于是只好苦逼的加班加點把整個項目的注釋統(tǒng)統(tǒng)修改了一遍埃碱，最近在簡書上看到小碼哥的一篇修改Xcode自動生成的文件注釋的文章，于是想到了結(jié)合這種方法來減輕我們導(dǎo)出文檔的難度酥泞。這里并不是說第三方插件生成的注釋不好，但是對于有相同需求的碼農(nóng)們可以參考我的這篇文章啃憎。廢話少說芝囤，先上文檔效果圖
- 導(dǎo)出注釋標準
/*!頭文件基本信息。這個用在每個源代碼文件的頭文件的最開頭辛萍。
@header 這里的信息應(yīng)該與該源代碼文件的名字一致
@abstract 關(guān)于這個源代碼文件的一些基本描述
@author Sindri Lin (作者信息)
@version 1.00 2012/01/20 Creation (此文檔的版本信息)
*/
/*!類信息悯姊。此注釋用在類聲明的開頭。
@class
@abstract 這里可以寫關(guān)于這個類的一些描述贩毕。
*/
/*!
@propertyproperty的相關(guān)注釋悯许。
@abstract 這里可以寫關(guān)于這個Property的一些基本描述。
*/
/*!
@method函數(shù)(方法)的相關(guān)注釋辉阶。
@abstract 這里可以寫一些關(guān)于這個方法的一些簡要描述
@discussion 這里可以具體寫寫這個方法如何使用先壕，注意點之類的瘩扼。如果你是設(shè)計一個抽象類或者一個共通類給給其他類繼承的話，建議在這里具體描述一下怎樣使用這個方法垃僚。
@param text 文字 (這里把這個方法需要的參數(shù)列出來)
@param error 錯誤參照
@result 返回結(jié)果
*/
/*!
@enumenum的相關(guān)注釋集绰。
@abstract 關(guān)于這個enum的一些基本信息
@constant HelloDocEnumDocDemoTagNumberPopupView PopupView的Tag
@constant HelloDocEnumDocDemoTagNumberOKButton OK按鈕的Tag
*/
/*!
@categorycategory的相關(guān)注釋。
@abstract NSString的Category
*/
/*!
@protocolprotocol的相關(guān)注釋
@abstract 這個HelloDoc類的一個protocol
@discussion 具體描述信息可以寫在這里
*/
上面的注釋很明顯跟我們平時的注釋不一樣谆棺，如果要嚴格按照這個格式進行注釋栽燕，估計要累死一群碼農(nóng)。但是改淑，上面的頭文件碍岔、類聲明和類別聲明我們都能通過修改Xcode本身的設(shè)置來實現(xiàn)創(chuàng)建文件時就將注釋文檔設(shè)置完畢。
- 修改Xcode自身生成的文件注釋
首先右鍵Xcode -> 選項 -> 在Finder中打開 -> 右鍵 -> 顯示包內(nèi)容
Contents -> Developer -> Platforms -> iPhoneOS.platform -> Developer -> Library -> Xcode -> Templates -> File Templates
到了這個目錄下朵夏，是不是覺得子目錄的名字有些熟悉呢蔼啦？
選中Source -> Cocoa Touch Class.xctemplate
這個目錄下面有很多后綴名為Objective-C跟Swift的文件夾，這么多怎么看呢侍郭？我們先打開NSObjectObjective-C下面的___FILEBASENAME___
上面那綠油油的注釋就是我們要修改的東西了询吴，注意它的格式，跟我們創(chuàng)建文件的頭部注釋是一樣的
這里用到了幾個系統(tǒng)的預(yù)處理宏定義亮元，包括__FILENAME__猛计、__PROJECTNAME__、__FULLUSERNAME__爆捞、__DATE__和__COPYRIGHT__奉瘤，分別表示的是文件名、項目名稱煮甥、系統(tǒng)用戶全稱盗温、當前日期和版權(quán)聲明，這些宏定義可以用在我們修改之后的注釋中成肘。我把它修改成下面這樣：
退出Xcode重新運行卖局，然后創(chuàng)建新類，我們就會發(fā)現(xiàn)新的類文件格式：
這樣我們需要的頭文件注釋文檔已經(jīng)自動生成了双霍，而且是一次操作砚偶，永久受益。大家可以如法炮制洒闸，在@interface的注釋模板上加上規(guī)范類信息的注釋文檔染坯，就可以直接創(chuàng)建類的注釋文檔。
- 如何導(dǎo)出文檔
修改好了Xcode的自動生成注釋格式丘逸，接下來就是最重要的導(dǎo)出API文檔操作单鹿。首先在選擇項目，然后add new target -> Other -> aggregate -> 命名 -> 創(chuàng)建完畢
選擇新創(chuàng)建好的target -> add New Run Script Phase
在建好的run script中填寫下面的信息
# shell script goes here
mkdir -p headerDoc
find (這里填寫導(dǎo)出文檔的絕對路徑) \*.h -print | xargs headerdoc2html -o headerDoc
gatherheaderdoc headerDoc
exit 0
選擇使用新建的target運行
然后運行成功后到填寫的路徑下就可以看到導(dǎo)出的API文檔文件夾
學會導(dǎo)出API文檔無疑可以極大的提高我們的代碼的可讀性深纲，而在很多重要的場合下仲锄，代碼的可讀性甚至要高于代碼的質(zhì)量
文／Sindri的小巢（簡書作者）
原文鏈接：http://www.reibang.com/p/d0c7d9040c93
著作權(quán)歸作者所有劲妙，轉(zhuǎn)載請聯(lián)系作者獲得授權(quán)，并標注“簡書作者”昼窗。
