使用Xcode生成API文檔---02HeaderDoc
阿新 • • 發佈：2017-12-22
scale clas pts help 圖片 db4 所有 模式 手寫 如何使用Xcode生成你的技術文檔.
生成技術文檔主要有三個工具: headerdoc, doxygen 和 appledoc.其中headerdoc是蘋果官方的生成工具,後兩個是第三方工具.如果Xcode版本更新,則需要重新配置第三方工具,個人感覺雖然功能強大,但是配置繁瑣,推薦大家使用headerdoc.
想要生成技術文檔,首先,你要有註釋,沒有註釋是沒法直接生成文檔的,你需要新建pages,慢慢手寫吧
規範的寫好註釋,一可以讓自己不至於忘了自己的代碼,二可以直接生成技術文檔,何樂而不為
用Objective-C創建一個demo app
我們從創建一個使用Objective-C的新工程開始，這工程也是我們將會用來對接下來要看到的東西做測試的。如果你還沒做，打開Xcode然後創建一個新的工程。因為我們不會做一個真的demo應用，選中Single View Application 就可以了。 
而且不僅這樣。當在鍵盤上按住Option 鍵，點擊myName屬性就會讓幫助窗口彈出：
可以看到Xcode把文檔裏的每個部分都格式化的展示出來。在help 彈出窗口裏也一樣（option鍵+點擊方法名）：
如果在viewDidLoad 方法中調用這個函數，那麽就可以在函數自動填充窗口裏看到簡介描述：
很棒，是不是？可以想象你的代碼那樣文檔化後會變得多有幫助且能自我解釋清楚代碼意義，特別是當你同其他團隊人員一起工作時。
為了讓這個例子更加有趣，我們添加另一個公有方法正好可以做相反的事情：把攝氏度轉換為華氏度。打開ViewController.h文件，然後添加下面的方法聲明，以及它的文檔註釋：
非常漂亮！現在你自己的文檔跟Xcode默認文檔比起來毫不遜色。
在進入下一部分前，打開ViewController.h文件，然後添加下面的屬性聲明（當然也包括註釋）：
然後點擊回車鍵，為了確保你在正確的目錄下可以使用pwd 指令（始終在terminal中）
在這裏我們要使用的HeaderDo指令叫做headerdoc2html，指令格式如下：
// This is a comment.
你可以（且必須）像上面那樣來放置你的註釋，以便分清每個部分。但是，當談到代碼註釋文檔，我肯定不是指的上面的註釋。如果整個教程都專註於此肯定毫無意義。註釋文檔意味著以結構化的方法使用特殊的關鍵字，也叫標簽來寫註釋，使用特殊的符號來標示註釋區域，因此編譯器可以完美的理解這個過程。只有一些簡單的規則需要遵守。上面操作的所有結果就是你的註釋文檔可以在三個不同的地方展示：- 在Utilities面板的Quick Help Inspector 裏。
- 當你按下Option鍵然後點擊方法，類或屬性名時彈出的幫助菜單 Help Popup 裏。
- 在代碼實現彈出框裏。
- 把你的註釋包含在/** – */ 塊裏。
- 把你的註釋包含在 /*! – */塊裏。
- 以三條斜杠 ///開始的註釋行
- @brief: 使用它來寫一段你正在文檔化的method, property, class, file, struct, 或enum的短描述信息。
- @discussion: 用它來寫一段詳盡的描述。如果需要你可以添加換行。
- @param: 通過它你可以描述一個 method 或 function的參數信息。你可以使用多個這種標簽。
- @return: 用它來制定一個 method 或 function的返回值。
- @see: 用它來指明其他相關的 method 或 function。你可以使用多個這種標簽。
- @sa: 同前一條類似。
- @code: 使用這個標簽，你可以在文檔當中嵌入代碼段。當在Help Inspector當中查看文檔時，代碼通過在一個特別的盒子中用一種不同的字體來展示。始終記住在寫的代碼結尾處使用@endcode標簽。
- @remark:在寫文檔時，用它來強調任何關於代碼的特殊之處。
@interface ViewController ()
@property (nonatomic, strong) NSString *myName;
@end
然後如下面所示添加註釋文檔：
/*! @brief This property knows my name. */
@property (nonatomic, strong) NSString *myName;
然後到viewDidLoad方法中，開始輸入這個屬性。你將看到在代碼填充彈出框裏我們剛剛寫下的註釋就在那裏！
更多的，如果在Utilities面板打開 Help Inspector，你會在那裏也找到相同的文檔。
/*! This property knows my name. */
@property (nonatomic, strong) NSString *myName;
同樣的，下面的也一樣：
/** This property knows my name. */
@property (nonatomic, strong) NSString *myName;
而且下面的這條也一樣：
/// This property knows my name. */
@property (nonatomic, strong) NSString *myName;
讓我們來看看第一個怎樣展示文檔方法的簡單示例。此時你必須了解如果你的目標是創建一個HTML文檔，那麽只是公有方法（在頭文件裏的）的文檔是可見的。無論你在類的私有部分中寫的任何文檔在Xcode幫助文檔裏都是可見的，但是任何實現部分都沒有被導出到註釋文檔裏。所以，記住這些，現在讓我們在ViewController.h 文件裏定義一個公有方法：
@interface ViewController : UIViewController
-(float)toCelcius:(float)fromFahrenheit;
@end
很顯然，這個方法將會把華氏度轉換為攝氏度。現在我們來添加註釋文檔：
/*!
@brief It converts temperature degrees from Fahrenheit to Celsius scale.
@discussion This method accepts a float value representing the temperature in Fahrenheit scale and it converts it to the Celsius scale.
To use it, simply call @c[self toCelsius: 50];
@param fromFahrenheit The input value representing the degrees in the Fahrenheit scale.
@return float The degrees in the Celsius scale.
*/
-(float)toCelcius:(float)fromFahrenheit;
註意在上面我們使用HTML開關來讓所有包含的文字分別是粗體和斜體。同樣註意我們是怎樣使用@c開關來標識內嵌代碼
為了在Xcode幫助當中查看這個註釋文檔是怎樣展示的，先打開 ViewController.m 文件然後定義這個方法如下：
-(float)toCelcius:(float)fromFahrenheit{
return(fromFahrenheit - 32) / 1.8;
}
然後把光標放到方法名上，在Quick Help Inspector裏查看：
可以看到Xcode把文檔裏的每個部分都格式化的展示出來。在help 彈出窗口裏也一樣（option鍵+點擊方法名）：
如果在viewDidLoad 方法中調用這個函數，那麽就可以在函數自動填充窗口裏看到簡介描述：
很棒，是不是？可以想象你的代碼那樣文檔化後會變得多有幫助且能自我解釋清楚代碼意義，特別是當你同其他團隊人員一起工作時。
為了讓這個例子更加有趣，我們添加另一個公有方法正好可以做相反的事情：把攝氏度轉換為華氏度。打開ViewController.h文件，然後添加下面的方法聲明，以及它的文檔註釋：
*!
@brief It converts temperature degrees from Celsius to Fahrenheit scale.
@param fromCelcius The celsius degrees value.
@returnfloat The degrees inthe Fahrenheit scale.
@code
float f = [self toCelsius:80];
@endcode
@remark This is a super-easy method.
*/
-(float)toFahrenheit:(float)fromCelcius;
在上面段落裏我們添加了兩個新的標簽：一對 @code – @endcode標簽和@remark 標簽。你將會馬上看到它們是怎樣展示的。
我們到 ViewController.m文件裏去實現這個方法：
-(float)toFahrenheit:(float)fromCelcius{
returnfromCelcius * 1.8 + 32;
}
現在我們看看Help彈出框如下：
非常漂亮！現在你自己的文檔跟Xcode默認文檔比起來毫不遜色。
在進入下一部分前，打開ViewController.h文件，然後添加下面的屬性聲明（當然也包括註釋）：
/*! An application delegate object. */
@property (nonatomic, strong) AppDelegate *appDelegate;
同它一起，導入AppDelegate類：
#import "AppDelegate.h"
添加上面屬性到類裏面的原因就是稍後可以讓我們看到屬性值和我們已經創建好的方法是怎樣用文檔工具（HeaderDoc )被導出的。
讓我介紹一些當你在記錄一個文件時會用到的新標簽：
- @file: 使用這個標簽來指出你正在記錄一個文件（header 文件或不是）。如果你將使用Doxygen來輸出文檔，那麽你最好在這個標簽後面緊接著寫上文件名字。它是一個top level 標簽。
- @header: 跟上面的類似，但是是在 HeaderDoc中使用。當你不使用 Doxygen時，不要使用上面的標簽。
- @author：用它來寫下這個文件的創建者信息
- @copyright: 添加版權信息
- @version: 用它來寫下這個文件的當前版本。如果在工程生命周期中版本信息有影響時這會很重要。
/*!
@header ViewController.h
@brief This is the header file where my super-code is contained.
This file contains the most importnant method and properties decalaration. It‘s parted by two methods in total, which can be used to perform temperature conversions.
@author Your_Name
@copyright 2015 Your_Name
@version 15.12.7
*/
你可以把Your_Name 替換成你自己的名字或者公司的名字。同樣的，使用 brief標簽而不是省略它是很好的習慣，因為它會讓文檔系統（在HeaderDoc 和 Doxygen中稍後將會看到）在輸出的HTML網頁上展示你在這兒添加的簡短描述。同樣的，在這裏你將不會看到剛才說的文檔長什麽樣，但是我們將會在後續輸出HTML文件時展示。
以上的都很棒，但是實事卻是在大多數情況下，你創建的新文件裏由Xcode自動添加的提供信息的默認註釋都非常好而且夠用了。當你在團隊裏同其他人一起協作，並且每個成員必須描述清楚他負責的那些文件的細節信息時，或者當你打算使用 HeaderDoc 來輸出一個工程的完整文檔時，又或者當你是獨立開發者但是工程擁有數量眾多的文件時，你可能想創建一個文件描述塊。不管怎樣，由你自己決定你的文檔系統需要完善到哪個level。
再一次的，我只給出最常用的標簽。自己查看說明文檔了解更多標簽信息。
- @class: 用它來指定一個class的註釋文檔塊的開頭。它是一個top level標簽，在它後面應該給出class名字。
- @interface: 同上
- @protocol: 同上兩個一樣，只是針對protocols
- @superclass: 當前class的superclass
- @classdesign: 用這個標簽來指出你為當前class使用的任何特殊設計模式（例如，你可以提到這個class是不是單例模式或者類似其它的模式）。
- @coclass: 與當前class合作的另外一個class的名字。
- @helps: 當前class幫助的class的名字。
- @helper: 幫助當前class的class名字。
- 在Terminal裏寫下cd 指令然後輸入空格鍵。不要按下回車。
- 在Finder裏，定位到包含工程的根目錄。
- 拖拉這個目錄到terminal下，如下圖所示。
headerdoc2html -o OutputDirectory InputDirectory
OutputDirectory目錄是我們先前創建的目錄，而input目錄是工程文件存在的目錄。
現在，讓我們實際使用它。在terminal窗口，寫下或者復制粘貼下面的指令：
headerdoc2html -o
註意：在-o後面有一個空格符號。
接下來，到Finder中找到將會存儲導出文檔的目錄。按照上面描述的步驟，拖拉目錄到terminal。之後，輸入input目錄地址且在後面加一個/符號。全部指令將會看起來像下面這樣：
headerdoc2html -o /Users/gabriel/Desktop/DocDemo/HeaderDoc DocDemoObjC/
ok,大功告成,接下來去桌面上的HeaderDoc裏面看一看吧,html的文檔已經生成好了.效果圖如下:
使用Xcode生成API文檔---02HeaderDoc