There are good reasons for making your own local javadocs, and it"s not particularly difficult!

First you need the source. At the time of writing the Java 8 JDK comes with a zip file called src.zip . Sometimes, for unexplained reasons, Oracle don"t always include the source. So for some older versions (and who knows about the future) you have to get hold of the Java source in another way. It"s worth also being aware that, in the past, Oracle have sometimes included the source with the Linux version of the JDK, but not with the Windows one.

I just unzipped this file... the top directories are "com", "java", "javax", "launcher" and "org". Directory launcher contains no files to document.

You can generate the javadocs very very simply from any or all of these by CD"ing at the command prompt/terminal to the directory ...\src . Then go

javadoc -d docs -Xmaxwarns 10 -Xmaxerrs 10 -Xdoclint:none -sourcepath . -subpackages java:javax:org:com

NB note that there is a "." after -sourcepath

Simple as that. Generating your own javadocs also has 2 huge advantages

1. you know they are precisely the right javadocs for the JDK (or any exernal jar file) you are using on your system
2. once you get into the habit, reconstituting your Javadocs is not a tiresome challenge (i.e. where to go looking for them). For example I just unzipped a couple of source jars whose packages are closely coupled, so their sources were in effect "merged" & then made a single Javadoc from them...

NB Swing is semi-officially DEAD. We should all be switching to JavaFX, which is helpfully bundled with Java 8 JDK, but in its own source file, javafx-src.zip .

Unzipped, this reveals 3 "root" packages: com , javafx and netscape (wha"?). These should be manually moved over the to appropriate places under the unzipped src directory (including the JavaFX com.sun packages under the Java com.sun strcture). Compiling all these Javadoc files took my machine a non-negligible time. I"d expect to see all the JavaFX source classes in with all the other source classes some time soon.

BTW, the same thinking applies to documenting any and all Java jars (with source) which you use. However, all versions of most jars will be found with their documentation available for download at Maven Central http://search.maven.org ...

PS afterthought:
using Eclipse and the "Gradle STS" plugin: the "New Gradle STS Project" wizard will create a gradle.build file containing the line

include plugin: "eclipse"

This magically downloads the source jar with the executable jar (under GRADLE_HOME) when you go

Giving you an extra degree of certainty that you have got the right src and therefore the right javadoc for the dependency in question.

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). Теперь вам хорошо идти, я пытался, и это сработало для меня.

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

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

Рисунок 1 - Структура каталога с документацией к Java.

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

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

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

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

Рисунок 2 - Описание класса String.

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

Рисунок 3 - Сводка методов класса String.

Если напротив метода вы увидите запись 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

Дескриптор	Применение	Описание
@author	Класс, интерфейс	Автор
@version	Класс, интерфейс	Версия. Не более одного дескриптора на класс
@since		Указывает, с какой версии доступно
@see	Класс, интерфейс, поле, метод	Ссылка на другое место в документации
@param	Метод	Входной параметр метода
@return	Метод	Описание возвращаемого значения
@exception имя_класса описание	Метод
@throws имя_класса описание	Метод	Описание исключения, которое может быть послано из метода
@deprecated	Класс, интерфейс, поле, метод	Описание устаревших блоков кода
{@link reference}	Класс, интерфейс, поле, метод	Ссылка
{@value}	Статичное поле	Описание значения переменной

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

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

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

/** * Класс продукции со свойствами 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:

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