如何阅读苹果开发文档

原文：How to read Apple’s developer documentation

对于不少人来讲，这篇文章听起来很奇怪，由于咱们已经习惯了 Apple 的 API 文档的工做方式，所以咱们精神上已经通过调整以快速找到咱们想要的东西。

但这是一个有趣的事实：去年我最热门的文章请求之一是帮助人们真正阅读 Apple 的代码文档。您如何找到您须要的 iOS API，如何浏览全部材料以找到您真正想要的内容，以及您如何深刻了解为何事情按照他们的方式工做？

因此，若是你曾经寻求帮助来理解 Apple 的开发者文档，首先我要让你知道你并不孤单 - 许多人都在努力解决这个问题。但其次，我但愿这篇文章会有所帮助：我会尽力解释它的结构，它有什么好处（以及很差的地方），以及如何使用它。

更重要的是，我将向您展现经验丰富的开发人员寻找额外信息的位置，这些信息一般比Apple的在线文档更有价值。

<!--more-->

“这是什么？” vs “你怎么用它？”

任何书面的 API 文档一般采用如下五种形式之一：

1. 接口代码，显示了什么是方法名称和参数，属性名称和类型，以及相似的，带有一些描述它应该作什么的文本。
2. API 的文本描述了它应该作什么以及通常指导用例。
3. 普遍使用的有用的 API​ ​示例代码。
4. 如何使用 API​​ 代码段。
5. 解决常见问题的简单教程：如何作 X，如何作 Y，以及如何作 Z 等等。

粗略地说，苹果公司第一点作了不少，其次是第二点和第三点，第四点不多，​​第五点几乎没有。

因此，若是你正在寻找“如何用 Y 作 X ”的具体例子，你最好从个人 Swift 知识库开始 - 这正是它的用途。

了解 Apple 的文档解决的问题，能够帮助您从中得到最大收益。它并非一个结构化的教程，它不会向您介绍一系列概念来帮助您实现目标，而是做为 Apple 支持的数千个 API 的参考指南。

寻找一个类

Apple的在线文档位于 https://developer.apple.com/d... ，虽然您能在 Xcode 中使用本地副本，但我会说大多数人使用在线版本只是由于他们能够更容易地找到内容。

绝大多数 Apple 的文档都描述了接口，而这正是大多数时候你会看到的。我想使用一个实际的例子，因此请先在您的网络浏览器中打开https://developer.apple.com/d... ，这是全部Apple开发者文档的主页。

您会看到全部 Apple 的 API 分为 App Frameworks 或 Graphics and Games 等类别，您已经看到了一件重要的事情：全部深蓝色文本都是可点击的，并会带您进入特定框架的API文档。是的，它使用相同的字体和大小，没有下划线，说实话，深蓝色连接和黑色文本之间没有太大区别，但你仍然须要留意这些连接 - 有不少他们，你会用它们来深刻挖掘主题。

如今请从 App Frameworks 类别中选择 UIKit，您将看到它的功能（为iOS建立用户界面）的简要概述，标有“重要”（Important）的大黄色框，而后是类别列表。那些黄色的盒子确实值得关注：虽然它们常常被使用，它们几乎总能阻止你犯下根本错误，这些错误致使出现奇怪的问题。

此页面上重要的是共同描述 UIKit 的类别列表。这是人们常常迷路的地方：他们想要了解像 UIImage 这样的东西，因此他们必须仔细查看该列表以找到它可能出现的合适位置。

在这种状况下，您可能会查看“资源管理”（Resource Management），由于它的副标题“管理存储在主可执行文件以外的图像，字符串，故事板和 nib 文件”听起来颇有但愿。可是，您会感到失望 - 您须要向下滚动到 “图像和 PDF”（Images and PDF）部分才能找到 UIImage。

这就是为何我谈过的大多数人只是使用本身喜欢的搜索引擎。他们输入他们关心的类，而且 - 只要它有“UI”，“SK”或相似的前缀 - 它多是第一个结果。

不要误会个人意思：我知道这种作法并不理想。可是面对搜索一个类或者去 https://developer.apple.com/d... ，选择一个框架，选择一个类别，而后选择一个类，第一个就是更快。

重要提示：不管您选择哪一种方法，最终都会在同一个地方，因此只作最适合您的方法。如今，请找到并选择 UIImage。

阅读类的接口

一旦选择了您关心的类，该页面就有四个主要组件：概述，版本摘要，接口和关系。

概述是“API的文本描述，描述了它应该作什么以及通常指导用例”，我以前提到过 - 我要求你选择 UIImage，由于它是文本描述什么时候运行良好的一个很好的例子。

当它是我第一次使用的类时，特别是若是它刚刚推出时，我一般会阅读概述文本。可是对于其余一切 - 我以前至少使用过一次的任何类 - 我跳过它并尝试找到我所获得的具体细节。请记住，Apple 文档确实不是一种学习工具：当您考虑到特定目的时，它最有效。

若是您不老是为所选 Apple 平台的最新版本开发，则版本摘要 - 页面右侧的侧栏 - 很是重要。在这种状况下，您将看到 iOS 2.0 +，tvOS 9.0+ 和 watchOS 2.0+，它告诉咱们什么时候 UIImage 类首次在这三个操做系统上可用，而且它仍然可用 - 若是它已被弃用（再也不可用）你会看到像 iOS 2.0-9.0 这样的东西。

此页面上的实际内容 - 以及做为 Apple 框架中特定类的主页的全部页面 - 都列在“主题”标题​​下。这将列出该类支持的全部属性和方法，再次分解为使用类别：“获取图像数据”，“获取图像大小和比例”等。

若是您选择的类具备任何自定义初始化方法，则始终会首先显示它们。 UIImage 有不少自定义初始化方法，你会看到它们都被列为签名 - 只是描述它所指望的参数的部分。因此，你会看到这样的代码：

init?(named: String)
init(imageLiteralResourceName: String)

提示：若是您看到 Objective-C 代码，请确保将语言更改成 Swift。您能够在页面的右上角执行此操做，也能够在重要的 iOS 测试版引入更改时启用 API 更改选项。

记住，初始化方法写成 init? 而不是 init 的是容易出错的 - 它们返回一个可选项，以便在初始化失败时它们能够返回 nil。

在初始化器的正下方，您有时会看到一些用于建立类的高度专业化实例的方法。这些不是 Swift 意义上的初始化器，但它们确实建立了类的实例。对于 UIImage，你会看到这样的事情：

class func animatedImageNamed(String, duration: TimeInterval) -> UIImage?

class func 部分意味着你将使用 UIImage.animatedImageNamed() 方式调用。

在初始化程序以后，事情变得有点不那么有条理：你会发现属性方法和枚举自由混合在一块儿。虽然您能够滚动查找您要查找的内容，但我能够认为大多数人只须要 Cmd + F 在页面上查找文字就能够了！

有三点须要注意：

• 嵌套类型 - 类，结构和枚举 - 与属性和方法一块儿列出，这须要一点时间习惯。例如，UIImage 包含嵌套的枚举 ResizingMode。
• 任何带有直线穿过的东西都是不推荐使用的。这意味着 Apple 打算在某些时候将其删除，所以您不该将其用于未来的代码，并建议开始重写任何现有代码。（在实践中，大多数API长期以来都被“弃用” - 许多许多年。）
• 一些很是复杂的类 - 例如，UIViewController - 会将额外的文档页面与其方法和属性混合在一块儿。查找它们旁边的页面图标，以及一个简单的英文标题，如“相对于安全区域定位内容”（Positioning Content Relative to the Safe Area）。

在页面的底部你会找到 Relationships，它告诉你它继承了哪一个类（在这种状况下它直接来自 NSObject），以及它符合的全部协议。当您查看 Swift 类型时，本节更有用，其中协议关系更复杂。

阅读属性或方法页面

您已经选择了一个框架和类，如今是时候查看特定的属性或方法了。查找并选择此方法：

class func animatedResizableImageNamed(String, capInsets: UIEdgeInsets, resizingMode: UIImage.ResizingMode, duration: TimeInterval) -> UIImage?

您应该在 Creating Specialized Image Objects 类别中找到它。

这不是一个复杂的方法，但它确实展现了这些页面的重要部分：

• Apple 有几种不一样的方法来编写方法名称。以前的那个 - 长 class func animatedResizableImageNamed - 而后是方法页面标题中显示的形式（animatedResizableImageNamed(_:capInsets:resizingMode:duration:)），以及方法页面的声明部分中的形式。
• 正如您在版本摘要中所看到的（在右侧），此方法在 iOS 6.0 中引入。所以，虽然主要的 UIImage 类从第1天开始就已存在，但这种方法是在几年后推出的。
• 方法声明的各个部分都是可点击的，都是紫色的。可是要当心：若是你单击 UIImage.ResizingMode，你将去哪里取决于你是否点击了“UIImage”或“ResizingMode”。 （提示：您一般须要单击右侧的那个。）
• 您将看到每一个参数含义和返回值的简要说明。
• “讨论”（Discussion）部分详细介绍了此方法的具体使用说明。这几乎老是 - 每一个页面中最有用的部分，由于在这里您能够看到“不要调用此方法”或“当心......”
• 你可能会找到一个 See Also 部分，但这有点受欢迎 - 这里只是咱们在上一页的方法列表。

如今，UIImage 是一个老类，并无太大变化，所以它的文档处于良好状态。可是一些较新的 API - 以及许多没有像 UIKit 那样被喜欢的旧 API - 仍然记录不足。例如，来自 SceneKit 的 SCNAnimation 或来自 UIKit 的 UITextDragPreviewRenderer：二者都是在 iOS 11 中引入的，而且在它们发布18个月后仍然包含“无可用概述（No overview available）”做为其文档。

当你看到“没有可用的概述（No overview available）”时，你会失望，但不要放弃：让我告诉你接下来要作什么......

查看代码

尽管 Apple 的在线文档至关不错，但您常常会遇到“无可用概述（No overview available）”，或者您发现没有足够的信息来回答您的问题。

康威定律（Conway's law）指出，设计系统的组织受制于设计，这些设计是这些组织的通讯结构的副本。“也就是说，若是你以某种方式工做，你将以相似的方式设计事物。

Apple 在咱们行业中的独特意位使他们以一种至关不寻常的方式工做 - 几乎能够确定它与您本身公司的工做方式彻底不一样。是的，他们有 API 审核讨论，他们试图讨论API应该如何用两种语言看待，是的，他们有专门的团队来制做文档和示例代码。

可是他们获取示例代码的门槛很是高：一般须要一些很是好的东西才能拿出来，而且经过多层检查来处理法律问题。所以，虽然我能够在一小时内输入一个项目并当即将其发布为文章，但 Apple 须要花费更长的时间才能完成一样的工做 - 他们很是认真地对待他们的形象，并且很是正确。若是你曾经想过为何文章不多出如今官方 Swift 博客上，如今你知道了！

如今，我说这一切的缘由是 Apple 有一个快速使用的捷径：他们的工程师在他们的代码中留下评论的门槛彷佛显着下降，这意味着你常常会在 Xcode 中找到有价值的信息。这些评论就像细小的金子（gold dust）同样：它们直接来自 Apple 的开发者，而不是他们的开发者出版（developer publications）团队，并且我对 devpubs 很是热爱，很高兴直接听到来自源头的声音。

还记得我提到过 SceneKit 的 SCNAnimation 在 Apple 的开发者网站上没有记录吗？好吧，让咱们来看看Xcode能够向咱们展现的内容：按 Cmd + O 打开“快速打开（Open Quickly）”菜单，确保右侧的 Swift 图标为彩色而不是空心，而后键入“SCNAnimation”。

您将看到列出的一些选项，但您正在寻找 SCNAnimation.h 中定义的选项。若是您不肯定，选择 YourClassName.h 文件是您最好的选择。

不管如何，若是你打开 SCNAnimation.h Xcode 将显示生成的 SCNAnimation 头文件版本。它的生成是由于原始版本是Objective-C，所以 Xcode 为 Swift 进行了实时翻译 - 这就是 Swift Quickly 框中的彩色 Swift 徽标的含义。

如今，若是你按 Cmd + F 并搜索“class SCNAnimation”，你会发现：

/**
 SCNAnimation represents an animation that targets a specific key path.
 */
@available(iOS 11.0, *)
open class SCNAnimation : NSObject, SCNAnimationProtocol, NSCopying, NSSecureCoding {  
    /*!
     Initializers
     */

    /**
     Loads and returns an animation loaded from the specified URL.

     @param animationUrl The url to load.
     */
    public /*not inherited*/ init(contentsOf animationUrl: URL)

这只是一个开始。 是的，该类及其全部内部都有文档，包括用法说明，默认值等。 全部这一切都应该在在线文档中，但不管出于什么缘由它仍然没有，因此要准备好查找代码做为一个有用的补充。

最后的提示

此时，您应该可以查找在线文档以获取您喜欢的任何代码，并查找头文件注释以获取额外的使用说明。

可是，在准备好面对所有 Apple 文档以前，还有两件事须要了解。

首先，您常常会遇到标记为“已归档（archived”）”，“遗留（“legacy”）”或“已退休（“retired）”的文档 - 即便对于相对较新的事物也是如此。当它真的老了，你会看到诸如“这篇文章可能不表明当前发展的最佳实践”之类的消息。下载和其余资源的连接可能再也不有效。“

尽管 Apple 是世界上最大的公司之一，但 Apple 的工程和 devpubs 团队几乎没有人员 - 他们不可能在保留全部内容的同时覆盖新的 API。所以，当你看到“存档”文档或相似文件时，请运用你的判断：若是它在某个版本的 Swift 中至少你知道它最近是模糊的，但即便不是，你仍然可能会发现那里有不少有价值的信息。

其次，Apple 拥有一些特别有价值的出色文档。这些都列在 https://developer.apple.com 的页脚中，但主要是人机界面指南。这将引导您完整地为 Apple 平台设计应用程序的全部部分，包括说明关键点的图片，并提供大量具体建议。即便这个文档是构建 iOS 应用程序时最重要的一个，但不多有开发人员彷佛已经阅读过它！

接下来作什么？

我以前曾写过关于 Apple 文档的问题 - 我担忧那里没有鼓励，但至少若是你在努力，它可能会让你以为不那么孤单。

幸运的是，我有不少可能更有用的材料：

• 个人Swift知识库（Swift Knowledge Base）包含针对 Swift 和 iOS 开发人员的600多个问答，技巧和技术点 - 它能够帮助您更快地解决问题。
• 个人Swift术语表（Glossary of Common Swift Terms）在 Swift 开发中定义了100多个经常使用术语，全部术语都在一页上。
• 我有一本全书使用项目教授 Swift 和 iOS，它专门用于在逻辑流程中引入概念。

您认为阅读Apple文档最有效的方法是什么？ 在Twitter上发送你的提示：@twostraws。