原文：How to read Apple’s developer documentation

對于很多人來說，這篇文章聽起來很奇怪，因為我們已經習慣了 Apple 的 API 文檔的工作方式，因此我們精神上已經經過調整以快速找到我們想要的東西。

但這是一個有趣的事實：去年我最熱門的文章請求之一是幫助人們真正閱讀 Apple 的代碼文檔。您如何找到您需要的 iOS API，如何瀏覽所有材料以找到您真正想要的內容，以及您如何深入了解為什么事情按照他們的方式工作？

所以，如果你曾經尋求幫助來理解 Apple 的開發者文檔，首先我要讓你知道你并不孤單 - 許多人都在努力解決這個問題。但其次，我希望這篇文章會有所幫助：我會盡力解釋它的結構，它有什么好處（以及不好的地方），以及如何使用它。

更重要的是，我將向您展示經驗豐富的開發人員尋找額外信息的位置，這些信息通常比Apple的在線文檔更有價值。

<!--more-->

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

任何書面的 API 文檔通常采用以下五種形式之一：

接口代碼，顯示了什么是方法名稱和參數，屬性名稱和類型，以及類似的，帶有一些描述它應該做什么的文本。

API 的文本描述了它應該做什么以及一般指導用例。

廣泛使用的有用的 API? ?示例代碼。

如何使用 API?? 代碼段。

解決常見問題的簡單教程：如何做 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。

總結

以上是生活随笔為你收集整理的如何阅读苹果开发文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。