[譯] 如何閱讀蘋果開發文件

qiwihui發表於2019-01-18
蘋果

coding-woman-5

原文：How to read Apple’s developer documentation

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

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

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

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

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

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

  1. 介面程式碼，顯示了什麼是方法名稱和引數，屬性名稱和型別，以及類似的，帶有一些描述它應該做什麼的文字。
  2. API 的文字描述了它應該做什麼以及一般指導用例。
  3. 廣泛使用的有用的 API​ ​示例程式碼。
  4. 如何使用 API​​ 程式碼段。
  5. 解決常見問題的簡單教程：如何做 X，如何做 Y，以及如何做 Z 等等。

粗略地說，蘋果公司第一點做了很多，其次是第二點和第三點，第四點很少，​​第五點幾乎沒有。

所以，如果你正在尋找“如何用 Y 做 X ”的具體例子，你最好從我的 Swift 知識庫開始 - 這正是它的用途。

瞭解 Apple 的文件解決的問題，可以幫助您從中獲得最大收益。它並不是一個結構化的教程，它不會向您介紹一系列概念來幫助您實現目標，而是作為 Apple 支援的數千個 API 的參考指南。

尋找一個類

Apple的線上文件位於 developer.apple.com/documentati… ，雖然您能在 Xcode 中使用本地副本，但我會說大多數人使用線上版本只是因為他們可以更容易地找到內容。

絕大多數 Apple 的文件都描述了介面，而這正是大多數時候你會看到的。我想使用一個實際的例子，所以請先在您的網路瀏覽器中開啟https://developer.apple.com/documentation/ ，這是所有Apple開發者文件的主頁。

apple-developer-documentation

您會看到所有 Apple 的 API 分為 App Frameworks 或 Graphics and Games 等類別，您已經看到了一件重要的事情：所有深藍色文字都是可點選的，並會帶您進入特定框架的API文件。是的，它使用相同的字型和大小，沒有下劃線，說實話，深藍色連結和黑色文字之間沒有太大區別，但你仍然需要留意這些連結 - 有很多他們，你會用它們來深入挖掘主題。

現在請從 App Frameworks 類別中選擇 UIKit，您將看到它的功能（為iOS建立使用者介面）的簡要概述，標有“重要”（Important）的大黃色框，然後是類別列表。那些黃色的盒子確實值得關注：雖然它們經常被使用，它們幾乎總能阻止你犯下根本錯誤，這些錯誤導致出現奇怪的問題。

uikit-overview

此頁面上重要的是共同描述 UIKit 的類別列表。這是人們經常迷路的地方：他們想要了解像 UIImage 這樣的東西，所以他們必須仔細檢視該列表以找到它可能出現的合適位置。

uikit-topics

在這種情況下，您可能會檢視“資源管理”（Resource Management），因為它的副標題“管理儲存在主可執行檔案之外的影象，字串，故事板和 nib 檔案”聽起來很有希望。但是，您會感到失望 - 您需要向下滾動到 “影象和 PDF”（Images and PDF）部分才能找到 UIImage。

這就是為什麼我談過的大多數人只是使用自己喜歡的搜尋引擎。他們輸入他們關心的類，並且 - 只要它有“UI”，“SK”或類似的字首 - 它可能是第一個結果。

不要誤會我的意思：我知道這種做法並不理想。但是面對搜尋一個類或者去 developer.apple.com/documentati… ，選擇一個框架，選擇一個類別，然後選擇一個類，第一個就是更快。

重要提示：無論您選擇哪種方法，最終都會在同一個地方，所以只做最適合您的方法。現在，請找到並選擇 UIImage。

閱讀類的介面

一旦選擇了您關心的類，該頁面就有四個主要元件：概述，版本摘要，介面和關係。

uiimage-overview

概述是“API的文字描述，描述了它應該做什麼以及一般指導用例”，我之前提到過 - 我要求你選擇 UIImage，因為它是文字描述何時執行良好的一個很好的例子。

當它是我第一次使用的類時，特別是如果它剛剛推出時，我通常會閱讀概述文字。但是對於其他一切 - 我之前至少使用過一次的任何類 - 我跳過它並嘗試找到我所得到的具體細節。請記住，Apple 文件確實不是一種學習工具：當您考慮到特定目的時，它最有效。

如果您不總是為所選 Apple 平臺的最新版本開發，則版本摘要 - 頁面右側的側欄 - 非常重要。在這種情況下，您將看到 iOS 2.0 +，tvOS 9.0+ 和 watchOS 2.0+，它告訴我們何時 UIImage 類首次在這三個作業系統上可用，並且它仍然可用 - 如果它已被棄用（不再可用）你會看到像 iOS 2.0-9.0 這樣的東西。

此頁面上的實際內容 - 以及作為 Apple 框架中特定類的主頁的所有頁面 - 都列在“主題”標題​​下。這將列出該類支援的所有屬性和方法，再次分解為使用類別：“獲取影象資料”，“獲取影象大小和比例”等。

uiimage-topics

如果您選擇的類具有任何自定義初始化方法，則始終會首先顯示它們。 UIImage 有很多自定義初始化方法，你會看到它們都被列為簽名 - 只是描述它所期望的引數的部分。所以，你會看到這樣的程式碼：

init?(named: String)
init(imageLiteralResourceName: String)
複製程式碼

**提示：**如果您看到 Objective-C 程式碼，請確保將語言更改為 Swift。您可以在頁面的右上角執行此操作，也可以在重要的 iOS 測試版引入更改時啟用 API 更改選項。

switch-swift

記住，初始化方法寫成 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 類別中找到它。

animatedresizableimagenamed-1
animatedresizableimagenamed-2

這不是一個複雜的方法，但它確實展示了這些頁面的重要部分：

  • 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 擁有一些特別有價值的出色文件。這些都列在 developer.apple.com 的頁尾中，但主要是人機介面指南。這將引導您完整地為 Apple 平臺設計應用程式的所有部分，包括說明關鍵點的圖片，並提供大量具體建議。即使這個文件是構建 iOS 應用程式時最重要的一個，但很少有開發人員似乎已經閱讀過它！

接下來做什麼？

我之前曾寫過關於 Apple 文件的問題 - 我擔心那裡沒有鼓勵，但至少如果你在努力，它可能會讓你覺得不那麼孤單。

幸運的是，我有很多可能更有用的材料：

您認為閱讀Apple文件最有效的方法是什麼？ 在Twitter上傳送你的提示：@twostraws。

相關文章