您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 訊息 >> iOS 相關資訊

用 HeaderDoc 與 Doxygen 為 Objective-C 與 Swift 程式碼寫文件

編輯:iOS 相關資訊

本文由 CocoaChina 譯者 YueWang 翻譯自 AppCoda,原文標題為 Documenting Your Objective-C and Swift Code in Xcode with HeaderDoc and Doxygen。

一個 App 從誕生到上線,要經過需求說明、美術素材、功能實作、測試等無數環節。寫程式碼或許佔了其中最大的比例,但同等重要的還有註解與文件。程式碼寫得再好,若缺乏對應的說明,六個月後回頭看很可能一頭霧水。

為什麼要寫程式碼註解

如果你是唯一開發者,很容易說服自己「寫文件太花時間,先跳過」。但這往往是整個開發週期中最糟的決定。假設 App 順利上線,半年後你要加幾個新功能做次版本,當你重新打開專案、準備寫下第一行新程式碼之前,會意識到一個殘酷的事實:你幾乎什麼都不記得了。做過什麼、怎麼做的、為什麼這樣做,全都需要重新「解密」自己的實作程式碼。幾行零散註解根本幫不上忙,最終你會耗掉大量時間與精力,甚至想直接從頭重寫。

如果你身處團隊之中,跳過註解更是災難。分享程式碼時你必須在裡頭解釋自己的思路:做了什麼、怎麼做、為什麼。每個程式員的風格都不同,把意圖寫清楚是團隊協作的基本禮貌,也能省下大量口頭交接的成本。

重點是:寫程式碼的時候就把文件一起寫掉。這樣無論是自己還是他人回頭修改,成本都最低。

建立 Objective-C Demo 專案

開啟 Xcode 建立新專案,選擇 Single View Application,命名為 DocDemoObjC,語言選 Objective-C,選一個目錄保存。

註解文件的標記方式

最簡單的註解是兩條斜線:

// This is a comment.

但「註解文件」指的是用結構化的特殊標籤撰寫、並以特定符號標示區塊,讓編譯器與文件工具能理解。完成後,你的註解會出現在三個地方:

  1. Utilities 面板的 Quick Help Inspector。
  2. 按住 Option 並點擊方法、類別或屬性時彈出的 Help Popup。
  3. 程式碼自動補全的下拉清單中。

此外,規範的註解讓你能用 HeaderDoc 與 Doxygen 這類工具產生完整的 HTML 文件。

在 Objective-C 中,標示註解文件區塊有三種寫法:

  1. 包在 /** – */ 區塊裡。
  2. 包在 /*! – */ 區塊裡。
  3. 以三條斜線 /// 開頭的單行註解。

本文採用第二種。原因有三:/*! */ 是唯一能被 HeaderDoc 正確識別的格式;Doxygen 雖然偏好第一種,但同樣支援第二種,因此兩邊都能通用;第三種則通常用於屬性等單行說明。

常用標籤

標籤分成兩大類。top level 標籤用來標示被註解的物件類型(類別、結構、檔案等),非必填,但會讓輸出結果更完整。second level 標籤則描述各個細節段落,是最實用的一組:

  • @brief:一段簡短描述。
  • @discussion:詳細描述,可換行。
  • @param:描述方法或函數的參數,可重複使用多個。
  • @return:描述回傳值。
  • @see / @sa:指向其他相關方法或函數。
  • @code … @endcode:嵌入程式碼片段,會以不同字體包在特殊方塊中呈現。
  • @remark:強調程式碼中值得注意之處。

每個標籤都以 @ 為前綴,也可以換成反斜線 /(Doxygen 風格)。另外還能用文字切換符改變樣式,例如 @c text 會讓 text 以程式碼字型呈現。本文統一使用 @,因為它在兩套工具中都通用。

為屬性與方法寫註解

在 ViewController.m 的類別擴充中加一個屬性並寫上註解:

/*! @brief This property knows my name. */
@property (nonatomic, strong) NSString *myName;

回到 viewDidLoad 開始輸入這個屬性,就會看到剛寫的說明出現在自動補清清單裡。

按住 Option 並點擊 myName,Help 視窗會直接彈出:

在 Utilities 面板開啟 Quick Help Inspector,也能看到同樣內容:

值得留意的是,@brief 標籤其實可以省略而不影響顯示,也就是說下面幾種寫法都有效:

/*! This property knows my name. */
/** This property knows my name. */
/// This property knows my name.

接著看方法的例子。要注意:若要輸出 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 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;

在 .m 中實作它:

- (float)toCelcius:(float)fromFahrenheit {
    return (fromFahrenheit - 32) / 1.8;
}

把游標停在方法名上,Quick Help Inspector 會把各段落格式化呈現:

Option + 點擊的 Help 彈出視窗內容相同:

在 viewDidLoad 中呼叫時,簡短描述也會出現在補清清單裡:

再加一個反向轉換的方法,示範 @code 與 @remark:

/*! @brief It converts temperature degrees from Celsius to Fahrenheit scale.

@param fromCelcius The celsius degrees value.
@return float The degrees in the Fahrenheit scale.

@code
float f = [self toCelsius:80];
@endcode

@remark This is a super-easy method.
*/
- (float)toFahrenheit:(float)fromCelcius;

Option + 點擊後,Help 彈出視窗會把程式碼片段獨立框起來,備註也另外成段:

寫到這個程度,你自己的文件在觀感上已經與 Xcode 內建文件沒有差別了。

為檔案、類別、結構與列舉寫註解

檔案層級的註解在分享程式碼或對外發布 SDK 時是必須的,因為這是最適合交代整體資訊的位置。常用的標籤有:

  • @file:標示這是一份檔案註解(Doxygen 建議在後面接檔名)。
  • @header:HeaderDoc 的對應寫法。
  • @author:作者資訊。
  • @copyright:版權聲明。
  • @version:目前版本。

放在 import 之前即可。使用 @brief 而非省略它是好習慣,因為文件工具會把它當成輸出頁面上的簡短摘要。

多數情況下 Xcode 自動產生的檔案註解模板已經堪用;但若是團隊協作、或專案檔案數量龐大、或你要輸出完整文件,就值得自己寫一份。

類別與 protocol 常用標籤:@class(後接類別名)、@interface、@protocol、@superclass、@classdesign(說明使用了何種設計模式,例如單例)、@coclass、@helps、@helper。實務上除了 superclass 之外較少用到,而且從 superclass 起的這幾個標籤只有 HeaderDoc 認得,Doxygen 不支援。

把游標移到類別名上並 Option + 點擊,就能看到描述。標籤本身不會顯示,只呈現數值:

宣告該類別的物件時,簡介也會出現在補清清單中:

protocol 的寫法相同:

這裡刻意宣告了一個 delegate 方法——它現在看不出意義,但匯出 HTML 文件時就會派上用場。

結構與列舉 在 HeaderDoc 中使用 @typedef 作為 top level 標籤;若改用 Doxygen,結構該用 @struct、列舉該用 @enum。結構内部的每個欄位可用 @field 描述,但這個標籤只有 HeaderDoc 支援;在 Doxygen 中要改成針對每個變數各自寫一段註解。

把結構應用到實作中,輸入任一欄位名稱時,說明就會出現在補清清單裡。列舉的做法完全相同,可以作為練習。

讓 Xcode 幫你抓出打錯的參數名

在 @param 後面必須寫出變數名稱,名稱一多就容易打錯,而錯的參數名不會有任何提示——除非你開啟一個設定。

在 Project Navigator 點選專案,切到 Build Settings,搜尋 comments 關鍵字,找到名為 Documentation Comments 的項目,把預設值從 NO 改為 YES。

設定完成後,若 @param 後的變數名與方法簽名不符,Xcode 會立刻跳警告,並在點擊警告時建議正確名稱,一鍵即可修正。以 targetcityName(缺少大寫 C)為例,這種錯誤在文件量大的專案裡幾乎必然發生,有了這道防線就再也不必擔心。

用 HeaderDoc 輸出 HTML 文件

HeaderDoc 是與檔案內註解搭配得非常好的命令列工具,能將專案所有註解輸出成 HTML 頁面。小專案用不太上,但大型專案或對外提供 SDK 時就非常必要。

先建立輸出的目錄。這裡在桌面建立 DocDemo 資料夾,並在裡面開 HeaderDoc 與 Doxygen 兩個子目錄,讓兩套工具的產物各自歸位。

開啟 Terminal,用幾個簡單步驟切換到專案目錄:

  1. 在 Terminal 輸入 cd 加一個空格,不要按 Enter。
  2. 在 Finder 中找到專案根目錄。
  3. 把該目錄直接拖進 Terminal 視窗。

按 Enter,並用 pwd 確認路徑正確。接著執行 headerdoc2html,其格式為 headerdoc2html -o 輸出目錄 輸入目錄(注意 -o 後有一個空格)。同樣用「拖資料夾進 Terminal」的方式填入路徑即可。

執行後畫面會滾動大量訊息,不必理會。完成後再執行 gatherheaderdoc 並貼上輸出目錄路徑,它會產生一份總目錄頁,把所有註解過的檔案、類別與方法彙整在同一處。

最後到 Finder 用瀏覽器打開 masterTOC.html:

點進 ViewController,會看到檔案描述、類別、protocol、結構的清單與簡短說明:

若某段內容重複出現(例如結構欄位既寫了 @field 又在上方各自註解),回 Xcode 刪掉其中一種再重新執行即可。點進類別頁面,則能看到描述、兩個方法與一個屬性的完整說明:

改用 Doxygen 輸出文件

Doxygen 並非一開始就為 Objective-C 設計,但它在 C 與 C++ 上表現優異,也支援大量其他語言。它提供的標籤比 HeaderDoc 更多,相容性更好,缺點是需要另外下載安裝。

官方網站左側的選單彙整了各部分的說明與 how-to,值得先瀏覽一遍。

下載 Mac 版本(約 55MB),解壓後把 Doxygen 拖進 Applications 目錄即可。它是完全自包含在單一 App 內的工具,放哪裡都行,移除時只要刪掉那個 App。若遇到「來自未認證開發者」的攔阻提示,在 Finder 中按住 Ctrl 點擊該 App,選擇 Open 再確認一次即可。

切換工具前,Xcode 端需要小改兩處:把檔案註解中的 @header 換成 @file,並把結構註解的 @typedef 換成 @struct。

Doxygen 提供兩種模式:Wizard 模式簡單直覺,Expert 模式則能指定大量細節設定。由於細節高度取決於個人需求,這裡聚焦 Wizard 模式,但值得先看看 Expert 模式——主面板往下滑會看到大量可調項目,左側 Topics 清單裡每個主題還有各自的設定頁。

回到 Wizard 模式,依序完成:點 Select 指定 Doxygen 應用所在目錄;在 Project Name 填入 DocDemo in Objective-C;指定專案路徑並勾選 Scan recursively 讓它掃描子目錄;最後把 Destination Directory 設為稍早在桌面建立的 Doxygen 子目錄。

在左側 Topics 選 Mode,把選項設為 All Entities:

再選 Output,這裡可以決定輸出格式。本例只保留 HTML、關掉 LaTeX:

Diagrams 保留預設即可。設定確認無誤後,點 Run,再點主區域出現的 Run doxygen 按鈕開始產生文件,白色區域會顯示執行訊息與錯誤。

完成後到輸出目錄用瀏覽器打開 index.html(或在 Doxygen 中直接點 Show HTML output):

首頁只放了專案名稱、產生時間與一排連結。點 Classes 會列出所有類別,每個旁邊都有我們寫的簡短描述:

點進 ViewController,能看到方法與公開屬性的完整文件:

Files 頁面則列出所有被分析過的檔案,選 ViewController.h 可看到檔案描述與其中宣告的所有型別:

點 More… 展開細節,還有一個「Go to the source code of this file」連結能直接跳到該檔案的程式碼。要注意的是,只有頭文件中的公開內容會被呈現,實作檔的內容不會出現——那是「專屬於你」的部分。

Swift 的註解文件

接著換成 Swift 專案:建立新的 Single View Application,命名 DocDemoSwift,語言選 Swift。

Swift 的註解文件能力目前不如 Objective-C 完整,HeaderDoc 與 Doxygen 都不支援 Swift,現行格式基於 reStructuredText。

先前介紹的標籤裡,只有 :param: 與 :return: 可用(注意結尾的 s),而且不用 @ 或反斜線,而是用冒號包住標籤名稱,後面接變數名與描述。@brief 與 @discussion 不存在,取而代之的規則是:註解區塊開頭的簡短文字就是簡介,之後較長的段落則是詳細描述。

在描述段落中還能加入有序與無序清單:

/**
 1. 第一個項目
 2. 第二個項目
 */

/**
 * 項目一
 * 項目二
 */

/**
 - 項目一
 - 項目二
 */

熟悉 Markdown 語法的人會覺得似曾相識。若要加入欄位說明,寫下被冒號包住的欄位名再接描述即可。

實作看看。在 ViewController.swift 定義方法並寫上註解(這裡使用 /** – */ 標記):

在 viewDidLoad 中輸入方法名,簡短描述同樣會出現在補清清單:

再宣告一個什麼都不做的方法,示範清單與欄位說明,Option + 點擊後的呈現如下:

這些大致就是撰寫 Swift 註解文件所需的一切。若想知道更多,可以查閱 reStructuredText 的手冊——它的功能相當廣泛。

總結

本文走過了程式碼註解的各個主要環節:Objective-C 與 Swift 的標記差異、常用標籤、如何為屬性、方法、檔案、類別、結構與列舉撰寫說明,以及 HeaderDoc 與 Doxygen 兩套輸出工具的操作流程。

Objective-C 的選項明顯更多,但這些工具面對 Swift 時同樣堪用。本文涵蓋的並非全部,還有大量標籤與設定值得你自己發掘,目標只是帶你掌握最常用、涵蓋九成情境的做法。

最後仍要強調:為程式碼寫註解是極重要的工作。你可能會不時懷疑它的價值,但在這上面花的每一秒都是值得的——它同時在幫現在的你和未來的你,以及所有接手這份程式碼的人。

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved