最近工作需要和其他公司進行項目交接的時候，原以為像往常一樣直接交付源代碼就行了，誰知道客戶公司需要我們提供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文檔無疑可以極大的提高我們的代碼的可讀性，而在很多重要的場合下，代碼的可讀性甚至要高于代碼的質量。因此，成為一名優秀的程序員也要能夠自覺規范自己的代碼注釋規范，來為隨時的導出文檔做好準備。代碼之路漫漫，且行且珍惜
