В стандартной библиотеке существует огромное количество классов и методов, запомнить которые невозможно. Поэтому для нахождения информации о конкретном методе или классе необходимо пользоваться оперативной документацией интерфейса API. Документация интерфейса API является составной частью набора инструментальных средств Java SDK и создана в HTML формате. Для каждой новой версии JDK имеется собственная документация, которую можно скачать по адресу http://java.sun.com в разделе Download. Кроме API в документации также можно найти следующую информацию (рис. 1):
- инструментальные средства и их опции запуска (каталог tools);
- описание различных языковых средств и технологий, которые составляют ядро Java (каталог guide).

Открыть документацию по интерфейсам классам или методам языка можно через файл docs/api/index.html. Окно документации разделено на три фрейма. В маленьком фрейме в правом углу приведены все доступные пакеты. Все пакеты можно увидеть также и в основном окне, щелкнув мышью на ссылке Overwiev в верхней строке основного окна. В правом нижнем фрейме перечислены все классы. Если щелкнуть кнопкой мыши на конкретном имени класса, то будет показана соответствующая документация по этому классу в основном окне.

Например, чтобы получить информацию о методах класса String, прокрутите левое нижнее окно, пока не увидите ссылку String. Щелкните на ней.

В основном окне для класса можно увидеть после его названия дерево наследования (рис. 2). Например, для класса String:

java.lang.Object
|_ java.lang.String

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

Если напротив метода вы увидите запись Deprecated , то использование данного метода нежелательно в данной версии JDK. Это означает, что данный метод может не во всех случаях отрабатывать корректно, либо создан альтернативный метод, который более эффективен.

Кроме ссылки Overwiev в верхней строки основного окна присутствуют также еще несколько полезных ссылок: Tree, Deprecated, Index, Help. С помощью ссылки Tree можно отобразить полное дерево наследования классов. С помощью ссылки Tree можно увидеть список всех нежелательных методов. С помощью ссылки Index можно легко найти класс, метод или интерфейс, зная только его имя. С помощью ссылки Help можно подробно ознакомиться с организацией и функционированием API.

Ссылки:

1. Хорстман К.С., Корнелл Г. Библиотека профессионала. Java 2. Том 1. Основы. - М.: Издательский дом Вильямс, 2003. - 848 с.
2. JavaTM 2 Platform Standard Edition 5.0 API Specification. http://java.sun.com

При документировании приложения необходима также поддержка документации программы. Если документация и код разделены, то непроизвольно создаются сложности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации при изменении программного кода.

Как правило, все существующие среды разработки IDE приложений Java предлагают решение по связыванию кода с документацией в процессе разработки с использованием javadoc . Для этого необходимо соответствующим образом написать комментарий к коду, т.е. документировать. Java комментарии необходимы как для комментирования программы, так и для составления или оформления документации.

Разработан специальный синтаксис для оформления документации в виде комментариев и инструмент для создания из комментариев документации. Этим инструментом является javadoc , который обрабатывая файл с исходным текстом программы, выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов, методов и полей. Таким образом, при минимальных усилиях создания комментариев к коду, можно получить хорошую документацию к программе.

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

При написании комментариев к кодам Java используют три типа комментариев:

// однострочный комментарий; /* многострочный комментарий */ /** комментирование документации */

С помощью утилиты javadoc , входящей в состав JDK, комментарий документации можно извлекать и помещать в НТМL файл. Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.

Дескрипторы javadoc , начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например {@code} , называются встроенными и могут применяться внутри описания.

Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.

javadoc дескрипторы: @author, @version, @since, @see, @param, @return

Форма документирования кода

Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.

В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа "@" должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.

/** * Класс продукции со свойствами maker и price. * @autor Киса Воробьянинов * @version 2.1 */ class Product { /** Поле производитель */ private String maker; /** Поле цена */ public double price; /** * Конструктор - создание нового объекта * @see Product#Product(String, double) */ Product() { setMaker(""); price=0; } /** * Конструктор - создание нового объекта с определенными значениями * @param maker - производитель * @param price - цена * @see Product#Product() */ Product(String maker,double price){ this.setMaker(maker); this.price=price; } /** * Функция получения значения поля {@link Product#maker} * @return возвращает название производителя */ public String getMaker() { return maker; } /** * Процедура определения производителя {@link Product#maker} * @param maker - производитель */ public void setMaker(String maker) { this.maker = maker; } }

Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа "#" его метод или поле.

Среда разработки IDE, как правило, помогает программисту "подсветкой" встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.

Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.

Сценарии ant и javadoc

Для создания документации можно использовать ant .

Пример сценария (задания) ant для формирования документации к приложению MyProject:

Подробная информация формирования документации представлена на странице

12 ответов

Eclipse не вытягивает всплывающие подсказки из местоположения javadoc. Он использует только расположение javadoc для добавления к ссылке, если вы говорите, что открыто в браузере, вам нужно загрузить и прикрепить источник для JDK, чтобы получить всплывающие подсказки. Для всех JAR под JRE у вас должно быть следующее для местоположения javadoc: http://java.sun.com/javase/6/docs/api/ . Для resources.jar, rt.jar, jsse.jar, jce.jar и charsets.jar вы должны приложить исходный доступный .

Чтобы использовать автономную документацию Java API в Eclipse, вам необходимо сначала загрузить ее. Ссылка на документы Java (последнее обновление: 2013-10-21):

• Извлеките zip файл в ваш локальный каталог.
• Из eclipse Window --> Preferences --> Java --> "Installed JREs" выберите доступную JRE (jre6: C:\Program Files (x86)\Java\jre6, например) и нажмите "Изменить".
• Выберите все "Библиотеки систем JRE" с помощью Control + A .
• Нажмите "Местоположение Javadoc"
• Измените "путь местоположения Javadoc:" от " http://download.oracle.com/javase/6/docs/api/ " to "file:/E:/Java/docs/api/".

Он должен работать, поскольку он работает для меня. Мне больше не нужно подключение к Интернету для просмотра документации API Java в Eclipse.

Для автономного Javadoc из zip файла, а не для его извлечения.

Почему этот подход?

Это уже ответ, в котором используются извлеченные данные zip, но он потребляет больше памяти, чем простой zip файл.

Сравнение zip файла и извлеченных данных.

Jdk-6u25-fcs-bin-b04-apidocs.zip ---> ~57 MB after extracting this zip file ---> ~264 MB !

Таким образом, этот подход экономит мои ок. 200 МБ.

Как использовать apidocs.zip?

1.Открыть Windows -> Preferences

2. Выберите jre из Installed JREs , затем нажмите Edit...

3.Выберите все.jar файлы из JRE system libraries , затем нажмите Javadoc Location...

4. Просмотрите файл apidocs.zip для Archive path и установите Path within archive , как показано выше. Что это.

5. Наведите курсор на любое имя класса или имя метода и нажмите Shift + F2

Старый вопрос, но у меня были текущие проблемы с этой проблемой. Поэтому я предоставляю вам мое решение. Теперь источники и javadocs находятся внутри jdk. Итак, разархивируйте версию jdk. Вы можете видеть, что contanins является файлом "src.zip". Вот ваши необходимые источники и файлы doc. Следуйте по пути: Window- > Preferences- > Java- > Установленные JREs- > выберите jre/jrd и нажмите "Изменить", Выберите все.jar файлы и нажмите Source Attachment. Выберите "Внешний файл..." и укажите его в файле src.zip.

Maibe необходим перезапуск в Eclipse. (обычно нет) Теперь вы должны увидеть документы, а также источники для классов из jdk.

Я столкнулся с той же проблемой, и я не нашел ответа на этот вопрос полезным, потому что они старые и с новым JDK 1.8, в разделе документации есть был перенесен в src.zip в папку JDK (C:\Program Files\Java\jdk1.8.0_101).

Теперь я попробовал все сверху, и он показывал мне ту же проблему, если я нажимаю ctrl и нажимаю (например, String или System) в своей программе, я получаю Источник не найден .

Теперь вы можете сделать это, перейдите в папку, где установлен JDK (C:\Program Files\Java\jdk1.8.0_101) , и попробуйте распаковать src.zip. Здесь вы можете столкнуться с проблемой как-то из-за административных прав в этой папке, это не позволит вам распаковать этот src.zip . Для решения проблемы скопируйте файл src.zip и вставьте его в любую другую папку (например, Desktop), а затем создайте папку src и разархивируйте ее. Теперь скопируйте эту папку обратно в папку JDK 1.8 ** (C:\Program Files\Java\jdk1.8.0_101). **

Теперь просто зайдите в eclipse и откройте любую программу и нажмите ctrl и нажмите на любые внешние объекты или что угодно (например, String или System). Вы получите Source not found, Now Нажмите Прикрепить источник → Внешнее местоположение → Внешняя папка и добавьте ваше местоположение src (C:\Program Files\Java\jdk1.8.0_101\src). Теперь вам хорошо идти, я пытался, и это сработало для меня.

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