代码的结构和组织关乎了开发童鞋们的节操问题。明确和一致的代码表示了明确和一贯的思想。编译器并没有一个挑剔的口味，但当谈到命名，空格或文档，人类的差异就体现出来了。
NSHipster 的读者无疑会记得去年发表的关于文档的文章，但很多东西已经在 Xcode 6 中发生了变化（幸运的是，基本上算是变得更好了）。因此，这一周，我们将在此为嗷嗷待哺的 Swift 开发者们记录一下文档说明。
好了，来让我们仔细看看。
从 00 年代早期，Headerdoc就一直作为苹果首选的文档标准。从 Perl 脚本解析勉强的Javadoc注释作为出发点，Headerdoc 最终成为了苹果在线文档及 Xcode 中的开发者文档的后台引擎。
随着 WWDC 2014 的发布，开发者文档被翻修并进行了时尚的新设计，包含了 Swift 和 Objective-C 的切换。 （如果你看过任何新的 iOS 8 的在线 API，那你已经见过这个新设计了）
真正让人意外的是，文档的格式也发生了变化。
在 Swift 的代码里调用快速文档 (Quick Documentation)（⌥ʘ）时 Headerdoc 没有正确解析注释：
Swift
/**
让我们随便来写点什么.
@param 啦啦啦啦，这货是参数。
@return 咯咯咯咯，这货是返回值。
*/
func foo(bar: String) -> AnyObject { ... }
:param: 啦啦啦啦，这货是参数。
:returns: 咯咯咯咯，这货是返回值。
那么，这个陌生的新文件格式是个什么情况？事实证明，SourceKit（Xcode 使用的私有框架，在此前以其高 FPS 崩溃闻名）包括一个解析reStructuredText的基本解析器。虽然仅实现了specification的一个子集，但涵盖基本的格式已经足够了。
基本标记
文档注释通过使用/** ... */的多行注释或///...的单行注释来进行区分。在注释块里面，段落由空行分隔。无序列表可由多个项目符号字符组成：-、+、*、•等，同时有序列表使用阿拉伯数字（1，2，3，...），后跟一个点符1.或右括号1)或两侧括号括起来(1)：
定义与字段列表
定义和字段列表跟 Xcode 里的快速文档弹出内容显示的差不多，定义列表会更紧凑一些：
Definition list
一些术语以及它们的定义.
Format
左对齐术语，放在缩进的定义下面.
:Field header:
字段列表隔开一些。
:Another field: 字段列表可以紧跟开始，不需要另起一行并缩进。
随后缩进的行也被视为内容的一部分.
*/
