本篇为译文,原文可见:链接
如果超过 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)"
}
总结
编写一个好文档并不容易,往往是比较耗时的。但是好文档的价值将会在未来体现出来。