В подавляющем большинстве случаев искомой страницей документации является справка о классе.
Для пользователей важно, чтобы страница справки о классе удобно и понятно описывала свойства класса, поэтому целесообразно остановиться на нем подробнее (рис. 8.1).
На справочной странице о классе особенно важную роль играет вложенное окно Details справочного окна Info, поэтому важно внимательно следить за информацией, которая отображается в окне Details при изучении класса (в презентации веб-браузера эта информация появляется в верхней части справочной страницы о классе).
Рис. 8.1. Начало справочной страницы о классе UIButton
Раздел Inherits From
Содержит ссылки на цепочки подклассов. Одна из самых больших ошибок новичков заключается в пренебрежении документацией о цепочке суперклассов. Класс является наследником своих суперклассов, поэтому функциональные свойства или информация, которую вы ищете, могут находиться в суперклассе. На странице класса UIButton не следует искать информацию о методе addTarget: action: forControlEvents:, так как она находится на странице класса UlControl. Не стоит также искать свойство frame в классе UIButton на странице класса UIButtone, — эта информация находится на странице класса UlView.
Раздел Conforms То
Содержит ссылки на протоколы, адаптированные классом. Протоколы обсуждаются в главе 10.
Раздел Framework
Сообщает, какому каркасу принадлежит этот класс. Для того чтобы использовать этот класс, ваш код должен ссылаться на этот каркас и импортировать заголовок каркаса (см. главу 6).
Раздел Availability
Указывает самую раннюю версию операционной системы, в которой реализован данный класс. Например, класс UIDynamicAnimator (вместе с каркасом UIKit Dynamics) не был изобретен до появления системы iOS 7. Таким образом, если вы хотите использовать эту функциональную возможность в своем приложении, то должны задать как цель только iOS 7 или более позднюю версию или указать, что ваше приложение никогда не использует этот класс при выполнении в системах более ранних версий.
Раздел Declared In
Заголовок (или заголовки), в котором объявлен класс. К сожалению, это не ссылка; я не нашел быстрого способа для просмотра заголовка в документации. Это неудобно, поскольку часто возникает необходимость просмотреть содержимое заголовочного файла, который может содержать полезные комментарии или другие детали. Заголовочный файл можно открывать в окне проекта, как будет показано далее.
Раздел Sample Code
Если справочная страница о классе ссылается на пример кода, может возникнуть желание просмотреть этот код. (См. мои замечания о примерах класса в следующем разделе.)
Раздел Related
Если справочная страница класса содержит список ссылок, щелкните на них и прочитайте справку. Например, справочная страница класса UlView содержит ссылки на справочник View Programming Guide for iOS. Справки представляют собой обзоры тем, содержат важную информацию (часто вместе с примерами кода) и могут служить ориентиром для принятия решений.
Справочная страница класса разделяется на разделы, перечисленные во вложенном окне Table of Contents в окне Info.
Раздел Overview
Некоторые справочные страницы класса содержат чрезвычайно важную информацию в разделе Overview, включая ссылки на связанные справки и другую информацию. (Например, см. справочную страницу класса UlView .)
Раздел Tasks
В этом разделе в категориальном порядке перечисляются ссылки на свойства и методы, упоминаемые на странице. Часто даже простой просмотр этого списка может дать полезную подсказку.
Разделы Properties, Class Methods, Instance Methods
Эти разделы содержат полную документацию о свойствах и методах класса. (Свойство — это метод, как правило, даже два метода доступа, get- и set-методы, — но в списке перечисляются именно свойства, а не методы доступа.)
Раздел Constants
Многие классы определяют константы, используемые в конкретных методах. Например, чтобы создать экземпляр класса UIButton в коде, можете вызвать метод класса buttonWithType:; значение аргумента будет константной, указанной в разделе Constants справочной страницы класса UIButtonType. (Для того чтобы облегчить ее поиск, в этом разделе есть ссылка из метода buttonWithType: в подраздел UIButtonType из раздела Constants.) Существует формальное определение константы, которое обычно не интересует программиста (см. главу 1, в которой описано, как прочитать формальное определение). Затем каждое значение объясняется, а имя значения можно скопировать и вставить в код.
В заключение поговорим о том, как на справочной странице класса перечисляются и объясняются индивидуальные свойства и методы. В последние годы эта часть документации достигла совершенства и снабжена прекрасными ссылками. Отметим следующие подразделы, следующие за именами свойств или методов.
Раздел Description
Краткое описание предназначения свойства или метода.
Раздел Formal Declaration
Описываются параметры метода и тип возвращаемого значения. (Объявление свойства описывается в главе 12.)
Раздел Parameters and Return Value
Точная информация о смысле и предназначении параметров и возвращаемого значения.
Раздел Discussion
Часто содержит чрезвычайно важные детали о поведении метода. Этот раздел необходимо внимательно изучить!
Раздел Availability
При обновлении операционной системы в старый класс можно включать новые методы; если новый метод критически важен для вашего приложения, вы можете запретить ее выполнение под управлением устаревших операционных систем, в которых этот метод не реализован.
Раздел See Also
Содержит ссылки на связанные методы. Очень полезен для понимания места метода в классе.
Раздел Related Sample Code
Иногда целесообразно посмотреть на образец кода, чтобы понять, как работает метод в реальной жизни.
Раздел Declared In
Соответствующий заголовочный файл.
Методы, включенные в класс с помощью категории (глава 10), часто не упоминаются на справочной странице, и их бывает трудно найти. Например, метод awakeFromNib (см. главу 7) не упоминается ни в документации о классе UIButton, ни в описаниях его суперклассов или протоколов. Это главный недостаток справочной системы компании Apple. В этом случае вам может помочь справочная система сторонней организации, например AppKiDo (http: //appkido. com).