值得一提的是，早在 Swift 3 开始就支持 Markdown 语法注释的渲染了。而它却较少的被提及。如果你还不知道什么是 Markdown，那么引用百度百科的解释就是：

Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。

使用 Markdown 做文档记录、做笔记等等来说是一种非常简便的方式，它可以让我们忽略像在办公软件 work 中大量的通过鼠标等操作设置标题，文字加粗等操作。我们只需通过 Markdown 语法即可排版出美观的文档出来。

Markdown 的基本用法演示

Markdown 文件的后缀名一般为 md，如 index.md ，要使用 Markdown，我们需要创建出 Markdown 文件，预览 Markdown 文件需要使用专门的预览器，市面上有很多的 Markdown 编辑器，如为知笔记、Typora 等都支持 Markdown 文件的编辑和预览。下面通过 Mac 平台的 Quiver 来演示 Markdown 的基本用法

Markdown.png

Swift 中的基本注释

单行注释

// 单行注释
var str: String

多行注释

/*
  多行注释的内容
*/

Swift 支持多行注释的嵌套

/*
 
 /* 多行注释可以嵌套 */
 
*/

文档注释

/**
 文档注释方式1
*/

/// 文档注释方式2

分组注释

//MARK: - 分组注释内容， 同 OC #pragma mark - 

标记待完成

//TODO: 标记未完成

标记待解决的 bug

//FIXME: 要解决的 BUG

注释使用 Markdown 标记

在 Playground 和项目源代码中，使用了两种不同的 Markdown 注释格式，所以我们需要分别了解它们。

① Playground 中注释使用 Markdown 标记

为了在 Playground 中可以方便的看到 Markdown 渲染效果，我们可以对 Xcode 设置快捷键来完成该操作。

打开 Xcode 的偏好设置，或者通过快捷键 option + , 按一下图示操作完成设置

快捷键设置.png

包含 Markdown 的单行注释用 //: 表示：

//: ### 标题3
let str: String = "Markdown"

包含 Markdown 的多行注释用下面的代码表示：

/*:
 * item1
 * item2
 * item3
 */
let height: Float = 173.0

此时按一下我们设置的 Markdown 渲染快捷键，如 option + m ，就可以看到渲染效果，再按一次 option + m 切换回去

image.png

② 项目中注释使用Markdown 标记

其实 Swift 中的多行注释就支持 Markdown 语法标记，如下演示

class ViewController: UIViewController {
    
    /// *高度*
    let height: Float = 173.0
    
    /**
     - 打印字符串
        - str: 要打印的字符串
     */
    func printStr(_ str: String) {
        print(str)
    }

    override func viewDidLoad() {
        super.viewDidLoad()
    }
}

需要注意的是我们在项目中是不能通过快捷键切换 Markdown 渲染效果，我们查看 Markdown 标记渲染的效果，可以通过按住 option 键，用鼠标点击常量、变量或函数名即可看到弹框说明；我们也可以在 Quick Help Inspector 面板中查看

image.png