В подавляющем большинстве случаев искомой страницей документации является справка о классе.

Для пользователей важно, чтобы страница справки о классе удобно и понятно описывала свойства класса, поэтому целесообразно остановиться на нем подробнее (рис. 8.1).

На справочной странице о классе особенно важную роль играет вложенное окно Details справочного окна Info, поэтому важно внимательно следить за информацией, которая отображается в окне Details при изучении класса (в презентации веб-браузера эта информация появляется в верхней части справочной страницы о классе).

 

Начало справочной страницы о классе UIButton

Рис. 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).


 

 

 

Добавить комментарий