在開發(fā)中,我們經(jīng)常使用快捷鍵 option + 鼠標(biāo)點(diǎn)擊某個(gè)關(guān)鍵字或方法,查看相應(yīng)的文檔信息,如下圖,是對(duì)String的系統(tǒng)說明文檔:

文檔注釋

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

基本默認(rèn)信息

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

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

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

效果如下圖:

添加注釋

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

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

另一種添加方式

這里的內(nèi)容是用Markdown的語法來書寫的,下面我們就來看看怎么書寫:

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

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

效果圖:

Markdown語法

同樣,我們也可以為注釋添加以下內(nèi)容:

• 添加標(biāo)題,一個(gè)#代表一級(jí)標(biāo)題,
• 添加粗體,兩個(gè)'*'或'_'是添加粗體
• 添加鏈接的基本語法為[顯示的鏈接名稱](鏈接URL地址)
• 添加圖片: 

代碼如下:

/**
 
 # 一個(gè)#是一級(jí)標(biāo)題
 ## 兩個(gè)是二級(jí)標(biāo)題
 ### 三級(jí)標(biāo)題
 #### 四級(jí)標(biāo)題
 ##### 五級(jí)標(biāo)題

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

效果:

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