Разбираемся с документацией по API Java

Барри Берд

Когда-то люди судили о языках программирования (включая Java) исключительно по их грамматическим особенностям. Есть лиеслизаявление делать то, что вы ожидаете от него? Легко ли использовать циклические операторы? Эффективно ли реализованы методы?

Сейчас все немного иначе. Java имеет целый набор грамматических функций, но Java - это гораздо больше, чем просто большой набор грамматических правил. В Java есть стандарт Приложение Интерфейс программирования ication - огромная библиотека, состоящая из более чем 4000 классов, каждый со своей функциональностью, собственными ограничениями и собственными правилами эффективного использования.



Поиск термина

Вы можете найти вещи в документации API разными способами. Каждый способ удобен в той или иной ситуации. Например, в Java есть метод с именемSystem.out.println. Ниже описаны два способа поискаSystem.out.printlnметод.

Использование индекса

Вот как что-то найти, напримерSystem.out.println, используя индекс:

  1. Посещение docs.oracle.com/javase/8/docs/api/ .

  2. Щелкните ссылку ИНДЕКС вверху страницы, чтобы открыть указатель, как показано на рисунке 1.

    Рисунок 1: Документация APIРисунок 1. Главная страница документации API.

    Список букв находится в верхней части указателя (см. Рисунок 2). Щелкните ссылку P, чтобы перейти в раздел сprintlnв этом.

    Рисунок 2: Документация API/> Рис. 2. Индексная страница документации по API.
  3. В разделе P выполните поискprintlnнайтиprintlnзаписи.

    Большинство веб-браузеров позволяют искать что-то вродеprintlnв тексте страницы. Вот как:

    1. Убедитесь, что браузер знает, что вы хотите искать в большом фрейме, занимающем большую часть страницы (а не в меньших фреймах в левой части страницы). Для этого щелкните мышью внутри большой рамки. (Не нажимайте на ссылку. Нажмите на нейтральную белую область кадра.)

    2. Откройте диалоговое окно браузера 'Поиск'. В большинстве браузеров Windows нажатие Ctrl + F выводит диалоговое окно «Найти» из укрытия. На Mac, нажав Command + F, можно добиться успеха.

    3. Когда вы увидите диалоговое окно 'Найти', введитеprintlnв текстовом поле и нажмите кнопку «Найти» или «Найти далее».

      уколы от блох для кошек
  4. Выберите один изprintlnзаписи.

    Секция P имеет большую лодкуprintlnзаписей, как показано на рисунке 3 ниже. Записи отличаются друг от друга двумя способами:

    • В каждой записи говоритсяprintln (число),println (строка), или жеprintln (someOtherTypeName). Имя типа может отличаться от одной записи к другой.

    • В каждой записи говорится, чтоprintlnэто метод в классеЯва. someStuff.someMoreStuff . Класс может отличаться от одной записи к другой.

      println в указателе документации API ./> Рисунок 3: Некоторыеprintlnзаписи в указателе документации API.

    На этом этапе стоит осмотреться. Если вы пытаетесь напечатать что-то вродеПривет мир!, вы хотите один изprintln (строка)записи. С другой стороны, если вы пытаетесь распечатать значениевngthOfStraightLine, вы, вероятно, выберетеprintln (двойной)Вход.

    Теперь предположим, что вы определились сprintln (строка). Вы можете выбрать из трехprintln (строка)записи. Один говорит, что это метод в классеjava.io.PrintStream, следующий - это метод в классеjava.io.PrintWriter, а третий - метод в классеjava.sql.DriverManager. Какую из этих трех записей вы выберете?

    Что ж, вы действительно пытаетесь назвать то, что называетсяSystem.out.println. Если вы пройдетесь через всю эту чепуху сSystemoutты найдешь этоSystem.outимеет типPrintStream. (См. Рисунок 4 ниже).println (строка)запись, которую вы решили выбрать,

    println (String) - Метод в классе java.io.PrintStream.

    переменная out имеет типPrintStream./> Рисунок 4:внепеременная имеет типPrintStream.
  5. Щелкните ссылку на запись, которую вы выбрали.

    Когда вы щелкаете ссылку println (String), браузер переводит вас на страницу, объясняющуюprintlnметод, как показано на рисунке 5. Страница сообщает вам, чтоprintlnделает (печатает строку, а затем ...) и указывает на другие полезные страницы, например страницу с документацией дляНить.

    println ./> Рисунок 5: Описаниеprintlnметод.

Использование списка классов

Вот как найти запись в API, начав в списке классов:

  1. Посещение docs.oracle.com/javase/8/docs/api/ .

  2. Найдите страницу, которая документируетСистемакласс.

    Вам нужна документация, объясняющаяSystem.out.println. Итак, вы смотрите вверхСистема, проложи свой путь квне, а оттуда проложите свой путь кprintln.

    Чтобы найти ссылку наСистемапосмотрите в нижний фрейм в левой части страницы. (См. Рис. 6.) Подсказки по поиску текста на странице см. В шаге 3 раздела Использование указателя.

    Системный класс ./> Рисунок 6: Поиск ссылки наСистемакласс.

    Если щелкнуть ссылку «Система», в вашем браузере отобразится страница документации дляСистемаclass, как показано на рисунке 7.

    Документация по системному классу ./> Рисунок 7:Системадокументация класса.
  3. На странице документации поСистемакласс, найдивнеПеременная.

    Если вы используете диалоговое окно «Найти» своего веб-браузера, вам придется несколько раз нажать кнопку «Найти далее». (Названиевненастолько распространен, что появляется несколько раз в разных контекстах наСистемастраницы документации.) Когда вы найдете то, что ищете, вы увидите таблицу, подобную той, которая показана на рисунке 4 выше.

  4. В таблицевнестроке щелкните ссылку PrintStream.

    Согласно документации,внепеременная относится к объекту типаPrintStream. Это значит, чтоprintlnявляется частьюPrintStreamкласс. Вот почему вы нажимаетеPrintStreamссылка на сайт.

  5. На странице документации дляPrintStream, найтиprintln (строка).

    Вы видите объяснение, подобное показанному на Рисунке 5 выше.

Вы тоже можете это сделать

Выполнив действия, описанные в этой статье, у вас может возникнуть соблазн сказать: «Отличная сделка! я могу найтиprintlnв документации по API, но, наверное, больше ничего не найду. И если люди создают документацию для вещей, которые они программируют самостоятельно, их документация не будет похожа на стандартную документацию API. Я пойду вверх по ручью.

Соответствующий ответ на такое возражение - вздор! Ерунда! Балдердаш! Конские перья! Вот почему:

  • Большинство уловок, которые вам понадобятся для поиска вещей в стандартной документации Java, проиллюстрированы в пошаговых инструкциях этой статьи. Если ты найдешьSystem.out.println, вы также можете найтиjavax.swing.JButtonили любую из 4200 программ в стандартном API Java.

    И по мере того, как вы узнаете больше о Java и отношениях между классами, методами и переменными, пошаговые инструкции в этой статье будут казаться более естественными.

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

    {@link #print(String)}

    Чтобы создать документацию по API, капитаны Java запустили программу под названием javadoc . Программа javadoc брала подобные строки прямо изPrintStream.javaфайл и использовал строки для создания документации, которую вы видите в своем веб-браузере.

    Другие программисты на Java делают то же самое. Фактически, каждый, кто пишет код Java, использует программу javadoc для создания документации. Так что вся документация по Java выглядит так же, как и документация по Java любого другого человека. Когда вы знаете, как читать стандартную документацию API, вы знаете, как читать чужую документацию по Java.

    И да, вы можете использовать программу javadoc для создания собственной документации. Когда вы загружаете JDK, вы получаете программу javadoc как часть сделки.