背景：如果代码注释可以生成如苹果官方文档样式的在线文档，并能使用 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 人员尽可能详细的书写文档。
