作者：Gabriel Theodoropoulos，原文鏈接峰尝，原文日期：2016-05-12
譯者：小鐵匠Linus偏窝；校對：Channe；定稿：numbbbbb
在 Xcode 7 的所有功能中祭往，有一個很特別：它給編寫代碼文檔提供了一個更好的方法。隨著 Xcode 7 的更新火窒，開發(fā)者可以使用 Markdown 語法書寫富文本格式的代碼文檔硼补，而且可以結(jié)合特定的關(guān)鍵詞來指明特殊部分（如參數(shù)，函數(shù)返回結(jié)果等）熏矿。作為新支持的 Markdown 文檔樣式已骇，它具有以下幾點優(yōu)勢：文本樣式的自定義程度更高，更加靈活票编，當(dāng)然也更有趣褪储。然而，如果你仍然對原來的文本樣式感興趣的話慧域，也可以看以前那篇教程鲤竹。
對每個開發(fā)者來說，代碼文檔是開發(fā)中非常重要的一件事昔榴。即使它看上去會拖慢開發(fā)進度辛藻，但實際上它是開發(fā)中不可或缺的一部分。我不反對給每個屬性互订、函數(shù)吱肌、類、結(jié)構(gòu)體等書寫正確且全面的文檔屁奏，但這并不是一件容易的事岩榆。不過错负，你可以通過以下幾點來編寫適當(dāng)?shù)奈臋n：
描述各個屬性、函數(shù)和類的真正用途勇边。此外偷厦，最好能在需要注意的地方高亮函數(shù)的具體使用情況晨横、用例或需求。
高亮函數(shù)的輸入和輸出（參數(shù)和返回值）。
為了幾個月后再打開項目還能清晰地記得每個函數(shù)做了什么杂拨，每個屬性是為了什么。
當(dāng)你把代碼共享或做成 lib 時扒怖，一定要讓其他開發(fā)者能輕松地理解怎么使用你的代碼罗侯。
使用工具制作具有專業(yè)外觀的使用手冊（比如：使用 Jazzy）。
你在 Xcode 里寫的代碼文檔能被預(yù)覽月杉，也可以用以下的三種方法訪問：
按住 Option/Alt 鍵點擊屬性名刃跛、方法名或類名等，會彈出快速預(yù)覽（Quick Look preview）苛萎。
光標(biāo)移動到屬性名桨昙、方法名或類名上，打開快速幫助（Quick Help Inspector）進行查看腌歉。
使用第三方工具可以產(chǎn)生使用手冊蛙酪。比如，Jazzy 就是這樣一款工具翘盖，我們稍后會講到桂塞。通過使用它，可以在你工程的文件夾里生成一個集成了所有你寫的代碼文檔的網(wǎng)頁馍驯。
代碼文檔不是很死板的東西阁危；它可以根據(jù)各自實體（屬性、方法汰瘫、類欲芹、結(jié)構(gòu)、枚舉）的修改而改變吟吝。如果你沒有在實現(xiàn)一個新的實體時添加文檔的話菱父，那么幾乎可以肯定，你永遠不會去添加文檔了剑逃。因此浙宜，試著養(yǎng)成一個這樣的習(xí)慣：在合適的時間點去書寫代碼文檔，并在新的實體實現(xiàn)后能花時間去更新文檔蛹磺。
Markdown 基礎(chǔ)語法
為了能更好地使用新的文檔樣式粟瞬，對 Markdown 語法有一個基本的認(rèn)識是很重要的。如果已經(jīng)對這部分有充分的了解的話萤捆，可以跳過這一章裙品，直接看下一章俗批。你可以在網(wǎng)絡(luò)上找到關(guān)于 Markdown 的很多信息，比如這里還有這里都能找到市怎。
盡管你能找到關(guān)于 Markdown 語法的其他資源岁忘，但是我覺得至少要講一下基礎(chǔ)語法。我的目的當(dāng)然不是要提供一整個 Markdown 使用指南区匠，只是為了呈現(xiàn)特定語法的常見用法干像。
因此，你大概知道（可能現(xiàn)在才知道）Markdown 語法是由特殊字符來格式化文本驰弄、添加資源（鏈接和圖片）以及添加文本塊（有序或無序列表麻汰，代碼塊等）。雖然這些字符很容易記住戚篙，但是還是需要經(jīng)常上網(wǎng)查查或看看下面列出來的五鲫。有必要在這里說一下，如果你習(xí)慣了 Markdown 語法（其實很容易就做到了）岔擂，然后通過使用合適的編輯器就可以生成不同格式的文檔了臣镣，例如：HTML 頁面、PDF 文檔等等智亮。說到 HTML 頁面，Markdown 支持內(nèi)聯(lián) HTML点待，也就是說阔蛉，你可以直接把 HTML 標(biāo)簽寫到文本里，這些標(biāo)簽都會被渲染癞埠。然而状原，使用 HTML 并不是 Markdown 的本質(zhì)，因此我們還是回到 Markdown 自己的語法吧苗踪。
以下列出了最常用的 Markdown 語法：
- #text#：文本標(biāo)題颠区，相當(dāng)于 HTML 中的 <H1> 標(biāo)簽。兩個 # 則對應(yīng) <H2> 標(biāo)簽通铲，以此類推毕莱，直到 <h6> 標(biāo)簽。末尾的 # 可以省略颅夺。
- **text**：使文本具有加粗的效果朋截。
- *text*：使文本具有斜體的效果。
- * text：使文本成為一個無序列表的元素吧黄，值得注意的是部服，有個 * 后面需要有一個空格。同樣拗慨，可以使用 + 或 - 實現(xiàn)這個的功能廓八。
- text：使文本成為一個有序列表的元素奉芦。
-
[linked text](http://some-url.com)：使文本成為可以點擊的超鏈接。 - > text：創(chuàng)建一個塊引用剧蹂。
- 使用 4 個空格或 1 個 tab 來縮進所寫的代碼塊声功，等價于 HTML 中的 <pre></pre> 標(biāo)簽」梗可以繼續(xù)使用 4 個空格或 1 個 tab 來添加另一個縮進减噪。
- 如果不想使用空格或 tab 的話，可以使用 ` 车吹。比如筹裕， `var myProperty` 會顯示成
var myProperty。 - 另一種創(chuàng)建代碼塊的方法是添加 4 個 `窄驹，并從下一行開始寫具體的代碼朝卒，最后添加 4 個 ` 表示結(jié)束。
- 反斜杠修飾 Markdown 的特殊字符就可以避免 Markdown 語法的解析了乐埠。比如抗斤，
\**this\**就不會產(chǎn)生加粗的效果。
以上這些是 Markdown 語法中比較重要的部分丈咐。雖然瑞眼，Markdown 語法中還有很多額外的細節(jié)可以深究。但是棵逊，以上提供的這些已經(jīng)足夠你開始使用 Markdown 了伤疙。
如果你發(fā)現(xiàn) Markdown 還蠻有意思的話，你可以下載一個編輯器具體嘗試一下辆影。使用編輯器徒像，你可以實時地看到你所寫的文本在轉(zhuǎn)化成 HTML 后的效果。
關(guān)于編輯器：你可以嘗試以下這些 Markdown 編輯器：StackEdit蛙讥，Typora锯蛀，Macdown，Focused 和 Ulysses次慢。
使用 Markdown
在編寫任何 Swift 中實體的文檔時旁涤，有些規(guī)則是一定要遵守的。你可以為屬性（變量和常量）迫像、方法拭抬、函數(shù)、類侵蒙、結(jié)構(gòu)體造虎、枚舉、協(xié)議纷闺、擴展和其他代碼結(jié)構(gòu)或?qū)嶓w編寫代碼文檔算凿。針對實體的每個文檔塊都要寫在定義或頭文件前面份蝴，且以 3 個斜線（///）或以下面的形式開頭：
/**
*/
雖然 // 也被視為注釋，但是這種語法會被 Xcode 忽略氓轰，而不產(chǎn)生對應(yīng)的代碼文檔婚夫。你可以在各種代碼塊中使用 // 來注釋，但是正如我上一句說的署鸡，這并不會產(chǎn)生對應(yīng)的代碼文檔案糙。（譯者注：老外就是這么啰嗦，怪我咯～）
讓我們來看一個簡單的例子熟悉一下 Markdown 語法吧靴庆。在下面的代碼塊中时捌，我們?yōu)橐粋€屬性添加了一行可以產(chǎn)生代碼文檔的注釋。我建議你可以打開 Xcode 中 Playground 來試試本文中提到的所有例子炉抒。(校對注：為了保持和截圖一致奢讨，下面的注釋沒有翻譯)
/// This is an **awesome** documentation line for a really *useful* variable.
var someVar = "This is a variable"
以上寫的代碼文檔會在 Xcode 中呈現(xiàn)以下效果：
值得注意的是，單詞 “awesome” 是加粗的焰薄，而 “useful” 是斜體的拿诸。前一個是由 ** 包含，后一個則由 * 包含產(chǎn)生的塞茅。
讓我們來對函數(shù)來做另一個例子：
/**
It calculates and returns the outcome of the division of the two parameters.
## Important Notes ##
1. Both parameters are **double** numbers.
2. For a proper result the second parameter *must be other than 0*.
3. If the second parameter is 0 then the function will return nil.
*/
func performDivision（number1: Double, number2: Double） -> Double! {
if number2 != 0 {
return number1 / number2
}
else {
return nil
}
}
拷貝以上代碼到 playground 中亩码，再按住 Option 鍵點擊函數(shù)名，就會彈出一個快速幫助（Quick Help）野瘦，如下圖：
這里我們使用了兩個新的 Markdown 元素描沟，標(biāo)題和有序列表。同時缅刽，也有加粗和斜體的文本〈缆纾可以看到的是衰猛，簡簡單單地使用了 Markdown 語法中的特殊字符就可以生成如此復(fù)雜的富文本代碼文檔。以下是快速幫助欄（Quick Help Inspector）的截圖：
下面例子中刹孔，我們?yōu)楹瘮?shù)添加一個代碼文檔中的代碼塊啡省。值得注意的是，除了創(chuàng)建了一個代碼塊髓霞，我們還用` 標(biāo)記了內(nèi)聯(lián)函數(shù)的名稱卦睹。
/**
It doubles the value given as a parameter.
### Usage Example: ###`
let single = 5
let double = doubleValue（single）
print（double）
`
* Use the `doubleValue（_:）` function to get the double value of any number.
* Only ***Int*** properties are allowed.
*/
func doubleValue（value: Int） -> Int {
return value * 2
}
以下是最終效果：
最后，讓我們來為枚舉添加代碼文檔方库，并在其他函數(shù)中使用结序。這個例子中有趣的是每個枚舉類型的代碼文檔：
/**
My own alignment options.`
case Left
case Center
case Right
`
*/
enum AlignmentOptions {
/// It aligns the text on the Left side.
case Left
/// It aligns the text on the Center.
case Center
/// It aligns the text on the Right side.
case Right
}
func doSomething（） {
var alignmentOption: AlignmentOptions!
alignmentOption = AlignmentOptions.Left
}
現(xiàn)在，當(dāng)你使用到這個枚舉時纵潦，Xcode 就會顯示之前你寫的對應(yīng)的代碼文檔：
使用關(guān)鍵字
使用 Markdown 語法只是為 Swift 代碼添加代碼文檔的一個好處徐鹤。顯而易見垃环，富文本格式很強大，可以展示精美的文檔內(nèi)容返敬，但是下面要介紹另一個很厲害的關(guān)鍵字遂庄。
當(dāng)你使用關(guān)鍵字時，Xcode 會在渲染代碼文檔時自動應(yīng)用對應(yīng)的文本格式（其他第三方庫也是這么做的）劲赠。關(guān)鍵字可以很方便地指出代碼結(jié)構(gòu)中常見的部分涛目，然后區(qū)分出來。舉個例子凛澎，有很多關(guān)鍵字可以高亮方法的參數(shù)霹肝、返回值、類的作者或方法的版本预厌。這個關(guān)鍵字的列表還挺長的阿迈，然而并不是每個關(guān)鍵字都會頻繁使用，有些基本沒人用轧叽。不過大多數(shù)常見的關(guān)鍵字最好還是記在腦子里苗沧，至于其它的可以在需要時再去查。
正如上面說的炭晒，是時候通過幾個簡單的例子來說明關(guān)鍵字的用法了待逞。首先來說一下，方法或函數(shù)中接收的參數(shù)吧：
/**
This is an extremely complicated method that concatenates the first and last name and produces the full name.
- Parameter firstname: The first part of the full name.
- Parameter lastname: The last part of the fullname.
*/
func createFullName（firstname: String, lastname: String) {
let fullname = "\（firstname） \（lastname）"
print（fullname）
}
以上代碼會顯示成這樣：
值得注意的是關(guān)鍵字前的 - 號以及與關(guān)鍵字中間的空格网严。后面跟隨的是具體的參數(shù)名识樱。你必須對所有的參數(shù)都書寫對應(yīng)的描述文字。
現(xiàn)在讓我們修改一下上面的函數(shù)震束，將這個函數(shù)返回一個字符串而不只是打印出來怜庸。為了實現(xiàn)這個，我們添加了一個可以描述函數(shù)返回值的關(guān)鍵字：
/**
This is an extremely complicated method that concatenates the first and last name and produces the full name.
- Parameter firstname: The first part of the full name.
- Parameter lastname: The last part of the fullname.
- Returns: The full name as a string value.
*/
func createFullName（firstname: String, lastname: String) -> String {
return "\（firstname） \（lastname）"
}
顯示結(jié)果是這樣的：
以上這兩個關(guān)鍵字（Parameter 和 Returns）是會用的比較頻繁的垢村。接下來的這個函數(shù)實現(xiàn)了與上一個函數(shù)完全相反的功能割疾，將全名拆分成姓和名：
/**
Another complicated function.
- Parameter fullname: The fullname that will be broken into its parts.
- Returns: A *tuple* with the first and last name.
- Remark:
There's a counterpart function that concatenates the first and last name into a full name.
- SeeAlso: `createFullName（_:lastname:）`
*/
func breakFullName（fullname: String) -> （firstname: String, lastname: String) {
let fullnameInPieces = fullname.componentsSeparatedByString（" "）
return （fullnameInPieces[0], fullnameInPieces[1]）
}
上面新出現(xiàn)的兩個關(guān)鍵字是 Remark 和 SeeAlso。通過使用 Remark嘉栓，你可以高亮你想要引起讀者注意的地方宏榕。關(guān)鍵字 SeeAlso 可以引用代碼的其它部分（比如，我們這個例子中是引用了前一個函數(shù)）或提供一個 URL侵佃。Xcode 中的快速幫助（Quick Help）會顯示如下：
試著想象一下麻昼，上面的這個函數(shù)會分享給其他開發(fā)者使用。你肯定希望所有使用這個函數(shù)的人都能知道：參數(shù) fullname 不能是空的馋辈，且姓和名要包含在全名里抚芦，并以空格分隔，這樣函數(shù)才能正確調(diào)用。為了實現(xiàn)這個燕垃，你需要使用另外兩個關(guān)鍵字 Precondition 和 Requires枢劝。讓我們來對應(yīng)的更新下上面的那個函數(shù)：
/**
Another complicated function.
- Parameter fullname: The fullname that will be broken into its parts.
- Returns: A *tuple* with the first and last name.
- Remark:
There's a counterpart function that concatenates the first and last name into a full name.
- SeeAlso: `createFullName（_:lastname:）`
- Precondition: `fullname` should not be nil.
- Requires: Both first and last name should be parts of the full name, separated with a *space character*.
*/
func breakFullName（fullname: String) -> （firstname: String, lastname: String) {
let fullnameInPieces = fullname.componentsSeparatedByString（" "）
return （fullnameInPieces[0], fullnameInPieces[1]）
}
展望未來，你可能會樂意記下未來計劃的變更：
- Todo: Support middle name in the next version.
你甚至可以在寫代碼文檔時卜壕，添加 warnings您旁、 version、author 和 notes：
/**
Another complicated function.
- Parameter fullname: The fullname that will be broken into its parts.
- Returns: A *tuple* with the first and last name.
- Remark:
There's a counterpart function that concatenates the first and last name into a full name.
- SeeAlso: `createFullName（_:lastname:）`
- Precondition: `fullname` should not be nil.
- Requires: Both first and last name should be parts of the full name, separated with a *space character*.
- Todo: Support middle name in the next version.
- Warning: A wonderful **crash** will be the result of a `nil` argument.
- Version: 1.1
- Author: Myself Only
- Note: Too much documentation for such a small function.
*/
func breakFullName（fullname: String) -> （firstname: String, lastname: String) {
let fullnameInPieces = fullname.componentsSeparatedByString（" "）
return （fullnameInPieces[0], fullnameInPieces[1]）
}
以下是顯示結(jié)果：
看了上面這么多例子轴捎，你應(yīng)該能理解關(guān)鍵字的詳細程度完全是由你確定的鹤盒。代碼中重要的部分（比如，上面拿來舉例子的函數(shù)）要有具體的代碼文檔侦副，而次要的部分只寫基本的文檔即可侦锯。
Apple 提供了一個所有代碼文檔中可能用到的關(guān)鍵字頁面，你如果點了下面提到的超鏈接秦驯，你可以看到每個關(guān)鍵字采用 Markdown 語法的具體使用指南尺碰。走過路過，不要錯過了译隘，進去瞧一瞧亲桥。
使用 Jazzy 產(chǎn)生代碼文檔
Jazzy 是一款可以為 Swift 和 Objective-C 代碼產(chǎn)生具有 Apple 風(fēng)格的代碼文檔工具。事實上固耘，Jazzy 會為你創(chuàng)建一個鏈接所有代碼文檔的獨立網(wǎng)頁题篷。它是一款命令行工具，但還是很容易使用的厅目。
我并不打算介紹 Jazzy 的具體使用方法番枚；只需要訪問它的 GitHub 頁面，你就能找到所有你想要的信息了损敷，包括使用要求和安裝方法葫笼。安裝過程真的很簡單，你所有要做的如下：
- 打開“終端”
- 輸入“sudo gem install jazzy”
- 輸入密碼
- 等待
為了方便你嘗試使用 Jazzy拗馒，我已經(jīng)準(zhǔn)備好了一個工程路星，你可以在這里下載。這個工程很簡單瘟忱，它就是基于之前提到的例子寫的奥额，即組合姓和名成全名以及全名分割成姓和名苫幢。
在這個工程里访诱，我已經(jīng)添加了和之前例子中類似的代碼文檔。即使這個工程只是為了演示韩肝，但是不管是用在什么場合触菜，它不僅能支持類、方法和屬性哀峻，還能支持結(jié)構(gòu)體涡相、枚舉哲泊、擴展、協(xié)議等等催蝗。
假設(shè)你現(xiàn)在已經(jīng)下載了那個工程切威，讓我們來看看 Jazzy 到底是怎么用的。一開始丙号，使用 cd 命令將目錄切換到工程對應(yīng)的目錄：
cd path_to_project_folder
簡單地輸入 Jazzy 然后敲回車等著先朦，然而，這樣并不能將類或其他沒有標(biāo)注為 public 的結(jié)構(gòu)寫入代碼文檔犬缨。因此喳魏，如果你想要包含所有的實體，就輸入一下：
jazzy --min-acl internal
另外怀薛，如果你用的不是 Swift 的最新版本刺彩，發(fā)現(xiàn)使用 Jazzy 后沒有效果的話，你可以通過以下命令來指定你的 Xcode 支持的 Swift 版本：
jazzy --swift-version 2.1.1 --min-acl internal
我強烈建議你輸入 jazzy -help 看看所有你使用 Jazzy 時可能使用到的參數(shù)枝恋。當(dāng)然创倔，你完全可以根據(jù)自己的喜好來得到最終的結(jié)果。
以下是你生成代碼文檔頁面時會看到的：
默認(rèn)輸出的文件夾位于工程的根目錄（你也可以更改輸出路徑）鼓择，叫 docs三幻。
使用 Finder 進入到對應(yīng)路徑，在瀏覽器中打開 index.html呐能。你立即就會發(fā)現(xiàn)念搬，默認(rèn)生成的頁面風(fēng)格和 Apple 官方文檔是非常相似的。在頁面里到處點擊看看摆出，看看具體顯示的代碼文檔朗徊。接下來，就嘗試在你自己的工程中使用吧偎漫。
總結(jié)
為代碼寫文檔是一件必要且重要的事爷恳，但是開發(fā)者往往因為缺乏時間而放棄了。當(dāng)項目臨近交付時間或在短短時間內(nèi)還有很多 bug 要修復(fù)象踊，這就很難有機會為項目的每一個部分寫出合適的文檔温亲。然而，我希望通過這篇文檔杯矩，你可以意識到代碼文檔的重要性栈虚，并試著盡量寫一下代碼文檔。你不需要寫下所有的細節(jié)史隆，但你至少要為代碼中的重要部分增加高亮魂务，方便其他開發(fā)者或以后你自己繼續(xù)在這個代碼基礎(chǔ)上進行修改。因此，你不要忘了還有一款專業(yè)的代碼文檔生成工具 Jazzy 可以使用粘姜。也許這可以成為你寫代碼文檔的動力吧鬓照！
本文由 SwiftGG 翻譯組翻譯，已經(jīng)獲得作者翻譯授權(quán)孤紧，最新文章請訪問 http://swift.gg豺裆。
