今天博主有一個Xcode生成API文檔的需求,遇到了一些困難點,在此和大家分享,希望能夠共同進步.

今天公司和客戶交接源碼,但是客戶提出不僅需要源碼,還需要相應的技術文檔,今天博主就和大家分享一下,如何使用Xcode生成你的技術文檔.

生成技術文檔主要有三個工具: headerdoc, doxygen 和 appledoc.其中headerdoc是蘋果官方的生成工具,后兩個是第三方工具.如果Xcode版本更新,則需要重新配置第三方工具,個人感覺雖然功能強大,但是配置繁瑣,推薦大家使用headerdoc.

想要生成技術文檔,首先,你要有注釋,沒有注釋是沒法直接生成文檔的,你需要新建pages,慢慢手寫吧

規范的寫好注釋,一可以讓自己不至于忘了自己的代碼,二可以直接生成技術文檔,何樂而不為

用Objective-C創建一個demo app

我們從創建一個使用Objective-C的新工程開始，這工程也是我們將會用來對接下來要看到的東西做測試的。如果你還沒做，打開Xcode然后創建一個新的工程。因為我們不會做一個真的demo應用，選中Single View application 就可以了。

在下一步中，命名工程為DocDemoObjC，在Language下拉菜單中確保選中Objective-C 選項。

文檔化細節

正如你知道的，在Objective-C 中寫一條注釋的最簡單辦法是用兩條斜杠，如下圖展示這樣：

你可以（且必須）像上面那樣來放置你的注釋，以便分清每個部分。但是，當談到代碼注釋文檔，我肯定不是指的上面的注釋。如果整個教程都專注于此肯定毫無意義。注釋文檔意味著以結構化的方法使用特殊的關鍵字，也叫標簽來寫注釋，使用特殊的符號來標示注釋區域，因此編譯器可以完美的理解這個過程。只有一些簡單的規則需要遵守。上面操作的所有結果就是你的注釋文檔可以在三個不同的地方展示：

1. 在Utilities面板的Quick Help Inspector 里。

2. 當你按下Option鍵然后點擊方法，類或屬性名時彈出的幫助菜單 Help Popup 里。

3. 在代碼實現彈出框里。

除此之外，合適的代碼注釋讓你可以使用眾多的工具來為你的應用創建完整的HTML文檔，例如the HeaderDoc 。它們兩個稍后會提到，而且你會看到我剛才所說的是怎樣實現的。

記住上面所說的，是時候更近一步了。當使用Objective-C寫代碼時有三種可能的方法來標示一個注釋文檔區域：

1. 把你的注釋包含在/** – */ 塊里。

2. 把你的注釋包含在 /*! – */塊里。

3. 以三條斜杠 ///開始的注釋行

在這個教程實例中我們將會用第二種方法來寫我們的注釋文檔。我選擇它出于兩個原因：第一，它是唯一一個能被HeaderDoc識別的格式，而且如果注釋塊不是以它開頭，幫助頁也不會被生成。第二，盡管Doxygen更傾向于第一種格式，它也能識別第二種。因此，第二種格式將會在兩種方法下都適用。第三種格式通常在注釋一行時用到，例如屬性值時，因此、，我們還是堅持用第二種格式。

現在，當寫注釋文檔時，你可以使用特定的關鍵值（或標簽）。標簽被分為兩個大類：第一個是 top level 標簽，它可以用來指定哪種類型的代碼被注釋了，例如類，結構體，文件，等等。注意top level標簽不是必須使用，但是肯定會幫助導出工具（例如 HeaderDoc）創建出更好的結果。第二個是second level標簽，它指定了每個注釋文檔塊的細節。這個類型的標簽正是你需要的，因為每一個都定義了另外的注釋文檔部分。

下面我給出了最重要的second level標簽，但是注意了這并不是全部。我們稍后會看到一些 top level標簽。我這里列出來的是最常用到的：

• @brief: 使用它來寫一段你正在文檔化的method, PRoperty, class, file, struct, 或enum的短描述信息。

• @discussion: 用它來寫一段詳盡的描述。如果需要你可以添加換行。

• @param: 通過它你可以描述一個 method 或 function的參數信息。你可以使用多個這種標簽。

• @return: 用它來制定一個 method 或 function的返回值。

• @see: 用它來指明其他相關的 method 或 function。你可以使用多個這種標簽。

• @sa: 同前一條類似。

• @code: 使用這個標簽，你可以在文檔當中嵌入代碼段。當在Help Inspector當中查看文檔時，代碼通過在一個特別的盒子中用一種不同的字體來展示。始終記住在寫的代碼結尾處使用@endcode標簽。

• @remark:在寫文檔時，用它來強調任何關于代碼的特殊之處。

你可以在 這里 （HeaderDoc User Guide）找到包含所有支持的標簽的列表。

注意@符號是每個標簽的前綴。同樣，你也可以在文本中使用特殊字符switches，這樣就可以改變它的類型和格式。例如，Text 以會讓 Text單詞成為黑體，同時Text也會讓 Text 單詞的類型為italic. 有趣的是你也可以把部分文本以代碼形式展現（不是代碼段），如果寫下@cText，當幫助文檔在Xcode上展現時，它會導致展示一個不同的字體格式。

除開上面說的，你也可以替換@符號為反斜杠(/)。那樣的話標簽就會像這樣被展示： /brief, /param, /return,等等。注意@符號常在HeaderDoc里面被使用。在這里我們會在所有地方使用@，因為它在兩個系統中都通用。

Objective-C代碼文檔化

讓我們看看以上我提到的內容是怎樣使用的。打開ViewController.m文件，在類的私有部分中添加下面的屬性：

然后如下面所示添加注釋文檔：

然后到viewDidLoad方法中，開始輸入這個屬性。你將看到在代碼填充彈出框里我們剛剛寫下的注釋就在那里！

而且不僅這樣。當在鍵盤上按住Option 鍵，點擊myName屬性就會讓幫助窗口彈出：

更多的，如果在Utilities面板打開 Help Inspector，你會在那里也找到相同的文檔。

注意在上面的注釋當中@brief  標簽可以被去掉而不會導致任何問題。意味著下面的這條注釋也是有效的：

同樣的，下面的也一樣：

而且下面的這條也一樣：

讓我們來看看第一個怎樣展示文檔方法的簡單示例。此時你必須了解如果你的目標是創建一個HTML文檔，那么只是公有方法（在頭文件里的）的文檔是可見的。無論你在類的私有部分中寫的任何文檔在Xcode幫助文檔里都是可見的，但是任何實現部分都沒有被導出到注釋文檔里。所以，記住這些，現在讓我們在ViewController.h 文件里定義一個公有方法：

很顯然，這個方法將會把華氏度轉換為攝氏度。現在我們來添加注釋文檔：

注意在上面我們使用HTML開關來讓所有包含的文字分別是粗體和斜體。同樣注意我們是怎樣使用@c開關來標識內嵌代碼

為了在Xcode幫助當中查看這個注釋文檔是怎樣展示的，先打開 ViewController.m 文件然后定義這個方法如下：

然后把光標放到方法名上，在Quick Help Inspector里查看：

可以看到Xcode把文檔里的每個部分都格式化的展示出來。在help 彈出窗口里也一樣（option鍵+點擊方法名）：

如果在viewDidLoad 方法中調用這個函數，那么就可以在函數自動填充窗口里看到簡介描述：

很棒，是不是？可以想象你的代碼那樣文檔化后會變得多有幫助且能自我解釋清楚代碼意義，特別是當你同其他團隊人員一起工作時。

為了讓這個例子更加有趣，我們添加另一個公有方法正好可以做相反的事情：把攝氏度轉換為華氏度。打開ViewController.h文件，然后添加下面的方法聲明，以及它的文檔注釋：

在上面段落里我們添加了兩個新的標簽：一對 @code – @endcode標簽和@remark 標簽。你將會馬上看到它們是怎樣展示的。

我們到 ViewController.m文件里去實現這個方法：

現在我們看看Help彈出框如下：

非常漂亮！現在你自己的文檔跟Xcode默認文檔比起來毫不遜色。

在進入下一部分前，打開ViewController.h文件，然后添加下面的屬性聲明（當然也包括注釋）：

同它一起，導入AppDelegate類：

添加上面屬性到類里面的原因就是稍后可以讓我們看到屬性值和我們已經創建好的方法是怎樣用文檔工具（HeaderDoc )被導出的。

讓我介紹一些當你在記錄一個文件時會用到的新標簽：

• @file: 使用這個標簽來指出你正在記錄一個文件（header 文件或不是）。如果你將使用Doxygen來輸出文檔，那么你最好在這個標簽后面緊接著寫上文件名字。它是一個top level 標簽。

• @header: 跟上面的類似，但是是在 HeaderDoc中使用。當你不使用 Doxygen時，不要使用上面的標簽。

• @author：用它來寫下這個文件的創建者信息

• @copyright: 添加版權信息

• @version: 用它來寫下這個文件的當前版本。如果在工程生命周期中版本信息有影響時這會很重要。

當然你還可以使用更多的標簽，但是這些都是最常使用的一部分。我建議你通覽HeaderDoc 文檔，這樣就可以發現一些額外的你想使用的關鍵字。

現在我們來看對ViewController.h 頭文件添加注釋。找到文件的開頭，就在import 命令之前。在那里添加下面的幾行：

你可以把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名字。

使用HeaderDoc生成文檔

現在關于代碼注釋我們已經涵蓋了主要內容，現在進入另一個部分，讓我們看看怎樣創建包含往工程里添加的注釋的HTML文件。在這個部分，我們將使用HeaderDoc，一個與寫入文件里的文檔配合很棒的好工具。我推薦你訪問 這個網站 來了解更多信息。我們將使用HeaderDoc來輸出工程的所有注釋部分到HTML頁面里。小工程這樣做可能沒太大意義，但是對于大型工程或你將為其他人提供自己的SDK時，一個對應的文檔會很有必要。HeaderDoc工具實際上是一個 command-line工具。它提供詳細的不同的分支來配置導出步驟，你可以在上面我提供的鏈接里找到。這里，我們將使用一個分支，那就是很有用的可以指定輸出目錄（保存被導出文檔的目錄）的分支。

我們來看怎么做。首先，為即將被生成的文檔創建一個目錄。為了便于訪問，我在桌面建一個目錄，當然你也可以選擇任何你喜歡的目錄，只要你更新稍后會看到的path路徑。我在桌面上創建了一個DocDemo目錄，并在此添加了一個子目錄：HeaderDoc。每個工具生成的文檔會讓在各自對應的文件夾中。

接下來，你必須打開Terminal，可以點擊LaunchPad > Other group > Terminal,來打開或者在Spotlight下輸入 terminal來打開。

現在，用terminal去定位到你的工程所在的目錄，使用下面幾個簡單步驟就可以達到目的：

1. 在Terminal里寫下cd  指令然后輸入空格鍵。不要按下回車。

2. 在Finder里，定位到包含工程的根目錄。

3. 拖拉這個目錄到terminal下，如下圖所示。

然后點擊回車鍵，為了確保你在正確的目錄下可以使用pwd 指令（始終在terminal中）

在這里我們要使用的HeaderDo指令叫做headerdoc2html，指令格式如下：

OutputDirectory目錄是我們先前創建的目錄，而input目錄是工程文件存在的目錄。

現在，讓我們實際使用它。在terminal窗口，寫下或者復制粘貼下面的指令：

注意：在-o后面有一個空格符號。

接下來，到Finder中找到將會存儲導出文檔的目錄。按照上面描述的步驟，拖拉目錄到terminal。之后，輸入input目錄地址且在后面加一個/符號。全部指令將會看起來像下面這樣：

 ok,大功告成,接下來去桌面上的HeaderDoc里面看一看吧,html的文檔已經生成好了.效果圖如下: