[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 "文档注释"
}

效果图:

Markdown语法

同样,我们也可以为注释添加以下内容:

• 添加标题,一个#代表一级标题,
• 添加粗体,两个'*'或'_'是添加粗体
• 添加链接的基本语法为[显示的链接名称](链接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的语法都可以使用在注释文档的书写上面,感兴趣的话,大家可以试一试.