如何阅读苹果开发文档
原文：How to read Apple’s developer documentation
對于很多人來說，這篇文章聽起來很奇怪，因?yàn)槲覀円呀?jīng)習(xí)慣了 Apple 的 API 文檔的工作方式，因此我們精神上已經(jīng)經(jīng)過調(diào)整以快速找到我們想要的東西。
但這是一個有趣的事實(shí)：去年我最熱門的文章請求之一是幫助人們真正閱讀 Apple 的代碼文檔。您如何找到您需要的 iOS API，如何瀏覽所有材料以找到您真正想要的內(nèi)容，以及您如何深入了解為什么事情按照他們的方式工作？
所以，如果你曾經(jīng)尋求幫助來理解 Apple 的開發(fā)者文檔，首先我要讓你知道你并不孤單 - 許多人都在努力解決這個問題。但其次，我希望這篇文章會有所幫助：我會盡力解釋它的結(jié)構(gòu)，它有什么好處（以及不好的地方），以及如何使用它。
更重要的是，我將向您展示經(jīng)驗(yàn)豐富的開發(fā)人員尋找額外信息的位置，這些信息通常比Apple的在線文檔更有價值。
<!--more-->
“這是什么？” vs “你怎么用它？”
任何書面的 API 文檔通常采用以下五種形式之一：
粗略地說，蘋果公司第一點(diǎn)做了很多，其次是第二點(diǎn)和第三點(diǎn)，第四點(diǎn)很少，??第五點(diǎn)幾乎沒有。
所以，如果你正在尋找“如何用 Y 做 X ”的具體例子，你最好從我的 Swift 知識庫開始 - 這正是它的用途。
了解 Apple 的文檔解決的問題，可以幫助您從中獲得最大收益。它并不是一個結(jié)構(gòu)化的教程，它不會向您介紹一系列概念來幫助您實(shí)現(xiàn)目標(biāo)，而是作為 Apple 支持的數(shù)千個 API 的參考指南。
尋找一個類
Apple的在線文檔位于 https://developer.apple.com/d... ，雖然您能在 Xcode 中使用本地副本，但我會說大多數(shù)人使用在線版本只是因?yàn)樗麄兛梢愿菀椎卣业絻?nèi)容。
絕大多數(shù) Apple 的文檔都描述了接口，而這正是大多數(shù)時候你會看到的。我想使用一個實(shí)際的例子，所以請先在您的網(wǎng)絡(luò)瀏覽器中打開https://developer.apple.com/d... ，這是所有Apple開發(fā)者文檔的主頁。
您會看到所有 Apple 的 API 分為 App Frameworks 或 Graphics and Games 等類別，您已經(jīng)看到了一件重要的事情：所有深藍(lán)色文本都是可點(diǎn)擊的，并會帶您進(jìn)入特定框架的API文檔。是的，它使用相同的字體和大小，沒有下劃線，說實(shí)話，深藍(lán)色鏈接和黑色文本之間沒有太大區(qū)別，但你仍然需要留意這些鏈接 - 有很多他們，你會用它們來深入挖掘主題。
現(xiàn)在請從 App Frameworks 類別中選擇 UIKit，您將看到它的功能（為iOS創(chuàng)建用戶界面）的簡要概述，標(biāo)有“重要”（Important）的大黃色框，然后是類別列表。那些黃色的盒子確實(shí)值得關(guān)注：雖然它們經(jīng)常被使用，它們幾乎總能阻止你犯下根本錯誤，這些錯誤導(dǎo)致出現(xiàn)奇怪的問題。
此頁面上重要的是共同描述 UIKit 的類別列表。這是人們經(jīng)常迷路的地方：他們想要了解像 UIImage 這樣的東西，所以他們必須仔細(xì)查看該列表以找到它可能出現(xiàn)的合適位置。
在這種情況下，您可能會查看“資源管理”（Resource Management），因?yàn)樗母睒?biāo)題“管理存儲在主可執(zhí)行文件之外的圖像，字符串，故事板和 nib 文件”聽起來很有希望。但是，您會感到失望 - 您需要向下滾動到 “圖像和 PDF”（Images and PDF）部分才能找到 UIImage。
這就是為什么我談過的大多數(shù)人只是使用自己喜歡的搜索引擎。他們輸入他們關(guān)心的類，并且 - 只要它有“UI”，“SK”或類似的前綴 - 它可能是第一個結(jié)果。
不要誤會我的意思：我知道這種做法并不理想。但是面對搜索一個類或者去 https://developer.apple.com/d... ，選擇一個框架，選擇一個類別，然后選擇一個類，第一個就是更快。
重要提示：無論您選擇哪種方法，最終都會在同一個地方，所以只做最適合您的方法。現(xiàn)在，請找到并選擇 UIImage。
閱讀類的接口
一旦選擇了您關(guān)心的類，該頁面就有四個主要組件：概述，版本摘要，接口和關(guān)系。
概述是“API的文本描述，描述了它應(yīng)該做什么以及一般指導(dǎo)用例”，我之前提到過 - 我要求你選擇 UIImage，因?yàn)樗俏谋久枋龊螘r運(yùn)行良好的一個很好的例子。
當(dāng)它是我第一次使用的類時，特別是如果它剛剛推出時，我通常會閱讀概述文本。但是對于其他一切 - 我之前至少使用過一次的任何類 - 我跳過它并嘗試找到我所得到的具體細(xì)節(jié)。請記住，Apple 文檔確實(shí)不是一種學(xué)習(xí)工具：當(dāng)您考慮到特定目的時，它最有效。
如果您不總是為所選 Apple 平臺的最新版本開發(fā)，則版本摘要 - 頁面右側(cè)的側(cè)欄 - 非常重要。在這種情況下，您將看到 iOS 2.0 +，tvOS 9.0+ 和 watchOS 2.0+，它告訴我們何時 UIImage 類首次在這三個操作系統(tǒng)上可用，并且它仍然可用 - 如果它已被棄用（不再可用）你會看到像 iOS 2.0-9.0 這樣的東西。
此頁面上的實(shí)際內(nèi)容 - 以及作為 Apple 框架中特定類的主頁的所有頁面 - 都列在“主題”標(biāo)題??下。這將列出該類支持的所有屬性和方法，再次分解為使用類別：“獲取圖像數(shù)據(jù)”，“獲取圖像大小和比例”等。
如果您選擇的類具有任何自定義初始化方法，則始終會首先顯示它們。 UIImage 有很多自定義初始化方法，你會看到它們都被列為簽名 - 只是描述它所期望的參數(shù)的部分。所以，你會看到這樣的代碼：
init?(named: String) init(imageLiteralResourceName: String)提示：如果您看到 Objective-C 代碼，請確保將語言更改為 Swift。您可以在頁面的右上角執(zhí)行此操作，也可以在重要的 iOS 測試版引入更改時啟用 API 更改選項(xiàng)。
記住，初始化方法寫成 init? 而不是 init 的是容易出錯的 - 它們返回一個可選項(xiàng)，以便在初始化失敗時它們可以返回 nil。
在初始化器的正下方，您有時會看到一些用于創(chuàng)建類的高度專業(yè)化實(shí)例的方法。這些不是 Swift 意義上的初始化器，但它們確實(shí)創(chuàng)建了類的實(shí)例。對于 UIImage，你會看到這樣的事情：
class func animatedImageNamed(String, duration: TimeInterval) -> UIImage?class func 部分意味著你將使用 UIImage.animatedImageNamed() 方式調(diào)用。
在初始化程序之后，事情變得有點(diǎn)不那么有條理：你會發(fā)現(xiàn)屬性方法和枚舉自由混合在一起。雖然您可以滾動查找您要查找的內(nèi)容，但我可以認(rèn)為大多數(shù)人只需要 Cmd + F 在頁面上查找文字就可以了！
有三點(diǎn)需要注意：
- 嵌套類型 - 類，結(jié)構(gòu)和枚舉 - 與屬性和方法一起列出，這需要一點(diǎn)時間習(xí)慣。例如，UIImage 包含嵌套的枚舉 ResizingMode。
- 任何帶有直線穿過的東西都是不推薦使用的。這意味著 Apple 打算在某些時候?qū)⑵鋭h除，因此您不應(yīng)將其用于將來的代碼，并建議開始重寫任何現(xiàn)有代碼。（在實(shí)踐中，大多數(shù)API長期以來都被“棄用” - 許多許多年。）
- 一些非常復(fù)雜的類 - 例如，UIViewController - 會將額外的文檔頁面與其方法和屬性混合在一起。查找它們旁邊的頁面圖標(biāo)，以及一個簡單的英文標(biāo)題，如“相對于安全區(qū)域定位內(nèi)容”（Positioning Content Relative to the Safe Area）。
在頁面的底部你會找到 Relationships，它告訴你它繼承了哪個類（在這種情況下它直接來自 NSObject），以及它符合的所有協(xié)議。當(dāng)您查看 Swift 類型時，本節(jié)更有用，其中協(xié)議關(guān)系更復(fù)雜。
閱讀屬性或方法頁面
您已經(jīng)選擇了一個框架和類，現(xiàn)在是時候查看特定的屬性或方法了。查找并選擇此方法：
class func animatedResizableImageNamed(String, capInsets: UIEdgeInsets, resizingMode: UIImage.ResizingMode, duration: TimeInterval) -> UIImage?您應(yīng)該在 Creating Specialized Image Objects 類別中找到它。
這不是一個復(fù)雜的方法，但它確實(shí)展示了這些頁面的重要部分：
- Apple 有幾種不同的方法來編寫方法名稱。之前的那個 - 長 class func animatedResizableImageNamed - 然后是方法頁面標(biāo)題中顯示的形式（animatedResizableImageNamed(_:capInsets:resizingMode:duration:)），以及方法頁面的聲明部分中的形式。
- 正如您在版本摘要中所看到的（在右側(cè)），此方法在 iOS 6.0 中引入。因此，雖然主要的 UIImage 類從第1天開始就已存在，但這種方法是在幾年后推出的。
- 方法聲明的各個部分都是可點(diǎn)擊的，都是紫色的。但是要小心：如果你單擊 UIImage.ResizingMode，你將去哪里取決于你是否點(diǎn)擊了“UIImage”或“ResizingMode”。 （提示：您通常需要單擊右側(cè)的那個。）
- 您將看到每個參數(shù)含義和返回值的簡要說明。
- “討論”（Discussion）部分詳細(xì)介紹了此方法的具體使用說明。這幾乎總是 - 每個頁面中最有用的部分，因?yàn)樵谶@里您可以看到“不要調(diào)用此方法”或“小心......”
- 你可能會找到一個 See Also 部分，但這有點(diǎn)受歡迎 - 這里只是我們在上一頁的方法列表。
現(xiàn)在，UIImage 是一個老類，并沒有太大變化，因此它的文檔處于良好狀態(tài)。但是一些較新的 API - 以及許多沒有像 UIKit 那樣被喜歡的舊 API - 仍然記錄不足。例如，來自 SceneKit 的 SCNAnimation 或來自 UIKit 的 UITextDragPreviewRenderer：兩者都是在 iOS 11 中引入的，并且在它們發(fā)布18個月后仍然包含“無可用概述（No overview available）”作為其文檔。
當(dāng)你看到“沒有可用的概述（No overview available）”時，你會失望，但不要放棄：讓我告訴你接下來要做什么......
查看代碼
盡管 Apple 的在線文檔相當(dāng)不錯，但您經(jīng)常會遇到“無可用概述（No overview available）”，或者您發(fā)現(xiàn)沒有足夠的信息來回答您的問題。
康威定律（Conway's law）指出，設(shè)計(jì)系統(tǒng)的組織受制于設(shè)計(jì)，這些設(shè)計(jì)是這些組織的通信結(jié)構(gòu)的副本。“也就是說，如果你以某種方式工作，你將以類似的方式設(shè)計(jì)事物。
Apple 在我們行業(yè)中的獨(dú)特地位使他們以一種相當(dāng)不尋常的方式工作 - 幾乎可以肯定它與您自己公司的工作方式完全不同。是的，他們有 API 審核討論，他們試圖討論API應(yīng)該如何用兩種語言看待，是的，他們有專門的團(tuán)隊(duì)來制作文檔和示例代碼。
但是他們獲取示例代碼的門檻非常高：通常需要一些非常好的東西才能拿出來，并且通過多層檢查來處理法律問題。因此，雖然我可以在一小時內(nèi)輸入一個項(xiàng)目并立即將其發(fā)布為文章，但 Apple 需要花費(fèi)更長的時間才能完成同樣的工作 - 他們非常認(rèn)真地對待他們的形象，而且非常正確。如果你曾經(jīng)想過為什么文章很少出現(xiàn)在官方 Swift 博客上，現(xiàn)在你知道了！
現(xiàn)在，我說這一切的原因是 Apple 有一個快速使用的捷徑：他們的工程師在他們的代碼中留下評論的門檻似乎顯著降低，這意味著你經(jīng)常會在 Xcode 中找到有價值的信息。這些評論就像細(xì)小的金子（gold dust）一樣：它們直接來自 Apple 的開發(fā)者，而不是他們的開發(fā)者出版（developer publications）團(tuán)隊(duì)，而且我對 devpubs 非常熱愛，很高興直接聽到來自源頭的聲音。
還記得我提到過 SceneKit 的 SCNAnimation 在 Apple 的開發(fā)者網(wǎng)站上沒有記錄嗎？好吧，讓我們來看看Xcode可以向我們展示的內(nèi)容：按 Cmd + O 打開“快速打開（Open Quickly）”菜單，確保右側(cè)的 Swift 圖標(biāo)為彩色而不是空心，然后鍵入“SCNAnimation”。
您將看到列出的一些選項(xiàng)，但您正在尋找 SCNAnimation.h 中定義的選項(xiàng)。如果您不確定，選擇 YourClassName.h 文件是您最好的選擇。
無論如何，如果你打開 SCNAnimation.h Xcode 將顯示生成的 SCNAnimation 頭文件版本。它的生成是因?yàn)樵及姹臼荗bjective-C，因此 Xcode 為 Swift 進(jìn)行了實(shí)時翻譯 - 這就是 Swift Quickly 框中的彩色 Swift 徽標(biāo)的含義。
現(xiàn)在，如果你按 Cmd + F 并搜索“class SCNAnimation”，你會發(fā)現(xiàn)：
/**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)這只是一個開始。 是的，該類及其所有內(nèi)部都有文檔，包括用法說明，默認(rèn)值等。 所有這一切都應(yīng)該在在線文檔中，但無論出于什么原因它仍然沒有，所以要準(zhǔn)備好查找代碼作為一個有用的補(bǔ)充。
最后的提示
此時，您應(yīng)該能夠查找在線文檔以獲取您喜歡的任何代碼，并查找頭文件注釋以獲取額外的使用說明。
但是，在準(zhǔn)備好面對全部 Apple 文檔之前，還有兩件事需要了解。
首先，您經(jīng)常會遇到標(biāo)記為“已歸檔（archived”）”，“遺留（“l(fā)egacy”）”或“已退休（“retired）”的文檔 - 即使對于相對較新的事物也是如此。當(dāng)它真的老了，你會看到諸如“這篇文章可能不代表當(dāng)前發(fā)展的最佳實(shí)踐”之類的消息。下載和其他資源的鏈接可能不再有效。“
盡管 Apple 是世界上最大的公司之一，但 Apple 的工程和 devpubs 團(tuán)隊(duì)幾乎沒有人員 - 他們不可能在保留所有內(nèi)容的同時覆蓋新的 API。因此，當(dāng)你看到“存檔”文檔或類似文件時，請運(yùn)用你的判斷：如果它在某個版本的 Swift 中至少你知道它最近是模糊的，但即使不是，你仍然可能會發(fā)現(xiàn)那里有很多有價值的信息。
其次，Apple 擁有一些特別有價值的出色文檔。這些都列在 https://developer.apple.com 的頁腳中，但主要是人機(jī)界面指南。這將引導(dǎo)您完整地為 Apple 平臺設(shè)計(jì)應(yīng)用程序的所有部分，包括說明關(guān)鍵點(diǎn)的圖片，并提供大量具體建議。即使這個文檔是構(gòu)建 iOS 應(yīng)用程序時最重要的一個，但很少有開發(fā)人員似乎已經(jīng)閱讀過它！
接下來做什么？
我之前曾寫過關(guān)于 Apple 文檔的問題 - 我擔(dān)心那里沒有鼓勵，但至少如果你在努力，它可能會讓你覺得不那么孤單。
幸運(yùn)的是，我有很多可能更有用的材料：
- 我的Swift知識庫（Swift Knowledge Base）包含針對 Swift 和 iOS 開發(fā)人員的600多個問答，技巧和技術(shù)點(diǎn) - 它可以幫助您更快地解決問題。
- 我的Swift術(shù)語表（Glossary of Common Swift Terms）在 Swift 開發(fā)中定義了100多個常用術(shù)語，所有術(shù)語都在一頁上。
- 我有一本全書使用項(xiàng)目教授 Swift 和 iOS，它專門用于在邏輯流程中引入概念。
您認(rèn)為閱讀Apple文檔最有效的方法是什么？ 在Twitter上發(fā)送你的提示：@twostraws。
總結(jié)
以上是生活随笔為你收集整理的如何阅读苹果开发文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： OSS全球传输加速开启公测，助力企业业务
- 下一篇： 浙江文成“红领巾”向交警敬礼：上下学感谢