Документация языка Java: Подробный разбор

Screen Shot 2015-10-31 at 9.29.06 PM

В своей статье Справочник Java  я начал рассказ о том, где искать информацию о классах и методах Java, а в статье Руководство к языку Java я рассказал, где искать синтаксис и элементы языка. В этой статье мы познакомимся с документацией к классам и интерфейсам Java, представленной в Руководстве к API Java.

С первого взгляда заглавная страница руководства к API может вызвать у вас небольшое потрясение. Слишком много информации!

Для начала рассмотрим каждое окно по отдельности. Если вы еще не открыли Руководство к API в соседней вкладке или в отдельном окне вашего браузера, сделайте это сейчас. Речь пойдет о том, что вы увидите перед собой. Откройте эту ссылку Руководство к API Java. Добавьте ее в закладки. Поместите к себе на панель закладок. Но не спешите набивать тату с ее адресом у себя на руке, потому что после выхода новой версии Java эта ссылка изменится, и вам будет стыдно ходить по улице со старой URL на руке, не так ли? Думаю, будет достаточно записать ссылку на стикере и наклеить его на рамку монитора.

В левом верхнем окне находится список пакетов (packages). Так, начало положено. Если вы знаете, какой из пакетов содержит нужные вам функции, то можете значительно сократить количество лишней информации вокруг, кликнув по названию этого пакета. К примеру, JFrame находится в javax.swing. Кликнув на javax.swing в левом верхнем окошке, вы увидите, как изменится отображаемая информация. Теперь в левом нижнем окне отображаются только классы, интерфейсы, а также enum’ы и исключения, описанные в javax.swing. Чтобы пролистать этот список понадобится гораздо меньше времени. Если же вы не знаете, какой пакет вам нужен, придется пролистать весь список (он отсортирован в алфавитном порядке).

Кликните по ссылке «All Classes» (Все классы), расположенной в левом верхнем окне в начале списка, чтобы еще раз раскрыть список всех классов, интерфейсов, enum’ов и исключений, имеющихся в API.

Как только вы найдете нужный класс в левом нижнем окне, его документация откроется в главном окне, расположенном справа. Результат может вас удивить. Раз уж мы завели речь о JFrame, давайте продолжим его изучение. Кликните на JFrame в левом нижнем окне. Если хотите, можете сначала кликнуть на javax.swing в левом верхнем окне, чтобы упростить поиск JFrame.
Screen Shot 2015-10-31 at 9.36.05 PM
В главном окне появится большой заголовок «Class JFrame «. Прямо над ним мелким шрифтом написано название пакета, в котором он находится. И если вы еще не знали, что JFrame находится в javax.swing, то уж теперь вы точно это усвоите. Запомните имя класса на случай, если понадобится найти еще что-нибудь в следующий раз. Или если вы захотите использовать класс и не будете знать, какой пакет импортировать, это вам пригодится.

Под Class JFrame находится перечень других классов, расположенных друг под другом, как маленькие ступеньки. Это родительские классы JFrame, от самого простого класса объекта Java, java.lang.Object до самого JFrame. JFrame является наследником всех этих классов. У JFrame есть все имеющиеся у них методы и поля.

Чтобы увидеть документацию к любому из них, просто кликните по названию класса. Но не делайте этого прямо сейчас. Сперва мы продолжим знакомство с документацией к JFrame.

Далее на странице находится список интерфейсов, реализуемых классом JFrame. Это означает, что в JFrame реализованы методы, которые вызывают эти интерфейсы. Это лишь капля информации об интерфейсах, но о них мы поговорим в другой раз. По сути, JFrame наследует функции этих интерфейсов, реализуя методы, которые они определяют.

Под этой строкой находится текстовое описание JFrame, начинающееся с его определения в виде псевдокода. Некоторые текстовые описания в Спецификации API Java будут вам очень полезны. Другие — чуть менее полезны. Описание к JFrame находится примерно посередине. Как и многие другие описания, оно сразу переходит к делу, предполагая, что вы уже в совершенстве знакомы с некоторыми другими компонентами Java, не описанными в данном разделе. В итоге придется потратить немного времени, чтобы найти начало всей этой «истории». Вы ищете JFrame, он ссылается на Frame, после этого вы возвращаетесь к Window, чтобы понять, о чем идет речь в документации к java.awt.Frame. После этого вы читаете всё о java.awt.Component и т.д. Не успеете оглянуться, как вы уже изучаете java.lang.Object и вспоминаете, что же хотели найти вначале, и на что было потрачено столько времени?

Так что не стоит возлагать на эти описания слишком большие надежды. Бегло просматривайте статьи, но если не можете найти то, что нужно — листайте дальше. Обычно, последние части раздела гораздо более информативны и прямолинейны. Если вам нужна какая-то метаинформация о классе, проверьте соответствующий урок на ‘Sun’ или используйте поисковик, чтобы найти хорошее описание или обучающую статью.

Я пропущу раздел «Nested Class Summary» (Информация о вложенных классах) и список наследованных вложенных классов и перейду прямо к разделу «Field Summary» (Информация о полях) под ними.

Поля — это переменные и константы, определенные для класса. Те, что находятся в начале списка, определены непосредственно внутри этого класса. Таблица описывает, как они были определены, и каково их предназначение. Ниже находится список тех, что были наследованы от родительских классов.

Раздел «Constructor Summary» (Информация о конструкторе) описывает доступные для данного класса конструкторы. Если вы надеялись найти конструктор JFrame, который бы позволил делать его невидимым и сразу задавать его размер, боюсь, вам не повезло. Конструкторы класса JFrame позволяют лишь задать заголовок (title) и/или настройки графики (gc) при создании его экземпляра. Так что размер и видимость вам придется задавать позже.

Способы задания размера и видимости, а также множество других вещей, которые можно делать с JFrame, находятся далее по списку. Они входят в состав раздела «Method Summary» (Информация о методах). В начале списка находятся методы, определенные внутри JFrame. Это новые методы, которые класс JFrame добавляет к методам, наследованным от родителей. В каждой строке представлены тип, имя и список параметров метода, а также его короткое описание. Дальше вы видите о-очень длинный список наследованных методов. В JFrame тоже есть все эти методы, но их описания расположены на страницах документации к тем классам, внутри которых они были определены изначально. Кликните на их названии, чтобы перейти на соответствующую страницу.

После этого идет подробное описание полей и методов JFrame. Чтобы быстро добраться до этого раздела, можно кликнуть по названию поля или метода в предыдущем разделе. Это самая ценная часть спецификации API Java. Здесь описано использование методов класса и их работа. Когда вы их запомните, короткого описания в предыдущем разделе будет достаточно (если оно вдруг вам понадобится).

Благодаря тому, что весь документ напичкан гиперссылками, пользоваться им гораздо удобнее, чем бумажной версией. Пришлось бы листать слишком много страниц.

Если вам понадобится локальная копия документации, вы можете скачать ее себе. PDF для Java 6 доступен на сайте ‘Sun’ , а для других версий его можно скачать со страницы Справочник к Java SE.

В этом случае вам не придется торчать в онлайне или переживать из-за скорости своего подключения, когда понадобится что-то найти.

Оригинал


Комментарии:

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

Ваш e-mail не будет опубликован. Обязательные поля помечены *

Можно использовать следующие HTML-теги и атрибуты: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>