Swift中使用“Markdown”来标注代码注释

在 Xcode 7 的所有功能中，有一个很特别：它给编写代码文档提供了一个更好的方法。随着 Xcode 7 的更新，开发者可以使用 Markdown 语法书写富文本格式的代码文档，而且可以结合特定的关键词来指明特殊部分（如参数，函数返回结果等）。
同时作为伴随swift3发布的api设计指南要求，为swift代码编写Markdown注释已经从一种道义上升为一种行为准则了。

Markdown的优点

---

• 纯文本，自定义程度更高，所以兼容性极强，可以用所有文本编辑器打开。
• 让你专注于文字而不是排版。
• 格式转换方便，更加灵活，Markdown 的文本你可以轻松转换为 html、电子书等。
• Markdown 的标记语法有极好的可读性。

Markdown 基础语法

---

以下列出了最常用的 Markdown 语法：

• #text#：文本标题，相当于 HTML 中的

  标签。两个 # 则对应

  标签，以此类推，直到

  标签。末尾的 # 可以省略。同理,你还可以增加二级标题、三级标题、四级标题、五级标题和六级标题，总共六级，只需要增加 # 即可，标题字号相应降低。

• **text**：使文本具有加粗的效果。
• *text*：使文本具有斜体的效果。
• * text：使文本成为一个无序列表的元素，值得注意的是，有个 * 后面需要有一个空格。同样，可以使用 + 或 - 实现这个的功能。
• 1. text：使文本成为一个有序列表的元素。
• [linked text](http://some-url.com)：使文本成为可以点击的超链接。
• > text：创建一个块引用。
• 使用 4 个空格或 1 个 tab 来缩进所写的代码块，等价于 HTML 中的
  标签。可以继续使用 4 个空格或 1 个 tab 来添加另一个缩进。如果不想使用空格或 tab 的话，可以使用 ` 。比如， `var myProperty` 会显示成var myProperty。创建多行代码块的方法是将```置于这段代码的首行和末行。
• 反斜杠修饰 Markdown 的特殊字符就可以避免 Markdown 语法的解析了。比如， **this** 就不会产生加粗的效果。
• 在一行中用三个以上的星号、减号、底线来建立一个分隔线，行内不能有其他东西。你也可以在星号或是减号中间插入空格。

以上这些是 Markdown 语法中比较重要的部分。虽然，Markdown 语法中还有很多额外的细节可以深究。但是，以上提供的这些已经足够你开始使用 Markdown 了。

关于编辑器：你可以尝试以下这些 Markdown 编辑器：StackEdit，Typora，Macdown，Focused 和 Ulysses。

使用 Markdown

---

在swift中，代码区域和playground的Markdown注释是不一样的，为了更好的切换Markdown的效果，我们先设置下快捷键，在Key Binding中输入show rendered markup，在key中设置快捷键option+M，后面就可以通过此快捷键切换Markdown的渲染效果了。

show rendered markup

在编写任何 Swift 中实体的文档时，有些规则是一定要遵守的。你可以为属性（变量和常量）、方法、函数、类、结构体、枚举、协议、扩展和其他代码结构或实体编写代码文档。针对实体的每个文档块都要写在定义或头文件前面,在代码里单行注释用///，多行注释如下：

/**

*/

虽然 // 也被视为注释，但是这种语法会被 Xcode 忽略，而不产生对应的代码文档。你可以在各种代码块中使用 // 来注释，但这并不会产生对应的代码文档。
举个例子看看实际的效果，如下：demo被加粗

/// A **demo** function
    func demo(){}

查看效果有两种方式：
1、将光标放在demo上，快捷键option+command+2，在右侧就可以看到效果
2、按住option，点击demo，在弹出框中可以查看效果

效果1

效果2

再看看多行注释的效果：

    /**
     * item1
     * item2
     * item3
     */
    func listdemo1(){}
    
    /**
      * item1
      * item2
      * item3
     */
    func listdemo2(){}
    
    /**
     a  listdemo function
     * item1
     * item2
     * item3
     */
    
    func listdemo3(){}

listdemo1

listdemo2

listdemo3

仔细看看这个注释有啥区别：在列表形式中，单独的列表形式不会显现效果，要想显示列表，在每一行加一个空格，或者不要让列表在第一行在上端加一个换行或说明。

而在playground中单行注释用//:的形式，多行注释用/*:*/的形式

//: [Next](@next)

/*:
 * item1
 * item2
 * item3
 */

option+M显示效果

一般情况下，有常用的注释范式

/**
 ## Important Notes: something important you want to mention:（一个简短的标题）
 a general description here（一段内容摘要）
（一个注意列表）
 1. item1
 2. item2
 3. item3
 ***（一个分隔,用来区分正文和参考内容）
 [more](https://www.baidu.com/)（一个提供更多内容的链接）
 */