讀古今文學網 > iOS編程基礎:Swift、Xcode和Cocoa入門指南 > 8.2 類文檔頁面 >

8.2 類文檔頁面

在大多數情況下,你所查找的文檔頁都是關於某個類的文檔。熟知類文檔頁面所提供的典型特性與信息是非常重要的,下面就來看看吧(如圖8-1所示)。

在學習某個類時,你可能還想關注相關的條目信息(單擊「More related items」鏈接查看):

Inherits from

父類鏈的列表,可以鏈接到相應的類。初學者常犯的一個嚴重錯誤就是不閱讀父類鏈的文檔。類是從其父類繼承下來的,這樣你所尋找的某些功能或信息可能位於父類中。你不可能在UIButton的類頁面中找到addTarget:action:forControlEvents:,因為該信息位於UIControl類頁面中。同樣不可能在UIButton的類頁面中找到frame屬性,因為該信息位於UIView類頁面中。

Conforms to

該類所使用的協議列表,可以鏈接到相應的協議。不查看所使用的協議信息是初學者常犯的一個嚴重錯誤。比如,你不會在UIViewController類文檔頁面中看到UIViewController有一個viewWillTransitionToSize:withTransitionCoordinator:事件:要查看UIContentContainer協議的文檔,它是UIViewController所使用的協議。

Framework

聲明該類屬於哪個框架。要想使用這個類,代碼需要鏈接到該框架並導入框架的頭文件;在Swift中,通過模塊名導入框架就足夠了(參見第6章)。

Availability

表明實現該類的最早的操作系統版本。比如,UIView layoutGuides屬性是個UILayoutGuide對像數組。不過UILayoutGuide是iOS 9才引入進來的。如果想要在應用中使用該特性,你需要確保應用針對的目標是iOS 9或更新的版本,或當應用運行在老版本的系統上時,代碼不會用到這個類。

Declared in

聲明該類的頭文件。遺憾的是,它並非鏈接;我還沒有找到從文檔中查看頭文件的便捷方式。這確實很遺憾,因為我們經常需要查看頭文件,它可能包含了一些有價值的註釋或其他細節信息。可以從項目窗口中打開頭文件,本章後面將會介紹。

Related documents

如果類文檔頁面列出了相關指南,那麼可以單擊鏈接並閱讀指南。比如,UIView類文檔頁面列出了(也會鏈接到)View Programming Guide for iOS。指南會涵蓋廣泛的主題;它們提供了重要的信息(常常包含一些有價值的代碼示例),可用於指導你的思考方向。

類文檔頁面劃分為多個部分,它們都列在了目錄窗格中:

Overview

一些類文檔頁面在Overview部分提供了非常重要的介紹性信息,包括對相關指南的鏈接以及進一步信息(比如,UIView的類文檔頁面)。

Tasks

這部分會按照類別列出該類的屬性與方法。

Constants

很多類都針對特定的方法定義了一些常量。比如,在UIButton類文檔頁面中,你會發現要想通過代碼創建UIButton實例,可以調用init(type:)初始化器;參數值列在了Constants部分的UIButtonType下面。

最後談談類文檔頁面是如何介紹其屬性與方法的。最近幾年,這部分文檔變得越來越好了,提供了很多超鏈接。如下部分位於屬性或方法名後面:

Description

簡要介紹屬性或方法的作用。

Declaration

介紹方法參數與返回類型等信息。

Parameters and Return Value

詳細介紹參數與返回值的含義與目的。

Discussion

通常包含關於方法行為的重要的細節信息。請重視這部分內容!

Availability

隨著操作系統的不斷發展,過去的類可能會添加新的方法;如果某個新方法對於應用很重要,那就需要確保應用不會在沒有實現該方法的老操作系統上運行。

See Also

指向相關方法與屬性的鏈接。有助於你從宏觀上瞭解該方法對於類的總體行為的意義。

通過類別(參見第10章)注入類中的方法通常不會顯示在類的文檔頁中,也很難找到。比如,awakeFromNib(參見第7章)並未在UIButton以及其父類和協議的文檔中提及。這是Apple在文檔組織上的一個主要缺點。