[iOS]书写Xcode注释文档

这篇文章,没有整体逻辑,纯属知识点的罗列,也是对自己书写文档的总结:

在开发中,我们经常使用快捷键 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地址

(完)