原文地址 Swift Documentation
代码结构和组织是开发人员引以为豪的事情。清晰一致的代码意味着清晰一致的思想。即使编译器在命名、空格或文档方面缺乏敏锐的品味，但它对人类合作者来说是完全不同的。
本周，我们将在Swift中记录此时此地的文档。
自20世纪初以来，Head erdoc一直是苹果首选的**文档标准。从分析捏造的Javadoc**注释的Perl脚本开始，Head erdoc最终将成为苹果在线和Xcode开发者文档的引擎。
但就像苹果开发者生态系统中的许多人一样，Swift改变了一切。本着*“旧的，新的”的精神，Xcode 7用Head doc换了粉丝*最喜欢的Markdown——特别是Swift风格的Markdown**。
文档注释和快速风格的降价
即使你以前从未写过一行降价，你也可以在几分钟内跟上速度。这里几乎是你需要知道的一切：
基本标记
文档注释看起来像普通注释，但是有一点额外的东西。单行文档注释有三个斜杠 (///). 多行文档注释在其开始分隔符中有一个额外的星号 (/** ... */).
标准Markdown规则适用于文档注释：
-
段落之间用空行分隔。
-
无序列表由项目符号 (-, +, *, 或）标记。
-
有序列表使用数字（1,2,3, …) 后跟句号（1.）或右括号（1））。
-
标题前面有#符号或用=或-加下划线。
/** # Lists You can apply *italic*, **bold**, or `code` inline styles. ## Unordered Lists - Lists are great, - but perhaps don't nest; - Sub-list formatting... - ...isn't the best. ## Ordered Lists 1. Ordered lists, too, 2. for things that are sorted; 3. Arabic numerals 4. are the only kind supported.*/
总结&
文档注释的前段成为文档摘要。任何附加内容都被分组到讨论部分。
参数和返回值
Xcode识别一些特殊的字段，并使它们与符号的描述分开。当样式为项目符号，然后是冒号时，参数、返回值和抛出部分在快速帮助弹出窗口和检查器中展开 (:).
-
Parameters：以Parameter<参数名称>**：**和参数说明开始行。
-
返回值：以**返回：**和有关返回值的信息开始一行。
-
抛出的错误：以抛出开始行：以及可以抛出的错误的描述。由于Swift不会键入检查抛出的错误是否符合错误，因此正确记录错误尤为重要。
/** Creates a personalized greeting for a recipient. - Parameter recipient: The person being greeted. - Throws: `MyError.invalidRecipient` if `recipient` is "Derek" (he knows what he did). - Returns: A new string saying hello to `recipient`. */func greeting(to recipient: String) throws -> String { guard recipient != "Derek" else { throw MyError.invalidRecipient } return "Greetings, \(recipient)!"}
您是否正在记录一个函数，其方法签名比黑客新闻线程中关于制表符和空格的参数更多？将您的参数分解成参数：标注下面的项目符号列表：
/// Returns the magnitude of a vector in three dimensions/// from the given components.////// - Parameters:/// - x: The *x* component of the vector./// - y: The *y* component of the vector./// - z: The *z* component of the vector.func magnitude3D(x: Double, y: Double, z: Double) -> Double { return sqrt(pow(x, 2) + pow(y, 2) + pow(z, 2))}
附加字段
除了参数、抛出和返回之外，Swift风格的Markdown还定义了一些其他字段，这些字段可以通过以下方式松散地组织：
Algorithm/Safety信息
前提条件
后置条件
需要
不变的，不变的
复杂性
重要的；重要的
警告；警告
元数据
作者
作者
版权所有
日期
查看更多
自从
版本
一般注意事项和规劝
注意啦
臭虫
实验，实验
注意事项
备注
待办事项
这些字段中的每一个都在快速帮助中呈现为一个粗体标题，后面跟着一个文本块：
字段头：
子字段的文本从下一行开始显示。
代码块
通过嵌入代码块来演示函数的正确用法或实现细节。插入代码块至少四个空格：
/** The area of the `Shape` instance. Computation depends on the shape of the instance. For a triangle, `area` is equivalent to: let height = triangle.calculateHeight() let area = triangle.base * height / 2*/var area: CGFloat { get }
有栅栏的代码块也可以识别，由三个反标 (`) 或波浪线分隔 (~):
/** The perimeter of the `Shape` instance. Computation depends on the shape of the instance, and is equivalent to: ~~~ // Circles: let perimeter = circle.radius * 2 * Float.pi // Other shapes: let perimeter = shape.sides.map { $0.length } .reduce(0, +) ~~~*/var perimeter: CGFloat { get }
文档是我的新自行车
当应用到整个班级时，这看起来怎么样？实际上相当不错！
/// 🚲 A two-wheeled, human-powered mode of transportation.class Bicycle { /// Frame and construction style. enum Style { /// A style for streets or trails. case road /// A style for long journeys. case touring /// A style for casual trips around town. case cruiser /// A style for general-purpose transportation. case hybrid } /// Mechanism for converting pedal power into motion. enum Gearing { /// A single, fixed gear. case fixed /// A variable-speed, disengageable gear. case freewheel(speeds: Int) } /// Hardware used for steering. enum Handlebar { /// A casual handlebar. case riser /// An upright handlebar. case café /// A classic handlebar. case drop /// A powerful handlebar. case bullhorn } /// The style of the bicycle. let style: Style /// The gearing of the bicycle. let gearing: Gearing /// The handlebar of the bicycle. let handlebar: Handlebar /// The size of the frame, in centimeters. let frameSize: Int /// The number of trips traveled by the bicycle. private(set) var numberOfTrips: Int /// The total distance traveled by the bicycle, in meters. private(set) var distanceTraveled: Double /** Initializes a new bicycle with the provided parts and specifications. - Parameters: - style: The style of the bicycle - gearing: The gearing of the bicycle - handlebar: The handlebar of the bicycle - frameSize: The frame size of the bicycle, in centimeters - Returns: A beautiful, brand-new bicycle, custom-built just for you. */ init(style: Style, gearing: Gearing, handlebar: Handlebar, frameSize centimeters: Int) { self.style = style self.gearing = gearing self.handlebar = handlebar self.frameSize = centimeters self.numberOfTrips = 0 self.distanceTraveled = 0 } /** Take a bike out for a spin. Calling this method increments the `numberOfTrips` and increases `distanceTraveled` by the value of `meters`. - Parameter meters: The distance to travel in meters. - Precondition: `meters` must be greater than 0. */ func travel(distance meters: Double) { precondition(meters > 0) distanceTraveled += meters numberOfTrips += 1 }}
选项-单击初始化器声明，描述用项目符号列表漂亮地呈现：
打开方法旅行的快速文档，并将参数解析为单独的字段，如预期的那样：
标记//修复
在目标C中，**预处理器指令#pragma标记**用于将功能划分为有意义的、易于导航的部分。在Swift中，同样可以通过//MARK：的注释来完成。
以下注释出现在Xcode源代码导航器中：
-
//马克：
-
//待办事项：
-
//修复：
Xcode无法识别其他传统的评论标签，如NOTE和XXX。
为了显示这些新的标签的作用，以下是如何扩展Bickcle类以采用Custom String Converble协议，并实现描述属性。
// MARK: - CustomStringConvertibleextension Bicycle: CustomStringConvertible { public var description: String { var descriptors: [String] = [] switch self.style { case .road: descriptors.append("A road bike for streets or trails") case .touring: descriptors.append("A touring bike for long journeys") case .cruiser: descriptors.append("A cruiser bike for casual trips around town") case .hybrid: descriptors.append("A hybrid bike for general-purpose transportation") } switch self.gearing { case .fixed: descriptors.append("with a single, fixed gear") case .freewheel(let n): descriptors.append("with a \(n)-speed freewheel gear") } switch self.handlebar { case .riser: descriptors.append("and casual, riser handlebars") case .café: descriptors.append("and upright, café handlebars") case .drop: descriptors.append("and classic, drop handlebars") case .bullhorn: descriptors.append("and powerful bullhorn handlebars") } descriptors.append("on a \(frameSize)\" frame") // FIXME: Use a distance formatter descriptors.append("with a total of \(distanceTraveled) meters traveled over \(numberOfTrips) trips.") // TODO: Allow bikes to be named? return descriptors.joined(separator: ", ") }}
在代码中整合所有内容：
var bike = Bicycle(style: .road, gearing: .freewheel(speeds: 8), handlebar: .drop, frameSize: 53)bike.travel(distance: 1_500) // Trip around the townbike.travel(distance: 200) // Trip to the storeprint(bike)// "A road bike for streets or trails, with a 8-speed freewheel gear, and classic, drop handlebars, on a 53" frame, with a total of 1700.0 meters traveled over 2 trips."
在撰写本文时，没有官方工具可以将文档注释转换成比Xcode中的快速帮助面板更有形的东西，
幸运的是，在需要的地方，开源（通常）提供。
爵士乐
**Jazzy**是一个非常棒的开源命令行实用程序，它将您项目的文档注释转换成一组类似苹果的超文本标记语言文档（但是在整个重新设计之前，那种不错的复古风格）。Jazzy使用Xcode的Source KitService来阅读您写得漂亮的类型和方法描述。
将Jazzy安装为gem，然后从项目文件夹的根目录运行以生成文档。
$ gem install jazzy$ jazzyRunning xcodebuildParsing ...building sitejam out ♪♫ to your fresh new docs in `docs`
**偷看一下Jazzy**生成的自行车类文档。
尽管围绕Swift的工具和文档仍在开发中，但明智的做法是尽早养成良好的习惯，将新的Markdown功能用于文档，并在Swift代码中使用MARK：注释。
继续并将其添加到您的TO DO：列表中。
