[译]如何阅读Apple开发文档
superleeyom opened this issue · 0 comments
周末外面一直下雨,闲着也是没事,尝试花了几个小时,把 Hacking with Swift 的创始人 Paul Hudson 在2019 年写的一篇关于「How to read Apple’s developer documentation」的文章翻译成了中文,虽然距离这篇文章发表已经过去两三年了,但是里面的**和方法却永远不会过时,希望能帮助大家,以下便是译文:
作者:Paul Hudson,日期:2019年1月18日
对于很多人来说,这篇文章看起来可能会比较奇怪,因为我们大多数人已经习惯了Apple的API文档的使用方式,并且也能快速的找到我们自己想要的东西。
但是有一个有意思的事实是:去年很多朋友希望我写一些关于如何阅读Apple开发文档的文章,比如有:你是如何去查看iOS的API接口的?如何在这些开发文档中找到你想要的东西?如何深入了解这些文档或者接口的底层原理?
你是不是曾经也希望有人帮助你去理解Apple的开发文档呢?其实并不只你一个人,有很多人的都有相同的苦恼。所以我希望这篇文章能对你有所帮助:我会尽力去解释它的整体结构,它有什么好的地方和不好的地方,以及我是如何使用Apple的开发者文档的。
更重要的一点是,我将向你展示那些有经验的人是如何去搜寻相关资料,并且这些资料要比Apple的在线文档更有价值。
“它是什么?” vs “你怎么用它?”
任何的API文档应该有以下5种特性之一:
- 接口代码通常需要展示:方法名称和参数、属性名称和类型等,并带有一小段文字描述它的功能是什么,它是做什么的。
- API应该有用例指导的描述
- 示例代码应该多多使用这些API,以使得它们更加的有用
- 展示如何使用基础的API代码片段
- 需要有一套总结常见的问题的方法:比如:如何做 X,如何做 Y,以及如何做 Z,等等。
通俗点讲,Apple第1点做的很不错,第2和第3点也做的很多,但是第4点做的相当少,第5点几乎就没有。
所以,如果你正在寻找「如何使用Y去做X」的具体示例,你可以尝试从我的「swift的基础知识」教程学起,这也正是这篇教程的用途。
理解 Apple 的文档所要解决的问题,将帮助你最大限度地利用它。它不是一个结构化的教程——它也不会向你介绍一系列的概念来帮助你实现一个目标,它只是作为苹果支持的数千个API 的参考指南。
寻找类
Apple的在线开发文档在:https://developer.apple.com/documentation/,虽然你有一个Xcode的本地离线版本,但是和我交流过的绝大多数的人都是使用的在线的版本,因为他们可以更容易的找到他们想要的东西。
Apple绝大多数的文档都有接口描述,这也是你看的最多的。我想用一个实际的例子,所以请从在你的浏览器中打开https://developer.apple.com/documentation/ (那是所有苹果开发者文档的主页)。
你会看到苹果所有的 API 都被分成了App Frameworks、Graphics 、Games等类别,并且你已经看到了一个重要的东西:所有深蓝色的文本都是可点击的,点击后它将带你进入特定框架的API文档。它使用相同的字体和大小,没有下划线,老实说,深蓝色链接和黑色文本之间没有太大区别,但你仍然需要留意这些链接,其中有很多,你将大量使用它们并进行深入研究。
现在请从App Frameworks类别中选择UIKit,你会看到它的简要概述(为iOS创建用户界面),一个标记为「重要」的黄色大框,然后是一个类别列表。这些黄色的框框确实值得注意:尽管它们被频繁使用,但它们几乎总能阻止你犯一些基础的错误,从而在以后引发一些奇怪的问题。
这个页面描述了UIKit的类别列表,这是也是大多数人通常会迷失的地方:他们想要学习一些类似于UIImage的东西,以至于他们必须查看整个列表,然后在合适的地方找到它。
在这种情况下,你可能会查看「Resource Management」这个类别,因为它的副标题写着 「管理存储在主可执行文件之外的图像、字符串、storyboards 和 nib 文件」,这听起来好像很有希望。 但是,你会感到失望,你需要向下滚动页面到「Images and PDF」 部分才能找到 UIImage
。
这就是为什么我交谈过的大多数人只使用他们最喜欢的搜索引擎,他们从搜索引擎中输入他们关心的类,只要它有一个像「UI」、「SK」或类似的前缀,通常搜索引擎的第一结果就是他们想要的。
不要误解我的意思,我知道这种方法并不理想。但是当你要搜索一个类,你要么去搜索引擎搜索,要么去 https://developer.apple.com/documentation/ 查询,选择一个框架,选择一个类别,然后再选择一个类,很显然第一种方式会更快。
重要的是:无论你选择哪种方法,结果都是一样的,最终都会出现在同一个地方,所以选择最适合你自己的搜索方式就行。现在,请你找到并选择UIImage
。
阅读类的接口
一旦你选择了你关心的类,页面就会有四个主要组成部分:概述、版本摘要、接口和关系。
概述是我前面提到的「描述一个API应该做什么以及用例指导」,我要求你选择 UIImage,因为它是文本描述的比较好的一个例子。
当这是我第一次使用的类时,尤其是最近才引入的类,我通常会阅读它的概述。 但是对于其他的类,任何我以前至少使用过一次的类,我会直接跳过它,并尝试找我想要的具体类容。 请记住一点,Apple 文档的设计目的并不是作为一种学习工具:当你有特定的目的时,它的效果才是最好的。
如果你并不总是为你所选择的Apple 平台的最新版本进行开发,那么页面右侧的「版本摘要」侧边栏就非常重要了。在这种情况下,你会看到 iOS 2.0+, tvOS 9.0+和watchOS 2.0+,这告诉我们 UIImage 这个类何时在这三个操作系统上第一次使用,并且它仍然可用,如果它被弃用(不再可用),你会看到类似 iOS 2.0-9.0 的东西。
这个页面上的真正内容,以及苹果开发框架中作为特定类主页的所有页面上的内容,都列在「主题」标题下。这将列出这个类支持的所有属性和方法,再细分为使用类别:「获取图像数据」,「获取图像大小和比例」等等。
如果你选择的类有任何自定义初始化器,它们应该总是首先显示。UIImage有很多自定义初始化器,你会看到它们都被列为签名,只是描述它期望的参数的部分。所以,你会看到这样的:
init?(named: String)
init(imageLiteralResourceName: String)
Tip:如果你看到的是Objective-C代码,确保你的语言是Swift。你可以在页面的右上角执行此操作,当重要的 iOS 测试版引入新的变化时,你也可以在此处启用 API 更改选项。
请记住,初始化器被写为 init?
而不是init
, 是有可能失败的,因为init?
返回一个可选的,以便在初始化失败时可以返回nil。
在初始化器的正下方,你有时会看到一些比较特殊的用于创建类的实例方法。这些不是Swift意义上的初始化方式,但它们确实创建了类的实例。对于UIImage,你会看到这样的东西:
class func animatedImageNamed(String, duration: TimeInterval) -> UIImage?
class func
意味着你可以调用UIImage.animatedImageNamed()
.
在初始化器之后,事情变得不那么有组织性了:你会发现属性、方法和枚举全部混合在一起。虽然你可以通过滚动页面找到你要找的东西,但我可以大胆的说,大多数人只是Cmd+F在页面上找到一些文本!
有以下三点需要注意:
- 嵌套类型(类、结构和枚举)与属性和方法一起列出,这需要一点时间来适应。 例如,
UIImage
包含嵌套的枚举ReizingMode
。 - 任何带有一条线的东西则说明被弃用了。 这意味着 Apple 打算在某个时候将其删除,因此你不应将其用于将来的代码,并且你应该开始重写已被已被弃用的代码。 (实际上,大多数 API 在很长一段时间内都处于“弃用”状态,—年复一年)
- 一些非常复杂的类,比如
UIViewController
,会有额外的文档页面和它们的方法和属性混合在一起。你看他们旁边的页面图标,都会加上一个简单的英文标题,比如「定位内容相对于安全区」。
在页面底部,你会找到对应的关系,它告诉你它继承自哪个类(在本例中,它直接来自 NSObject),以及它遵循的所有协议。 当你查看协议关系更复杂的 Swift 类型时,本节会更有帮助。
阅读属性和方法页面
你已经选择了一个框架和类,现在是时候查看一个特定的属性或方法了。 查找并选择此方法:
class func animatedResizableImageNamed(String, capInsets: UIEdgeInsets, resizingMode: UIImage.ResizingMode, duration: TimeInterval) -> UIImage?
你应该在创建专用图像对象类别中找到它。
这不是一个复杂的方法,但它确实展示了这些页面的重要部分:
- Apple 有几种不同的编写方法名称的方式。 前有
class func animatedResizableImageNamed
, 然后是方法页面标题中显示的表单(animatedResizableImageNamed(_:capInsets:resizingMode:duration:))
,以及方法页面的声明部分中的表单。 - 正如你在版本摘要中看到的(在右侧),此方法是在 iOS 6.0 中引入的。虽然主要的 UIImage 类从第一天就已经存在,但这种方法是在几年后引入的。
- 方法声明的各个部分,颜色是紫色的都是可点击的。 不过要小心:如果你点击
UIImage.ResizingMode
,你会去哪里取决于你点击的是UIImage
还是ResizingMode
。 (提示:你通常需要单击右侧的那个) - 你将看到每个参数的含义和返回值的简要说明。
- 「Discussion」部分详细介绍了此方法的具体使用说明。 这是几乎是每个页面中最有用的部分,因为在这里你会看到诸如「不要调用此方法」或「当……时要小心」之类的内容。
- 你可能会发现「See Also」部分,这里的方法列表与我们在前一页中使用的方法相同。
UIImage
是一个旧类,它没有太多改变,所以它的文档状态很好。但是一些较新的api,以及许多不像UIKit
那样受欢迎的老API,仍然没有得到足够的文档支持。例如,来自SceneKit
的SCNAnimation
,或来自UIKit
的UITextDragPreviewRenderer
:都是在iOS 11中引入的,并且在发布 18 个月后,它们的文档中仍然包含「没有可用的概述」。
当你看到「没有可用的概述」时,你的心会沉下去,但不要放弃:让我告诉你我接下来要做什么……
查看代码
尽管 Apple 的在线文档非常好,但你经常会遇到「没有可用的概述」,或者你发现没有足够的信息来回答你的问题。
康威定律指出,「设计系统的架构受制于产生这些设计的组织的沟通结构」,也就是说,如果你以某种方式工作,你也会以类似的方式设计东西。
Apple 在我们行业的独特地位使他们以一种相当不寻常的方式工作,这几乎可以肯定这与你自己公司的工作方式完全不同。他们有API审查讨论,试图研究在两种语言下API应该是什么样子,他们有专门的团队来制作文档和示例代码。
但是他们获得示例代码的门槛非常高:通常需要非常好的代码才能获得示例代码,并且要经过多层审查,例如法律问题。虽然我可以在一个小时内输出一个项目,然后直接把它作为一篇文章实时发布,但 Apple 做同样的事情要花更长的时间,他们非常重视自己的形象。如果你曾经好奇为什么Swift 官方博客上很少有文章出现,现在你知道了!
现在我说这些的原因是Apple 有一个被广泛使用的捷径:他们的工程师在他们的代码中留下注释的门槛似乎很低,这意味着你经常会在Xcode中找到有价值的信息。这些评论就像金粉一样:它们直接来自Apple 的开发者而不是他们的开发者发行团队,尽管我非常喜欢devpub,但很高兴直接从源头那里找到。
还记得我之前提到 SceneKit
的 SCNAnimation
在 Apple 的开发者网站上没有记录吗? 好吧,让我们看看 Xcode 可以显示什么:按 Shift+Cmd+O
调出 Open Quickly
菜单,确保右侧的 Swift 图标是彩色的而不是空心的,然后输入SCNAnimation
。
你将看到列出的一些选项,但你正在寻找在 SCNAnimation.h
中定义的选项。 如果你不确定,最好选择 YourClassName.h
文件。
无论如何,如果你打开SCNAnimation.h, Xcode会显示一个生成的SCNAnimation头文件的版本。因为原始版本是Objective-C,所以Xcode为Swift做了一个实时翻译,这就是 Open Quickly 框中带颜色的 Swift 标志的含义。
现在,如果你按下 Command+F 并搜索「class SCAnimation」,你会发现:
/**
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 开发文档之前,你还需要了解两件事。
首先,你会经常遇到标记为「已归档」、「旧版」或「已停用」的文档,即使是相对较新的文档。 当它真的很旧时,你会看到这样的消息:「这个文档可能不代表当前开发的最佳实践,下载和其他资源的链接可能不再有效」。
尽管Apple 是世界上最大的公司之一,但它的工程和开发团队还没有达到人满为患的地步,他们不可能在更新所有内容的同时还涵盖新的 API。所以,你看到「归档」文档或类似文件时,请进行判断:如果它是Swift 的某个版本,至少你知道它是最近的,即使不是,你可能仍然会发现有很多有价值的信息。
其次,Apple 还有一些特别有价值且非常出色的文档。 这些都列在 https://developer.apple.com 的页脚中,但主要的是人机交互界面指南。 这份文档这将带你了解苹果平台应用设计的各个部分,包括用图片来说明关键点,并提供大量具体建议。 尽管此文档是构建 iOS 应用程序时要考虑的非常重要的一个文档,但令人惊讶的是,似乎很少有开发人员阅读过它!
接下来?
我之前写过关于 Apple 文档问题的文章,虽然那里没有鼓励,但至少它可以帮助你在挣扎时感觉不那么孤单。
幸运的是,我有很多可能更有用的材料:
- 我的 Swift 知识库 包含 600 多个适用于 Swift 和 iOS 开发人员的答案、提示和技术,它可以帮助你更快地解决问题。
- 我的 Swift 术语表 定义了 Swift 开发中的 100 多个常用术语,全部在一页上。
- 我有一整本书使用项目来教授 Swift 和 iOS,它专门用于以逻辑流程介绍概念。
你认为阅读 Apple 文档最有效的方法是什么? 在 Twitter 上和我交流你的想法:@twostraws。