利用HeaderDoc自動生成API文檔

利用HeaderDoc自動生成API文檔

最近在爲公司寫框架和組件庫。你們都建議在文檔上須要更加完善一些。因而在思考如何規範地完善文檔？ 面向非技術型的boss們的說明性文檔，手工寫便可。面向組件使用者的文檔呢？一方面，要保證註釋的完整性，以保證其餘同事在使用的時候只看註釋便可。另外一方面又須要要一份文本文檔，以便隨時查閱。如何同時作到這兩點？

關於文檔，業界有一些成熟的解決方案。例如評價頗高的AppleDoc，還有從Xcode 5,iOS7開始集成在Xcode中的HeaderDoc。本着一切以官方爲準的原則，選擇了HeaderDoc來完成這項工做。

用HeaderDoc有什麼好處？

與Xocde兼容

將鼠標移動到某一行方法上，按option+鼠標左鍵試試？

能夠自動導出文檔

竟然如此炫酷，還不趕忙跟我一塊兒用起HeaderDoc,走(tiao)上(jin)人(wen)生(dang)巔(da)峯(keng)？

HeaderDoc 的註釋標準

HeaderDoc的註釋，通常咱們會用到如下幾種：

頭文件註釋

頭文件基本信息。這個用在每一個源代碼文件的頭文件的最開頭。

/*! @header UIImage+Scale.h @abstract 圖片壓縮的Category @author Created by Pan on 16/1/24. @version 1.2.0 16/1/24 Creation

 */

• @header  與該源代碼文件的名字一致

• @abstract 關於這個源代碼文件的一些基本描述

• @author  Sheng Pan (做者信息)

• @version  1.2.0 2012/01/20 Creation (此文檔的版本信息)

類註釋

關於此類的一些信息。此註釋用在類聲明的開頭。

/*!@class PSCarouselView@abstract 輪播控件，實現了常見的圖片輪播功能。

*/

• @class  與該類名一致

屬性註釋

/*!@property nameLabel@abstract 用於顯示用戶名的Label

*/

• @property 與該屬性名一致

方法註釋

/*! @abstract 將圖片等比縮小 @discussion 將圖片等比縮小,注意:此方法在主線程運行，處理大量圖片請使用scaleImageOnBackgroud: @param ratio 縮小的倍數。例如，如想縮小爲原圖的1/2 ratio = 2.0 @result UIImage

 */

• @discussion 該方法的詳細描述，包括方法的一些注意事項，適用狀況條件等等。

枚舉註釋

/*! @enum Gender @abstract 性別枚舉 @constant GenderUnknow 性別未知 @constant GenderMale 男 @constant GenderFemale 女

 */

• @enum 與枚舉名稱一致

• @constant 與枚舉值一致，後面添加描述

Category註釋

/*! @category  Scale @abstract  UIImage的Category,添加圖片壓縮的相關功能

 */

• @category 與Category名稱一致

Protocol註釋

/*!@protocol HTModelCallBack@abstract Model的回調接口。@discussion 想接收Model回調的類，申明並實現此接口，便可獲取從HTBaseModel中回調的信息。注意：接收回調的前提，是使用DESIGNATED_INITIALIZER來初始化HTBaseModel(或其子類).

*/

• @Protocol 與Protocol名稱一致

經常使用的註釋基本上就是這些，若是還須要瞭解更多註釋的關鍵字請查閱官方文檔。

自動生成標準註釋

以上的註釋格式如此繁瑣，手工輸入絕對不是我等懶鬼的做風。自動生成註釋有如下幾種方法

1. 修改Xcode模版文件，一勞永逸。 

2. 利用Xode的code snapshot，快速編寫註釋。 

3. fork一份VV-Documentor-Xcode而後修改裏面的註釋風格。（VV-Documentor-Xcode原來的註釋風格不支持導出文檔）。

後兩種很少作介紹，在此介紹一下修改Xcode模版文件的方法。

打開finder，前往以下路徑

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/File Templates/Source/Cocoa Touch Class.xctemplate

咱們會看到這樣一個目錄

每一個文件夾下面的文件，就是各類系統類(包括你繼承下來的子類)的模版文件。修改哪一個文件夾下的模版文件，建立對應類(和繼承自其子類的類)時，就會自動生成模版裏預約的註釋。

文件夾內包含了.h和.m兩份文件，分別對應.h和.m文件的模版

咱們打開.h模版文件，能夠看到以下信息

此處有幾個系統的宏

• FILENAME：文件名

• PROJECTNAME：項目名

• FULLUSERNAME：當前mac用戶全稱

• DATE：日期

• COPYRIGHT：版權聲明

咱們將頭文件修改成以下格式，在建立類的時候就能夠自動生成咱們須要的註釋格式了。

/*! 

  @header ___FILENAME___

  @abstract <#abstract#>

  @author Created by ___FULLUSERNAME___ on ___DATE___.  @version <#version#> ___DATE___ Creation___COPYRIGHT___

 */

___IMPORTHEADER_cocoaTouchSubclass___

/*!  @class ___FILEBASENAMEASIDENTIFIER___

  @abstract <#description#>

 */
@interface ___FILEBASENAMEASIDENTIFIER___ : ___VARIABLE_cocoaTouchSubclass___

@end

其餘文件如法炮製便可。

*注意: 記得逐一修改Cocoa Touch Class.xctemplate文件夾內每個類的模版文件。只有修改過的類和其子類會起做用。

自動導出文檔。

規範的註釋標好後，導出文檔就很方便了。有兩種方法能夠導出文檔。

用命令行導出文檔

首先輸出文檔

headerdoc2html -o DESTINATION_PATH PROJECT_PATH

• DESTINATION_PATH：文檔輸出目標文件夾。如~/Desktop/documentation

• PROJECT_PATH ：項目目錄。如~/Desktop/project

而後建立一個文檔索引

gatherheaderdoc DESTINATION_PATH INDEX_PAGE_NAME

• DESTINATION_PATH：文檔輸出目標文件夾。如~/Desktop/documentation

• INDEX_PAGE_NAME：索引頁的名字。如index.html

用Xcode Build一份文檔

這個方法本質上也是用命令行導出文檔。無非是能夠再也不須要手動管理文檔路徑，每一個項目能夠對應一個文檔路徑。用流行的話來講，就是一次配置，處處留情。哦不，是一次配置，自動運行。

首先在你的項目中新建一個target。類型選擇爲Other-Aggregate。

在Target的Build-Phases中，點擊加號，選擇New Run Phases Script。

粘貼以下腳本（注意修改你本身的工程目錄和導出目錄）

# shell script goes hereheaderdoc2html -o ~/Desktop/doc /Users/pan/DEV/iOS/ios-standardization/Example/Pods/Headers/Public/HTStandardgatherheaderdoc ~/Desktop/doc index.html

exit 0

最後，選擇這個target，並Run。而後就等待奇蹟的發生吧。