美文网首页iOSios开发App
[iOS]Xcode使用技巧之文档注释一

[iOS]Xcode使用技巧之文档注释一

作者: 流火绯瞳 | 来源:发表于2016-07-29 16:57 被阅读2072次

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

    代码如下:

    /**
     
     # 一个#是一级标题
     ## 两个是二级标题
     ### 三级标题
     #### 四级标题
     ##### 五级标题
    
     - 可以使用两个'*'或者两个'_'来添加粗体文字,例如:**粗体文字**,或者: __粗体__
     
     - 添加链接的方式为[链接名称](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的语法都可以使用在注释文档的书写上面,感兴趣的话,大家可以试一试.

    相关文章

      网友评论

      • 69d8f15bf144:关于显示图片的问题想探讨下
      • 123123dfgj656:赞一波,还在想///到底是干嘛用的
        123123dfgj656:@流火绯瞳 感觉///比/**/看起来舒服点
        流火绯瞳:/// 和/**/差不多, Swift里基本都是///或//添加注释
      • d9431116937e:请问一下 文档显示的中文是怎么弄出来的?
        d9431116937e:@流火绯瞳 噢我明白了
        d9431116937e:@流火绯瞳 我是说你Xcode description的地方不都是中文的吗,想请问这是怎么做到的
        流火绯瞳:@R了个G 中文?直接按上面的规则写,写什么就显示什么的

      本文标题:[iOS]Xcode使用技巧之文档注释一

      本文链接:https://www.haomeiwen.com/subject/rehzjttx.html