Mattt Thompson 和 Nate Cook撰写、 April Peng翻译
代码的结构和组织关乎了开发童鞋们的节操问题。明确和一致的代码表示了明确和一贯的思想。编译器并没有一个挑剔的口味,但当谈到命名,空格或文档,人类的差异就体现出来了。
NSHipster 的读者无疑会记得去年发表的关于文档的文章,但很多东西已经在 Xcode 6 中发生了变化(幸运的是,基本上算是变得更好了)。因此,这一周,我们将在此为嗷嗷待哺的 Swift 开发者们记录一下文档说明。
好了,来让我们仔细看看。
从 00 年代早期,Headerdoc 就一直作为苹果首选的文档标准。从 Perl 脚本解析勉强的 Javadoc 注释作为出发点,Headerdoc 最终成为了苹果在线文档及 Xcode 中的开发者文档的后台引擎。
随着 WWDC 2014 的发布,开发者文档被翻修并进行了时尚的新设计,包含了 Swift 和 Objective-C 的切换。 (如果你看过任何新的 iOS 8 的在线 API,那你已经见过这个新设计了)
真正让人意外的是,文档的格式 也发生了变化。
在 Swift 的代码里调用快速文档 (Quick Documentation)(⌥ʘ
)时 Headerdoc 没有正确解析注释:
/**
让我们随便来写点什么.
@param 啦啦啦啦,这货是参数。
@return 咯咯咯咯,这货是返回值。
*/
func foo(bar: String) -> AnyObject { ... }
但如果修改一下标记方式,就 可以 被正确解析:
/**
让我们随便来写点什么.
:param: 啦啦啦啦,这货是参数。
:returns: 咯咯咯咯,这货是返回值。
*/
func foo(bar: String) -> AnyObject { ... }
那么,这个陌生的新文件格式是个什么情况?事实证明,SourceKit(Xcode 使用的私有框架,在此前以其高 FPS 崩溃闻名)包括一个解析 reStructuredText 的基本解析器。虽然仅实现了 specification 的一个子集,但涵盖基本的格式已经足够了。
基本标记
文档注释通过使用 /** ... */
的多行注释或 ///...
的单行注释来进行区分。在注释块里面,段落由空行分隔。无序列表可由多个项目符号字符组成:-
、+
、 *
、 •
等,同时有序列表使用阿拉伯数字(1,2,3,...),后跟一个点符 1.
或右括号 1)
或两侧括号括起来 (1)
:
/**
你可以制作 *斜体*, **粗体**, 或 `代码` 的字体风格.
- 列表很不错,
- 但最好不要叠套
- 子列表的格式
- 就不太好了.
1. 有序列表也一样
2. 对那些有序的东西来说;
3. 阿拉伯数字
4. 是唯一支持的格式.
*/
定义与字段列表
定义和字段列表跟 Xcode 里的快速文档弹出内容显示的差不多,定义列表会更紧凑一些:
/**
Definition list
一些术语以及它们的定义.
Format
左对齐术语,放在缩进的定义下面.
:Field header:
字段列表隔开一些。
:Another field: 字段列表可以紧跟开始,不需要另起一行并缩进。
随后缩进的行也被视为内容的一部分.
*/
两个特殊字段用于记录参数和返回值:分别为::param:
和 :returns:
。:param:
后跟的是参数的名称,然后是说明。返回值没有名字,所以 :returns:
后就是说明:
/**
重复一个字符串 `times` 次.
:param: str 需要重复的字符串.
:param: times 需要重复 `str` 的次数.
:returns: 一个重复了 `str` `times` 次的新字符串.
*/
func repeatString(str: String, times: Int) -> String {
return join("", Array(count: times, repeatedValue: str))
}
代码块
代码块也可以嵌入到文档的注释里,这对于演示正确的使用方式或实现细节很有用。用至少两个空格来插入代码块:
/**
`Shape` 实例的面积.
计算取决于该实例的形状。如果是三角形,`area` 将相当于:
let height = triangle.calculateHeight()
let area = triangle.base * height / 2
*/
var area: CGFloat { get }
我的自行车类的新文档
当这个应用在整个类的时候看起来怎么样?事实上,看起来相当的不错:
import Foundation
///