在大多数情况下,你所查找的文档页都是关于某个类的文档。熟知类文档页面所提供的典型特性与信息是非常重要的,下面就来看看吧(如图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在文档组织上的一个主要缺点。