一般我們寫程序時(shí)改执，都會(huì)為代碼加上一些注釋絮短，一個(gè)是為了給別人看囚玫，另一個(gè)原因就是如果項(xiàng)目越寫越大時(shí)喧锦，可能就忘了之前寫的函數(shù)或類是什么作用了，所以養(yǎng)成邊寫代碼編寫注釋甚至是實(shí)現(xiàn)功能前就加上注釋的習(xí)慣是很重要的抓督。
那么燃少，在Swift里是怎么為代碼加注釋，加了注釋又會(huì)有什么效果呢铃在。 大部分語(yǔ)言的單行注釋是兩個(gè)/阵具，多行注釋是/加*號(hào)。Swift當(dāng)然也支持這種注釋定铜。
// 單行注釋
/*
多行注釋
*/
但是在Swift里阳液，除了上面的兩種注釋外，還支持使用Markdown編寫注釋揣炕，但是如果要讓Markdown編寫的注釋可以在XCode的Quick Help里可以展示帘皿，則單行注釋需要使用三個(gè)/，多行注釋開頭需要使用/**畸陡，結(jié)尾*/鹰溜。否則虽填，注釋里寫的Markdown是不會(huì)被識(shí)別出來(lái)的，在Quick Help里也無(wú)法查看奉狈，
/// 單行注釋卤唉，支持*Markdown*
/**
多行注釋
*/
單詞分隔符
在注釋中還定義了一些特殊的文字分隔符作為注釋的標(biāo)記，比如下圖中可以給方法備注上作者仁期。需要注意的是桑驱，-前后需要空格， 另外Author:中的Author單詞對(duì)大小寫無(wú)嚴(yán)格規(guī)定跛蛋，但是一般按照大駝峰命名規(guī)則寫熬的。也就是單詞首字母大寫。
支持的單詞分隔符有：（要獲取最新的可以看蘋果官方文檔）：
Attention
Author
Authors
Bug
Complexity
Copyright
Date
Experiment
Important
Invariant
Note
Parameter
Parameters
Postcondition
Precondition
Remark
Returns
Requires
SeeAlso
Since
Throws
ToDo
Version
Warning
用法(-也可用+或*代替)
/**
- Attention: description
- Author: author name
- Authors: author name
- Bug: this is a bug, fix it.
*/
/**
Play a song.
- parameter song: The song you want play.
*/
func play(song songName: String) {
}
/**
Send a message to someone.
- parameter message: message want send.
- parameter user: send message to user.
*/
func send(msg message: String, to user: String) {
}
由多個(gè)參數(shù)時(shí)除了分行寫parameter外押框，還有下面這種寫法：
/**
Send a message to someone.
- parameters:
- message: message want send.
- user: send message to user.
*/
func send(msg message: String, to user: String) {
}
需要注意的是，parameters 下面寫的參數(shù)需要往里縮進(jìn)一格（加一個(gè)tab或者兩個(gè)空格都可以）
/**
- parameters:
- min: min number
- max: max number
- returns:
number between min and max
*/
func returnsExample(min: Int, max: Int) -> Int{
// TODO: - finish it
return 0
}
注釋中加入無(wú)序列表
/**
An example of using a *bulleted list*
* item 1
* item 2
* item 2.1
* item 3
*/
func bulletedListExample() {
}
有序列表
/**
An example of using a *numbered list*
1. Fruit
1. Apple
2. Banana
2. Vegetable
1. Cabbage
*/
func numberedListExample() {
}
在注釋中加上示例代碼
方式1: 將示例代碼縮進(jìn)
/**
An example of using a *code block*
A loop to print each character on a seperate line
for s in str.characters {
print(s)
}
*/
func codeBlockExample(_ str: String) {
for s in str.characters {
print(s)
}
}
方式二：
給注釋中的文字加粗或重點(diǎn)標(biāo)注
/**
Markup uses simple character-based delimiters to mark formatted text in *playgrounds* and in *Quick Help* for Swift symbols.
Some of the delimiters are used for both rendered `playground` documentation and in `Quick Help`. Other delimiters are used with _either playgrounds or with Quick Help_. The documentation for each delimiter **includes** information __on where it can be used__.
*/
func importantCharacters(){
}
注釋中插入鏈接
/**
An example of using the seealso field
- Note:
[SeeAlso](https://developer.apple.com/library/content/documentation/Xcode/Reference/xcode_markup_formatting_ref/Links.html)
*/
func linksExample() {
}
總結(jié)
注釋算是項(xiàng)目中非常重要的內(nèi)容理逊，這里總結(jié)的只是我覺得在XCode中寫代碼會(huì)比較常用的注釋橡伞，其實(shí)官網(wǎng)還有一些強(qiáng)大的注釋是給Playground用的，這里就不總結(jié)了晋被，自己去看吧兑徘。在這次總結(jié)里面我從蘋果的文檔中嘗試失敗的有兩個(gè)，一個(gè)是SeeAlso羡洛，另一個(gè)是在注釋里插入網(wǎng)絡(luò)圖片挂脑，大家可以嘗試一下，歡迎留言指正欲侮。另外崭闲，可以使用快捷鍵cmd+opt+/直接在方法或?qū)傩陨喜迦胱⑨專绻旖萱I沒用威蕉，可能是被當(dāng)前其他應(yīng)用給占據(jù)了刁俭，可以把快捷鍵在XCode中修改為其他自己熟悉的快捷鍵。
