[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地址

(完)