這篇文章,沒有整體邏輯,純屬知識點的羅列,也是對自己書寫文檔的總結:

在開發中,我們經常使用快捷鍵 option + 鼠標點擊某個關鍵字或方法,查看相應的文檔信息,如下圖,是對String的系統說明文檔:

 

變量string是我們定義的變量名,在沒有寫任何注釋的時候,我們按住option + 鼠標左鍵查看時,會有一些基本信息:

 

下面,我們就來看一下怎麼書寫這些文檔注釋:
添加文檔注釋有兩種方式:

第一種基本的寫法和我們平時的多行注釋很相似

 

/**
 注意,這裡多了一個*
 這裡就是我們的文檔內容
 */
func SomeFunc(name: String) -> String {
    
    return "文檔注釋"
}

效果如下圖:

 

第二種和我們的單行注釋相似

 

/// 單行的文檔注釋,只能寫一行,
///
/// 換行的話需要再添加三個/,同樣換行的話需要插入空行,三個/不能少
func SomeFunc1(name: String) -> String {
    
    return "文檔注釋"
}

 

 

這裡的內容是用Markdown的語法來書寫的,下面我們就來看看怎麼書寫:

 

- 段落之間(或者換行)使用空行來分割;
- 無序的列表使用-或+或*加上空格;
- 有序列表可直接使用數字後跟.跟空格,即:1. 內容
- 插入代碼使用三個\`(鍵盤tab鍵左上角那個按鍵)開始,三個\`結束,之間插入代碼段
代碼如下:

 

/**
 
 這裡就是我們的文檔內容,這裡是第一段的文字
 
 如果有多段描述,需要分段,需要在段落之間添加一個空行
 
 如果有分類,無序列表可使用-或+或*後跟一個空格來書寫,如下:
 - 第一項
 - 第二項
 + 第三項
 * 第四項
 
 有序列表可直接按如下方式書寫:
 1. 第一項
 2. 第二項
 3. 第三項
 
 插入代碼段:
  `` `
 let a = 1
 let name = "注釋"
 print("\(name)"
`` `
 */
func SomeFunc(name: String) -> String {
   
    return "文檔注釋"
}

 

 

效果圖:

 

同樣,我們也可以為注釋添加以下內容:
- 添加標題,一個#代表一級標題,
- 添加粗體,兩個'*'或'_'是添加粗體
- 添加鏈接的基本語法為\[顯示的鏈接名稱](鏈接URL地址)
- 添加圖片: 

 

代碼如下:

 

/**
 
 # 一個#是一級標題
 ## 兩個是二級標題
 ### 三級標題
 #### 四級標題
 ##### 五級標題

 - 可以使用兩個'*'或者兩個'_'來添加粗體文字,例如:**粗體文字**,或者: __粗體__
 
 - 添加鏈接的方式為[鏈接名稱](URL地址),
 - 例如: [我的簡書](http://www.jianshu.com/users/2846c3d3a974/timeline)
 
 - 添加圖片: ![圖片名稱](圖片URL)
 
 - ![swift](http://c.hiphotos.baidu.com/baike/w%3D268/sign=a8324ff660d0f703e6b292da30fb5148/500fd9f9d72a6059070cf8fb2a34349b033bba36.jpg)
 
 */
func SomeFunc2(name: String) -> String {
    
    return "文檔注釋"
}

 

 

效果圖:

其實,很多的markdown的語法都可以使用在注釋文檔的書寫上面,感興趣的話,大家可以試一試.

 

另外在書寫注釋文檔的時候,有一些常用關鍵字,下面簡單介紹一下:

1. Parameter
這個關鍵字主要是為一些方法的參數添加說明的,基本格式:
 

- parameter 參數名 說明

例如:

 

/**
 
 - parameter name: 姓名
 - parameter age: 年齡
 */
func SomeFunc3(name: String ,age: Int ) -> String {
    
    return "Parameters"
}

如果參數比較多的話,每個都要加上parameter,很麻煩,可以使用parameters關鍵字,不要忘記其後的冒號:

 

 

/**
 
 
 - parameters:
    - name: 姓名
    - age: 年齡
 */
func SomeFunc4(name: String ,age: Int ) -> String {
    
    return "Parameters"
}

/**

以上兩種寫法的效果是一樣,會發現,在注釋文檔內多了一個域,關於參數說明的:


2. returns
這個是為返回值添加說明的,使用格式為:

 

- returns: 返回值說明
 

/**
 
 - returns: 返回值
 */
func SomeFunc5(name: String ,age: Int ) -> String {
    
    return "Parameters"
}

這時,文檔會多個Returns的域:





3. throws
異常拋出的關鍵字,格式:

 

- throws: 異常說明
 

/**
  - throws: 拋出異常
 */
func SomeFunc6(name: String ,age: Int ) throws -> String {
    
    return "Parameters"
}

 

 

以上是三個比較重要的關鍵字,下面列舉一些其他的關鍵字
4.其他關鍵字
算法相關:

 

/**
 
 - Precondition: 算法前置條件
 - postcondition: 算法後置條件
 - requires: 算法內容
 - invariant: 循環不變量
 - complexity: O(n^n)算法復雜度
 - important: 一些重要信息描述
 - warning: 警告
 - attention: 警告信息
 - note: 一些記錄
 - remark: 一些評論
 */
func someFunc7(name: String) {
    
    
}

描述信息:

/**
 
 - author: LQQ 開發者
 - authors: 所有開發者
 - date: 16-07-29 11:07:21
 - copyright: 版權所有
 - since: 開始時間
 - version: 版本號
*/
func someFunc8(name: String) {
    
}

以上就是文檔注釋中常用的一些關鍵字,還有其他一些關鍵字,大家不仿查詢嘗試一下.

這裡有個demo,很簡單,可以看看具體效果:Demo地址

 

(完)