本篇为译文，原文可见：链接
如果超过 6 个月没看过自己写的代码的话，你可能会认为这些代码是其他人写的。
-Eagleson’s Law
当我们使用 Apple 的 class 时，如果不知道如何使用它们的话，我们有很多方式可以去查找资料。比如你可以通过 Apple Developer Documentation 在线文档或者通过 Xcode 来查找。
Quick help popover
你可以通过 ⌥ – Option + click 方式查看任何 class：
Symbol inspector Quick Help
Quick help 也显示在 Quick Help 检查面板（inspector panel）上。
Code completion hint
当你开始打字时，Xcode 将会有相应的提示信息（包含 class 中的 function/property/enum）
接下来将介绍如何给自己的代码加上这些提示。
Syntax
给代码写文档就像写注释一样，但是有一点点语法上的差别。你需要 /// 来标注单行的文档。
/// This is your User documentation.
struct User {
let firstName: String
let lastName: String
}对于多行文档，你需要 /** ... */ 符号。
/**
This is your User documentation.
A very long one.
*/
struct User {
let firstName: String
let lastName: String
}
Summary and Discussion
上述文档注释将会生成一个包含 summary 的文档。
如果要增加 discussion 区域，你只需要编写另一段即可。非第一段的内容都将属于 discussion 区域。
注：Swift 的文档注释支持 Markdown 语法。Markdown 中段落是根据空行数（需大于等于 1 个空行）分隔的。
因此，上述例子包含了两句话（属于同一个段落），它们将属于 summary 区域。
/**
This is your User documentation.
A very long one.
*/如果想要第二句话出现在 discussion 区域，在两个句子之间加入一个新空行就可以了。
/**
This is your User documentation (This is summary).
A very long one (This will be shown in the discussion section).
*/你也可以在文档中使用标准的 markdown 语法。
/**
This is your User documentation.
A very long one.
# Text
It's very easy to make some words **bold** and other words *italic* with Markdown. You can even [link to Google!](http://google.com)
# Lists
Sometimes you want numbered lists:
1. One
2. Two
3. Three
Sometimes you want bullet points:
* Start a line with a star
* Profit!
Alternatively,
- Dashes work just as well
- And if you have sub points, put two spaces before the dash or star:
- Like this
- And this
*/
struct User {
let firstName: String
let lastName: String
}效果如下：
对于注释 class、property 或者简单的 function，Summary 和 discussion 足够了。对于复杂的 function，我们可以添加更多的区域来展现。
Parameters
对于带参数的 function，你可以在 Quick Help 添加 parameter 区域。有两种方式可以给参数添加注释，一个是 Parameters Section，另一个是 separate Parameter Fields 。
Separate Parameter Fields
- Parameter x: ...
- Parameter y: ...Parameters Section
这种声明方式满足多参数的 function。对于多参数的 funcion 来说，如果使用 Separate Parameter Fields 方式的话，可能会显得比较冗余。
- Parameters:
- x: ...
- y: ...
- z: ...Returns
对于一个有返回值的 function，你可以添加 return 区域，语法跟添加参数类似。
- Returns: ...注：你可以指定多个返回值，但是只有最后一个会显示在
Xcode中的QuickHelp。
Throws
Throws 语法如下：
- Throws: ...被标记为 Throws 的 Functions 需要包含 error 描述和对应的场景。
/// A way that this user greets others.
///
/// Use this method to get the greeting for the user. The person you specify don't affect the way user greet, just the first name, and last name will be used.
/// - Warning: The greeting is always in the caller localization.
/// - Throws:
/// - <code>MyError.invalidPerson</code>
/// if <code>person</code> is not known by the caller.
/// - <code>MyError.hardToPronounce</code>
/// if <code>person</code> name is longer than 20 characters.
/// - Parameter person: <code>User</code> you want to greet
/// - Returns: A greeting of the current <code>User</code>.
func greeting(person: User) throws -> String {
return "Hello \(person.firstName) \(person.lastName)"
}
注：注释中只能处理一个
Thorws，不支持多个Throws。
Auto-generate Quick Help documentation
Xcode 提供了一种简易方式来生成文档。在任何想要加文档注释的地方，按下 ⌥ – Option + ⌘ - command + /，或通过 Xcode 菜单 Editor > Structure > Add documentation，Xcode 将会为你生成文档模版。
/// <#Description#>
/// - Parameter person: <#person description#>注：这个功能在不同的 Xcode 版本上可能会不一样。
Extra Fields
文档中可以添加 Callout ，语法如下：
- Callout: description下面这些是你能使用的 Callout ：
- Attention: ...
- Author: ...
- Authors: ...
- Bug: ...
- Complexity: ...
- Copyright: ...
- Date: ...
- Experiment: ...
- Important: ...
- Invariant: ...
- Note: ...
- Postcondition: ...
- Precondition: ...
- Remark: ...
- Remarks: ...
- Requires: ...
- See: ...
- Since: ...
- Todo: ...
- Version: ...
- Warning: ...Callout 将呈现在 Quick Help 中，它处于 discussion 区域下面。
示例如下：
/// A way that this user greets others.
///
/// Use this method to get the greeting for the user. The person you specify don't affect the way user greet, just the first name, and last name will be used.
/// - Warning: The greeting is always in the caller localization.
/// - Parameter person: <code>User</code> you want to greet
/// - Returns: A greeting of the current <code>User</code>.
func greeting(person: User) -> String {
return "Hello \(person.firstName) \(person.lastName)"
}
总结
编写一个好文档并不容易，往往是比较耗时的。但是好文档的价值将会在未来体现出来。