在 Xcode 7 的所有功能中，有一个很特别：它给编写代码文档提供了一个更好的方法。随着 Xcode 7 的更新，开发者可以使用 Markdown 语法书写富文本格式的代码文档，而且可以结合特定的关键词来指明特殊部分（如参数，函数返回结果等）。
同时作为伴随swift3发布的api设计指南要求，为swift代码编写Markdown注释已经从一种道义上升为一种行为准则了。
Markdown的优点
- 纯文本，自定义程度更高，所以兼容性极强，可以用所有文本编辑器打开。
- 让你专注于文字而不是排版。
- 格式转换方便，更加灵活，Markdown 的文本你可以轻松转换为 html、电子书等。
- Markdown 的标记语法有极好的可读性。
Markdown 基础语法
以下列出了最常用的 Markdown 语法：
- #text#：文本标题，相当于 HTML 中的 <H1> 标签。两个 # 则对应 <H2> 标签，以此类推，直到 <h6> 标签。末尾的 # 可以省略。同理,你还可以增加二级标题、三级标题、四级标题、五级标题和六级标题，总共六级，只需要增加 # 即可，标题字号相应降低。
- **text**：使文本具有加粗的效果。
- *text*：使文本具有斜体的效果。
- * text：使文本成为一个无序列表的元素，值得注意的是，有个 * 后面需要有一个空格。同样，可以使用 + 或 - 实现这个的功能。
- text：使文本成为一个有序列表的元素。
- [linked text](http://some-url.com)：使文本成为可以点击的超链接。
- > text：创建一个块引用。
- 使用 4 个空格或 1 个 tab 来缩进所写的代码块，等价于 HTML 中的 <pre></pre> 标签。可以继续使用 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/)（一个提供更多内容的链接）
*/
网友评论