修改Xcode自動生成的文件註釋來導出API文檔

修改Xcode自動生成的文件註釋來導出API文檔

 

最近工做須要和其餘公司進行項目交接的時候，原覺得像往常同樣直接交付源代碼就好了，誰知道客戶公司須要咱們提供API文檔。瞬間我和小夥伴們都驚呆了，什麼鬼！歷來沒作過。後來看了一下安卓組提供的API文檔發現是HTML格式的類文件註釋介紹，因而殘酷的打消了我想手動編寫API文檔的想法。

抱着這樣的想法在網上搜索了蠻久，總算是找到了Xcode自帶的導出API文檔的方法。但做爲崇拜貓神的一員的我，使用的是貓神的VVDocumenter插件，驚訝的發現這個插件生成的註釋並不能支持導出正確的文檔。因而只好苦逼的加班加點把整個項目的註釋通通修改了一遍，最近在簡書上看到小碼哥的一篇修改Xcode自動生成的文件註釋的文章，因而想到告終合這種方法來減輕咱們導出文檔的難度。這裏並非說第三方插件生成的註釋很差，可是對於有相同需求的碼農們能夠參考個人這篇文章。廢話少說，先上文檔效果圖

 

 

---

- 導出註釋標準

 

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

@header 這裏的信息應該與該源代碼文件的名字一致

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

@author Sindri Lin (做者信息)

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

*/

 

/*!  類信息。此註釋用在類聲明的開頭。

@class

@abstract 這裏能夠寫關於這個類的一些描述。

*/

 

/*!

@property  property的相關注釋。

@abstract 這裏能夠寫關於這個Property的一些基本描述。

*/

 

/*!

@method  函數(方法)的相關注釋。

@abstract 這裏能夠寫一些關於這個方法的一些簡要描述

@discussion 這裏能夠具體寫寫這個方法如何使用，注意點之類的。若是你是設計一個抽象類或者一個共通類給給其餘類繼承的話，建議在這裏具體描述一下怎樣使用這個方法。

@param text 文字 (這裏把這個方法須要的參數列出來)

@param error 錯誤參照

@result 返回結果

*/

 

/*!

@enum  enum的相關注釋。

@abstract 關於這個enum的一些基本信息

@constant HelloDocEnumDocDemoTagNumberPopupView PopupView的Tag

@constant HelloDocEnumDocDemoTagNumberOKButton OK按鈕的Tag

*/

 

/*!

@category  category的相關注釋。

@abstract NSString的Category

*/

 

/*!

@protocol  protocol的相關注釋

@abstract 這個HelloDoc類的一個protocol

@discussion 具體描述信息能夠寫在這裏

*/

 

上面的註釋很明顯跟咱們平時的註釋不同，若是要嚴格按照這個格式進行註釋，估計要累死一羣碼農。可是，上面的頭文件、類聲明和類別聲明咱們都能經過修改Xcode自己的設置來實現建立文件時就將註釋文檔設置完畢。

 

---

- 修改Xcode自身生成的文件註釋

首先右鍵Xcode -> 選項 -> 在Finder中打開 -> 右鍵 -> 顯示包內容

Contents -> Developer -> Platforms -> iPhoneOS.platform -> Developer -> Library -> Xcode -> Templates -> File Templates

到了這個目錄下，是否是以爲子目錄的名字有些熟悉呢？

選中Source -> Cocoa Touch Class.xctemplate

這個目錄下面有不少後綴名爲Objective-C跟Swift的文件夾，這麼多怎麼看呢？咱們先打開NSObjectObjective-C下面的___FILEBASENAME___

上面那綠油油的註釋就是咱們要修改的東西了，注意它的格式，跟咱們建立文件的頭部註釋是同樣的

這裏用到了幾個系統的預處理宏定義，包括__FILENAME__、__PROJECTNAME__、__FULLUSERNAME__、__DATE__和__COPYRIGHT__，分別表示的是文件名、項目名稱、系統用戶全稱、當前日期和版權聲明，這些宏定義能夠用在咱們修改以後的註釋中。我把它修改爲下面這樣：

退出Xcode從新運行，而後建立新類，咱們就會發現新的類文件格式：

這樣咱們須要的頭文件註釋文檔已經自動生成了，並且是一次操做，永久受益。你們能夠如法炮製，在@interface的註釋模板上加上規範類信息的註釋文檔，就能夠直接建立類的註釋文檔。

 

---

- 如何導出文檔

修改好了Xcode的自動生成註釋格式，接下來就是最重要的導出API文檔操做。首先在選擇項目，而後add new target -> Other -> aggregate -> 命名 -> 建立完畢

選擇新建立好的target -> add New Run Script Phase

在建好的run script中填寫下面的信息

# shell script goes here

mkdir -p headerDoc

find (這裏填寫導出文檔的絕對路徑) \*.h -print | xargs headerdoc2html -o headerDoc

gatherheaderdoc headerDoc

exit 0

選擇使用新建的target運行

而後運行成功後到填寫的路徑下就能夠看到導出的API文檔文件夾

 

---

學會導出API文檔無疑能夠極大的提升咱們的代碼的可讀性，而在不少重要的場合下，代碼的可讀性甚至要高於代碼的質量。所以，成爲一名優秀的程序員也要可以自覺規範本身的代碼註釋規範，來爲隨時的導出文檔作好準備。代碼之路漫漫，且行且珍惜