Spec-Zone .ru
спецификации, руководства, описания, API
Содержание документации

javadoc - Генератор Документации API Java

Генерирует страницы HTML документации API от исходных файлов Java. Этот документ содержит примеры Javadoc для Соляриса.

СОДЕРЖАНИЕ

Справочник

Выполнение

Справочник

РЕЗЮМЕ

javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]

Параметры могут быть в любом порядке. См. обработку Исходных файлов для деталей о том, как инструмент Javadoc определяет который".java"файлы, чтобы обработать.

options
Параметры командной строки, как определено в этом документе. Чтобы видеть типичное использование javadoc опций, см. Реальный Пример.
packagenames
Серия имен пакетов, разделенных пробелами, такой как java.lang java.lang.reflect java.awt. Следует отдельно определить каждый пакет, который Вы хотите задокументировать. Подстановочные знаки не позволяются; используйте-subpackages для рекурсии. Использование инструмента Javadoc -sourcepath искать эти имена пакета. См. Пример - Документирование Того или Большего количества Пакетов
sourcefilenames
Серия имен исходного файла, разделенных пробелами, каждые из которых могут начаться с пути и содержать подстановочный знак, такой как звездочка (*). Инструмент Javadoc обработает каждый файл, имя которого заканчивается ".java", и чье имя, когда лишено того суффикса, является фактически юридическим именем класса (см. Спецификацию языка Java). Поэтому, можно назвать файлы с тире (такой как X-Buffer), или другие запрещенные символы, чтобы препятствовать тому, чтобы они были задокументированы. Это полезно для тестовых файлов, и шаблон регистрирует путь, который предшествует, имя исходного файла определяет, где javadoc будет искать файл. (Инструмент Javadoc не использует -sourcepath искать эти имена исходного файла.) Относительные пути относительно текущего каталога, таким образом передавая в Button.java идентично ./Button.java. Имя исходного файла с абсолютным путем и подстановочным знаком, например, /home/src/java/awt/Graphics*.java. См. Пример - Документирование Того или Большего количества Классов. Можно также смешать packagenames и sourcefilenames, как в Пример - Документирующий И Пакеты и Классы
-subpackages pkg1:pkg2:...
Генерирует документацию от исходных файлов в указанных пакетах и рекурсивно в их подпакетах. Альтернатива предоставлению packagenames или sourcefilenames.
@argfiles
Один или более файлов, которые содержат список опций Javadoc, packagenames и sourcefilenames в любом порядке. Подстановочные знаки (*) и -J опции не позволяются в этих файлах.

ОПИСАНИЕ

Инструмент Javadoc анализирует объявления и комментарии для документации в ряде исходных файлов Java и производит соответствующий набор страниц HTML, описывающих (по умолчанию) общедоступные и защищенные классы, вложенные классы (но не анонимные внутренние классы), интерфейсы, конструкторы, методы, и поля. Можно использовать это, чтобы генерировать API (Прикладной программный интерфейс) документация или документация реализации для ряда исходных файлов.

Можно выполнить инструмент Javadoc на всех пакетах, отдельных исходных файлах, или обоих. Документируя все пакеты, можно или использовать -subpackages для того, чтобы пересечь рекурсивно вниз из высокоуровневого каталога, или передачи в явном списке имен пакета. Документируя отдельные исходные файлы, Вы передаете в списке источника (.java) имена файлов. Примеры даются в конце этого документа. То, как Javadoc обрабатывает исходные файлы, покрывается затем.

Обработка исходных файлов

Инструмент Javadoc обрабатывает файлы тот конец в".java"плюс другие файлы описывается под Исходными файлами. Если Вы выполняете инструмент Javadoc, явно передавая в отдельных исходных именах файлов, можно определить точно который".java"файлы обрабатываются. Однако, это не то, как большинство разработчиков хочет работать, поскольку более просто передать на имена пакета. Инструмент Javadoc может быть выполнен три пути, явно не определяя исходные имена файлов. Вы можете (1) передача на имена пакета, (2) использование -subpackages, и (3) подстановочные знаки использования с исходными именами файлов (*.java). В этих случаях инструмент Javadoc обрабатывает".java"файл, только если это выполняет все следующие требования:

Обрабатывая ссылок - Во время выполнения, инструмент Javadoc автоматически добавляет ссылки перекрестной ссылки к пакету, именам классов и именам элемента, которые документируются как часть того выполнения. Ссылки появляются в нескольких местах:

Можно добавить гиперссылки к существующему тексту для классов, не включенных в командную строку (но сгенерированный отдельно) посредством -link и -linkoffline опции.

Другие детали обработки - инструмент Javadoc представляет один полный документ каждый раз, когда это выполняется; это не может сделать инкрементных сборок - то есть, это не может изменить или непосредственно бестелесные следствия предыдущих выполнений инструмента Javadoc. Однако, это может соединиться со следствиями других выполнений, как только упомянуто.

Как реализовано, инструмент Javadoc требует и полагается на компилятор java, чтобы сделать его задание. Инструмент Javadoc вызывает часть javac скомпилировать объявления, игнорируя задействованную реализацию. Это создает богатое внутреннее представление классов, включая иерархию классов, и отношения "использования", затем генерирует HTML от этого. Инструмент Javadoc также поднимает предоставленную пользователем документацию из комментариев для документации в исходном коде.

Фактически, инструмент Javadoc будет работать .java исходные файлы, которые являются чистыми тупиковыми файлами без тел метода. Это означает, что можно записать комментарии для документации и выполнить инструмент Javadoc на ранних стадиях проекта, создавая API, прежде, чем записать реализацию.

Доверие компилятору гарантирует, что вывод HTML соответствует точно фактической реализации, которая может положиться на неявный, а не явный, исходный код. Например, конструкторы по умолчанию документов инструмента Javadoc (см. Спецификацию языка Java), которые присутствуют в .class файлы, но не в исходном коде.

Во многих случаях инструмент Javadoc позволяет Вам генерировать документацию для исходных файлов, код которых является неполным или ошибочным. Это - преимущество, которое позволяет Вам генерировать документацию перед всей отладкой, и поиск и устранение неисправностей делается. Например, согласно Спецификации языка Java, класс, который содержит абстрактный метод, должен самостоятельно быть объявлен кратким обзором. Инструмент Javadoc не проверяет на это, и продолжился бы без предупреждения, тогда как javac компилятор останавливается на этой ошибке. Инструмент Javadoc действительно делает некоторую примитивную проверку комментариев документа. Используйте DocCheck doclet, чтобы проверить комментарии документа более тщательно.

Когда инструмент Javadoc создает свою внутреннюю структуру для документации, он загружает все классы, на которые ссылаются. Из-за этого инструмент Javadoc должен быть в состоянии найти все классы, на которые ссылаются, ли классы начальной загрузки, расширения, или пользовательские классы. Для больше об этом, см., Как Классы Находятся. Вообще говоря, классы, которые Вы создаете, должны или быть загружены как расширение или в пути к классу инструмента Javadoc.

Javadoc Doclets

Можно настроить контент и формат вывода инструмента Javadoc при использовании doclets. У инструмента Javadoc есть "встроенный" doclet по умолчанию, названный стандартом doclet, который генерирует отформатированную HTML документацию API. Можно изменить или разделить стандарт на подклассы doclet, или записать свой собственный doclet, чтобы генерировать HTML, XML, MIF, RTF или безотносительно выходного формата, который Вы хотели бы. Информация о doclets и их использовании в следующих расположениях:

Когда пользовательский doclet не будет определен с параметром командной строки -doclet, инструмент Javadoc будет использовать стандарт по умолчанию doclet. У javadoc инструмента есть несколько параметров командной строки, которые доступны, независимо от которого используется doclet. Стандарт doclet добавляет дополнительный набор параметров командной строки. Оба набора опций описываются ниже в разделе опций.

Связанный Documentation и Doclets

Терминология

Комментарий для документации сроков, комментарий документа, основное описание, тег, метка блока, и встроенный тег описываются в Комментариях для документации. У этих других сроков есть определенные значения в пределах контекста инструмента Javadoc:

сгенерированный документ
Документ, сгенерированный javadoc инструментом из документа, комментирует в исходном коде Java. Значение по умолчанию сгенерированный документ находится в HTML и создается стандартом doclet.

имя
Имя элемента программы, записанного на Языке Java - то есть, имя пакета, класса, интерфейса, поля, конструктора или метода. Имя может быть полностью определено, такой как java.lang.String.equals(java.lang.Object), или частично квалифицированный, такой как equals(Object).

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

включенные классы
Классы и интерфейсы, детали которых документируются во время выполнения инструмента Javadoc. То же самое как задокументированные классы.

исключенные классы
Классы и интерфейсы, детали которых не документируются во время выполнения инструмента Javadoc.

классы, на которые ссылаются,
Классы и интерфейсы, которые явно упоминаются в определении (реализация) или комментарии документа задокументированных классов и интерфейсов. Примеры ссылок включают тип возврата, тип параметра, тип броска, расширенный класс, реализованный интерфейс, импортированные классы, классы, используемые в телах метода, @see, {@link}, {@linkplain}, и {@inheritDoc} теги. (Заметьте, что это определение изменилось с тех пор 1.3.), Когда инструмент Javadoc выполняется, он должен загрузить в память все классы, на которые ссылаются, в bootclasspath javadoc и пути к классу. (Инструмент Javadoc печатает "Класс, не найденный" предупреждение для классов, на которые ссылаются, не найденных.) Инструмент Javadoc может получить достаточную информацию из.class файлов, чтобы определить их существование и полностью определенные имена их элементов.

внешние классы, на которые ссылаются,
Классы, на которые ссылаются, документация которых не сгенерирована во время выполненного javadoc. Другими словами эти классы не передают в инструмент Javadoc на командной строке. Ссылки в сгенерированной документации к тем классам, как говорят, являются внешними ссылками или внешними ссылками. Например, если Вы работаете на инструменте Javadoc только java.awt пакет, тогда любой класс в java.lang, такой как Object, внешний класс, на который ссылаются. Внешние классы, на которые ссылаются, могут быть соединены с использованием -link и -linkoffline опции. Важное свойство внешнего класса, на который ссылаются, - то, что его исходные комментарии обычно не доступны выполненному Javadoc. В этом случае эти комментарии не могут быть наследованы.

ИСХОДНЫЕ ФАЙЛЫ

Инструмент Javadoc генерирует вывод, происходящий из четырех различных типов "исходных" файлов: файлы Исходного кода на языке Java для классов (.java), файлы комментария пакета, файлы комментария краткого обзора, и разное необработанные файлы. Этот раздел также покрывает тестовые файлы и шаблонные файлы, которые могут также быть в исходном дереве, но которые Вы хотите убедиться не к документу.

Файлы Исходного кода класса

У каждого класса или интерфейса и его элементов могут быть их собственные комментарии для документации, содержавшиеся в a .java файл. Для получения дополнительной информации об этих комментариях документа, см. Комментарии для документации.

Файлы Комментария пакета

У каждого пакета может быть свой собственный комментарий для документации, содержавшийся в его собственном "исходном" файле, что инструмент Javadoc объединится в сводную страницу пакета, которую это генерирует. Вы обычно включаете в этот комментарий любую документацию, которая применяется ко всему пакету.

Чтобы создать пакет комментируют файл, у Вас есть выбор двух файлов поместить Ваши комментарии:

У пакета может быть сингл package.html файл или сингл package-info.java файл, но не оба. Поместите любой файл в каталог пакета в исходном дереве наряду с Вашим .java файлы.

package-info.java - Этот файл может содержать комментарий пакета следующей структуры - комментарий помещается перед объявлением пакета:

Файл: java/applet/package-info.java

/**
 * Provides the classes necessary to create an  
 * applet and the classes an applet uses 
 * to communicate with its applet context.
 * <p>
 * The applet framework involves two entities:
 * the applet and the applet context.
 * An applet is an embeddable window (see the
 * {@link java.awt.Panel} class) with a few extra
 * methods that the applet context can use to 
 * initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;

Отметьте что в то время как разделители комментария /** и /* должен присутствовать, ведущие звездочки на промежуточных строках могут быть опущены.

package.html - Этот файл может содержать комментарий пакета следующей структуры - комментарий помещается в <body> элемент:

Файл: java/applet/package.html

<HTML>
<BODY>
Provides the classes necessary to create an applet and the 
classes an applet uses to communicate with its applet context.
<p>
The applet framework involves two entities: the applet
and the applet context. An applet is an embeddable
window (see the {@link java.awt.Panel} class) with a
few extra methods that the applet context can use to
initialize, start, and stop the applet. 

@since 1.0 
@see java.awt
</BODY>
</HTML>

Заметьте, что это - только нормальный файл HTML и не включает объявление пакета. Контент файла комментария пакета пишется в HTML, как все другие комментарии, с одним исключением: комментарий для документации не должен включать разделители комментария /** и */ или ведущие звездочки. При записи комментария следует сделать первое предложение сводкой о пакете, и не поместить заголовок или любой другой текст между <body> и первое предложение. Можно включать теги пакета; как с любым комментарием для документации, все метки блока должны появиться после основного описания. Если Вы добавляете a @see тег в пакете комментирует файл, у него должно быть полностью определенное имя. Для получения дополнительной информации см. пример package.html.

Обрабатывая пакета комментирует файл - Когда инструмент Javadoc будет работать, это будет автоматически искать файл комментария пакета; если найдено, инструмент Javadoc делает следующее:

Файл Комментария краткого обзора

У каждого приложения или набора пакетов, которые Вы документируете, может быть свой собственный комментарий для документации краткого обзора, сохраненный в его собственном "исходном" файле, что инструмент Javadoc объединится в страницу краткого обзора, которую это генерирует. Вы обычно включаете в этот комментарий любую документацию, которая применяется ко всему приложению или набору пакетов.

Чтобы создать краткий обзор комментируют файл, можно назвать файл чем-либо, что Вы хотите, обычно overview.html и поместите это куда угодно, обычно на верхнем уровне исходного дерева. Например, если исходные файлы для java.applet пакет содержится в /home/user/src/java/applet каталог, Вы могли создать файл комментария краткого обзора в /home/user/src/overview.html.

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

Контент файла комментария краткого обзора является одним большим комментарием для документации, записанным в HTML, как файл комментария пакета, описанный ранее. См. то описание для деталей. Чтобы повторить, при записи комментария, следует сделать первое предложение сводкой о приложении или наборе пакетов, и не поместить заголовок или любой другой текст между <body> и первое предложение. Можно включать теги краткого обзора; как с любым комментарием для документации, всеми тегами кроме встроенных тегов, такой как {@link}, должен появиться после основного описания. Если Вы добавляете a @see тег, у этого должно быть полностью определенное имя.

Когда Вы выполняете инструмент Javadoc, Вы определяете, что краткий обзор комментирует имя файла с - опция краткого обзора. Файл тогда обрабатывается подобный тому из файла комментария пакета.

Разные Необработанные Файлы

Можно также включать в свой источник любые разные файлы, которые Вы хотите, чтобы инструмент Javadoc скопировал в целевой каталог. Они обычно включают графические файлы, источник Java в качестве примера (.java) и класс (.class) файлы, и самопостоянные файлы HTML, контент которых сокрушил бы комментарий для документации нормального исходного файла Java.

Чтобы включать необработанные файлы, поместите их в вызванный каталог doc-files который может быть подкаталогом любого каталога пакета, который содержит исходные файлы. У Вас может быть один такой подкаталог для каждого пакета. Вы могли бы включать изображения, пример кода, исходные файлы.class файлы, апплеты и файлы HTML. Например, если Вы хотите включать изображение кнопки button.gif в java.awt.Button документация класса, Вы помещаете тот файл в /home/user/src/java/awt/doc-files/ каталог. Заметьте doc-files каталог не должен быть расположен в /home/user/src/java/doc-files потому что java не пакет - то есть, он непосредственно не содержит исходных файлов.

Все ссылки к этим необработанным файлам должны быть трудно кодированы, потому что инструмент Javadoc не смотрит на файлы - он просто копирует каталог и все его содержание месту назначения. Например, ссылка в Button.java комментарий документа мог бы быть похожим:

    /**
     * This button looks like this: 
     * <img src="doc-files/Button.gif">
     */

Тестовые Файлы и Шаблонные Файлы

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

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

Тестовые файлы отличаются от шаблонных файлов в этом, прежний - юридические, компилируемые исходные файлы, в то время как последние не, но могут закончиться ".java".

Тестовые файлы - Часто разработчики хотят поместить компилируемые, выполнимые тестовые файлы для данного пакета в том же самом каталоге как исходные файлы для того пакета. Но они хотят, чтобы тестовые файлы принадлежали пакету кроме пакета исходного файла, такого как неназванный пакет (таким образом, у тестовых файлов нет никакого оператора пакета или различного оператора пакета из источника). В этом сценарии, когда источник документируется, определяя его имя пакета, определенное на командной строке, тестовые файлы вызовут предупреждения или ошибки. Вы должны поместить такие тестовые файлы в подкаталог. Например, если Вы хотите добавить тестовые файлы для исходных файлов в com.package1, поместите их в подкаталог, который был бы недопустимым именем пакета (потому что это содержит дефис):

    com/package1/test-files/

Тестовый каталог будет пропущен инструментом Javadoc без предупреждений.

Если Ваши тестовые файлы содержат комментарии документа, можно установить отдельное выполнение инструмента Javadoc, чтобы произвести документацию тестовых файлов, передавая в их тестовых исходных именах файлов с подстановочными знаками, такой как com/package1/test-files/*.java.

Шаблоны для исходных файлов - у Шаблонных файлов есть имена, которые часто заканчиваются в ".java" и не являются компилируемыми. Если у Вас есть шаблон для исходного файла, который Вы хотите сохранить в исходном каталоге, можно назвать это с тире (такой как Buffer-Template.java), или любой другой недопустимый символ Java, чтобы препятствовать тому, чтобы это было обработано. Это полагается на факт, что инструмент Javadoc только обработает исходные файлы, имя которых, когда лишено суффикса ".java", является фактически юридическим именем класса (см. информацию об Идентификаторах в Спецификации языка Java).

СГЕНЕРИРОВАННЫЕ ФАЙЛЫ

По умолчанию javadoc использует стандарт doclet, который генерирует отформатированную HTML документацию. Этот doclet генерирует следующие виды файлов (где каждый HTML "страница" соответствует отдельному файлу). Отметьте, что javadoc генерирует файлы с двумя типами имен: названные в честь классов/интерфейсов, и тех, которые не являются (такой как package-summary.html). Файлы в последней группе содержат дефисы, чтобы предотвратить конфликты имени файла с теми в прежней группе.

Основные Страницы Контента

Страницы перекрестной ссылки

Файлы поддержки

Фреймы HTML

Инструмент Javadoc генерирует или два или три фрейма HTML, как показано в числе ниже. Это создает минимальное необходимое число фреймов, опуская список пакетов, если есть только один пакет (или никакие пакеты). Таким образом, когда Вы передадите единственное имя пакета или исходные файлы (*.java) принадлежащий единственному пакету как параметры в javadoc команду, это создаст только один фрейм (C) в левом столбце - список классов. Когда Вы передаете в javadoc два или больше имени пакета, он создает третий фрейм (P) перечисляющий все пакеты, так же как страницу краткого обзора (Деталь). У этой страницы краткого обзора есть имя файла overview-summary.html. Таким образом этот файл создается, только если Вы передаете на два или больше имени пакета. Можно обойти фреймы, не щелкая по "Никаким Фреймам" ссылка или входя в overview-summary.html.

Если Вы незнакомы с фреймами HTML, следует знать, что фреймы могут сфокусироваться для печати и прокрутки. Чтобы дать фокус фрейма, щелкните по этому. Затем на многих браузерах клавиши со стрелками и ключи страницы прокрутят тот фрейм, и команда меню печати напечатает его.

Загрузите один из следующих двух файлов как начальная страница в зависимости от того, хотите ли Вы фреймы HTML или нет:

Сгенерированная Файловая структура

Сгенерированный класс и интерфейсные файлы организуются в той же самой иерархии каталогов, что исходные файлы Java и файлы класса организуются. Эта структура является одним каталогом на подпакет.

Например, документ сгенерирован для класса java.applet.Applet класс был бы расположен в java/applet/Applet.html. Файловая структура для java.applet пакета следует, учитывая, что целевой каталог называют apidocs. Все файлы, которые содержат слово "фрейм", появляются в верхних левых или нижних левых фреймах, как отмечено. Все другие файлы HTML появляются в правом фрейме.

ОТМЕТЬТЕ - Каталоги показывают полужирным. Звездочки (*) укажите на файлы и каталоги, которые опускаются, когда параметрами javadoc являются исходные имена файлов (*.java), а не имена пакета. Также, когда параметрами являются исходные имена файлов, package-list создается, но пуст. Каталог файлов документа не будет создаваться в месте назначения, если он не будет существовать в исходном дереве.


apidocs                             Top directory
   index.html                       Initial page that sets up HTML frames
 * overview-summary.html            Lists all packages with first sentence summaries
   overview-tree.html               Lists class hierarchy for all packages
   deprecated-list.html             Lists deprecated API for all packages
   constant-values.html             Lists values of static fields for all packages
   serialized-form.html             Lists serialized form for all packages
 * overview-frame.html              Lists all packages, used in upper-left frame
   allclasses-frame.html            Lists all classes for all packages, used in lower-left frame
   help-doc.html                    Lists user help for how these pages are organized
   index-all.html                   Default index created without -splitindex option
   index-files                      Directory created with -splitindex option
       index-<number>.html          Index files created with -splitindex option
   package-list                     Lists package names, used only for resolving external refs
   stylesheet.css                   HTML style sheet for defining fonts, colors and positions
   java                             Package directory
       applet                       Subpackage directory
            Applet.html             Page for Applet class
            AppletContext.html      Page for AppletContext interface
            AppletStub.html         Page for AppletStub interface
            AudioClip.html          Page for AudioClip interface
          * package-summary.html    Lists classes with first sentence summaries for this package
          * package-frame.html      Lists classes in this package, used in lower left-hand frame
          * package-tree.html       Lists class hierarchy for this package
            package-use             Lists where this package is used
            doc-files               Directory holding image and example files
            class-use               Directory holding pages API is used
                Applet.html         Page for uses of Applet class
                AppletContext.html  Page for uses of AppletContext interface
                AppletStub.html     Page for uses of AppletStub interface
                AudioClip.html      Page for uses of AudioClip interface
   src-html                         Source code directory
       java                         Package directory
           applet                   Subpackage directory
                Applet.html         Page for Applet source code
                AppletContext.html  Page for AppletContext source code
                AppletStub.html     Page for AppletStub source code
                AudioClip.html      Page for AudioClip source code

Сгенерированные Объявления API

Инструмент Javadoc генерирует объявление в начале каждого класса, интерфейса, поля, конструктора, и описания метода для того элемента API. Например, объявление для Boolean класс:

public final class Boolean
extends Object
implements Serializable

и объявление для Boolean.valueOfметод:

public static Boolean valueOf(String s)

Инструмент Javadoc может включать модификаторы public, protected, private, abstract, final, static, transient, и volatile, но нет synchronized или native. Эти последние два модификатора считают деталью реализации и не частью спецификации API.

Вместо того, чтобы полагаться на ключевое слово synchronized, API должны задокументировать свою семантику параллелизма в основном описании комментария, как в "сингле Enumeration не может использоваться многократными потоками одновременно". Документ не должен описать, как достигнуть их семантика. Как другой пример, в то время как Hashtable должно быть ориентировано на многопотоковое исполнение, нет никакой причины определить, что мы достигаем этого, синхронизируя все ее экспортируемые методы. Мы должны зарезервировать право синхронизироваться внутренне на уровне блока, таким образом предлагая более высокий параллелизм.

КОММЕНТАРИИ ДЛЯ ДОКУМЕНТАЦИИ

Исходная "Спецификация Комментария для документации" может быть найдена в соответствии со связанной документацией.

Комментарий Исходного кода

Можно включать комментарии для документации ("комментарии документа") в исходном коде, перед объявлениями для любого класса, интерфейса, метода, конструктора, или поля. Можно также создать комментарии документа для каждого пакета и другой для краткого обзора, хотя их синтаксис немного отличается. Комментарии документа также известны неофициально, как "Джейвэдок комментирует" (но этот термин нарушает свое использование торговой марки). Комментарий документа состоит из символов между символами /** это начинает комментарий и символы */ тот конец это. Ведущие звездочки позволяются на каждой строке и описываются далее ниже. Текст в комментарии может продолжаться на многократные строки.

/**
 * This is the typical format of a simple documentation comment
 * that spans two lines.
 */

Чтобы оставить свободное место, можно поместить комментарий к одной строке:

/** This comment takes up only one line. */

Размещение комментариев - Комментарии для документации распознаются только когда помещено сразу перед классом интерфейс, конструктор, метод, или полевые объявления - видят пример класса, пример метода, и полевой пример. Игнорируются комментарии для документации, помещенные в тело метода. Только один комментарий для документации на оператор объявления распознается инструментом Javadoc.

Частая ошибка состоит в том, чтобы поместить import оператор между классом комментирует и объявление класса. Избегите этого, поскольку инструмент Javadoc проигнорирует комментарий класса.

   /**
    * This is the class comment for the class Whatever.
    */

    import com.sun;   // MISTAKE - Important not to put import statement here

    public class Whatever {
    }

Комментарий документа составляется из основного описания, сопровождаемого разделом тега - основное описание начинается после запускающегося разделителя /** и продолжается до раздела тега. Раздел тега запускается с первой метки блока, которая определяется первым @ символ, который начинает строку (игнорирующий ведущие звездочки, пробел, и ведущий разделитель /**). Возможно иметь комментарий с только разделом тега и никакое основное описание. Основное описание не может продолжаться после того, как раздел тега начинается. Параметр тегу может охватить многократные строки. Может быть любое число тегов - некоторые типы тегов могут быть повторены, в то время как другие не могут. Например, это @see запускает раздел тега:

/**
 * This sentence would hold the main description for this doc comment.
 * @see java.lang.Object
 */

Метки блока и встроенные теги - тег является специальным ключевым словом в пределах документа, комментируют, что инструмент Javadoc может обработать. Есть два вида тегов: метки блока, которые появляются как @tag (также известный как "автономные теги"), и встроенные теги, которые появляются в пределах изогнутых фигурных скобок, как {@tag}. Чтобы быть интерпретированной, метка блока должна появиться в начале строки, игнорируя ведущие звездочки, пробел, и разделитель (/**). Это означает, что можно использовать @ символ в другом месте в тексте и это не будет интерпретироваться как запуск тега. Если Вы хотите запустить строку с @ у символа и не есть это быть интерпретированным, использовать объект HTML &#064;. Каждая метка блока связала текст, который включает любой текст после тега до, но не включая, или следующий тег, или конец комментария документа. Этот связанный текст может охватить многократные строки. Встроенный тег позволяется и интерпретируется где угодно, что текст позволяется. Следующий пример содержит метку блока @deprecated и встроенный тег {@link}.

/**
 * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
 */

Комментарии пишутся в HTML - текст должен быть записан в HTML, в котором они должны использовать объекты HTML и могут использовать HTML-тэги. Можно использовать, какой бы ни версия HTML Ваш браузер поддерживает; мы записали стандарт doclet, чтобы генерировать HTML 3.2-совместимый код в другом месте (за пределами комментариев для документации) с включением каскадных таблиц стилей и фреймов. (Мы снабжаем каждый сгенерированный файл предисловием с "HTML 4.0" из-за наборов фрейма.)

Например, объекты для меньше (<) и больше - чем (>) символы должны быть записаны &lt; и &gt;. Аналогично, амперсанд (&) должен быть записан &amp;. Полужирный HTML-тэг <b> показывается в следующем примере.

Вот комментарий документа:

/**
 * This is a <b>doc</b> comment.
 * @see java.lang.Object
 */

Ведущие звездочки - Когда javadoc анализирует комментарий документа, ведущая звездочка (*) символы на каждой строке отбрасываются; пробелы и вкладки, предшествующие начальной звездочке (*) символы также отбрасываются. Запускаясь с 1.4, если Вы опускаете ведущую звездочку на строке, ведущий пробел больше не удаляется. Это позволяет Вам вставить примеры кода непосредственно в комментарий документа внутри a <PRE> тег, и его добавление отступа будут соблюдать. Пробелы обычно интерпретируются браузерами более однородно чем вкладки. Добавление отступа относительно левого поля (а не разделитель /** или <PRE> тег).

Первое предложение - первое предложение каждого комментария документа должно быть сводным предложением, содержа краткое, но полное описание объявленного объекта. Это предложение заканчивается в первый период, который сопровождается пробелом, вкладкой, или разделителем строки, или в первой метке блока. Инструмент Javadoc копирует это первое предложение в задействованную сводку наверху страницы HTML.

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

/** 
 * The horizontal and vertical distances of point (x,y)
 */
public int x, y;      // Avoid this

Инструмент Javadoc генерирует следующую документацию от вышеупомянутого кода:

public int x
Горизонталь и вертикальные расстояния точки (x, y)
public int y
Горизонталь и вертикальные расстояния точки (x, y)

Используйте теги заголовка тщательно - при записи комментариев для документации для элементов, лучше не использовать теги заголовка HTML, такие как <H1> и <H2>, потому что инструмент Javadoc создает весь структурированный документ, и эти структурные теги могли бы вмешаться в форматирование сгенерированного документа. Однако, прекрасно использовать эти заголовки в классе и комментарии пакета, чтобы обеспечить Вашу собственную структуру.

Автоматическое Копирование Комментариев Метода

У инструмента Javadoc есть возможность скопировать или "наследовать" комментарии метода в классах и интерфейсах при следующих двух обстоятельствах. Конструкторы, поля и вложенные классы не наследовали комментарии документа.

Исходный файл для наследованного метода должен только быть на пути, определенном-sourcepath для комментария документа, чтобы фактически быть доступным копии. Ни в классе, ни в его пакете нельзя передать на командной строке. Это контрастирует с 1.3.x и более ранние выпуски, где класс должен был быть задокументированным классом

Наследуйтесь от классов и интерфейсов - Наследование комментариев происходит во всех трех возможных случаях наследования от классов и интерфейсов:

В первых двух случаях, для переопределений метода, инструмент Javadoc генерирует подзаголовок "Переопределения" в документации для метода переопределения со ссылкой к методу, который это переопределяет, наследован ли комментарий.

В третьем случае, когда метод в данном классе реализует метод в интерфейсе, инструмент Javadoc генерирует подзаголовок, "Определенный" в документации для метода переопределения со ссылкой к методу, который это реализует. Это происходит, наследован ли комментарий.

Алгоритм для Наследования Комментариев Метода - Если метод не имеет комментария документа, или имеет {@inheritDoc} тег, инструмент Javadoc, ищет применимый комментарий, используя следующий алгоритм, который разрабатывается, чтобы найти самый определенный применимый комментарий документа, давая предпочтение интерфейсам по суперклассам:

  1. Смотрите в каждом непосредственно реализованном (или расширенный) интерфейс в порядке, они появляются после реализаций слова (или расширяется) в объявлении метода. Используйте первый комментарий документа, найденный для этого метода.
  2. Если шаг 1, отказавший, чтобы найти комментарий документа, рекурсивно примените этот весь алгоритм к каждому непосредственно реализованному (или расширенный) интерфейс в том же самом порядке, они были исследованы в шаге 1.
  3. Если шаг 2, отказавший, чтобы найти комментарий документа и это - класс кроме Объекта (не интерфейс):
    1. Если у суперкласса есть комментарий документа для этого метода, используйте это.
    2. Если шаг 3a, отказавший, чтобы найти комментарий документа, рекурсивно примените этот весь алгоритм к суперклассу.

ТЕГИ JAVADOC

Инструмент Javadoc анализирует специальные теги, когда они встраиваются в пределах комментария документа Java. Эти теги документа позволяют Вам автоматически сгенерировать полный, хорошо отформатированный API из своего исходного кода. Теги запускаются с "в" знаке (@) и являются чувствительными к регистру - они должны быть введены с прописными и строчными буквами как показано. Тег должен запуститься в начале строки (после того, как любые ведущие пробелы и дополнительная звездочка), или он обрабатывается как нормальный текст. Условно, теги с тем же самым именем группируются. Например, поместите все @see теги вместе.

Теги прибывают в два типа:

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

Текущие теги:

Тег Представленный в JDK/SDK
@author 1.0
{@code} 1.5
{@docRoot} 1.3
@deprecated 1.0
@exception 1.0
{@inheritDoc} 1.4
{@link} 1.2
{@linkplain} 1.4
{@literal} 1.5
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
{@value} 1.4
@version 1.0

Для пользовательских тегов см. - опция тега.

@author name-text
Добавляет запись "Автора" с указанным name-text к сгенерированным документам, когда - опция автора используется. Комментарий документа может содержать многократный @author теги. Можно определить одно имя на @author тег или многократные имена на тег. В прежнем случае инструмент Javadoc вставляет запятую (,) и пространство между именами. В последнем случае весь текст просто копируется в сгенерированный документ без того, чтобы быть проанализированным. Поэтому, можно использовать многократные имена на строку, если Вы хотите локализованный разделитель имени кроме запятой.

Для получения дополнительной информации см., Где Теги Могут Использоваться и пишущий @author теги.

@deprecated deprecated-text
Отметьте: можно осудить элемент программы, используя @Deprecated аннотацию.

Добавляет комментарий, указывающий, что этот API больше не должен использоваться (даже при том, что это может продолжать работать). Инструмент Javadoc перемещает deprecated-text перед основным описанием, помещая это курсивом и предшествуя этому с полужирным предупреждением: "Осуждаемый". Этот тег допустим во всех комментариях документа: краткий обзор, пакет, класс, интерфейс, конструктор, метод и поле.

Первое предложение deprecated-text должно, по крайней мере, сказать пользователю, когда API осуждался и что использовать в качестве замены. Инструмент Javadoc копирует только первое предложение в сводный раздел и индекс. Последующие предложения могут также объяснить, почему это было осуждено. Следует включать a {@link} тег (для Javadoc 1.2 или позже), который указывает на заменяющий API:

Для получения дополнительной информации см. запись @deprecated теги.

Для больше об осуждении, см. тег @deprecated.

{@code text}
Эквивалентный <code>{@literal}</code>.

Дисплеи text в code шрифт, не интерпретируя текст как разметка HTML или вложенные теги javadoc. Это позволяет Вам использовать регулярные угловые скобки (< и >) вместо объектов HTML (&lt; и &gt;) в комментариях документа, такой как в типах параметра (<Object>), неравенства (3 < 4), или стрелки (<-). Например, текст комментария документа:

     {@code A<B>C}

дисплеи в сгенерированной неизменной странице HTML, как:

     A<B>C

Примечательная точка то, что <B> не интерпретируется как полужирный и находится в шрифте кода.

Если Вы хотите ту же самую функциональность без шрифта кода, использовать {@literal}.

{@docRoot}
Представляет относительный путь сгенерированному документу (место назначения) корневой каталог от любой сгенерированной страницы. Полезно, когда Вы хотите включать файл, такой как страница авторского права или логотип компании, на который Вы хотите сослаться от всех сгенерированных страниц. Соединение со страницей авторского права от нижней части каждой страницы распространено.

Это {@docRoot} тег может использоваться и на командной строке и в комментарии документа: Этот тег допустим во всех комментариях документа: краткий обзор, пакет, класс, интерфейс, конструктор, метод и поле, включая текстовую часть любого тега (такого как @return, @param и @deprecated).

  1. На командной строке, где заголовок/нижний колонтитул/нижняя часть определяются: 
       javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'

    ОТМЕТЬТЕ - При использовании {@docRoot} этот путь в make-файле, некоторые программы make-файла требуют специального выхода для фигурной скобки {} символы. Например, Inprise ДЕЛАЮТ версию 5.2, работающую на Windows, требует двойных фигурных скобок: {{@docRoot}}. Это также требует двойной (а не единственный) кавычки включать параметры опциям такой как -bottom (с кавычками вокруг href опущенный параметр).

  2. В комментарии документа: 
       /**
    * See the <a href="{@docRoot}/copyright.html">Copyright</a>.
    */

Причина этот тег необходим, состоит в том, потому что сгенерированные документы находятся в иерархических каталогах, столь же глубоко как число подпакетов. Это выражение:

  <a href="{@docRoot}/copyright.html">

решил бы к:

  <a href="../../copyright.html">      for java/lang/Object.java

и

  <a href="../../../copyright.html">   for java/lang/ref/Reference.java

@exception class-name description
@exception тег является синонимом для @throws.

{@inheritDoc} 
Наследовался (копирует) документацию с "самого близкого" наследуемого класса или интерфейса implementable в текущий комментарий документа в расположении этого тега. Это позволяет Вам писать более общим комментариям выше дерево наследования, и писать вокруг скопированного текста.

Этот тег допустим только в этих местах в комментарии документа:

См. Автоматическое Копирование Комментариев Метода для более точного описания того, как комментарии находятся в иерархии наследования. Отметьте, что, если этот тег отсутствует, комментарий или автоматически не наследован согласно правилам, описанным в том разделе.

{@link package.class#member label}
Вставляет встроенную ссылку с видимой текстовой меткой, которая указывает на документацию для указанного пакета, имени класса или имени элемента класса, на который ссылаются. Этот тег допустим во всех комментариях документа: краткий обзор, пакет, класс, интерфейс, конструктор, метод и поле, включая текстовую часть любого тега (такого как @return, @param и @deprecated).

Этот тег очень simliar к @see - и потребуйте тех же самых ссылок и примите точно тот же самый синтаксис для package.class#member и label. Основное различие - это {@link} генерирует встроенную ссылку вместо того, чтобы поместить ссылку в, "См. Также" раздел. Кроме того, {@link} тег начинается и заканчивается изогнутыми фигурными скобками, чтобы разделить это от остальной части встроенного текста. Если Вы должны использовать"}" в метке, используйте нотацию объекта HTML &#125;

Нет никакого предела числу {@link} теги позволяются в предложении. Можно использовать этот тег в основной части описания любого комментария для документации или в текстовой части любого тега (такого как @deprecated, @return или @param).

Например, вот комментарий, который относится к getComponentAt(int, int) метод:

Use the {@link #getComponentAt(int, int) getComponentAt} method.

От этого стандарт doclet генерировал бы следующий HTML (предполагающий, что это обращается к другому классу в том же самом пакете):

Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.

Который появляется на веб-странице как:

Use the getComponentAt method.

Можно расшириться {@link} соединяться с классами, не задокументированными при использовании -link опция.

Для получения дополнительной информации см. запись {@link} теги.

{@linkplain package.class#member label}
Идентичный {@link}, кроме метки ссылки выводится на экран в простом тексте чем шрифт кода. Полезный, когда метка является простым текстом. Пример: 
     Refer to {@linkplain add() the overridden method}.

Это вывело бы на экран как:

Обратитесь к переопределенному методу.

{@literal text}
Дисплеи text, не интерпретируя текст как разметка HTML или вложенные теги javadoc. Это позволяет Вам использовать регулярные угловые скобки (< и >) вместо объектов HTML (&lt; и &gt;) в комментариях документа, такой как в типах параметра (<Object>), неравенства (3 < 4), или стрелки (<-). Например, текст комментария документа: 
     {@literal A<B>C}

дисплеи, неизменные в сгенерированной странице HTML в Вашем браузере, как:

     <B> C

Примечательная точка то, что <B> не интерпретируется как полужирный (и это не находится в шрифте кода).

Если Вы хотите ту же самую функциональность, но с текстом в шрифте кода, использовать {@code}.

@param parameter-name description
Добавляет параметр с указанным parameter-name, сопровождаемым указанным description к разделу "Параметров". При записи комментария документа можно продолжать description на многократные строки. Этот тег допустим только в комментарии документа для метода, конструктора или класса.

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

Пример параметра типа класса:

     /**
      * @param <E> Type of element stored in a list
      */
     public interface List<E> extends Collection<E> {
     }

Пример параметра типа метода:

     /**
      * @param string  the string to be converted
      * @param type    the type to convert the string to
      * @param <T>     the type of the element
      * @param <V>     the value of the element
      */
     <T, V extends T> V convert(String string, Class<T> type) {
     }

Для получения дополнительной информации см. запись @param теги.

@return description
Добавляет раздел "Возвратов" с текстом description. Этот текст должен описать тип возврата и допустимый диапазон значений. Этот тег допустим только в комментарии документа для метода.

Для получения дополнительной информации см. запись @return теги.

@see reference
Добавляет, "Видят Также" заголовок со ссылкой или вводом текста, который указывает на reference. Комментарий документа может содержать любое число @see теги, которые все группируются в соответствии с тем же самым заголовком. @see у тега есть три изменения; третья форма ниже наиболее распространена. Этот тег допустим в любом комментарии документа: краткий обзор, пакет, класс, интерфейс, конструктор, метод или поле. Для того, чтобы вставить встроенную ссылку в пределах предложения к пакету, классу или элементу, см. {@link}.
@see "string"
Добавляет ввод текста для string. Никакая ссылка не сгенерирована. string является книгой или другой ссылкой на информацию, не доступную URL. Инструмент Javadoc отличает это от предыдущих случаев, ища двойную кавычку (") как первый символ. Например: 
     @see "The Java Programming Language"

Это генерирует текст, такой как:

См. Также:
"Язык программирования Java"
@see <a href="URL#value">label</a>
Добавляет ссылку как определено URL#value. URL#value является относительный или абсолютный URL. Инструмент Javadoc отличает это от других случаев, ища меньше символ (<) как первый символ. Например: 
     @see <a href="spec.html#section">Java Spec</a>
Это генерирует ссылку, такую как:
См. Также:
Спецификация Java
@see package.class#member label
Добавляет ссылку, с видимым текстом label, который указывает на документацию для указанного имени на Языке Java, на который ссылаются. label является дополнительным; если опущено, имя появляется вместо этого, как видимый текст, соответственно сокращенный - видит, Как имя выводится на экран. Используйте-noqualifier, чтобы глобально удалить имя пакета из этого видимого текста. Используйте метку, когда Вы хотите, чтобы видимый текст отличался от автоматически сгенерированного видимого текста.

Только в версии 1.2, только имя, но не метка автоматически появилось бы в <коде>, HTML-тэги, Запускающиеся с 1.2.2, <код>, всегда включаются вокруг видимого текста, используется ли метка.

  • package.class#member является любым допустимым именем элемента программы, на которое ссылаются - пакет, класс, интерфейс, конструктор, имя метода или имя поля - за исключением того, что символ перед именем элемента должен быть символом хеша (#). class представляет любой верхний уровень или вложенный класс или интерфейс. member представляет любого конструктора, метод или поле (не вложенный класс или интерфейс). Если это имя будет в задокументированных классах, то инструмент Javadoc автоматически создаст ссылку к нему. Чтобы создать ссылки к внешним классам, на которые ссылаются, используйте -link опция. Используйте любой из других двух @see формы для того, чтобы сослаться на документацию имени, которое не принадлежит классу, на который ссылаются. Этот параметр описывается в большей длине ниже при Определении Имени.
  • label является дополнительным текстом, который видим как метка ссылки. label может содержать пробел. Если label будет опущен, то package.class.member появится, соответственно сокращенный относительно текущего класса и пакета - видят, Как имя выводится на экран.
  • Пространство является разделителем между package.class#member и label. Пространство в круглых скобках не указывает на запуск метки, таким образом, пробелы могут использоваться между параметрами в методе.

Пример - В этом примере, @see тег (в Character класс), обращается к equals метод в String класс. Тег включает оба параметра: имя"String#equals(Object)"и метка"equals".

 /**
  * @see String#equals(Object) equals
  */
Стандарт doclet производит HTML что-то вроде этого: 
<dl>
<dt><b>See Also:</b>
<dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>
</dl>
Который выглядит примерно так в браузере, где метка является видимым текстом ссылки:
См. Также:
равняется

Определение имени - Этот package.class#Имя member может быть или полностью определено, такой как java.lang.String#toUpperCase() или нет, такой как String#toUpperCase() или #toUpperCase(). Если менее чем полностью определенный, инструмент Javadoc использует нормальный порядок поиска компилятора Java счесть это, далее описанным ниже в Поисковом порядке на @see. Имя может содержать пробел в пределах круглых скобок, такой как между параметрами метода.

Конечно, преимущество обеспечения более коротких, "частично квалифицированных" имен состоит в том, что они короче, чтобы ввести и в исходном коде есть меньше помехи. Следующая таблица показывает различные формы имени, где Class может быть классом или интерфейсом, Type может быть классом, интерфейс, массив, или примитивный, и method могут быть методом или конструктором.

Типичные формы для @see package.class#member
Ссылка на элемент   текущего класса
@see #field
@see # method(Type, Type,...)
@see #   method(Type argname, Type argname,...)
@see # constructor(Type, Type,...)
@see #   constructor(Type argname, Type argname,...)
Ссылка на другой класс в  текущих или импортированных пакетах
@see Class#field
@see Class# method(Type, Type,...)
@see Class#   method(Type argname, Type argname,...)
@see Class# constructor(Type, Type,...)
@see Class#   constructor(Type argname, Type argname,...)
@see Class.NestedClass
@see Class
Ссылка на элемент в другом пакете (полностью определяется)
@see package.Class#field
@see package.Class# method(Type, Type,...)
@see package.Class#   method(Type argname, Type argname,...)
@see package.Class# constructor(Type, Type,...)
@see package.Class#   constructor(Type argname, Type argname,...)
@see package.Class.NestedClass
@see package.Class
@see package

Следующие примечания применяются к вышеупомянутой таблице:

  • Первый набор форм (без класса или пакета) заставит инструмент Javadoc искать только через иерархию текущего класса. Это найдет элемент текущего класса или интерфейса, одного из его суперклассов или суперинтерфейсов, или одного из его классов включения или интерфейсов (поисковые шаги 1-3). Это не будет искать остальную часть текущего пакета или других пакетов (поисковые шаги 4-5).
  • Если какой-либо метод или конструктор вводятся как имя без круглых скобок, такой как getValue, и если не будет никакого поля с тем же самым именем, то инструмент Javadoc правильно создаст ссылку к нему, но напечатает предупреждающее сообщение, напоминающее Вам добавить круглые скобки и параметры. Если этот метод будет перегружен, то инструмент Javadoc соединится с первым методом, с которым встречается его поиск, который является неуказанным.
  • Вложенные классы должны быть определены как outer.inner, не просто inner, для всех форм.
  • Как утверждено, символ хеша (#), а не точка (.) разделяет элемент от его класса. Это позволяет инструменту Javadoc разрешить неоднозначности, так как точка также разделяет классы, вложенные классы, пакеты, и подпакеты. Однако, инструмент Javadoc обычно снисходителен и должным образом проанализирует точку, если Вы знаете, что нет никакой неоднозначности, хотя он напечатает предупреждение.

Поисковый порядок на @see - инструмент Javadoc обработает a @see тег, который появляется в исходном файле (.java), файл пакета (package.html или пакет-info.java) или файл краткого обзора (overview.html). В последних двух файлах следует полностью определить имя, которое Вы предоставляете @see. В исходном файле можно определить имя, которое полностью определяется или частично квалифицируется.

Когда инструмент Javadoc встречается с a @see тег в a .java файл, который не полностью определяется, это ищет указанное имя в том же самом порядке, как компилятор Java был бы (кроме инструмента Javadoc, не будет обнаруживать определенные неоднозначности пространства имен, так как это предполагает, что исходный код является бесплатным от этих ошибок). Этот поисковый порядок формально определяется в Спецификации языка Java. Поиски инструмента Javadoc того имени через все связанные и импортированные классы и пакеты. В частности это ищет в этом порядке:

  1. текущий класс или интерфейс
  2. любые классы включения и интерфейсы, ища самый близкий сначала
  3. любые суперклассы и суперинтерфейсы, ища самый близкий сначала
  4. текущий пакет
  5. любые импортированные пакеты, классы и интерфейсы, ищущие в порядке оператора импорта

Инструмент Javadoc продолжает искать рекурсивно через шаги 1-3 для каждого класса, с которым он встречается, пока он не находит соответствие. Таким образом, после того, как это перероет текущий класс и его класс E включения, это перероет суперклассы Э перед классами включения Э. В шагах 4 и 5 инструмент Javadoc не ищет классы или интерфейсы в пределах пакета в любом указанном порядке (что порядок зависит от определенного компилятора). В шаге 5, видах инструмента Javadoc в java.lang, так как это автоматически импортируется всеми программами.

Инструмент Javadoc не обязательно смотрит в подклассах, и при этом это не будет смотреть в других пакетах, даже если их документация будет сгенерирована в том же самом выполнении. Например, если @see тег находится в java.awt.event.KeyEvent класс и обращается к имени в java.awt пакет, javadoc не смотрит в том пакете, если тот класс не импортирует это.

Как имя выводится на экран - Если label опускается, то package.class.member появляется. Вообще, это соответственно сокращается относительно текущего класса и пакета. "Сокращенным" мы подразумеваем, что инструмент Javadoc выводит на экран только минимальное необходимое имя. Например, если String.toUpperCase() метод содержит ссылки на элемент того же самого класса и к элементу различного класса, имя класса выводится на экран только в последнем случае, как показано в следующей таблице.

Используйте-noqualifier, чтобы глобально удалить имена пакета.

Тип Ссылки Пример в String.toUpperCase() Дисплеи Как
@see тег обращается к элементу того же самого класса, того же самого пакета @see String#toLowerCase() toLowerCase() (опускает пакет и имена классов),
@see тег обращается к элементу различного класса, того же самого пакета @see Character#toLowerCase(char) Character.toLowerCase(char) (опускает имя пакета, включает имя класса),
@see тег обращается к элементу различного класса, различного пакета @see java.io.File#exists() java.io.File.exists() (включает пакет и имена классов),

Примеры @see
Комментарий к праву показывает, как имя было бы выведено на экран если @see тег находится в классе в другом пакете, такой как java.applet.Applet.

                                           See also: 
@see java.lang.String                   //  String                           
@see java.lang.String The String class  //  The String class                 
@see String                             //  String                           
@see String#equals(Object)              //  String.equals(Object)            
@see String#equals                      //  String.equals(java.lang.Object)   
@see java.lang.Object#wait(long)        //  java.lang.Object.wait(long)      
@see Character#MAX_RADIX                //  Character.MAX_RADIX              
@see <a href="spec.html">Java Spec</a>  //  Java Spec            
@see "The Java Programming Language"    //  "The Java Programming Language"
Можно расшириться @see соединяться с классами, не задокументированными при использовании -link опция.

Для получения дополнительной информации см. запись @see теги.

@serial field-description | include | exclude
Используемый в документе комментируют для сериализуемого поля по умолчанию.

Дополнительный field-description должен объяснить значение поля и перечислить приемлемые значения. Если нужно описание может охватить многократные строки. Стандарт doclet добавляет эту информацию к сериализированной странице формы.

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

include и exclude параметры идентифицируют, должны ли класс или пакет быть включены или исключены из сериализированной страницы формы. Они работают следующим образом:

Примеры: javax.swing пакет отмечается @serial exclude (в package.html или package-info.java). Общедоступный класс java.security.BasicPermission отмечается @serial exclude. Частный на пакет класс java.util.PropertyPermissionCollection отмечается @serial include.

Тег @serial на уровне класса переопределяет @serial на уровне пакета.

Для получения дополнительной информации о том, как использовать эти теги, наряду с примером, см. "Документирующие Сериализуемые Поля и Данные для Класса," Раздел 1.6 из Спецификации Сериализации Объекта Java. Также см. FAQ Сериализации, который покрывает общие вопросы, такой как, "Почему я вижу javadoc предупреждения утвердить, что я пропускаю теги @serial для частных полей, если я не выполняю javadoc с - частный переключатель?". Также см. критерии Sun для включения классов в сериализированной спецификации формы.

@serialField field-name field-type field-description
Документирует ObjectStreamField компонент a Serializable класс serialPersistentFields элемент. Один @serialField тег должен использоваться для каждого ObjectStreamField компонент.

@serialData data-description
data-description документирует типы и порядок данных в сериализированной форме. Определенно, эти данные включают дополнительные данные, записанные writeObject метод и все данные (включая базовые классы) записанный Externalizable.writeExternal метод.

@serialData тег может использоваться в комментарии документа для writeObject, readObject, writeExternal, readExternal, writeReplace, и readResolve методы.

@since since-text
Добавляет "Начиная с" заголовка с указанным since-text к сгенерированной документации. У текста нет никакой специальной внутренней структуры. Этот тег допустим в любом комментарии документа: краткий обзор, пакет, класс, интерфейс, конструктор, метод или поле. Этот тег означает, что это изменение или функция существовали начиная с выпуска программного обеспечения, определенного since-text. Например: 
    @since 1.5

Для исходного кода в платформе Java этот тег указывает на версию спецификации API платформы Java (не обязательно, когда это было добавлено к ссылочной реализации). Многократные теги @since позволяются и обрабатываются как многократные теги @author. Вы могли использовать многократные теги, если prgram элемент используется больше чем одним API.

@throws class-name description
@throws и @exception теги являются синонимами. Добавляет подзаголовок "Бросков" к сгенерированной документации с текстом description и class-name. class-name является именем исключения, которое может быть выдано методом. Этот тег допустим только в комментарии документа для метода или конструктора. Если этот класс не является полностью указанным, инструмент Javadoc использует поисковый порядок искать этот класс. Многократный @throws теги могут использоваться в данном комментарии документа для тех же самых или различных исключений.

Гарантировать, что все проверенные исключения документируются, если a @throws тег не существует для исключения в пункте бросков, инструмент Javadoc автоматически добавляет, что исключение к выводу HTML (без описания), как будто это было задокументировано с тегом @throws.

@throws документация копируется от переопределенного метода до подкласса только, когда исключение явно объявляется в переопределенном методе. То же самое является истиной для того, чтобы скопировать от интерфейсного метода до метода реализации. Можно использовать {@inheritDoc}, чтобы вынудить @throws наследовать документацию.

Для получения дополнительной информации см. запись @throws теги.

{@value package.class#field}
Когда {@value} используется (без любого параметра) в комментарии документа статического поля, это выводит на экран значение той константы: 
    /**
     * The value of this constant is {@value}.
     */
    public static final String SCRIPT_START = "<script>"

Когда использующийся с параметром package.class#field в любом комментарии документа, это выводит на экран значение указанной константы:

    /**
     * Evaluates the script starting with {@value #SCRIPT_START}.
     */
    public String evalScript(String script) {
    }

package.class#field параметра принимает форму, идентичную тому из @see параметра, за исключением того, что элемент должен быть статическим полем.

Эти значения этих констант также выводятся на экран на Постоянной странице Значений полей.

@version version-text
Добавляет подзаголовок "Версии" с указанным version-text к сгенерированным документам, когда - опция версии используется. Этот тег предназначается, чтобы содержать число текущей версии программного обеспечения, из которого этот код является частью (в противоположность @since, который содержит номер версии, где этот код был представлен). У version-text нет никакой специальной внутренней структуры. Чтобы видеть, где тег версии может использоваться, см., Где Теги Могут Использоваться.

Комментарий документа может содержать многократный @version теги. Если это имеет смысл, можно определить один номер версии на @version тег или многократные номера версий на тег. В прежнем случае инструмент Javadoc вставляет запятую (,) и пространство между именами. В последнем случае весь текст просто копируется в сгенерированный документ без того, чтобы быть проанализированным. Поэтому, можно использовать многократные имена на строку, если Вы хотите локализованный разделитель имени кроме запятой.

Для получения дополнительной информации см. запись @version теги.

Где Теги Могут Использоваться

Следующие разделы описывают, где теги могут использоваться. Отметьте, что эти теги могут использоваться во всех комментариях документа: @see, @since, @deprecated, {@link}, {@linkplain}, и {@docroot}.

Теги Документации краткого обзора

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

ОТМЕТЬТЕ - {@link} у тега есть ошибка в документах краткого обзора в версии 1.2 - текст появляется должным образом, но не имеет никакой ссылки. {@docRoot} тег в настоящий момент не работает в документах краткого обзора.

Теги краткого обзора

Теги Документации пакета

Теги пакета являются тегами, которые могут появиться в комментарии для документации для пакета (который находится в названном исходном файле package.html или package-info.java). @serial тег может только использоваться здесь с include или exclude параметр.

Теги пакета

Класс и Интерфейсные Теги Документации

Следующее является тегами, которые могут появиться в комментарии для документации для класса или интерфейса. @serial тег может только использоваться здесь с include или exclude параметр.

Теги класса/Интерфейса

Пример комментария класса:

/**
 * A class representing a window on the screen.
 * For example:
 * <pre>
 *    Window win = new Window(parent);
 *    win.show();
 * </pre>
 *
 * @author  Sami Shaio
 * @version 1.13, 06/08/06
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow {
   ...
}

Полевые Теги Документации

Следующее является тегами, которые могут появиться в

Полевые Теги

Пример полевого комментария:

    /**
     * The X-coordinate of the component.
     *
     * @see #getLocation()
     */
    int x = 1263732;

Конструктор и Теги Документации Метода

Следующее является тегами, которые могут появиться в комментарии для документации для конструктора или метода, за исключением @return, который не может появиться в конструкторе, и {@inheritDoc}, у которого есть определенные ограничения. @serialData тег может только использоваться в комментарии документа для определенных методов сериализации.

Теги метода/Конструктора

Пример комментария документа метода:

    /**
     * Returns the character at the specified index. An index 
     * ranges from <code>0</code> to <code>length() - 1</code>.
     *
     * @param     index  the index of the desired character.
     * @return    the desired character.
     * @exception StringIndexOutOfRangeException 
     *              if the index is not in the range <code>0</code> 
     *              to <code>length()-1</code>.
     * @see       java.lang.Character#charValue()
     */
    public char charAt(int index) {
       ...
    }

ОПЦИИ

javadoc инструмент использует doclets, чтобы определить его вывод. Инструмент Javadoc использует стандарт по умолчанию doclet, если пользовательский doclet не определяется с-doclet опцией. Инструмент Javadoc обеспечивает ряд параметров командной строки, которые могут использоваться с любым doclet - эти опции описываются ниже под подзаголовком Опции Javadoc. Стандарт doclet обеспечивает дополнительный набор параметров командной строки, которые описываются ниже под Возможностями подзаголовка, предоставленными Стандартным Doclet. Все имена опции являются нечувствительными к регистру, хотя их параметры могут быть чувствительными к регистру.

Опции:

-1.1
-автор
-bootclasspath
-нижняя часть
-breakiterator
-набор символов
-путь к классу
-d
-docencoding
-docfilessubdirs
-doclet
-docletpath
-doctitle
-кодирование
-исключить
-excludedocfilessubdir
-extdirs
-нижний колонтитул
-группа
 -заголовок
-справка
-helpfile
-J
-ключевые слова
-ссылка
-linkoffline
-linksource
-локаль
-nocomment
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-noqualifier
-nosince
-notimestamp
-notree
-краткий обзор
-пакет
 -частный
-защищенный
-общественность
-тихий
-serialwarn
-источник
-sourcepath
-sourcetab
-splitindex
-stylesheetfile
-подпакеты
-тег
-taglet
-tagletpath
-вершина
-заголовок
-использовать
-многословный
-версия
-windowtitle

Варианты, показывавшие в курсиве, являются возможностями ядра Javadoc, которые предоставляются фронтэндом инструмента Javadoc и доступны всему doclets. Стандарт сам doclet предоставляет некурсивные возможности.

Опции Javadoc

-  путь/имя файла краткого обзора
Определяет, что javadoc должен получить текст для документации краткого обзора от "исходного" файла, определенного путем/именем файла, и поместить это на странице Краткого обзора (overview-summary.html). Путь/имя файла относительно текущего каталога.

В то время как можно использовать любое имя, Вы хотите для имени файла и помещаете его куда угодно, Вы хотите для пути, типичная вещь сделать состоит в том, чтобы назвать его overview.html и поместите это в исходное дерево в каталоге, который содержит самые верхние каталоги пакета. В этом расположении никакой путь не необходим, документируя пакеты с тех пор -sourcepath укажет на этот файл. Например, если исходное дерево для java.lang пакет /src/classes/java/lang/, тогда Вы могли поместить файл краткого обзора в /src/classes/overview.html. См. Пример Реального мира.

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

Отметьте, что страница краткого обзора создается, только если Вы передаете в javadoc два или больше имени пакета. Для дальнейшего объяснения см. Фреймы HTML.)

Заголовок на странице краткого обзора устанавливается -doctitle.
- общественность
Шоу только общедоступные классы и элементы.
- защищенный
Шоу только защищенные и общедоступные классы и элементы. Это - значение по умолчанию.
- пакет
Шоу только пакет, защищенные, и общедоступные классы и элементы.
- частный
Шоу все классы и элементы.
- справка
Выводит на экран онлайновую справку, которая перечисляет эти javadoc и doclet параметры командной строки.
-doclet class
Определяет файл класса, который запускает doclet, используемый в генерировании документации. Используйте полностью определенное имя. Этот doclet определяет контент и форматирует вывод. Если -doclet опция не используется, javadoc использует стандарт doclet для того, чтобы генерировать формат HTML по умолчанию. Этот класс должен содержать start(Root) метод. Путь к этому начальному классу определяется -docletpath опция.

Например, чтобы вызвать MIF doclet, используйте: 
    -doclet com.sun.tools.doclets.mif.MIFDoclet
Для полных, рабочих примеров выполнения определенного doclet см. MIF Doclet документация.
-docletpath classpathlist
Определяет путь к doclet запускающийся файл класса (определенный с -doclet опция), и любые файлы фляги это зависит от. Если запускающийся файл класса находится в файле фляги, то это определяет путь к тому файлу фляги, как показано в примере ниже. Можно определить абсолютный путь или путь относительно текущего каталога. Если classpathlist содержит разнообразные пути или файлы фляги, они должны быть разделены двоеточием (:) на Солярисе и точке с запятой (;) на Windows. Эта опция не необходима, если doclet запускающийся класс уже находится в пути поиска.

Пример пути к файлу фляги, который содержит запуск doclet файл класса. Заметьте, что имя файла фляги включается. 
   -docletpath /home/user/mifdoclet/lib/mifdoclet.jar
Пример пути к запуску doclet файл класса. Заметьте, что имя файла класса опускается. 
   -docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/
Для полных, рабочих примеров выполнения определенного doclet см. MIF Doclet документация.
-1.1
Эта функция была удалена из Javadoc 1.4. Нет никакой замены для этого. Эта опция создаваемая документация с появлением и функциональностью документации, сгенерированной Javadoc 1.1 (это никогда не поддерживало вложенные классы). Если Вы нуждаетесь в этой опции, используйте Javadoc 1.2 или 1.3 вместо этого.
- исходный выпуск
Определяет версию принятого исходного кода. Следующие значения для выпуска позволяются: Используйте значение выпуска, соответствующего используемому, компилируя код с javac.
-sourcepath sourcepathlist
Определяет пути поиска для того, чтобы найти исходные файлы (.java) передавая имена пакета или -subpackages в javadoc команда. sourcepathlist может содержать разнообразные пути, разделяя их двоеточием (:). Инструмент Javadoc будет искать во всех подкаталогах указанных путей. Отметьте, что эта опция не только используется, чтобы определить местоположение исходных файлов, задокументированных, но также и найти исходные файлы, которые не документируются, но чьи комментарии наследованы задокументированными исходными файлами.

Отметьте, что можно использовать -sourcepath опция только, передавая пакет называет в javadoc команду - это не будет располагаться .java файлы, которые передают в javadoc команда. (Чтобы расположиться .java файлы, cd к тому каталогу или включают путь перед каждым файлом, как показано при Документировании Того или Большего количества Классов.), Если -sourcepath опускается, javadoc использует путь к классу, чтобы найти исходные файлы (см. - путь к классу). Поэтому, значение по умолчанию-sourcepath является значением пути к классу. Если - путь к классу опускается, и Вы передаете имена пакета в javadoc, это смотрит в текущем каталоге (и подкаталоги) для исходных файлов.

Установите sourcepathlist в корневой каталог исходного дерева для пакета, который Вы документируете. Например, предположите, что Вы хотите задокументировать вызванный пакет com.mypackage чьи исходные файлы располагаются в: 
  /home/user/src/com/mypackage/*.java
В этом случае Вы определили бы sourcepath к /home/user/src, каталог, который содержит com/mypackage, и затем предоставьте имя пакета com.mypackage: 
  % javadoc -sourcepath /home/user/src/ com.mypackage
Это легко помнить, замечая, что, если Вы связываете значение sourcepath и имени пакета вместе и изменяете точку на наклонную черту "/", Вы заканчиваете с полным путем к пакету: /home/user/src/com/mypackage.

Указать на два исходных пути: 
  % javadoc -sourcepath /home/user1/src:/home/user2/src com.mypackage
- путь к классу classpathlist
Определяет пути, где javadoc будет искать классы, на которые ссылаются (.class файлы) - они - задокументированные классы плюс любые классы, на которые ссылаются те классы. classpathlist может содержать разнообразные пути, разделяя их двоеточием (:). Инструмент Javadoc будет искать во всех подкаталогах указанных путей. Следуйте инструкциям в документации пути к классу для того, чтобы определить classpathlist.

Если -sourcepath опускается, использование инструмента Javadoc -classpath найти исходные файлы так же как файлы класса (для обратной совместимости). Поэтому, если Вы хотите искать источник и файлы класса в отдельных путях, используйте обоих -sourcepath и -classpath.

Например, если Вы хотите задокументировать com.mypackage, чьи исходные файлы находятся в каталоге /home/user/src/com/mypackage, и если этот пакет полагается на библиотеку в /home/user/lib, Вы определили бы: 
  % javadoc -classpath /home/user/lib -sourcepath /home/user/src com.mypackage
Как с другими инструментами, если Вы не определяете -classpath, инструмент Javadoc использует переменную окружения ПУТИ К КЛАССУ, если это устанавливается. Если оба не устанавливаются, инструмент Javadoc ищет классы из текущего каталога.

Для всестороннего описания того, как инструмент Javadoc использует -classpath чтобы найти пользовательские классы, поскольку это касается классов расширения и классов начальной загрузки, см., Как Классы Находятся.

Как специальное удобство, элемент пути к классу, содержащий базовое имя * считается эквивалентным определению списка всех файлов в каталоге с расширением .jar или .JAR (программа Java не может сказать различие между этими двумя вызовами).

Например, если каталог foo содержит a.jar и b.JAR, тогда элемент пути к классу foo/* расширяется до a A.jar:b.JAR, за исключением того, что порядок файлов фляги является неуказанным. Все файлы фляги в указанном каталоге, даже скрытых, включаются в список. Запись пути к классу, состоящая просто из * расширяется до списка всех файлов фляги в текущем каталоге. CLASSPATH переменная окружения, где определено, будет так же расширена. Любое подстановочное расширение пути к классу происходит прежде, чем виртуальная машина Java запускается - никакая программа Java никогда не будет видеть нерасширенные подстановочные знаки кроме, запрашивая среду. Например; вызывая System.getenv("CLASSPATH").
-subpackages  package1:package2:...
Генерирует документацию от исходных файлов в указанных пакетах и рекурсивно в их подпакетах. Эта опция полезна, добавляя новые подпакеты к исходному коду, поскольку они автоматически включаются. Каждым параметром пакета является любой высокоуровневый подпакет (такой как java) или полностью определенный пакет (такой как javax.swing) это не должно содержать исходные файлы. Параметры разделяются двоеточиями (на всей работе systmes). Подстановочные знаки не необходимы или позволяются. Использовать -sourcepath определить, где найти пакеты. Эта опция умна о не обработке исходных файлов, которые находятся в исходном дереве, но не принадлежат пакетам, как описано при обработке исходных файлов.

Например: 
  % javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
Эта команда генерирует документацию для пакетов, названных "java" и "javax.swing" и всеми их подпакетами.

Можно использовать -subpackages в соединении с -exclude исключить определенные пакеты.
- исключают  packagename1:packagename2:...
Безоговорочно исключает указанные пакеты и их подпакеты от списка, сформированного -subpackages. Это исключает те пакеты, даже если они были бы иначе включены некоторыми предыдущими или позже -subpackages опция. Например: 
  % javadoc -sourcepath /home/user/src -subpackages java -exclude java.net:java.lang
включал бы java.io, java.util, и java.math (среди других), но исключил бы пакеты, базированные в java.net и java.lang. Заметьте, что это исключает java.lang.ref, подпакет java.lang).
-bootclasspath classpathlist
Определяет пути, где классы начальной загрузки находятся. Они - номинально классы платформы Java. bootclasspath является частью пути поиска, который инструмент Javadoc будет использовать, чтобы искать файлы класса и источник. См., Как Классы Находятся. для большего количества деталей. Отдельные каталоги в classpathlist с двоеточиями (:).
-extdirs dirlist
Определяет каталоги, где классы расширения находятся. Они - любые классы, которые используют механизм Расширения Java. extdirs является частью пути поиска, который инструмент Javadoc будет использовать, чтобы искать файлы класса и источник. См. -classpath (выше) для большего количества деталей. Отдельные каталоги в dirlist с двоеточиями (:).
- многословный
Обеспечивает более подробные сообщения, в то время как javadoc работает. Без многословной опции сообщения появляются для того, чтобы загрузить исходные файлы, генерируя документацию (одно сообщение на исходный файл), и сортировка. Многословная опция заставляет печать дополнительных сообщений, определяющих число миллисекунд анализировать каждый исходный файл java.
- тихий
Отключает неошибку и непредупреждающие сообщения, оставляя только предупреждения, и ошибки кажутся, делая их легче просмотреть. Также подавляет строку версии.
-breakiterator 
Использует интернационализировавшую границу предложения java.text.BreakIterator определить конец первого предложения для английского языка (все другие локали уже используют BreakIterator), а не английский язык, специфичный для локали алгоритм. Первым предложением мы имеем в виду первое предложение в основном описании пакета, класса или элемента. Это предложение копируется в пакет, класс или задействованную сводку, и в алфавитный индекс.

От JDK 1.2 прямой, класс BreakIterator уже используется, чтобы определить конец предложения для всех языков, но английского языка. Поэтому, -breakiterator опция не имеет никакого эффекта за исключением английского языка от 1.2 вперед. У английского языка есть свой собственный алгоритм по умолчанию: ОТМЕТЬТЕ: Мы удалили от 1.5.0 breakiterator предупреждающие сообщения, которые были в 1.4.x и оставили алгоритм повреждения предложения по умолчанию неизменным. Таким образом,-breakiterator опция не является значением по умолчанию в 1.5.0, и при этом мы не ожидаем, что это станет значением по умолчанию. Это - реверсирование от нашего прежнего намерения, что значение по умолчанию изменилось бы в "следующей главной версии" (1.5.0). Это означает, не изменили ли Вы свой исходный код, чтобы устранить breakiterator предупреждения в 1.4.x, тогда Вы ничего не должны сделать, и предупреждения уходят, запускаясь с 1.5.0. Причина этого реверсирования состоит в том, потому что любое преимущество к наличию breakiterator становится значением по умолчанию, был бы перевешен несовместимым исходным изменением, которого это потребует. Мы сожалеем о любой дополнительной работе и беспорядке, который это вызвало.
- локаль language_country_variant
Важный - -locale опция должна быть помещена вперед (налево) любых возможностей, предоставленных стандартом doclet или любым другим doclet. Иначе, панели навигации появятся на английском языке. Это - единственный параметр командной строки, который зависим от порядка.

Определяет локаль, которую javadoc использует, генерируя документацию. Параметром является имя локали, как описано в java.util. Документация локали, такой как en_US (Английский язык, Соединенные Штаты) или en_US_WIN (Разновидность Windows).

Определение локали заставляет javadoc выбирать файлы ресурсов той локали для сообщений (строки в панели навигации, заголовках для списков и таблиц, содержания справочного файла, комментариев в stylesheet.css, и т.д). Это также определяет порядок сортировки для списков, сортированных в алфавитном порядке, и разделитель предложения, чтобы определить конец первого предложения. Это не определяет локаль текста комментария документа, определенного в исходных файлах задокументированных классов.
- кодирующий имя
Определяет имя кодирования исходных файлов, такой как EUCJIS/SJIS. Если эта опция не определяется, преобразователь значения по умолчанию платформы используется.

Также см.-docencoding и - набор символов.
-Jflag
Передачи отмечают непосредственно к системному java времени выполнения, который выполняет javadoc. Уведомление там не должно быть никаким пространством между J и флаг. Например, если Вы должны гарантировать, что система откладывает 32 мегабайта памяти, в которой можно обработать сгенерированную документацию, тогда Вы вызвали бы -Xmx опция java следующим образом (-Xms является дополнительным, поскольку это только устанавливает размер начальной памяти, которая полезна, если Вы знаете минимальное количество требуемой памяти): 
   % javadoc -J-Xmx32m -J-Xms32m com.mypackage
Чтобы сказать, какую версию javadoc Вы используете, вызовите"-version"опция java: 
   % javadoc -J-version
   java version "1.2"
   Classic VM (build JDK-1.2-V, green threads, sunwjit)
(Номер версии стандарта doclet появляется в его потоке вывода.)

Возможности, предоставленные Стандартным Doclet

-d directory
Определяет целевой каталог, где javadoc сохранил сгенерированные файлы HTML. ("d" означает "место назначения."), Опускающий эту опцию заставляет файлы быть сохраненными к текущему каталогу. Значение directory может быть абсолютным, или относительно текущего рабочего каталога. С 1.4, автоматически создается целевой каталог, когда javadoc выполняется.

Например, следующее генерирует документацию для пакета com.mypackage и сохраняет результаты в /home/user/doc/ каталог: 
  % javadoc -d /home/user/doc com.mypackage
- используют
Включает одну страницу "Использования" для каждого задокументированного класса и пакета. Страница описывает то, что упаковывает, классы, методы, конструкторы и поля используют любой API данного класса или пакета. Данный класс C, вещи, которые используют класс C, включали бы подклассы C, поля, объявленные как C, методы, которые возвращают C, и методы и конструкторов с параметрами типа C.

Например, давайте смотреть на то, что могло бы появиться на странице "Использования" для Строки. getName() метод в java.awt.Font класс возвращает тип String. Поэтому, getName() использование String, и Вы найдете что метод на странице "Использования" для String.

Отметьте, что это документирует только использование API, не реализацию. Если метод использует String в его реализации, но не берет строку в качестве параметра или возвращает строку, которую не считают "использованием" String.

Можно получить доступ к сгенерированной странице "Использования" первым движением к классу или пакету, затем щелкая по ссылке "Использования" в панели навигации.
- версия
Включает @version текст в сгенерированные документы. Этот текст опускается по умолчанию. Чтобы сказать, какую версию инструмента Javadoc Вы используете, используйте -J-version опция.
- автор
Включает @author текст в сгенерированные документы.
-splitindex
Разделяет индексный файл на многократные файлы, в алфавитном порядке, один файл на букву, плюс файл для любых элементов индекса, которые запускаются с неалфавитных символов.
 Заголовок-windowtitle
Определяет заголовок, который будет помещен в HTML <заголовок> тег. Это появляется в заголовке окна и в любых закладках браузера (любимые места), что кто-то создает для этой страницы. Этот заголовок не должен содержать HTML-тэги, поскольку браузер не будет должным образом интерпретировать их. Любые внутренние кавычки в пределах заголовка, вероятно, придется оставить. Если-windowtitle опускается, инструмент Javadoc использует значение-doctitle для этой опции. 
  % javadoc -windowtitle "Java SE Platform" com.mypackage
 Заголовок-doctitle
Определяет заголовок, который будет помещен около вершины сводного файла краткого обзора. Заголовок будет помещен как центрируемый, выровняет тот, возглавляющий непосредственно ниже верхней панели навигации. Заголовок может содержать html-тэги и пробел, хотя, если это делает, это должно быть включено в кавычки. Любые внутренние кавычки в пределах заголовка, вероятно, придется оставить. 
  % javadoc -doctitle "Java™" com.mypackage
- заголовок заголовка
Эта опция больше не существует. Это существовало только в Бета-версиях Javadoc 1.2. Это было переименовано к -doctitle. Эта опция переименовывается, чтобы прояснить, что она определяет заголовок документа, а не заголовок окна.
- заголовок заголовка
Определяет текст заголовка, который будет помещен наверху каждого выходного файла. Заголовок будет помещен направо от верхней панели навигации. заголовок может содержать HTML-тэги и пробел, хотя, если это делает, это должно быть включено в кавычки. Любые внутренние кавычки в пределах заголовка, вероятно, придется оставить. 
  % javadoc -header "<b>Java 2 Platform </b><br>v1.4" com.mypackage
Футов длиной нижний колонтитул
Определяет текст нижнего колонтитула, который будет помещен у основания каждого выходного файла. Нижний колонтитул будет помещен направо от более низкой панели навигации. нижний колонтитул может содержать html-тэги и пробел, хотя, если это делает, это должно быть включено в кавычки. Любые внутренние кавычки в нижнем колонтитуле, вероятно, придется оставить.
- вершина
Определяет текст, который будет помещен наверху каждого выходного файла.
- нижний текст
Определяет текст, который будет помещен у основания каждого выходного файла. Текст будет помещен внизу страницы ниже более низкой панели навигации. text может содержать HTML-тэги и пробел, хотя, если это делает, это должно быть включено в кавычки. Любые внутренние кавычки в пределах text, вероятно, придется оставить.
- ссылка extdocURL
Создает ссылки к существующей javadoc-сгенерированной документации внешних классов, на которые ссылаются. Требуется один параметр: Можно определить многократный -link опции в данном javadoc, выполненном, чтобы соединиться с многократными документами.

Выбор между-linkoffline и - ссылка:

Использовать -link: Использовать -linkoffline:

Пример используя абсолютные ссылки к внешним документам - Позволял нам говорить, что Вы хотите соединиться с java.lang, java.io и другие пакеты Платформы Java в http://download.oracle.com/javase/7/docs/api/. Следующая команда генерирует документацию для пакета com.mypackage со ссылками к Java пакеты Платформы SE. Сгенерированная документация будет содержать ссылки к Object класс, например, в деревьях класса. (Другие опции, такой как -sourcepath и -d, не показываются.) 
  % javadoc -link http://download.oracle.com/javase/7/docs/api/ com.mypackage
Пример используя родственника соединяется с внешними документами - Позволяют нам говорить, что у Вас есть два пакета, документы которых сгенерированы в различных выполнениях инструмента Javadoc, и те документы разделяются относительным путем. В этом примере пакеты com.apipackage, API, и com.spipackage, SPI (Служба Обеспечивают Интерфейс). Вы хотите, чтобы документация находилась в docs/api/com/apipackage и docs/spi/com/spipackage. Принятие документации пакета API уже сгенерировано, и это docs текущий каталог, Вы задокументировали бы пакет SPI со ссылками к документации API, работая: 
  % javadoc -d ./spi -link ../api com.spipackage
Заметьте -link параметр относительно целевого каталога (docs/spi).

Детали - -link опция позволяет Вам соединиться с классами, на которые ссылается к Ваш код, но не задокументированные в ток javadoc выполненный. Для этих ссылок, чтобы пойти в допустимые страницы, следует знать, где те страницы HTML располагаются, и определяют то расположение с extdocURL. Это позволяет, например, сторонней документации соединяться с java.* документация относительно http://java.sun.com.

Опустите -link опция для javadoc, чтобы создать ссылки только к API в пределах документации это генерирует в выполненном токе. (Без -link опция, инструмент Javadoc не создает ссылки к документации для внешних ссылок, потому что это не знает, если или где та документация существует.)

Эта опция может создать ссылки в нескольких местах в сгенерированной документации.

Другое использование для перекрестных ссылок между наборами пакетов: Выполните javadoc на одном наборе пакетов, затем выполните javadoc снова на другом наборе пакетов, создавая ссылки оба пути между обоими наборами.

Как на Класс Нужно Сослаться - Для ссылки к внешнему классу, на который ссылаются, чтобы фактически появиться (и не только его текстовая метка), на класс нужно сослаться следующим образом. Не достаточно для этого быть сосланным в теле метода. На это нужно сослаться в любом import оператор или в объявлении. Вот примеры как класс java.io.File может быть сослан: Важное заключение - это, когда Вы используете -link опция, может быть много ссылок, которые неумышленно не появляются из-за этого ограничения. (Текст появился бы без гипертекстовой ссылки.) Можно обнаружить их предупреждениями, которые они испускают. Самый безвредный способ должным образом сослаться на класс и таким образом добавить ссылку состоял бы в том, чтобы импортировать тот класс, как показано выше.

Список пакета - -link опция требует что названный файл package-list, который сгенерирован инструментом Javadoc, существуйте в URL, с которым Вы определяете -link. package-list файл является простым текстовым файлом, который перечисляет имена пакетов, задокументированных в том расположении. В более раннем примере инструмент Javadoc ищет названный файл package-list в данном URL, чтениях на имена пакета и затем соединяется с теми пакетами в том URL.

Например, список пакета для Java SE 6 API располагается в http://download.oracle.com/javase/7/docs/api/package-list. и запускается следующим образом: 
  java.applet  
  java.awt
  java.awt.color
  java.awt.datatransfer
  java.awt.dnd
  java.awt.event
  java.awt.font
  etc.
Когда javadoc выполняется без -link опция, когда это встречается с именем, которое принадлежит внешнему классу, на который ссылаются, он печатает имя без ссылки. Однако, когда -link опция используется, инструмент Javadoc ищет package-list файл в указанном extdocURL расположении для того имени пакета. Если это находит имя пакета, это префиксы имя с extdocURL.

Для там, чтобы быть никакими неработающими ссылками, вся документация для внешних ссылок должна существовать в указанных URL. Инструмент Javadoc не будет проверять, что эти страницы существуют - только, что список пакета существует.

Многократные Ссылки - можно предоставить многократный -link опции, чтобы соединиться с любым числом внешних сгенерированных документов. У Javadoc 1.2 есть известная ошибка, которая препятствует тому, чтобы Вы предоставили больше чем один -link команда. Это было фиксировано в 1.2.2.

Определите различную опцию ссылки для каждого внешнего документа, чтобы соединиться с:

  % javadoc -link extdocURL1 -link extdocURL2 ... -link extdocURLn com.mypackage

где extdocURL1, extdocURL2 ... extdocURLn указывают соответственно на корни внешних документов, каждый из которых содержит названный файл package-list.

Перекрестные ссылки - Примечание, что "начальная загрузка" может требоваться, перекрестный соединяя два или больше документа, которые не были ранее сгенерированы. Другими словами, если package-list не существует ни для одного документа, когда Вы выполняете инструмент Javadoc на первом документе, package-list еще не будет существовать для второго документа. Поэтому, чтобы создать внешние ссылки, следует регенерировать первый документ после генерирования второго документа.

В этом случае цель первого генерирования документа состоит в том, чтобы создать package-list (или можно создать это вручную это, если Вы уверены в именах пакета). Затем генерируйте второй документ с его внешними ссылками. Инструмент Javadoc печатает предупреждение если необходимое внешнее package-list файл не существует.
-linkoffline extdocURL packagelistLoc
Эта опция является изменением -link; они оба создают ссылки к javadoc-сгенерированной документации для внешних классов, на которые ссылаются. Используйте -linkoffline опция, соединяясь с документом о сети, когда инструмент самого Javadoc является "офлайновым" - то есть, он не может получить доступ к документу посредством веб-подключения.

Более определенно использовать -linkoffline если внешний документ package-list файл не доступен или не существует в extdocURL расположении, но действительно существует в различном расположении, которое может быть определено packageListLoc (обычно локальный). Таким образом, если extdocURL доступен только во всемирной паутине, -linkoffline удаляет ограничение, что у инструмента Javadoc есть веб-подключение, генерируя документацию.

Другое использование как "взлом", чтобы обновить документы: После того, как Вы выполнили javadoc на полном комплекте пакетов, тогда можно выполнить javadoc снова на onlya меньшем наборе измененных пакетов, так, чтобы обновленные файлы могли быть вставлены назад в исходный набор. Примеры даются ниже.

-linkoffline опция берет два параметра - первое для строки, которая будет встроена в <a href> ссылки, второе сообщение этого, где найти package-list: Можно определить многократный -linkoffline опции в данном javadoc работают. (До 1.2.2, это могло быть определено только однажды.)

Пример используя абсолютные ссылки к внешним документам - Позволял нам говорить, что Вы хотите соединиться с java.lang, java.io и другой Java пакеты Платформы SE в http://download.oracle.com/javase/7/docs/api/, но у Вашей оболочки нет веб-доступа. Вы могли открыться package-list файл в браузере в http://download.oracle.com/javase/7/docs/api/package-list, сохраните это к локальному каталогу, и укажите на эту локальную копию со вторым параметром, packagelistLoc. В этом примере файл списка пакета был сохранен к текущему каталогу".". Следующая команда генерирует документацию для пакета com.mypackage со ссылками к Java пакеты Платформы SE. Сгенерированная документация будет содержать ссылки к Object класс, например, в деревьях класса. (Другие необходимые опции, такой как -sourcepath, не показываются.) 
% javadoc -linkoffline http://download.oracle.com/javase/7/docs/api/ . com.mypackage
Пример используя родственника соединяется с внешними документами - не очень распространено использовать -linkoffline с относительными путями, по простой причине это -link обычно достаточен. При использовании -linkoffline, package-list файл обычно локален, и при использовании относительных ссылок, файл, с которым Вы соединяетесь, также обычно локален. Таким образом, является обычно ненужным дать различный путь для этих двух параметров -linkoffline. Когда эти два параметра идентичны, можно использовать -link. См. -link относительный пример.

Вручную Создание a package-list Файл - Если a package-list файл еще не существует, но Вы знаете то, с чем именами пакета соединится Ваш документ, можно создать свою собственную копию этого файла вручную и определить его путь с packagelistLoc. Примером был бы предыдущий случай где список пакета для com.spipackage не существовал когда com.apipackage был сначала сгенерирован. Этот метод полезен, когда Вы должны генерировать документацию, которая соединяется с новой внешней документацией, имена пакета которой Вы знаете, но который еще не публикуется. Это - также способ создать package-list файлы для пакетов, сгенерированных с Javadoc 1.0 или 1.1, где package-list файлы не были сгенерированы. Аналогично, две компании могут совместно использовать свое неопубликованное package-list файлы, позволяя им выпустить их перекрестную соединенную документацию одновременно.

Соединяясь с Многократными Документами - можно включать -linkoffline однажды для каждого сгенерированного документа Вы хотите обратиться к (каждый вариант показывается на отдельной строке для ясности):

% javadoc -linkoffline extdocURL1 packagelistLoc1 \
          -linkoffline extdocURL2 packagelistLoc2 \
          ...

Обновление документов - Другое использование для -linkoffline опция полезна, если у Вашего проекта есть десятки или сотни пакетов, если Вы уже выполнили javadoc на всем дереве, и теперь, в отдельном выполнении, Вы хотите быстро сделать некоторые небольшие изменения и запустить повторно javadoc на только небольшой части исходного дерева. Это - своего рода взлом, в котором это работает должным образом, только если Ваши изменения только к комментариям документа а не к объявлениям. Если Вы должны были добавить, удалить или изменить какие-либо объявления из исходного кода, то неработающие ссылки могли обнаружиться в индексе, дереве пакета, наследованных списках элементов, используйте страницу, и другие места.

Во-первых, Вы создаете новый целевой каталог (вызовите его update) для этого нового маленького выполнения. Давайте скажем, что исходный целевой каталог назвали html. В самом простом примере, cd к родителю html. Установите первый параметр -linkoffline к текущему каталогу "." и набору второй параметр относительному пути к html, где это может найти package-list, и передача на только имена пакета пакетов Вы хотите обновить: 
  % javadoc -d update -linkoffline . html com.mypackage
Когда инструмент Javadoc делается, скопируйте эти сгенерированные страницы класса в update/com/package (не краткий обзор или индекс), по исходным файлам в html/com/package.
-linksource 
Создает версию HTML каждого исходного файла (с номерами строки) и добавляет ссылки им из стандартной документации HTML. Ссылки создаются для классов, интерфейсов, конструкторов, методов и полей, объявления которых находятся в исходном файле. Иначе, ссылки не создаются, такой что касается конструкторов по умолчанию и сгенерированных классов.

Эта опция представляет все частные детали реализации во включенных исходных файлах, включая частные классы, частные поля, и тела закрытых методов, независимо от -public, -package, -protected и -private опции. Если Вы также не используете -private опция, не все частные классы или интерфейсы обязательно будут доступны через ссылки.

Каждая ссылка появляется на имени идентификатора в его объявлении. Например, ссылка к исходному коду Button класс был бы на слове "Button": 
    public class Button
    extends Component
    implements Accessible
и ссылка к исходному коду getLabel() метод в классе Кнопки был бы на слове "getLabel": 
    public String getLabel()
- группа groupheading packagepattern:packagepattern:...
Разделяет пакеты на странице краткого обзора в любые группы, которые Вы определяете, одна группа на таблицу. Вы определяете каждую группу с различным -group опция. Группы появляются на странице в порядке, определенном на командной строке; пакеты располагаются в алфавитном порядке в пределах группы. Для данного -group опция, пакеты, соответствующие список выражений packagepattern, появляется в таблице с возглавляющим groupheading. ОТМЕТЬТЕ: используя звездочку в образце или списке образца, список образца должен быть внутренними кавычками, такой как "java.lang*:java.util"

Если Вы не предоставляете никого -group опция, все пакеты помещаются в одну группу с возглавляющими "Пакетами". Если все группы не включают все задокументированные пакеты, любые оставшиеся пакеты появляются в разделять группе с заголовком "Других Пакетов".

Например, следующая опция разделяет четыре задокументированных пакета на ядро, расширение и другие пакеты. Заметьте, что запаздывающая "точка" не появляется в "java.lang *" - включая точку, такой, поскольку "java.lang. *" опустил бы java.lang пакет. 
  % javadoc -group "Core Packages" "java.lang*:java.util"
            -group "Extension Packages" "javax.*"
            java.lang java.lang.reflect java.util javax.servlet java.new
Это приводит к группировкам:
Базовые Пакеты
java.lang
java.lang.reflect
java.util
Пакеты расширения
javax.servlet
Другие Пакеты
java.new
-nodeprecated
Предотвращает генерацию любого осуждаемого API вообще в документации. Это делает то, что делает-nodeprecatedlist, плюс это не генерирует осуждаемого API всюду по остальной части документации. Это полезно при записи кода, и Вы не хотите быть отвлеченными осуждаемым кодом.
-nodeprecatedlist
Предотвращает генерацию файла, содержащего список осуждаемых API (deprecated-list.html) и ссылки в панели навигации к той странице. (Однако, javadoc продолжает генерировать осуждаемый API всюду по остальной части документа.) Это полезно, если Ваш исходный код не содержит осуждаемого API, и Вы хотите сделать уборщика панели навигации.
-nosince
Опускает из сгенерированных документов "Начиная с" разделов, связанных с тегами @since.
-notree
Опускает страницы иерархии класса/интерфейса из сгенерированных документов. Они - страницы, Вы достигаете использования кнопки "Tree" в панели навигации. Иерархия производится по умолчанию.
-noindex
Опускает индекс из сгенерированных документов. Индекс производится по умолчанию.
-nohelp
Опускает ссылку СПРАВКИ в панелях навигации вверху и внизу каждой страницы вывода.
-nonavbar
Предотвращает генерацию панели навигации, заголовка и нижнего колонтитула, иначе найденного вверху и внизу сгенерированных страниц. Имеет не влияют на "нижней" опции. -nonavbar опция полезна, когда Вы интересуетесь только контентом и не имеете никакой потребности в навигации, такой как преобразование файлов к PostScript или PDF для печати только.
 Путь/имя файла-helpfile
Определяет путь альтернативного пути/имени файла справочного файла, с которым соединяется ссылка СПРАВКИ в вершине и нижних панелях навигации. Без этой опции инструмент Javadoc автоматически создает справочный файл help-doc.html это трудно кодируется в инструменте Javadoc. Эта опция позволяет Вам переопределить это значение по умолчанию. Имя файла может быть любым именем и не ограничивается help-doc.html - инструмент Javadoc скорректирует ссылки в панели навигации соответственно. Например: 
  % javadoc -helpfile /home/user/myhelp.html java.awt
 Путь/имя файла-stylesheetfile
Определяет путь альтернативного файла таблицы стилей HTML. Без этой опции инструмент Javadoc автоматически создает файл таблицы стилей stylesheet.css это трудно кодируется в инструменте Javadoc. Эта опция позволяет Вам переопределить это значение по умолчанию. Имя файла может быть любым именем и не ограничивается stylesheet.css. Например: 
  % javadoc -stylesheetfile /home/user/mystylesheet.css com.mypackage
-serialwarn
Генерирует предупреждения времени компиляции для того, чтобы пропустить теги @serial. По умолчанию Javadoc 1.2.2 (и более поздние версии) не генерирует последовательных предупреждений. (Это - реверсирование от более ранних версий.) Используют эту опцию, чтобы вывести на экран последовательные предупреждения, который помогает должным образом задокументировать сериализуемые поля по умолчанию и writeExternal методы.
- имя набора символов
Определяет набор символов HTML для этого документа. Имя должно быть привилегированным именем MIME как дано в Реестре IANA. Например: 
  % javadoc -charset "iso-8859-1" mypackage
вставил бы следующую строку в главу каждой сгенерированной страницы: 
   <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
Этот тег МЕТЫ описывается в стандарте HTML. (4197265 и 4137321)

Также см. - кодирование и-docencoding.
 Имя-docencoding
Определяет кодирование сгенерированных файлов HTML. Имя должно быть привилегированным именем MIME как дано в Реестре IANA. Если Вы опускаете эту опцию, но использование - кодирование, то кодирование сгенерированных файлов HTML определяется - кодирование. Пример: 
  % javadoc -docencoding "ISO-8859-1" mypackage
Также см. - кодирование и - набор символов.
- ключевые слова
Добавляет HTML meta теги ключевого слова к сгенерированному файлу для каждого класса. Эти теги могут помочь странице быть найденными поисковыми системами, которые ищут теги meta. (Большинство поисковых систем, которые ищут весь Интернет, не смотрит на теги meta, потому что страницы могут неправильно использовать их; но поисковые системы, предлагаемые компаниями, которые ограничивают их поиск их собственным сайтом, могут извлечь выгоду, смотря meta теги.)

Теги meta включают полностью определенное имя класса и неполные имена полей и методов. Конструкторы не включаются, потому что они идентичны имени класса. Например, Строка класса запускается с этих ключевых слов: 
     <META NAME="keywords" CONTENT="java.lang.String class">
     <META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
     <META NAME="keywords" CONTENT="length()">
     <META NAME="keywords" CONTENT="charAt()">
- тег  tagname:Xaoptcmf:"taghead"
Позволяет инструменту Javadoc интерпретировать простую, пользовательскую метку блока с одним параметром @tagname в комментариях документа. Таким образом, инструмент Javadoc может "проверить орфографию" имен тега, важно включать a -tag опция для каждого пользовательского тега, который присутствует в исходном коде, отключая (с X) те, которые не выводятся в выполненном токе.

Двоеточие (:) всегда разделитель. Чтобы использовать двоеточие в tagname, см. Использование Двоеточия на Имя тега.

-tag опция выводит заголовок тега taghead полужирным, последовал следующая строка текстом от его единственного параметра, как показано в примере ниже. Как любая метка блока, текст этого параметра может содержать встроенные теги, которые также интерпретируются. Вывод подобен стандартным тегам с одним параметром, такой как @return и @author. Исключение taghead заставляет tagname появляться как заголовок.

Размещение тегов - Xaoptcmf часть параметра определяет, где в исходном коде тегу позволяют быть помещенным, и может ли тег быть запрещен (использование X). Можно предоставить также a, позволить тег во всех местах, или любую комбинацию других букв:

X (отключите тег),
a (все)
o (краткий обзор)
p (пакеты)
t (типы, который является классами и интерфейсами),
c (конструкторы)
m (методы)
f (поля)


Примеры единственных тегов - пример опции тега для тега, который может использоваться где угодно в исходном коде: 
    -tag todo:a:"To Do:"
Если бы Вы хотели, чтобы использовался только с конструкторами, методами и полями, то Вы использовали бы: 
    -tag todo:cmf:"To Do:"
Заметьте последнее двоеточие (:) выше не разделитель параметра, но часть возглавляющего текста (как показано ниже). Вы использовали бы любую опцию тега для исходного кода, который содержит тег @todo, такой как: 
     @todo The documentation for this method needs work.
Использование Двоеточия на Имя тега - двоеточие может использоваться на имя тега, если этого оставляют с наклонной чертой влево. Для этого комментария документа: 
    /**
     * @ejb:bean
     */
используйте эту опцию тега: 
    -tag ejb\\:bean:a:"EJB Bean:"
Имена тега проверки орфографии (Запрещающий теги) - Некоторые разработчики помещенные пользовательские теги в исходном коде, который они не всегда хотят вывести. В этих случаях важно перечислить все теги, которые присутствуют в исходном коде, включая тем Вы хотите вывести и отключение тех, Вы не хотите выводить. Присутствие X отключает тег, в то время как его отсутствие включает тегу. Это дает инструменту Javadoc достаточную информацию, чтобы знать, неизвестен ли тег, с которым это встречается, вероятно результаты опечатки или орфографической ошибки. Это печатает предупреждение в этих случаях.

Можно добавить X к значениям размещения уже представляют, так, чтобы, когда Вы хотите включить тегу, можно было просто удалить X. Например, если @todo является тегом, который Вы хотите подавить на выводе, Вы использовали бы: 
    -tag todo:Xcmf:"To Do:"
или, если Вы сохранили бы это простым: 
    -tag todo:X
Синтаксис -tag todo:X работы, даже если @todo определяется taglet.

Порядок тегов - порядок -tag (и -taglet) опции определяют порядок, теги выводятся. Можно смешать пользовательские теги со стандартными тегами, чтобы вкрапить их. Опции тега для стандартных тегов являются заполнителями только для того, чтобы определить порядок - они берут только имя стандартного тега. (Подзаголовки для стандартных тегов не могут быть изменены.) Это иллюстрируется в следующем примере.

Если -tag отсутствует, тогда позиция -taglet определяет его порядок. Если они оба существуют, то, какой бы ни кажется последним на командной строке, определяет ее порядок. (Это происходит, потому что теги и taglets обрабатываются в порядке, что они появляются на командной строке. Например, если -taglet и -tag у обоих есть имя "todo", тот, который кажется последним на командной строке, определит свой порядок.

Пример полного набора тегов - Этот пример вставляет, "Чтобы Сделать" после "Параметров" и перед "Бросками" в выводе. При использовании "X", это также определяет, что @example является тегом, с которым можно было бы встретиться в исходном коде, который не должен быть выведен во время этого выполнения. Заметьте, что, если Вы используете @argfile, можно поместить теги в отдельные строки в файле параметра как это (никакие необходимые символы продолжения строки): 
   -tag param
   -tag return
   -tag todo:a:"To Do:"
   -tag throws
   -tag see
   -tag example:X
Когда javadoc анализирует комментарии документа, любой тег, с которым встречаются, который не является ни стандартным тегом, ни передал в с -tag или -taglet считается неизвестным, и предупреждение бросается.

Стандартные теги первоначально сохранены внутренне в списке в их порядке по умолчанию. Всякий раз, когда -tag опции используются, те теги добавляются к этому списку - стандартные теги перемещаются от их позиции по умолчанию. Поэтому, если a -tag опция опускается для стандартного тега, это остается в его позиции по умолчанию.

Уход от Конфликтов - Если Вы хотите нарезать свое собственное пространство имен, можно использовать разделенное от точки соглашение о присвоении имен, подобное используемому для пакетов: com.mycompany.todo. Oracle будет продолжать создавать стандартные теги, имена которых не содержат точки. Любой тег, который Вы создаете, переопределит поведение тега тем же самым именем, определенным Oracle. Другими словами, если Вы создаете тег или taglet @todo, у этого всегда будет то же самое поведение, которое Вы определяете, даже если Oracle позже создает стандартный тег того же самого имени.

Аннотации по сравнению с Тегами Javadoc - Вообще, если разметка Вы хотите добавить, предназначаются, чтобы влиять или произвести документацию, это должен, вероятно, быть тег javadoc; иначе, это должна быть аннотация. См. Сравнение Теги Javadoc и Аннотации<

Можно также создать более сложные метки блока, или пользовательские встроенные теги с-taglet опцией.
  Класс-taglet
Определяет файл класса, который запускает taglet, используемый в генерировании документации для того тега. Используйте полностью определенное имя для класса. Этот taglet также определяет число текстовых параметров, что пользовательский тег имеет. taglet принимает те параметры, обрабатывает их, и генерирует вывод. Для обширной документации с примером taglets, см.: Taglets полезны для блока или встраивают теги. Они могут иметь любое число параметров и реализовать пользовательское поведение, такое как создание текста полужирные, форматирующие маркеры, выписывание текст к файлу, или запуск других процессов.

Taglets может только определить, где тег должен появиться и в какой форма. Все другие решения принимаются doclet. Таким образом, taglet не может сделать вещей тех, которые удаляют имя класса из списка включенных классов. Однако, это может выполнить побочные эффекты, такие как печать текста тега к файлу или инициированию другого процесса.

Используйте -tagletpath опция, чтобы определить путь к taglet. Вот пример, который вставляет, "Чтобы Сделать" taglet после "Параметров" и перед "Бросками" в сгенерированных страницах: 
    -taglet com.sun.tools.doclets.ToDoTaglet
    -tagletpath /home/taglets 
    -tag return
    -tag param
    -tag todo
    -tag throws
    -tag see
Альтернативно, можно использовать -taglet опция вместо -tag опция, но это может быть более трудно считать.
-tagletpath  tagletpathlist
Определяет пути поиска для того, чтобы найти taglet файлы класса (.class). tagletpathlist может содержать разнообразные пути, разделяя их двоеточием (:). Инструмент Javadoc будет искать во всех подкаталогах указанных путей.
-docfilessubdirs 
Включения, глубоко копируя"doc-files"каталоги. Другими словами подкаталоги и все содержание рекурсивно копируются в место назначения. Например, каталог doc-files/example/images и все его содержание было бы теперь скопировано. Есть также опция, чтобы исключить подкаталоги.
-excludedocfilessubdir  name1:name2...
Исключает любого"doc-files"подкаталоги с именами. Это предотвращает копирование SCCS и других подкаталогов управления исходным кодом.
-noqualifier  all |  packagename1:packagename2:...
Опускает квалифицировать имя пакета от перед именами классов в выводе. Параметр -noqualifier любой"all"(все спецификаторы пакета опускаются), или отдельный от двоеточия список пакетов, с подстановочными знаками, чтобы быть удаленным как спецификаторы. Имя пакета удаляется из мест, где класс или интерфейсные имена появляются.

Следующий пример опускает все спецификаторы пакета: 
    -noqualifier all
Следующий пример опускает "java.lang" и "java.io" спецификаторы пакета: 
    -noqualifier java.lang:java.io
Следующий пример опускает спецификаторы пакета, запускающиеся с "java", и "com.sun" подпакетов (но не "javax"): 
    -noqualifier java.*:com.sun.*
Где спецификатор пакета появился бы из-за вышеупомянутого поведения, имя может быть соответственно сокращено - видят, Как имя выводится на экран. Это правило состоит в действительности в том действительно ли -noqualifier используется.
-notimestamp 
Подавляет метку времени, которая скрывается в комментарии HTML в сгенерированном HTML около вершины каждой страницы. Полезный, когда Вы хотите выполнить javadoc на двух исходных основах и разности их, поскольку это препятствует тому, чтобы метки времени вызвали разность (который иначе был бы разностью на каждой странице). Метка времени включает javadoc номер версии, и в настоящий момент похожа на это: 
     <!-- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 -->
-nocomment 
Подавите все тело комментария, включая основное описание и все теги, генерируя только объявления. Это опция позволяет снова использовать исходные файлы, первоначально предназначенные в различной цели, произвести скелетную документацию HTML на ранних стадиях нового проекта.
-sourcetab tabLength
Определите число пробелов, которые каждая вкладка приводит в рабочее состояние в источнике.

ФАЙЛЫ ПАРАМЕТРА КОМАНДНОЙ СТРОКИ

Чтобы сократить или упростить javadoc командную строку, можно определить один или более файлов, которые непосредственно содержат параметры javadoc команда (кроме -J опции). Это позволяет Вам создать javadoc команды любой длины на любой операционной системе.

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

Имена файлов в пределах файла параметра относительно текущего каталога, не расположения файла параметра. Подстановочные знаки (*) не позволяются в этих списках (такой что касается определения *.java). Использование символа '@', чтобы рекурсивно интерпретировать файлы не поддерживается. -J опции не поддерживаются, потому что их передают к средству запуска, которое не поддерживает файлы параметра.

Выполняясь javadoc, передайте в пути и имени каждого файла параметра с '@' ведущий символ. Когда javadoc встречается с параметром, начинающимся с символьного `@', он разворачивает содержание того файла в список параметров.

Пример - Единственный Файл Аргумента

Вы могли использовать единственный файл параметра, названный"argfile"чтобы содержать все параметры Javadoc:

  % javadoc @argfile

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

Пример - Два Файла Аргумента

Можно создать два файла параметра - один для опций Javadoc и другого для имен пакета или исходных имен файлов: (Заметьте, что у следующих списков нет никаких символов продолжения строки.)

Создайте файл, названный"options"содержа:

     -d docs-filelist 
     -use 
     -splitindex
     -windowtitle 'Java SE 7 API Specification'
     -doctitle 'Java SE 7 API Specification'
     -header '<b>Java™ SE 7</b>'
     -bottom 'Copyright &copy; 1993-2011 Oracle and/or its affiliates. All rights reserved.'
     -group "Core Packages" "java.*"
     -overview /java/pubs/ws/1.7.0/src/share/classes/overview-core.html
     -sourcepath /java/pubs/ws/1.7.0/src/share/classes

Создайте файл, названный"packages"содержа:

     com.mypackage1
     com.mypackage2
     com.mypackage3

Вы тогда выполнили бы javadoc с:

  % javadoc @options @packages

Пример - Файлы Аргумента с Путями

У файлов параметра могут быть пути, но любые имена файлов в файлах относительно текущего рабочего каталога (нет path1 или path2):

  % javadoc @path1/options @path2/packages

Пример - Параметры Опции

Вот пример сохранения только параметра javadoc опции в файле параметра. Мы будем использовать -bottom опция, так как у этого может быть длинный параметр. Вы могли создать файл, названный"bottom"содержа его текстовый параметр:

<font size="-1">
      <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
      Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
      Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
      Other names may be trademarks of their respective owners.</font>

Затем выполните инструмент Javadoc с:

  % javadoc -bottom @bottom @packages

Или Вы могли включать -bottom опция в начале файла параметра, и затем только выполненный это как:

  % javadoc @bottom @packages

Выполнение

ВЫПОЛНЕНИЕ JAVADOC

Номера версий - номер версии javadoc может быть определен, используя javadoc - J-версия. Номер версии стандарта doclet появляется в его потоке вывода. Это может быть выключено с -quiet.

Общедоступный программируемый интерфейс - Чтобы вызвать инструмент Javadoc изнутри программ, записанных на языке Java. Этот интерфейс находится в com.sun.tools.javadoc.Main (и javadoc повторно используем). Для получения дополнительной информации см. Стандартный Doclet.

Выполняя Doclets - инструкции, данные ниже, для того, чтобы вызвать стандартный HTML doclet. Чтобы вызвать пользовательский doclet, используйте-doclet и-docletpath опции. Для полных, рабочих примеров выполнения определенного doclet см. MIF Doclet документация.

ПРОСТЫЕ ПРИМЕРЫ

Можно выполнить javadoc на всех пакетах или отдельных исходных файлах. У каждого имени пакета есть соответствующее имя каталога. В следующих примерах исходные файлы располагаются в /home/src/java/awt/*.java. Целевой каталог /home/html.

Документирование Одного или Более Пакетов

Задокументировать пакет, исходные файлы (*.java) поскольку тот пакет должен быть расположен в каталоге, имеющем то же самое имя как пакет. Если имя пакета составляется из нескольких идентификаторов (разделенный точками, такой как java.awt.color), каждый последующий идентификатор должен соответствовать более глубокому подкаталогу (такой как java/awt/color). Можно разделить исходные файлы для единственного пакета среди двух таких деревьев каталогов, расположенных в различных местах, пока -sourcepath точки им обоим - например src1/java/awt/color и src2/java/awt/color.

Можно выполнить javadoc любой, изменяя каталоги (с cd) или при использовании -sourcepath опция. Примеры ниже иллюстрируют обе альтернативы.

Результат: Все случаи генерируют отформатированную HTML документацию для общедоступных и защищенных классов и интерфейсов в пакетах java.awt и java.awt.event и сохраните файлы HTML в указанном целевом каталоге (/home/html). Поскольку два или больше пакета сгенерированы, у документа есть три фрейма HTML - для списка пакетов, списка классов, и основных страниц класса.

Документирование Одного или Более Классов

Второй способ выполнить инструмент Javadoc, передавая в одном или более исходных файлах (.java). Можно выполнить javadoc любой из следующих двух путей - изменяя каталоги (с cd) или полностью определяющим путь к .java файлы. Относительные пути относительно текущего каталога. -sourcepath опция игнорируется, передавая в исходных файлах. Можно использовать подстановочные знаки командной строки, такие как звездочка (*), чтобы определить группы классов.

Документирование И Пакеты и Классы

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

  % javadoc -d /home/html -sourcepath /home/src java.awt /home/src/java/applet/Applet.java

Этот пример генерирует отформатированную HTML документацию для пакета java.awt и класс Applet. (Инструмент Javadoc определяет имя пакета для Applet от объявления пакета, если таковые вообще имеются, в Applet.java исходный файл.)

ПРИМЕР РЕАЛЬНОГО МИРА

У инструмента Javadoc есть много полезных опций, некоторые из которых более обычно используются чем другие. Вот эффективно команда, которую мы используем, чтобы выполнить инструмент Javadoc на API платформы Java. Мы используем 180 МБ памяти, чтобы генерировать документацию на 1500 (приблизительно). общедоступные и защищенные классы в Java Платформа SE, Standard Edition, v1.2.

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

Пример Командной строки

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

% javadoc -sourcepath /java/jdk/src/share/classes \
    -overview /java/jdk/src/share/classes/overview.html \
    -d /java/jdk/build/api \
    -use \
    -splitIndex \
    -windowtitle 'Java Platform, Standard Edition 7 API Specification' \
    -doctitle 'Java Platform, Standard Edition 7 API Specification' \
    -header '<b>Java™ SE 7</b>' \
    -bottom '<font size="-1">
      <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
      Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
      Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
      Other names may be trademarks of their respective owners.</font>' \
    -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \
    -group "Extension Packages" "javax.*" \
    -J-Xmx180m \  
    @packages

где packages имя файла, содержащего пакеты, чтобы обработать, такой как java.applet java.lang. Ни одна из опций не должна содержать символы новой строки между одинарными кавычками. (Например, если Вы копируете и вставляете этот пример, удаляете символы новой строки из -bottom опция.) См. другие упомянутые ниже примечания.

Пример make-файла

Это - пример make-файла GNU. Для примера make-файла Windows см. создание make-файла для Windows.

javadoc -sourcepath $(SRCDIR)              \   /* Sets path for source files     */
        -overview $(SRCDIR)/overview.html  \   /* Sets file for overview text    */
        -d /java/jdk/build/api             \   /* Sets destination directory     */
        -use                               \   /* Adds "Use" files               */
        -splitIndex                        \   /* Splits index A-Z               */
        -windowtitle $(WINDOWTITLE)        \   /* Adds a window title            */
        -doctitle $(DOCTITLE)              \   /* Adds a doc title               */
        -header $(HEADER)                  \   /* Adds running header text       */
        -bottom $(BOTTOM)                  \   /* Adds text at bottom            */
        -group $(GROUPCORE)                \   /* 1st subhead on overview page   */
        -group $(GROUPEXT)                 \   /* 2nd subhead on overview page   */
        -J-Xmx180m                         \   /* Sets memory to 180MB           */
        java.lang java.lang.reflect        \   /* Sets packages to document      */
        java.util java.io java.net         \
        java.applet
        
WINDOWTITLE = 'Java™ SE 7 API Specification'
DOCTITLE = 'Java™ Platform Standard Edition 7 API Specification'
HEADER = '<b>Java™ SE 7</font>'
BOTTOM = '<font size="-1">
      <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
      Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
      Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
      Other names may be trademarks of their respective owners.</font>'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
GROUPEXT  = '"Extension Packages" "javax.*"'
SRCDIR = '/java/jdk/1.7.0/src/share/classes'

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

ПРИМЕЧАНИЯ

ПОИСК И УСТРАНЕНИЕ НЕИСПРАВНОСТЕЙ

Общий Поиск и устранение неисправностей

Ошибки и Предупреждения

Сообщения об ошибках и предупреждающие сообщения содержат имя файла и номер строки к строке объявления, а не к определенной строке в комментарии документа.

СРЕДА

CLASSPATH
Переменная окружения, которая обеспечивает путь который использование javadoc найти пользовательские файлы класса. Эта переменная окружения переопределяется -classpath опция. Разделите каталоги двоеточием, например:
.:/home/classes:/usr/local/java/classes

СМ. ТАКЖЕ

Oracle и/или его филиалы Авторское право © 1993, 2011, Oracle и/или его филиалы. Все права защищены.
Свяжитесь с Нами