代码注释中使用 Markdown 并生成在线文档

背景：如果代码注释可以生成如苹果官方文档样式的在线文档，并能使用 Markdown 语法进行编辑，将是一件极好的事情，于是发现了 这篇专题。进行精简之后就有了本文。IDE 要求 Xcode7 及以上

代码注释的重要性

通过写注释，你可以：

• 详细介绍工程中类、方法、属性所表达的意思
• 高亮显示方法中的参数和返回值
• 在几个月后再去看你项目，可以无障碍的知道里面的方法是用来做什么的，属性又代表了什么意思等
• 当你把代码分享出去或制作成库时，开发者可以方便的使用你的代码
• 使用工具比如：Jazzy，生成看上去很专业的使用指南，就像苹果官方文档一样

可以通过3种方式，来预览和查看代码文档：

• 按住 option/alt 按钮，点击某个属性，方法，类名，就会弹出 Quick Help 快速预览
• 光标移到某个属性，方法，类名，打开 Xcode 右边工具栏，在 Quick Help 中查看
• 使用第三方工具，生成一份指南。比如工具 Jazzy ，它可以把所有的注释生成网页，然后把这些网页组成一个单独的网站，并保存到项目的一个子目录中

Markdown 基本语法

请参考 Markdown

开始使用 Markdown 语法

你可以对项目中的属性,方法，类，结构体，枚举，协议，扩展以及任何代码结构或实体进行注释。

注释块写在某个声明的上面，或者某个实体的头一行。每一行以3个斜杠(///)开头，或者所有的注释都写在下面这个块中：

/**

*/

• 我们来看第一个使用 Markdown 语法的代码片段，新建一个 Playground，加入以下代码：

/// This is an **awesome** documentation line for a really *useful* variable
var someVar = "This is a variable"

预览一下这个变量，预览效果如下图：

请注意单词 awesome 是加粗的，因为它被两个星号对包围。而单词 useful 是斜体，因为它被一个星号对包围。

• 我们再来看一个例子，给函数添加注释，添加以下代码：

/**
    It calculates and returns the outcome of the division of the two parameters.
 
    ## Important Notes ##
    1. Both parameters are **double** numbers.
    2. For a proper result the second parameter *must be other than 0*
    3. If the second parameter is 0 then the function will return nil.
 */
func performDivision(number1: Double, number2: Double) -> Double! {
    
    if number2 != 0 {
        return number1 / number2
    }
    else {
        return nil
    }
}

然后，按住 option 键，点击这个函数名称，就会弹出 Quick Help，预览效果如下图：

在注释中，我们使用了两个新元素，header 和 ordered list ，同时也使用了加粗和斜体。只要你按着 Markdown 的语法要求，使用这些特殊的字符，就可以很容易的写出富文本的文档了。下图是在 Xcode 右侧工具栏的 Quick Help 中展示文档的效果：

• 接下来，我们尝试在注释中加入 代码块，为了展示 代码块 的区域效果，需要使用符号 (`) 。在 Playground 中添加以下代码：

/**
    It doubles the value given as a parameter.
    ### Usage Example: ###
    ```
        let single = 5
        let double = doubleValue(single)
        print(double)
    ```
        * Use the `doubleValue(_:)` function to get the double value of any number.
        * Only ***Int*** properties are allowed.
*/
func doubleValue(value: Int) -> Int {
    return value * 2
}

预览效果如下图：

• 最后，我们给 enum 添加注释，每一个 case 都有相应的注释，然后在另外一个函数中使用它。添加如下代码：

/**
    My own alignment options.
    ```
    case Left
    case Center
    case Right
   ```
*/
enum AlignmentOptions  {
    
    /// It aligns the text on the Left side.
    case Left

    /// It aligns the text on the Center.
    case Center
    
    /// It aligns the text on the Right Side.
    case Right
}
func doSomething() {
    
    var alignmentOption :AlignmentOptions!
    alignmentOption = AlignmentOptions.Center
    print(alignmentOption)
}

当我们使用枚举 AlignmentOptions 中的某一个 case 的时候，Xcode 会自动显示相对应的注释，如图所示：

文档中使用关键字

有了富文本，那么再加上些 keywords 会使得文档更加完美。Xcode 会根据 keyword 渲染出对应的格式(同样适用于第三方库生成的文档)，比如高亮显示 参数、返回值、某个类的作者、函数版本等。 keyword 有很多，我们只介绍最常用的几个

• 关键字 parameter（不区分大小写）。

在 Playground 中添加以下代码：

/**
    This is an extremely complicated method that concatenates the first and last name and produces the full name.
    
    - Parameter firstname: The first part of the fullname.
    - parameter lastname: The last part of the fullname.
 
 */
func createFullName(firstname: String, lastname: String) {
    
    let fullname = "\(firstname) \(lastname)"
    print(fullname)
}

文档预览效果如下图：

• 关键字 Returns(记得加上冒号)。

修改上面的代码，返回 full name，文档中添加关键字 Returns 如下：

/**
    This is an extremely complicated method that returns the full name.
     
    - Parameter firstname: The first part of the fullname.
    - parameter lastname: The last part of the fullname.
    - Returns: The full name as a string value.
 */
func returnFullName(firstname: String, lastname: String) -> String{
    
    return "\(firstname) \(lastname)"
}

文档预览效果如下图：

• 以上两个关键字 parameter 和 Returns 是最常用的。

• 关键字 Remark 和 SeeAlso。

写一个函数，把一个 full name，拆分为两部分：firstname 和 lastname，并返回。代码如下：

/**
    Another complicated function.
    - Parameter fullname: The fullname that will be broken into its parts.
    - Returns: A *tuple* with the first and last name.
 
    - Remark:
        There's a counterpart function that contatenates the first and last name into a full name.
    - SeeAlso: `returnFullName(_:lastname:)`
 */
func breakFullName(fullname: String) -> (firstname: String, lastname: String) {
    
    let namesTuple = fullname.componentsSeparatedByString(" ")
    return (namesTuple[0],namesTuple[1])
}

Remark 在文档中高亮显示(吸引开发者注意)，介绍代码中重要的或特殊的地方。SeeAlso 也会高亮显示，其主要是用来延伸到其他地方，或者提供一个 URL 链接，上面的代码中，引用了函数 returnFullName(_:lastname:)。文档预览效果如下：

• 关键字 Precondition 和 Requires。

假设上面的函数是某个库的一部分，为了让开发者正确使用这个函数，需要让开发者知道两点要求：

• 参数 fullname 不能为 nil
• fullname 包含 fistname 和 lastname，它们之间用空格隔开

更新上面的文档：

/**
    Another complicated function.
    - Parameter fullname: The fullname that will be broken into its parts.
    - Returns: A *tuple* with the first and last name.
 
    - Remark:
        There's a counterpart function that contatenates the first and last name into a full name.
    - SeeAlso: `returnFullName(_:lastname:)`
 
    - Precondition: `fullname` should not be nil.
    - Requires: Both first and last name should be parts of the full name,separated with a *space character*.
 */
func breakFullName(fullname: String) -> (firstname: String, lastname: String) {
    
    let namesTuple = fullname.componentsSeparatedByString(" ")
    return (namesTuple[0],namesTuple[1])
}

预览文档效果如下：

• 关键字 Todo。

  在将来的某个版本，也许会去完善这个功能，比如可支持 middle name。那么用 Todo 来介绍：

 - Todo: Suppotr middle name in the next version.

还有很多其它的关键字，比如：warnings, version, author, notes。把它们都加进去，然后看一下效果：

/**
    Another complicated function.
    - Parameter fullname: The fullname that will be broken into its parts.
    - Returns: A *tuple* with the first and last name.
 
    - Remark:
        There's a counterpart function that contatenates the first and last name into a full name.
    - SeeAlso: `returnFullName(_:lastname:)`
 
    - Precondition: `fullname` should not be nil.
    - Requires: Both first and last name should be parts of the full name,separated with a *space character*.
 
    - Todo: Support middle name in the next version.
    - Warning: A wonderful **crash** will be the result of a `nil` parameter.
    - Version: 1.0
    - Author: Cook
    - Note: Too much documentation for such a small function.
 */
func breakFullName(fullname: String) -> (firstname: String, lastname: String) {
    
    let namesTuple = fullname.componentsSeparatedByString(" ")
    return (namesTuple[0],namesTuple[1])
}

生成在线文档

使用 Jazzy 来制作在线文档。Jazzy 这个工具非常棒，可以生成和苹果官方文档一样的在线文档，支持 swift (默认) 和 OC。详细介绍请看 github

• 安装 Jazzy
  打开终端，输入：

sudo gem install jazzy

根据提示输入密码，进行安装。如果安装失败，请查看这个 issue。成功之后会有下图这样类似的信息：

• 你需要一个项目
  你需要一个项目进行文档转换，可以下载 这个项目 作为转换的对象，里面包含有简单的文档说明。

• 开始生成文档
  cd 到刚才下载的文件目录

cd the_path_of_your_project_folder

由于项目中都是用的默认internal 属性，为了包含所有的内容，在终端输入：

jazzy --min-acl internal

回车，成功之后的样子如下图：

• 你可以使用 jazzy -help 来查看所有可以使用的适合你的参数。

• 最后说明
  生成的文档会保存在项目目录下 docs 文件夹中。进入这个文件夹，双击打开 index.html，就可以在网页上查看生成的文档了：

• 总结
  文档在一个项目中的地位是和重要的，尤其是多人合作开发。如果一段文档不能清晰的表达代码意思，对于开发者的效率来说是致命的。故，通过此文章，来鼓励 IT 人员尽可能详细的书写文档。