如何閱讀蘋果開發文檔

原文：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。