Swift 文件注釋規範

**的結構和組織關乎了開發童鞋們的節操問題。明確和一致的**表示了明確和一貫的思想。編譯器並沒有乙個挑剔的口味，但當談到命名，空格或文件，人類的差異就體現出來了。

nshipster 的讀者無疑會記得去年發表的關於文件的文章，但很多東西已經在 xcode 6 中發生了變化（幸運的是，基本上算是變得更好了）。因此，這一周，我們將在此為嗷嗷待哺的 swift 開發者們記錄一下文件說明。

好了，來讓我們仔細看看。

真正讓人意外的是，文件的格式也發生了變化。

在 swift 的**裡呼叫快速文件 (quick documentation)（⌥ʘ）時 headerdoc 沒有正確解析注釋：

swift

/**
讓我們隨便來寫點什麼.
@param 啦啦啦啦，這貨是引數。
@return 咯咯咯咯，這貨是返回值。
*/func
foo(
bar:
string
)->
anyobject

但如果修改一下標記方式，就可以被正確解析：

swift

/** 讓我們隨便來寫點什麼. :param: 啦啦啦啦，這貨是引數。 :returns: 咯咯咯咯，這貨是返回值。 */func foo( bar: string )-> anyobject

那麼，這個陌生的新檔案格式是個什麼情況？事實證明，sourcekit（xcode 使用的私有框架，在此前以其高 fps 崩潰聞名）包括乙個解析 restructuredtext 的基本解析器。雖然僅實現了 specification 的乙個子集，但涵蓋基本的格式已經足夠了。

基本標記

文件注釋通過使用/** ... */的多行注釋或///...的單行注釋來進行區分。在注釋塊裡面，段落由空行分隔。無序列錶可由多個專案符號字元組成：-、+、*、•等，同時有序列表使用阿拉伯數字（1，2，3，...），後跟乙個點符1.或右括號1)或兩側括號括起來(1)：

swift

/** 你可以製作 *斜體*, **粗體**, 或 `**` 的字型風格. - 列表很不錯, - 但最好不要疊套 - 子列表的格式 - 就不太好了. 1. 有序列表也一樣 2. 對那些有序的東西來說; 3. 阿拉伯數字 4. 是唯一支援的格式.

*/

定義與字段列表

定義和字段列表跟 xcode 裡的快速文件彈出內容顯示的差不多，定義列表會更緊湊一些：

swift

/** definition list 一些術語以及它們的定義. format 左對齊術語，放在縮排的定義下面. :field header: 字段列表隔開一些。 :another field: 字段列表可以緊跟開始，不需要另起一行並縮排。隨後縮排的行也被視為內容的一部分.

*/

兩個特殊字段用於記錄引數和返回值：分別為：:param:和:returns:。:param:後跟的是引數的名稱，然後是說明。返回值沒有名字，所以:returns:後就是說明：

swift

/** 重複乙個字串 `times` 次. :param: str 需要重複的字串. :param: times 需要重複 `str` 的次數. :returns: 乙個重複了 `str` `times` 次的新字串. */func repeatstring (str :string ,times :int )-> string

**塊也可以嵌入到文件的注釋裡，這對於演示正確的使用方式或實現細節很有用。用至少兩個空格來插入**塊：

swift

/**
`shape` 例項的面積.
計算取決於該例項的形狀。如果是三角形，`area` 將相當於:
let height = ********.calculateheight()
let area = ********.base * height / 2
*/var
area
:cgfloat

當這個應用在整個類的時候看起來怎麼樣？事實上，看起來相當的不錯：

swift

import foundation ///

Swift 文件注釋規範

Swift文件注釋

文件化開發注釋規範

技術總結 swift文件注釋總結

Swift 文件注釋規範

Swift文件注釋

文件化開發注釋規範

技術總結 swift文件注釋總結

相關推薦