利用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
*/</pre> 
 
 
  
 @header 與該源代碼文件的名字一致 

 @abstract 關于這個源代碼文件的一些基本描述 
 @author Sheng Pan (作者信息) 
 @version 1.2.0 2012/01/20 Creation (此文檔的版本信息) 
</ul>
類注釋
關于此類的一些信息。此注釋用在類聲明的開頭。
/*!

@class PSCarouselView
@abstract 輪播控件，實現了常見的圖片輪播功能。
*/</pre> 
 
 
  
 @class 與該類名一致 

</ul>
屬性注釋
/*!

@property nameLabel
@abstract 用于顯示用戶名的Label
*/</pre> 
 
 
  
 @property 與該屬性名一致 

</ul>
方法注釋
/*!

@abstract 將圖片等比縮小
@discussion 將圖片等比縮小,注意:此方法在主線程運行，處理大量圖片請使用scaleImageOnBackgroud:
@param ratio 縮小的倍數。例如，如想縮小為原圖的1/2 ratio = 2.0
@result UIImage
*/</pre> 
 
 
  
 @discussion 該方法的詳細描述，包括方法的一些注意事項，適用情況條件等等。 

</ul>
枚舉注釋
/*!

@enum Gender
@abstract 性別枚舉
@constant GenderUnknow 性別未知
@constant GenderMale 男
@constant GenderFemale 女
*/</pre> 
 
 
  
 @enum 與枚舉名稱一致 

 @constant 與枚舉值一致，后面添加描述 
</ul>
Category注釋
/*!

@category  Scale
@abstract  UIImage的Category,添加圖片壓縮的相關功能
*/</pre> 
 
 
  
 @category 與Category名稱一致 

</ul>
Protocol注釋
/*!

@protocol HTModelCallBack
@abstract Model的回調接口。
@discussion 想接收Model回調的類，申明并實現此接口，即可獲取從HTBaseModel中回調的信息。注意：接收回調的前提，是使用DESIGNATED_INITIALIZER來初始化HTBaseModel(或其子類).
*/</pre> 
 
 
  
 @Protocol 與Protocol名稱一致 

</ul>
 常用的注釋基本上就是這些，如果還需要了解更多注釋的關鍵字請查閱 官方文檔 。 
自動生成標準注釋
以上的注釋格式如此繁瑣，手工輸入絕對不是我等懶鬼的作風。自動生成注釋有以下幾種方法
 
  
修改Xcode模版文件，一勞永逸。

  
利用Xode的code snapshot，快速編寫注釋。

  
 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
*/
_IMPORTHEADERcocoaTouchSubclass
/*!
@class FILEBASENAMEASIDENTIFIER
@abstract <#description#>
*/
@interface FILEBASENAMEASIDENTIFIER : _VARIABLEcocoaTouchSubclass
@end</pre> 
 
其他文件如法炮制即可。

  *注意:  記得逐一修改 Cocoa Touch Class.xctemplate 文件夾內每一個類的模版文件。只有修改過的類和其子類會起作用。 
自動導出文檔。
規范的注釋標好后，導出文檔就很方便了。有兩種方法可以導出文檔。
用命令行導出文檔
首先輸出文檔
headerdoc2html -o DESTINATION_PATH PROJECT_PATH  
 
 
 
  
 DESTINATION_PATH ：文檔輸出目標文件夾。如 ~/Desktop/documentation 

 PROJECT_PATH ：項目目錄。如 ~/Desktop/project 
</ul>
然后創建一個文檔索引
gatherheaderdoc DESTINATION_PATH INDEX_PAGE_NAME
 
 
 
  
 DESTINATION_PATH ：文檔輸出目標文件夾。如 ~/Desktop/documentation 

 INDEX_PAGE_NAME ：索引頁的名字。如 index.html 
</ul>
用Xcode Build一份文檔
這個方法本質上也是用命令行導出文檔。無非是可以不再需要手動管理文檔路徑，每個項目可以對應一個文檔路徑。用流行的話來說，就是一次配置，到處留情。哦不，是一次配置，自動運行。
首先在你的項目中新建一個target。類型選擇為Other-Aggregate。
  
在Target的Build-Phases中，點擊加號，選擇New Run Phases Script。
  
粘貼如下腳本（注意修改你自己的工程目錄和導出目錄）
# shell script goes here

headerdoc2html -o ~/Desktop/doc /Users/pan/DEV/iOS/ios-standardization/Example/Pods/Headers/Public/HTStandard
gatherheaderdoc ~/Desktop/doc index.html
exit 0  </pre> 
 
最后，選擇這個target，并Run。然后就等待奇跡的發生吧。
 </div>