在开发中,我们经常使用快捷键 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 "文档注释"
}
效果图:
Markdown语法
同样,我们也可以为注释添加以下内容:
- 添加标题,一个#代表一级标题,
- 添加粗体,两个'*'或'_'是添加粗体
- 添加链接的基本语法为[显示的链接名称](链接URL地址)
- 添加图片: 
代码如下:
/**
# 一个#是一级标题
## 两个是二级标题
### 三级标题
#### 四级标题
##### 五级标题
- 可以使用两个'*'或者两个'_'来添加粗体文字,例如:**粗体文字**,或者: __粗体__
- 添加链接的方式为[链接名称](URL地址),
- 例如: [我的简书](http://www.jianshu.com/users/2846c3d3a974/timeline)
- 添加图片: 
- 
*/
func SomeFunc2(name: String) -> String {
return "文档注释"
}
效果:
其实,很多的markdown的语法都可以使用在注释文档的书写上面,感兴趣的话,大家可以试一试.
