
本文由 CocoaChina 譯者 YueWang 翻譯自 AppCoda。原文:Documenting Your Objective-C and Swift Code in Xcode with HeaderDoc and Doxygen
一個 App 從無到有要經過無數環節:需求說明、美術素材、功能實作、上線前的測試。寫程式碼大概佔了其中最大一塊,因為正是它賦予 App 生命——但光有程式碼並不夠,與它同等重要的是註解與文件。程式碼寫得再好,若缺少對應的說明,日後很可能變成燙手山芋。不幸的是,許多開發者忽略或低估了文件的重要性,而這非常可惜,因為好軟體從來不只是好程式碼而已。
談到寫註解文件,顯然不是指在實作檔案裡隨手加幾行註解而已,那背後有更多東西。先問一個問題:為什麼註解這麼重要?這裡有兩種情境——你是獨立開發者,或者你是團隊的一員。
如果你是唯一的開發者,很容易說服自己「寫文件很花時間,跳過能更快交付」。但相信我,這會是整個開發週期裡最糟的決定之一。假設你順利完成並交付了 App,把它封存起來。六個月後,你需要加上幾個新功能、推出新版本。當你重新打開專案、瀏覽既有程式碼時,會意識到一個殘酷的事實:你幾乎什麼都不記得了!做過什麼、怎麼做的、為什麼要那樣做,全都想不起來。你只能沿著最痛苦的路線,一行行「解密」自己的實作,直到重新理解全部邏輯——耗時又耗神。讀到這裡的人大概不少都有過這種經歷,我也一樣。那簡直是噩夢,那時你甚至會想乾脆重寫一個專案算了。而避免這一切,只需要一點點寫合適註解文件的習慣。
另一方面,如果你身處團隊,略過文件幾乎是災難性的。當你把程式碼交給其他開發者時,你必須在程式碼裡說明自己的思路:當時做了什麼、怎麼做、為什麼這樣做,其他人也一樣。沒有一個情境是「專案裡所有開發者都完全理解彼此寫的程式碼」,因為那會浪費大量不必要的時間。所以此時的註解一方面像溝通,另一方面是幫團隊其他成員理解你的意圖。畢竟每個工程師的風格都不同,把你的程式碼講清楚是必須完成的功課。
希望觀點表達清楚了。接著談談跨語言、跨平台通用的寫作習慣:無論你寫 iOS、Web 還是桌面應用,重點都是在寫程式碼的當下就把文件寫好,這樣後續(你或他人)修改時會輕鬆很多。
本教程會聚焦程式碼註解文件中最關鍵的部分,同時涵蓋 Objective-C 與 Swift——這兩種語言都有大量開發者在用,我也會指出它們的相似與差異。此外我會示範如何產出完整的網頁版文件,不過要先坦白說:這部分目前只有 Objective-C 支援。
作為 Xcode 使用者,你可能以為兩種語言的註解寫法一致。事實並非如此:與 Objective-C 相比,Swift 支援的標籤少得多(至少在我寫這篇文章時如此)。但兩者都提供了足夠的「彈藥」,讓你寫出優秀的註解。我們會從 Objective-C 開始,因為它能講的東西更多,最後再談 Swift。
開始之前提醒兩件事:第一,我不是要你把寫文件變成一種強迫症,而是想說服你——合適的註解確實能提升你的開發品質;第二,寫程式碼文件是必須養成的習慣,絕對不是浪費時間。
先建立一個 Objective-C 專案作為後續的試驗場。打開 Xcode 新增專案,因為我們不做真正的 Demo,選擇 Single View Application 即可。下一步把專案命名為 DocDemoObjC,並確認 Language 下拉選單選的是 Objective-C。

最後選擇硬碟上的儲存位置,完成建立。
在 Objective-C 與 Swift 中寫註解最簡單的方式是用兩條斜線:
// This is a comment.
你當然可以(也應該)這樣分區說明。但程式碼「文件」指的不是這種註解,否則整篇教程就沒有意義了。真正的文件化,是用結構化的方式搭配特殊關鍵字(標籤)與特定符號來標示註解區塊,讓工具能正確解析。規則並不多,而成果會出現在三個地方:
除此之外,規範的註解讓你能用 HeaderDoc、Doxygen 等工具為專案產出完整的 HTML 文件。
在 Objective-C 中,標示文件區塊有三種寫法:
/** – */ 區塊裡;/*! – */ 區塊裡;/// 開頭的單行註解。本教程採用第二種。原因有三:它是唯一能被 HeaderDoc 正確識別的格式,否則不會產生說明頁;Doxygen 雖然偏好第一種,但同樣能識別第二種,所以這格式在兩套工具下都通用;第三種通常用於單行註解(例如屬性說明),因此我們仍舊以第二種為主。
寫文件時可以使用特定關鍵字(標籤)。標籤分兩大類:top level 標籤用來標示被註解的是哪一類程式碼(類別、結構、檔案等),它並非必填,但確實能讓 HeaderDoc、Doxygen 產出更好的結果;second level 標籤則描述每個區塊的細節,這才是你真正需要的部分。
以下是最常用的 second level 標籤(並非全部):
完整支援標籤清單可查閱 HeaderDoc User Guide。每個標籤前都要加上 @ 前綴。你也可以在文字中使用格式開關,例如 ab Text 讓 Text 變粗體、abi Text 讓它變斜體;更有趣的是 @cText 會讓部分文字以程式碼字型呈現(注意這與程式碼片段不同)。
此外,@ 符號可以替換成反斜線(\),寫成 \brief、\param、\return 等。實務上反斜線多見於 Doxygen 體系,@ 多見於 HeaderDoc;由於 @ 在兩套系統中都通用,本文一律使用 @。
打開 ViewController.m,在類別的私有區塊加入一個屬性:
@interface ViewController () @property (nonatomic, strong) NSString *myName; @end
接著加上文件註解:
/*! @brief This property knows my name. */ @property (nonatomic, strong) NSString *myName;
然後在 viewDidLoad 中開始輸入這個屬性,你會看到自動補全清單裡出現了我們剛寫的說明!

而且不只如此。按住 Option 並點擊 myName,說明視窗就會彈出:

若在 Utilities 面板打開 Help Inspector,也能看到同一份文件。

要注意的是,@brief 標籤其實可以省略而不影響運作,以下寫法同樣有效:
/*! 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;注意我們用格式開關讓部分文字變成粗體與斜體,並用 @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.
@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;這裡多了兩個新標籤:@code – @endcode 一對,以及 @remark。接著到 ViewController.m 實作:
-(float)toFahrenheit:(float)fromCelcius {
return fromCelcius * 1.8 + 32;
}現在看 Help 彈出視窗的呈現:

非常漂亮——你自己寫的文件跟 Xcode 官方文件的質感已經不相上下。
進入下一部分前,在 ViewController.h 加入一個屬性宣告(同樣附上註解):
/*! An application delegate object. */ @property (nonatomic, strong) AppDelegate *appDelegate;
並記得引入 AppDelegate 類別。加上它的目的,是稍後要示範屬性與方法如何被 HeaderDoc 與 Doxygen 匯出。
前面我們看了屬性與方法的寫法,之所以從這裡開始,是因為大部分開發時間都花在這兩者上。現在來看檔案、類別、結構與列舉的註解方式。
先談檔案。當你與他人協作,或以開源元件形式散布程式碼時,檔案層級的說明是必須的——這是最適合向夥伴或使用者傳達明確資訊的位置。通常你會更關注標頭檔(.h)裡的描述,因為它會保留在最終匯出的文件中;但這不代表實作檔就不需要說明。不要忘記在 Xcode 中打開專案時,所有內容都在眼前,因此別留下沒有文件的部分。實作內容不會出現在匯出文件裡,但檔案層級的描述始終可見。
寫檔案說明時會用到的新標籤:
當然還有更多標籤,建議通讀 HeaderDoc 或 Doxygen 文件,找出你想用的關鍵字。
現在為 ViewController.h 加上註解,位置在檔案開頭、import 之前:
/*! @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 標籤而不是省略,因為它會讓文件系統在輸出的 HTML 頁面上顯示這段簡述。同樣地,Doxygen 裡可以用反斜線取代 @。
實務上,多數情況下 Xcode 為新檔案自動生成的預設註解已經夠用。但當你在團隊中協作、每位成員都需要描述自己負責的檔案時,或者你準備用 HeaderDoc/Doxygen 輸出完整專案文件時,又或者你是獨立開發者但專案檔案數量龐大時,就值得建立完整的檔案描述區塊。究竟要做到多細,由你自己決定。
接著看類別與協定的註解。同樣只列出最常用的標籤:
實務上除了 superclass,上面這些標籤幾乎用不到。可用標籤清單很長,但列更多意義不大。要特別注意:從 superclass 開始往下,這些標籤都只有 HeaderDoc 能識別,Doxygen 不支援。另外,在 Xcode 的 Quick Help 與 Help Popup 中,呈現的是標籤旁的值,標籤本身不會顯示。所以用不用、用哪一套,取決於你採用哪個文件系統。
/*!
@class ViewController
@brief The ViewController class
@discussion
This class was designed and implemented to help people covert temperatures
between the Fahrenheit and Celsius scales.
@superclass SuperClass: UIViewController
@classdesign No special design is applied here.
@coclass AppDelegate
@helps It helps no other classes.
@helper No helper exists for this class.
*/把游標移到 ViewController 類別名稱上,或按住 Option 點擊它,就會在 Xcode 說明視窗中看到上述描述。

可以看到標籤本身都沒有顯示,在這種情況下並無影響。
更實用的是:當你宣告這個類別的物件時,也能看到類別簡述。打開 ViewController.m 並定位到 viewDidLoad,宣告一個本地 ViewController 物件,自動補全清單裡就會出現類別簡介。

協定的註解方式相同。在 ViewController.h 開頭加上:
/*!
@protocol ViewControllerDelegate
@brief The ViewControllerDelegate protocol
It's a protocol used as a demo here. In a real application it would be quite useful.
*/
@protocol ViewControllerDelegate
/*!
Nothing to say here... Just testing documentation.
*/
-(void)thisIsADelegateMethod;
@end按住 Option 並點擊協定名稱,註解就會顯示在 Help 彈出視窗中。

我們同時宣告了一個協定方法,看起來沒意義,但這是刻意的示範——當我們用 HeaderDoc 與 Doxygen 匯出文件時,就會在頁面上看到它。
最後看結構與列舉。兩者的共同點是都用 @typedef 這個 top level 標籤來標示區塊開頭(再提醒一次,top level 標籤純屬自願)。特別是對 Doxygen 而言:不用 @typedef 的話,結構該用 @struct,列舉該用 @enum。
在 ViewController.h 的 interface 之前加入結構定義:
typedef struct {
int sun;
int clouds;
int rain;
int snow;
} WeatherConditionsInDays;並在前面加上註解:
/*! @typedef WeatherConditionsInDays @brief A struct about the weather. @discussion The values of this structure represent how many sunny, cloudy, rainy, and snowy days existed over the last year. If this was a real app, they could be perfectly used. @field sun Good weather @field clouds Where's the sun? @field rain Get an umbrella @field snow Watch out... A snowball is coming! */
這裡出現了新標籤 @field,用來描述結構中的每一個變數。此處又見 HeaderDoc 與 Doxygen 的差異:HeaderDoc 接受 @field,Doxygen 則不支援。若使用 Doxygen,做法是針對每個變數分別寫註解,這樣在實作檔中使用時也能看到各自的說明:
/*! @typedef WeatherConditionsInDays
@brief A struct about the weather.
@discussion ...
@field sun Good weather
...
*/
typedef struct {
/*! Good weather */
int sun;
/*! At least it's not raining */
int clouds;
/*! Don't forget to get your umbrella */
int rain;
/*! Time to go skiiiiiing */
int snow;
} WeatherConditionsInDays;現在到 ViewController.m 定義一個這個結構的變數,輸入其中任一成員,彈出視窗就會顯示它的描述。列舉的做法完全一樣,就當作練習留給你:建立一個 enum 並寫上註解,然後到 viewDidLoad 中確認說明是否出現在 Xcode 的說明選項裡。
前面的例子可以看到,@param 標籤旁必須先寫變數名稱,再寫描述。變數名一旦打錯(特別是名稱較長時)就會產生錯誤文件。好消息是 Xcode 可以在這時成為你的可靠助手。
在 Project Navigator 中點擊專案,找到 Build Settings 標籤:

在搜尋框輸入 comments,等結果出現後找到名為 Documentation Comments 的設定項,其預設值通常是 NO。把它的值改成 YES,一切就準備好了。

現在來看這個設定如何幫上忙。打開 ViewController.m,在私有類別中宣告一個私有方法:
@interface ViewController () -(float)showCurrentTemperatureInCity:(NSString *)targetCityName showInScale:(NSString *)preferredScale; @end
這個方法會傳回指定城市的天氣值,單位是先前提到的華氏或攝氏。在它之前加上註解:
/*!
This method returns the current temperature in the selected city, expressed in either
Fahrenheit or Celsious degrees.
@param targetcityName The city that the temperature will be returned for.
@param preferredScale Fahrenheit or Celsius.
@return float The current temperature of the city.
*/
-(float)showCurrentTemperatureInCity:(NSString *)targetCityName showInScale:(NSString *)preferredScale;把這段貼進 Xcode 後,第一個參數註解處立刻會出現警告:方法宣告中找不到變數名 targetcityName。猜怎麼著?這是對的——我故意(也是不小心的)把 city 的首字母沒大寫,寫成了 targetcityName。這正是大型專案裡最容易被忽略的疏漏,幸好 Xcode 給了我們「另一雙眼」。
點擊警告欄左側的三角圖示,Xcode 會建議正確的變數名,點一下即可修正,當然你也可以自己改。

有了這道防線,再也不必擔心寫文件時打錯變數名。
關於註解我們已涵蓋主要內容,接著看怎麼把這些註解變成 HTML 檔案。這部分使用 HeaderDoc,它與寫在檔案中的文件搭配得非常好。HeaderDoc 其實是一個命令列工具,提供大量參數來配置匯出流程;這裡我們只用一個最實用的參數——指定輸出目錄。
首先為即將產生的文件建立一個目錄。為了方便,我在桌面建了 DocDemo 資料夾,並在其中加了 HeaderDoc 與 Doxygen 兩個子目錄,兩套工具的文件各自輸出到對應資料夾。

接著打開 Terminal,可以從 LaunchPad > Other 群組 > Terminal 開啟,或在 Spotlight 輸入 terminal。

現在用 Terminal 定位到專案所在目錄,步驟很簡單:
cd 並按一個空格,不要按 Enter。
按 Enter 後,可以用 pwd 指令確認自己是否在正確的目錄下。
我們要用的 HeaderDoc 指令叫 headerdoc2html,格式如下:
headerdoc2html -o OutputDirectory InputDirectory
OutputDirectory 是我們先前建立的目錄,InputDirectory 則是專案檔案所在目錄。實際操作時,在 Terminal 輸入:
headerdoc2html -o
注意:-o 後面要有一個空格。接著到 Finder 找到儲存匯出文件的目錄,用同樣的拖曳方式帶進 Terminal,然後輸入輸入目錄路徑並在後面加上一個 / 符號。完整指令看起來像這樣:
headerdoc2html -o /Users/gabriel/Desktop/DocDemo/HeaderDoc DocDemoObjC/

畫面會滾動出大量訊息,此時不必特別留意。等它執行完畢,把輸出目錄路徑複製下來,在 Terminal 輸入:
gatherheaderdoc
然後貼上路徑並按 Enter。這個指令會產生一個目錄頁,讓所有註解過的檔案、類別與方法集中呈現。
完成後到 Finder 用瀏覽器打開 masterTOC.html,你會看到類似下圖的內容:

點擊 ViewController 連結,會被導引到這個頁面:

這裡能看到檔案描述、類別、協定與結構,以及它們的連結與簡述。同一頁面上也會顯示結構的詳細資訊。

注意有一部分出現了重複的值,那是因為我們同時用了 @field 標籤,又在每個結構變數上方寫了註解。若覺得多餘,可以回到 Xcode 刪掉其中一種,再重新執行 HeaderDoc 指令。
點擊類別連結會跳到新頁面,這裡可以看到類別描述,以及標頭檔中宣告的兩個方法與一個屬性。

接下來隨意瀏覽各個區塊,看看所有內容是如何被呈現的。HeaderDoc 的能力遠不止於此,但這些在絕大多數場景下已經足夠。
接著換用另一套廣為流傳的註解系統:Doxygen。先說明一件事——Doxygen 最初並不是為 Objective-C 設計的,但它處理 C 與 C++ 的表現堪称完美,而且支援的語言非常多。此外它提供的標籤數量遠多於 HeaderDoc,若你決定採用它,可以靈活搭配以獲得更好的相容性。
Doxygen 是第三方應用,使用前必須下載。它對各大作業系統都有對應版本,因此並不限於 iOS 開發。這裡有三個重要連結:程式碼註解的所有資源說明、支援標籤的完整清單(點擊每個標籤可看用途),以及應用程式下載頁。
在 Doxygen 官網上你能找到遠比本文豐富的內容——如截圖所示,左側有一個選單面板,可以瀏覽各個章節、細節與 how-to。

前往下載頁後,滑到頁面下方找到名為「A binary distribution for Mac OS X 10.5 and later」的區塊,點擊 ftp 或 http 連結開始下載。依網速不同,大約 55Mb 的檔案可能需要幾秒到幾十秒。
下載完成後打開壓縮檔,找到 Doxygen 應用並拖進 Applications 目錄。不一定要放這裡——Doxygen 是完全自包含的應用,放在任何位置都可以,移除時只要刪掉它的 App 檔案即可。
假設你已複製到目錄中,從 LaunchPad 找到並啟動它。注意:如果系統提示「應用程式來自未認證的開發者而無法開啟」,可以在 Finder 中打開 Applications 目錄,找到 Doxygen,按住 Ctrl 並點擊它,在選單中選擇 Open,然後在新的視窗中再按一次 Open。
先把 Doxygen 放一邊,回到 Xcode。我們要調整兩處標籤,讓所有內容都能被正確識別:請確認 ViewController.h 已打開,把描述區塊中的 @header top level 標籤替換為 @file;另外,結構註解區塊中的 @typedef 都要改成 @struct。完成後離開 Xcode。
Doxygen 首次啟動時的初始視窗如下:

Doxygen 提供兩種使用模式:Wizard 模式由簡單通用的步驟組成;Expert 模式則可指定大量設定,讓你針對輸出文件的每個細節做高度客製。
本文不深入 Expert 模式,因為要套用哪些設定高度取決於個人需求。在主視圖區域點擊 Expert 按鈕,你會立刻看到大量可調參數,而且左側的 Topics 面板還能切換到各自的設定群組,有時間的話值得全部瀏覽一遍,你會找到不少實用選項。
接下來把焦點放回 Wizard 模式。首先在視窗頂端指定 Doxygen 程式的位置:點擊 Select 按鈕,選擇你放置 Doxygen 應用的目錄。
接著指定專案名稱,在 Project Name 欄位輸入 DocDemo in Objective-C(或任何你想要的名稱),下方欄位也可以自由填寫。其下要指定專案路徑,同樣用 Select 按鈕定位到專案根目錄,並建議勾選 Scan recursively,讓 Doxygen 一併掃描所有子目錄。
最後指定文件輸出的位置——也就是我們先前在桌面 DocDemo 目錄下建立的 Doxygen 子目錄,點擊 Destination Directory 旁的 Select 按鈕選取它。

接著在左側 Topics 清單中選擇 Mode,在新的設定區中勾選 All Entities:

同樣在 Topics 清單中選擇 Output,這裡有許多匯出格式可選。本範例中我關閉了 LaTeX,只保留 HTML:

最後,Diagrams 選項保留預設即可。
現在可以輸出文件了。請確認前述設定都已就緒,然後點擊 Run 按鈕(位於 Wizard 與 Expert 按鈕旁),主視圖區會出現一個名為 Run doxygen 的新按鈕,點擊它讓程式開始建立 HTML。白色區域會顯示輸出訊息,若有錯誤也會呈現在這裡。
執行完畢後打開 Finder 定位到輸出目錄,你會看到一系列檔案被建立,其中要找的目標是 index.html,雙擊用瀏覽器打開即可。若不想手動翻資料夾,也可以直接在 Doxygen 視窗中點擊 Show HTML output。
這是打開 index 頁面時看到的第一個畫面:

它只包含我們先前設定的專案名稱、產生時間,以及頂部的一排連結。用這些連結瀏覽各個區塊——例如點擊 Classes,就會得到專案中所有類別的清單,每個類別旁還附有簡短描述(僅限我們寫過的那些)。

點擊 ViewController 類別時會看到:

專案中的方法與那個公開屬性的詳細文件都在這裡。另一個有趣的地方是 Files 選單——所有被分析過的檔案都會列出,選中 ViewController.h 後,可以看到檔案描述以及我們宣告的所有內容:類別、協定與結構。

點擊 More… 連結可查看更多細節。還有一個名為「Go to the source code of this file.」的連結,點擊後會展示 ViewController.h 的程式碼——注意,標頭檔中任何 public 內容都會呈現於此,但別期待看到實作程式碼,那部分「只屬於你」。

到這裡,你應該已經對整個流程有了概念。可以定位到輸出的 HTML 頁面,回到 Xcode 修改註解內容,然後重新匯出全部文件。也別猶豫去調整進階設定看看會發生什麼——不論專案大小,Doxygen 都是個很棒的工具,多試幾次就會越來越熟。
接著翻開新的一頁,談談 Swift 程式碼的文件化。為了讓事情盡可能清晰,我們再建立一個新專案,這次使用 Swift。在 Xcode 的第一步中選擇 Single View Application 模板,命名為 DocDemoSwift,並確認語言選的是 Swift,最後選擇儲存路徑。
Swift 的註解文件能力比 Objective-C 弱,原因我放到最後再說。不幸的是,HeaderDoc 與 Doxygen 目前都不支援 Swift(至少此刻如此,未來難說),現行的文件格式基於 reStructuredText——這是一個開源專案,可查到更多資訊。
本文先前介紹的標籤裡,只有兩個能在 Swift 中使用:param 與 return(注意結尾的 s)。此外,@ 與反斜線 \ 都不支援,取而代之的是把標籤包在冒號中,例如 :param:,之後寫變數名,再寫描述。
brief 與 discussion 標籤不存在,但對應位置仍可照常寫文件:區塊最開頭的簡短文字會被當成簡介,後續較長的內容則被視為詳細描述。
這裡有個有趣的新能力:在描述區塊中,你可以加入有序與無序清單。有順序的清單這樣寫:
1. First item 2. Second item 3. Third item
無序清單則可用星號(*)或破折號(-):
* An item * Another item * More items
或者:
- An item - Another item - More items
注意:如果你熟悉 Markdown 語法,這些內容對你來說應該很直觀。
要在描述區加入 field,只需寫下被冒號包住的欄位名稱,然後接描述:
:MyField: This is a field example
以上這些,加上 param 與 returns 兩個標籤,就足以寫出得體的文件。雖然不像 Objective-C 那樣選擇豐富,但我認為已經足夠,因此不再展開。
回到 Xcode 實際看看。打開 ViewController.swift,定義一個方法(與 Objective-C 範例對應):
func toCelsius(fromFahrenheit: Float) -> Float {
return (fromFahrenheit - 32) / 1.8;
}依照前面對 Swift 註解規則的說明,同樣的內容會寫成:
/**
It converts temperature degrees from Fahrenheit to Celsius scale.
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 toCelsius(50) or self.toCelsius(50)
:param: fromFahrenheit The input value representing the degrees in the Fahrenheit scale.
:returns: float The degrees in the Celsius scale.
*/
func toCelsius(fromFahrenheit: Float) -> Float {
return (fromFahrenheit - 32) / 1.8;
}注意這裡用的是 /** – */ 標記。在 Help 彈出視窗中查看,結果如下:

同樣地,如果在 viewDidLoad 中輸入方法名稱,簡述會出現在自動補全清單裡:

接著建立一個什麼都不做、超級簡單的方法:
func myHelloMethod() {
println("Hello there")
}我們用它的文件來示範清單與 field 的寫法(邏輯不必深究,純屬展示):
/**
This method was implemented to do nothing hard, just to say hello.
Here is a demo of an ordered list:
1. One
2. Two
3. Three
4. Four
How about an unordered list?
* North
* East
* South
* West
Let's add a couple of fields now:
:Job: My dreaming job
:Salary: My dreaming salary
*/
func myHelloMethod() {
println("Hello there")
}按住 Option 並點擊方法名,Help 彈出視窗中呈現的內容如下:

以上幾乎就是你記錄 Swift 程式碼所需的全部知識。不過,讀完 reStructuredText 手冊之後,一定要多試幾個選項——它的功能非常廣泛。
本教程涵蓋了程式碼註解的許多面向,同時走過 Objective-C 與 Swift,並整理出各自最重要的規則。你會發現 Objective-C 的選項更多,但這些工具面對 Swift 時也很好用。我展示的並非全部,還有很多內容待你發掘,我的目標只是帶你認識最常用的文件化方法——你看到的這些,大概涵蓋了九成會遇到的情況。此外別忘了 HeaderDoc 與 Doxygen 這兩個有趣的工具,它們都能輸出優質文件,會成為你的好夥伴。最後我想再次強調:為程式碼寫註解是非常重要的工作。你可能時常懷疑這點,但相信我,花在這裡的每一秒都值得。用合適的註解幫助自己與他人,直指核心地解釋你做的每一件事。如果你還不習慣,最好從現在開始養成——無論你已經不是新手開發者,或正好相反。