Spec-Zone .ru
спецификации, руководства, описания, API
|
@tag
)
-option
)
javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages
pkg1:pkg2:... ] [ @argfiles ]
Параметры могут быть в любом порядке. См. обработку Исходных файлов для деталей о том, как инструмент Javadoc определяет который".java
"файлы, чтобы обработать.
options
packagenames
java.lang java.lang.reflect java.awt
. Следует отдельно определить каждый пакет, который Вы хотите задокументировать. Подстановочные знаки не позволяются; используйте-subpackages для рекурсии. Использование инструмента Javadoc -sourcepath
искать эти имена пакета. См. Пример - Документирование Того или Большего количества Пакетовsourcefilenames
X-Buffer
), или другие запрещенные символы, чтобы препятствовать тому, чтобы они были задокументированы. Это полезно для тестовых файлов, и шаблон регистрирует путь, который предшествует, имя исходного файла определяет, где javadoc будет искать файл. (Инструмент Javadoc не использует -sourcepath
искать эти имена исходного файла.) Относительные пути относительно текущего каталога, таким образом передавая в Button.java
идентично ./Button.java
. Имя исходного файла с абсолютным путем и подстановочным знаком, например, /home/src/java/awt/Graphics*.java
. См. Пример - Документирование Того или Большего количества Классов. Можно также смешать packagenames и sourcefilenames, как в Пример - Документирующий И Пакеты и Классы-subpackages
pkg1:pkg2:...@argfiles
-J
опции не позволяются в этих файлах. Можно выполнить инструмент Javadoc на всех пакетах, отдельных исходных файлах, или обоих. Документируя все пакеты, можно или использовать -subpackages
для того, чтобы пересечь рекурсивно вниз из высокоуровневого каталога, или передачи в явном списке имен пакета. Документируя отдельные исходные файлы, Вы передаете в списке источника (.java
) имена файлов. Примеры даются в конце этого документа. То, как Javadoc обрабатывает исходные файлы, покрывается затем.
.java
"плюс другие файлы описывается под Исходными файлами. Если Вы выполняете инструмент Javadoc, явно передавая в отдельных исходных именах файлов, можно определить точно который".java
"файлы обрабатываются. Однако, это не то, как большинство разработчиков хочет работать, поскольку более просто передать на имена пакета. Инструмент Javadoc может быть выполнен три пути, явно не определяя исходные имена файлов. Вы можете (1) передача на имена пакета, (2) использование -subpackages
, и (3) подстановочные знаки использования с исходными именами файлов (*.java
). В этих случаях инструмент Javadoc обрабатывает".java
"файл, только если это выполняет все следующие требования: .java
"снабдите суффиксом, фактически юридическое имя class (см. Спецификацию языка Java для юридических символов),Обрабатывая ссылок - Во время выполнения, инструмент Javadoc автоматически добавляет ссылки перекрестной ссылки к пакету, class и именам элемента, которые документируются как часть того выполнения. Ссылки появляются в нескольких местах:
@see
теги{@link}
теги@throws
теги-link
и -linkoffline
опции. Другие детали обработки - инструмент Javadoc представляет один полный документ каждый раз, когда это выполняется; это не может сделать инкрементный, создает - то есть, это не может изменить или непосредственно бестелесные следствия предыдущих выполнений инструмента Javadoc. Однако, это может соединиться со следствиями других выполнений, как только упомянуто.
Как реализовано, инструмент Javadoc требует и полагается на компилятор java, чтобы сделать его задание. Инструмент Javadoc вызывает часть javac
скомпилировать объявления, игнорируя задействованную реализацию. Это создает богатое внутреннее представление классов, включая иерархию class, и отношения "использования", затем генерирует HTML от этого. Инструмент Javadoc также поднимает предоставленную пользователем документацию из комментариев для документации в исходном коде.
Фактически, инструмент Javadoc будет работать .java
исходные файлы, которые являются чистыми тупиковыми файлами без тел метода. Это означает, что можно записать комментарии для документации и выполнить инструмент Javadoc на ранних стадиях проекта, создавая API, прежде, чем записать реализацию.
Доверие компилятору гарантирует, что вывод HTML соответствует точно фактической реализации, которая может положиться на неявный, а не явный, исходный код. Например, конструкторы по умолчанию документов инструмента Javadoc (см. Спецификацию языка Java), которые присутствуют в .class
файлы, но не в исходном коде.
Во многих случаях инструмент Javadoc позволяет Вам генерировать документацию для исходных файлов, код которых является неполным или ошибочным. Это - преимущество, которое позволяет Вам генерировать документацию перед всей отладкой, и поиск и устранение неисправностей делается. Например, согласно Спецификации языка Java, class, который содержит абстрактный метод, должен самостоятельно быть объявлен кратким обзором. Инструмент Javadoc не проверяет на это, и продолжился бы без предупреждения, тогда как javac компилятор останавливается на этой ошибке. Инструмент Javadoc действительно делает некоторую примитивную проверку комментариев документа. Используйте DocCheck doclet, чтобы проверить комментарии документа более тщательно.
Когда инструмент Javadoc создает свою внутреннюю структуру для документации, он загружает все классы, на которые ссылаются. Из-за этого инструмент Javadoc должен быть в состоянии найти все классы, на которые ссылаются, ли классы начальной загрузки, расширения, или пользовательские классы. Для больше об этом, см., Как Классы Находятся. Вообще говоря, классы, которые Вы создаете, должны или быть загружены как расширение или в инструменте Javadoc путь class.
java.lang.String.equals(java.lang.Object)
, или частично квалифицированный, такой как equals(Object)
.
java.awt
пакет, тогда любой class в java.lang
, такой как Object
, внешний class, на который ссылаются. Внешние классы, на которые ссылаются, могут быть соединены с использованием -link
и -linkoffline
опции. Важное свойство внешнего class, на который ссылаются, - то, что его исходные комментарии обычно не доступны выполненному Javadoc. В этом случае эти комментарии не могут быть наследованы..java
), файлы комментария пакета, файлы комментария краткого обзора, и разное необработанные файлы. Этот раздел также покрывает тестовые файлы и шаблонные файлы, которые могут также быть в исходном дереве, но которые Вы хотите убедиться не к документу.
.java
файл. Для получения дополнительной информации об этих комментариях документа, см. Комментарии для документации.
Чтобы создать пакет комментируют файл, у Вас есть выбор двух файлов поместить Ваши комментарии:
package-info.java
- Может содержать объявление пакета, аннотации пакета, комментарии пакета и теги Javadoc. Этот файл обычно предпочитается package.html.package.html
- Может содержать только комментарии пакета и теги 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, как все другие комментарии, с одним исключением: комментарий для документации не должен включать разделители комментария /**
и */
или ведущие звездочки. При записи комментария следует сделать первое предложение сводкой о пакете, и не поместить title или любой другой текст между <body>
и первое предложение. Можно включать теги пакета; как с любым комментарием для документации, все метки блока должны появиться после основного описания. Если Вы добавляете a @see
тег в пакете комментирует файл, у него должно быть полностью определенное имя. Для получения дополнительной информации см. package.html
Обрабатывая пакета комментирует файл - Когда инструмент Javadoc будет работать, это будет автоматически искать файл комментария пакета; если найдено, инструмент Javadoc делает следующее:
package.html
, копии весь контент между <body>
и </body>
HTML-тэги. Можно включать a <head>
раздел, чтобы поместить a <title>
, оператор авторского права исходного файла, или другая информация, но ни один из них не появится в сгенерированной документации.)Чтобы создать краткий обзор комментируют файл, можно назвать файл чем-либо, что Вы хотите, обычно overview.html
и поместите это куда угодно, обычно на верхнем уровне исходного дерева. Например, если исходные файлы для java.applet
пакет содержится в C:\user\src\java\applet
каталог, Вы могли создать файл комментария краткого обзора в C:\user\src\overview.html
.
Заметьте, что у Вас могут быть многократные файлы комментария краткого обзора для того же самого набора исходных файлов, в случае, если Вы хотите выполнить javadoc многократно на различных наборах пакетов. Например, Вы могли выполнить javadoc однажды с - частный за внутреннюю документацию и снова без той опции для общедоступной документации. В этом случае Вы могли описать документацию как общедоступную или внутреннюю в первом предложении каждого файла комментария краткого обзора.
Контент файла комментария краткого обзора является одним большим комментарием для документации, записанным в HTML, как файл комментария пакета, описанный ранее. См. то описание для деталей. Чтобы повторить, при записи комментария, следует сделать первое предложение сводкой о приложении или наборе пакетов, и не поместить title или любой другой текст между <body>
и первое предложение. Можно включать теги краткого обзора; как с любым комментарием для документации, всеми тегами кроме встроенных тегов, такой как {@link}
, должен появиться после основного описания. Если Вы добавляете a @see
тег, у этого должно быть полностью определенное имя.
Когда Вы выполняете инструмент Javadoc, Вы определяете, что краткий обзор комментирует имя файла с - опция краткого обзора. Файл тогда обрабатывается подобный тому из файла комментария пакета.
<body>
и </body>
теги для того, чтобы обработать.Чтобы включать необработанные файлы, поместите их в вызванный каталог doc-files
который может быть подкаталогом любого каталога пакета, который содержит исходные файлы. У Вас может быть один такой подкаталог для каждого пакета. Вы могли бы включать изображения, пример кода, исходные файлы.class файлы, апплеты и файлы HTML. Например, если Вы хотите включать изображение кнопки button.gif
в java.awt.Button
Документация class, Вы помещаете тот файл в /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", является фактически юридическим именем class (см. информацию об Идентификаторах в Спецификации языка Java).
package-summary.html
). Файлы в последней группе содержат дефисы, чтобы предотвратить конфликты имени файла с теми в прежней группе. Основные Страницы Контента
.html
) для каждого class или интерфейса это документирует. package-summary.html
) для каждого пакета это документирует. Инструмент Javadoc будет включать любой текст HTML, обеспеченный в названный файл package.html
или package-info.java
в каталоге пакета исходного дерева. overview-summary.html
) для всего набора пакетов. Это - первая полоса сгенерированного документа. Инструмент Javadoc будет включать любой текст HTML, обеспеченный в файл, определенный с -overview
опция. Отметьте, что этот файл создается, только если Вы передаете в javadoc два или больше имени пакета. Для дальнейшего объяснения см. Фреймы HTML.)Страницы перекрестной ссылки
overview-tree.html
). Чтобы просмотреть это, щелкните "по Краткому обзору" в панели навигации, затем щелкните "по Дереву". package-tree.html
) Чтобы просмотреть это, пойдите в определенный пакет, class или страницу интерфейса; щелкните по "Tree", чтобы вывести на экран иерархию для того пакета. package-use.html
) и отдельный для каждого class и интерфейса (class-use/
имя класса.html
). Эта страница описывает то, что упаковывает, классы, методы, конструкторы и поля используют любую часть данного class, интерфейса или пакета. Учитывая class или интерфейс A, его страница "использования" включает подклассы A, поля, объявленные как A, методы, которые возвращают A, и методы и конструкторов с параметрами типа A. Можно получить доступ к этой странице первым движением к пакету, class или интерфейсу, затем щелкая по ссылке "Использования" в панели навигации. deprecated-list.html
) перечисление всех осуждаемых имен. (Осуждаемое имя не рекомендуется для использования, обычно из-за улучшений, и заменяющее имя обычно дается. Осуждаемые API могут быть удалены в будущих реализациях.) constant-values.html
) для значений статических полей. serialized-form.html
) для информации о сериализуемых и externalizable классах. У каждого такого class есть описание его полей сериализации и методов. Эта информация представляет интерес для переконструкторов, не разработчикам, использующим API. В то время как нет никакой ссылки в панели навигации, можно добраться до этой информации, идя к любому, сериализировал class, и щелчок "Сериализированная Форма" в "Видит также" раздел комментария class. Стандарт doclet автоматически генерирует сериализированную страницу формы: любой class (общедоступный или непубличный), который реализует Сериализуемый, включается, наряду с readObject
и writeObject
методы, поля, которые сериализируются, и комментарии документа от @serial
, @serialField
, и @serialData
теги. Общедоступные сериализуемые классы могут быть исключены, отмечая их (или их пакет) с @serial exclude
, и частные на пакет сериализуемые классы могут быть включены, отмечая их (или их пакет) с @serial include
. С 1.4, можно генерировать полную сериализированную форму для общедоступных и частных классов, работая javadoc, не определяя -private
опция.index-*.html
) из всего class, интерфейса, конструктора, имен полей и имен методов, в алфавитном порядке расположенных. Это интернационализируется для Unicode и может быть сгенерировано как единственный файл или как отдельный файл для каждого начального символа (такого как A-Z для английского языка).Файлы поддержки
help-doc.html
) это описывает панель навигации и вышеупомянутые страницы. Можно обеспечить свой собственный справочный файл, чтобы переопределить использование значения по умолчанию -helpfile
.*-frame.html
) содержа списки пакетов, классов и интерфейсов, используемых, когда фреймы HTML выводятся на экран. package-list
), используемый -link
и -linkoffline
опции. Это - текстовый файл, не HTML, и не достижимо через любые ссылки. stylesheet.css
) это управляет ограниченным количеством цвета, семейства шрифтов, размера шрифта, стиля шрифта и располагающий на сгенерированных страницах. Инструмент Javadoc генерирует или два или три фрейма HTML, как показано в числе ниже. Это создает минимальное необходимое число фреймов, опуская список пакетов, если есть только один пакет (или никакие пакеты). Таким образом, когда Вы передадите единственное имя пакета или исходные файлы (*.java) принадлежащий единственному пакету как параметры в javadoc команду, это создаст только один фрейм (C) в левом столбце - список классов. Когда Вы передаете в javadoc два или больше имени пакета, он создает третий фрейм (P) перечисляющий все пакеты, так же как страницу краткого обзора (Деталь). У этой страницы краткого обзора есть имя файла overview-summary.html
. Таким образом этот файл создается, только если Вы передаете на два или больше имени пакета. Можно обойти фреймы, не щелкая по "Никаким Фреймам" ссылка или входя в overview-summary.html.
Если Вы незнакомы с фреймами HTML, следует знать, что фреймы могут сфокусироваться для печати и прокрутки. Чтобы дать фокус фрейма, щелкните по этому. Затем на многих браузерах клавиши со стрелками и ключи страницы прокрутят тот фрейм, и команда меню печати напечатает его.
Загрузите один из следующих двух файлов как начальная страница в зависимости от того, хотите ли Вы фреймы HTML или нет:
index.html
(для фреймов)overview-summary.html
(ни для каких фреймов)Сгенерированный class и файлы интерфейса организуются в той же самой иерархии каталогов, что исходные файлы Java и файлы class организуются. Эта структура является одним каталогом на подпакет.
Например, документ сгенерирован для class java.applet.Applet
class был бы расположен в 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
Boolean
class: 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. */Размещение комментариев - Комментарии для документации распознаются только когда помещено сразу перед class интерфейс, конструктор, метод, или полевые объявления - видят пример class, пример метода, и полевой пример. Игнорируются комментарии для документации, помещенные в тело метода. Только один комментарий для документации на оператор объявления распознается инструментом Javadoc.
Частая ошибка состоит в том, чтобы поместить import
оператор между class комментирует и объявление class. Избегите этого, поскольку инструмент Javadoc проигнорирует комментарий class.
/** * 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 @
. Каждая метка блока связала текст, который включает любой текст после тега до, но не включая, или следующий тег, или конец комментария документа. Этот связанный текст может охватить многократные строки. Встроенный тег позволяется и интерпретируется где угодно, что текст позволяется. Следующий пример содержит метку блока @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" из-за наборов фрейма.)
Например, объекты для меньше (<
) и больше - чем (>
) символы должны быть записаны <
и >
. Аналогично, амперсанд (&
) должен быть записан &
. Полужирный 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
public int y
@return
, @param
или @throws
тег отсутствует в комментарии метода, инструмент Javadoc копирует соответствующее основное описание или комментарий тега от метода, который это переопределяет или реализации (если любой) согласно алгоритму ниже. Более определенно, когда a @param
тег для определенного параметра отсутствует, тогда комментарий для того параметра копируется с метода далее иерархия наследования. Когда a @throws
тег для определенного исключения отсутствует, @throws
тег копируется, только если то исключение объявляется.
Это поведение контрастирует с версией 1.3 и ранее, где присутствие любого основного описания или тега препятствовало бы тому, чтобы все комментарии были наследованы.
{@inheritDoc}
в методе основное описание или @return
, @param
или @throws
комментарий тега – соответствующий наследованный основной комментарий описания или тега копируется в то пятно.Исходный файл для наследованного метода должен только быть на пути, определенном-sourcepath для комментария документа, чтобы фактически быть доступным копии. Ни в class, ни в его пакете нельзя передать на командной строке. Это контрастирует с 1.3.x и более ранние выпуски, где class должен был быть задокументированный class
Наследуйтесь от классов и интерфейсов - Наследование комментариев происходит во всех трех возможных случаях наследования от классов и интерфейсов:
В первых двух случаях, для переопределений метода, инструмент Javadoc генерирует подзаголовок "Переопределения" в документации для метода переопределения со ссылкой к методу, который это переопределяет, наследован ли комментарий.
В третьем случае, когда метод в данном class реализует метод в интерфейсе, инструмент Javadoc генерирует подзаголовок, "Определенный" в документации для метода переопределения со ссылкой к методу, который это реализует. Это происходит, наследован ли комментарий.
Алгоритм для Наследования Комментариев Метода - Если метод не имеет комментария документа, или имеет {@inheritDoc} тег, инструмент Javadoc, ищет применимый комментарий, используя следующий алгоритм, который разрабатывается, чтобы найти самый определенный применимый комментарий документа, давая предпочтение интерфейсам по суперклассам:
@
) и являются чувствительными к регистру – они должны быть введены с прописными и строчными буквами как показано. Тег должен запуститься в начале строки (после того, как любые ведущие пробелы и дополнительная звездочка), или он обрабатывается как нормальный текст. Условно, теги с тем же самым именем группируются. Например, поместите все @see
теги вместе.
@tag
.{@tag}
.Текущие теги:
Тег | Представленный в 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@author
теги. Можно определить одно имя на @author
тег или многократные имена на тег. В прежнем случае инструмент Javadoc вставляет запятую (,
) и пространство между именами. В последнем случае весь текст просто копируется в сгенерированный документ без того, чтобы быть проанализированным. Поэтому, можно использовать многократные имена на строку, если Вы хотите локализованный разделитель имени кроме запятой. Для получения дополнительной информации см., Где Теги Могут Использоваться и
@deprecated
deprecated-textПервое предложение deprecated-text должно, по крайней мере, сказать пользователю, когда API осуждался и что использовать в качестве замены. Инструмент Javadoc копирует только первое предложение в сводный раздел, и индексировать. Последующие предложения могут также объяснить, почему это было осуждено. Следует включать a {@link}
тег (для Javadoc 1.2 или позже), который указывает на заменяющий API:
Для получения дополнительной информации см.
{@link}
тег. Это создает встроенную ссылку, где Вы хотите ее. Например: /** * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */
@see
тег (который не может быть встроен) для каждого @deprecated
тег.Для больше об осуждении, см. тег @deprecated.
{@code
text}
<code>{@literal}</code>
. Дисплеи text в code
шрифт, не интерпретируя текст как разметка HTML или вложенные теги javadoc. Это позволяет Вам использовать регулярные угловые скобки (<
и >
) вместо объектов HTML (<
и >
) в комментариях документа, такой как в типах параметра (<Object>
), неравенства (3 < 4
), или стрелки (<-
). Например, текст комментария документа:
{@code A<B>C}
дисплеи в сгенерированной неизменной странице HTML, как:
A<B>C
Примечательная точка то, что <B>
не интерпретируется как полужирный и находится в шрифте кода. Если Вы хотите ту же самую функциональность без шрифта кода, использовать {@literal}
.
{@docRoot}
Это {@docRoot}
тег может использоваться и на командной строке и в комментарии документа: Этот тег допустим во всех комментариях документа: краткий обзор, пакет, class, интерфейс, конструктор, метод и поле, включая текстовую часть любого тега (такого как @return, @param и @deprecated).
javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'ОТМЕТЬТЕ - При использовании
{@docRoot}
этот путь в make-файле, некоторые программы make-файла требуют специального выхода для фигурной скобки {} символы. Например, Inprise ДЕЛАЮТ версию 5.2, работающую на Windows, требует двойных фигурных скобок: {{@docRoot}}
. Это также требует двойной (а не единственный) кавычки включать параметры опциям такой как -bottom
(с кавычками вокруг href
опущенный параметр)./** * 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}
Этот тег допустим только в этих местах в комментарии документа:
См. Автоматическое Копирование Комментариев Метода для более точного описания того, как комментарии находятся в иерархии наследования. Отметьте, что, если этот тег отсутствует, комментарий или автоматически не наследован согласно правилам, описанным в том разделе.
{@link
package.class#
member label}
Этот тег очень simliar к @see
– и потребуйте тех же самых ссылок и примите точно тот же самый синтаксис для package.class#
member и label. Основное различие - это {@link}
генерирует встроенную ссылку вместо того, чтобы поместить ссылку в, "См. Также" раздел. Кроме того, {@link}
тег начинается и заканчивается изогнутыми фигурными скобками, чтобы разделить это от остальной части встроенного текста. Если Вы должны использовать"}" в метке, используйте нотацию объекта HTML }
Нет никакого предела числу {@link}
теги позволяются в предложении. Можно использовать этот тег в основной части описания любого комментария для документации или в текстовой части любого тега (такого как @deprecated, @return или @param).
Например, вот комментарий, который относится к getComponentAt(int, int)
метод:
Use the {@link #getComponentAt(int, int) getComponentAt} method.От этого стандарт doclet генерировал бы следующий HTML (предполагающий, что это обращается к другому class в том же самом пакете):
Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.Который появляется на веб-странице как:
Use the getComponentAt method.Можно расшириться
{@link}
соединяться с классами, не задокументированными при использовании -link
опция. Для получения дополнительной информации см.
{@linkplain
package.class#
member label}
{@link}
, кроме метки ссылки выводится на экран в простом тексте чем шрифт кода. Полезный, когда метка является простым текстом. Пример: Refer to {@linkplain add() the overridden method}.Это вывело бы на экран как:
Refer to the overridden method.
{@literal
text}
<
и >
) вместо объектов HTML (<
и >
) в комментариях документа, такой как в типах параметра (<Object>
), неравенства (3 < 4
), или стрелки (<-
). Например, текст комментария документа:
{@literal A<B>C}
дисплеи, неизменные в сгенерированной странице HTML в Вашем браузере, как:
<B> C
<B>
не интерпретируется как полужирный (и это не находится в шрифте кода). Если Вы хотите ту же самую функциональность, но с текстом в шрифте кода, использовать {@code}
.
@param
parameter-name
descriptionparameter-name может быть именем параметра в методе или конструкторе, или именем параметра типа class, метода или конструктора. Используйте угловые скобки вокруг этого названия параметра, чтобы определить использование параметра типа.
Пример параметра типа class:
/** * @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) { }Для получения дополнительной информации см.
@return
descriptionДля получения дополнительной информации см.
@see
reference@see
теги, которые все группируются в соответствии с тем же самым заголовком. @see
у тега есть три изменения; третья форма ниже наиболее распространена. Этот тег допустим в любом комментарии документа: краткий обзор, пакет, class, интерфейс, конструктор, метод или поле. Для того, чтобы вставить встроенную ссылку в пределах предложения к пакету, class или элементу, см. {@link}
. @see
"
string""
) как первый символ. Например: @see "The Java Programming Language"Это генерирует текст, такой как:
See Also: "The Java Programming Language"
@see
<a href="
URL#value">
label</a>
<
) как первый символ. Например: @see <a href="spec.html#section">Java Spec</a>Это генерирует ссылку, такую как:
See Also: Java Spec
@see
package.class#
member labelТолько в версии 1.2, только имя, но не метка автоматически появилось бы в <коде>, HTML-тэги, Запускающиеся с 1.2.2, <код>, всегда включаются вокруг видимого текста, используется ли метка.
#
member является любым допустимым именем элемента программы, на которое ссылаются – пакет, class, интерфейс, конструктор, имя метода или имя поля – за исключением того, что символ перед именем элемента должен быть символом хеша (#
). class представляет любой верхний уровень или вкладывал class или интерфейс. member представляет любого конструктора, метод или поле (не вложенный class или интерфейс). Если это имя будет в задокументированных классах, то инструмент Javadoc автоматически создаст ссылку к нему. Чтобы создать ссылки к внешним классам, на которые ссылаются, используйте -link
опция. Используйте любой из других двух @see
формы для того, чтобы сослаться на документацию имени, которое не принадлежит class, на который ссылаются. Этот параметр описывается в большей длине ниже при Определении Имени.#
member и label. Пространство в круглых скобках не указывает на запуск метки, таким образом, пробелы могут использоваться между параметрами в методе.Пример - В этом примере, @see
тег (в Character
class), обращается к equals
метод в String
class. Тег включает оба параметра: имя"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>Который выглядит примерно так в браузере, где метка является видимым текстом ссылки:
See Also: equals
Определение имени - Этот package.class#
Имя member может быть или полностью определено, такой как java.lang.String#toUpperCase()
или нет, такой как String#toUpperCase()
или #toUpperCase()
. Если менее чем полностью определенный, инструмент Javadoc использует нормальный порядок поиска компилятора Java счесть это, далее описанным ниже в порядке Поиска на @see. Имя может содержать пробел в пределах круглых скобок, такой как между параметрами метода.
Конечно, преимущество обеспечения более коротких, "частично квалифицированных" имен состоит в том, что они короче, чтобы ввести и в исходном коде есть меньше помехи. Следующая таблица показывает различные формы имени, где Class может быть class или интерфейс, Type может быть class, интерфейс, массив, или примитивный, и method могут быть методом или конструктором.
Типичные формы для @see
package.class#member |
---|
Ссылка на элемент текущего class@see # field@see # method(Type, Type,...)@see # method(Type argname, Type argname,...)@see # constructor(Type, Type,...)@see # constructor(Type argname, Type argname,...)Ссылка на другой class в текущих или импортированных пакетах @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 |
Следующие примечания применяются к вышеупомянутой таблице:
getValue
, и если не будет никакого поля с тем же самым именем, то инструмент Javadoc правильно создаст ссылку к нему, но напечатает предупреждающее сообщение, напоминающее Вам добавить круглые скобки и параметры. Если этот метод будет перегружен, то инструмент Javadoc соединится с первым методом, с которым встречается его поиск, который является неуказанным..
inner, не просто inner, для всех форм.#
), а не точка (.
) разделяет элемент от его class. Это позволяет инструменту Javadoc разрешить неоднозначности, так как точка также разделяет классы, вложенные классы, пакеты, и подпакеты. Однако, инструмент Javadoc обычно снисходителен и должным образом проанализирует точку, если Вы знаете, что нет никакой неоднозначности, хотя он напечатает предупреждение. Порядок поиска на @see - инструмент Javadoc обработает a @see
тег, который появляется в исходном файле (.java), файл пакета (package.html или пакет-info.java) или файл краткого обзора (overview.html). В последних двух файлах следует полностью определить имя, которое Вы предоставляете @see
. В исходном файле можно определить имя, которое полностью определяется или частично квалифицируется.
Когда инструмент Javadoc встречается с a @see
тег в a .java
файл, который не полностью определяется, это ищет указанное имя в том же самом порядке, как компилятор Java был бы (кроме инструмента Javadoc, не будет обнаруживать определенные неоднозначности пространства имен, так как это предполагает, что исходный код свободен от этих ошибок). Этот порядок поиска формально определяется в Спецификации языка Java. Поиски инструмента Javadoc того имени через все связанные и импортированные классы и пакеты. В частности это ищет в этом порядке:
Инструмент Javadoc продолжает искать рекурсивно через шаги 1-3 для каждого class, с которым он встречается, пока он не находит соответствие. Таким образом, после того, как это перероет текущий class и его включение class E, это перероет суперклассы Э перед классами включения Э. В шагах 4 и 5 инструмент Javadoc не ищет классы или интерфейсы в пределах пакета в любом указанном порядке (что порядок зависит от определенного компилятора). В шаге 5, видах инструмента Javadoc в java.lang, так как это автоматически импортируется всеми программами.
Инструмент Javadoc не обязательно смотрит в подклассах, и при этом это не будет смотреть в других пакетах, даже если их документация будет сгенерирована в том же самом выполнении. Например, если @see
тег находится в java.awt.event.KeyEvent
class и обращается к имени в java.awt
пакет, javadoc не смотрит в том пакете если, что class импортирует это.
Как имя выводится на экран - Если label опускается, то пакет. class.member появляется. Вообще, это соответственно сокращается относительно текущего class и пакета. "Сокращенным" мы подразумеваем, что инструмент Javadoc выводит на экран только минимальное необходимое имя. Например, если String.toUpperCase()
метод содержит ссылки на элемент того же самого class и к элементу различного class, имя class выводится на экран только в последнем случае, как показано в следующей таблице.
Используйте-noqualifier, чтобы глобально удалить имена пакета.
Тип Ссылки | Пример в String.toUpperCase() |
Дисплеи Как |
---|---|---|
@see тег обращается к элементу того же самого class, того же самого пакета |
@see String#toLowerCase() |
toLowerCase() (опускает пакет и имена class), |
@see тег обращается к элементу различного class, того же самого пакета |
@see Character#toLowerCase(char) |
Character.toLowerCase(char) (опускает имя пакета, включает имя class), |
@see тег обращается к элементу различного class, различного пакета |
@see java.io.File#exists() |
java.io.File.exists() (включает пакет и имена class), |
Примеры @see
Комментарий к праву показывает, как имя было бы выведено на экран если @see
тег находится в class в другом пакете, такой как 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
опция. Для получения дополнительной информации см.
@serial
field-description
| include | exclude
Дополнительный field-description должен объяснить значение поля и перечислить приемлемые значения. Если нужно описание может охватить многократные строки. Стандарт doclet добавляет эту информацию к сериализированной странице формы.
Если бы сериализуемое поле было добавлено к class некоторое время после того, как class был сделан сериализуемым, то оператор должен быть добавлен к его основному описанию, чтобы идентифицировать, в которой версии это было добавлено.
include
и exclude
параметры идентифицируют, должны ли class или пакет быть включены или исключены из сериализированной страницы формы. Они работают следующим образом:
Serializable
не включается если, что class (или его пакет) отмечается @serial exclude
.Serializable
не исключается если, что class (или его пакет) отмечается @serial include
.Примеры: javax.swing
пакет отмечается @serial exclude
(в package.html
или package-info.java
). Общедоступный class java.security.BasicPermission
отмечается @serial exclude
. Частный на пакет class java.util.PropertyPermissionCollection
отмечается @serial include
.
Тег @serial на уровне class переопределяет @serial на уровне пакета.
Для получения дополнительной информации о том, как использовать эти теги, наряду с примером, см. "Документирующие Сериализуемые Поля и Данные для Класса," Раздел 1.6 из Спецификации Сериализации Объекта Java. Также см.
@serialField
field-name field-type field-descriptionObjectStreamField
компонент a Serializable
class serialPersistentFields
элемент. Один @serialField
тег должен использоваться для каждого ObjectStreamField
компонент.
@serialData
data-descriptionwriteObject
метод и все данные (включая базовые классы) записанный Externalizable.writeExternal
метод. @serialData
тег может использоваться в комментарии документа для writeObject
, readObject
, writeExternal
, readExternal
, writeReplace
, и readResolve
методы.
@since
since-text@since 1.5Для исходного кода в платформе Java этот тег указывает на версию спецификации API платформы Java (не обязательно, когда это было добавлено к ссылочной реализации). Многократные теги @since позволяются и обрабатываются как многократные теги @author. Вы могли использовать многократные теги, если prgram элемент используется больше чем одним API.
@throws
class-name description@throws
и @exception
теги являются синонимами. Добавляет подзаголовок "Бросков" к сгенерированной документации с текстом description и class-name. class-name является именем исключения, которое может быть выдано методом. Этот тег допустим только в комментарии документа для метода или конструктора. Если этот class не является полностью указанным, инструмент Javadoc использует порядок поиска искать этот class. Многократный @throws
теги могут использоваться в данном комментарии документа для тех же самых или различных исключений. Гарантировать, что все проверенные исключения документируются, если a @throws
тег не существует для исключения в пункте бросков, инструмент Javadoc автоматически добавляет, что исключение к выводу HTML (без описания), как будто это было задокументировано с тегом @throws.
@throws
документация копируется от переопределенного метода до подкласса только, когда исключение явно объявляется в переопределенном методе. То же самое является истиной для того, чтобы скопировать от метода интерфейса до метода реализации. Можно использовать {@inheritDoc}, чтобы вынудить @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
теги. Если это имеет смысл, можно определить один номер версии на @version
тег или многократные номера версий на тег. В прежнем случае инструмент Javadoc вставляет запятую (,
) и пространство между именами. В последнем случае весь текст просто копируется в сгенерированный документ без того, чтобы быть проанализированным. Поэтому, можно использовать многократные имена на строку, если Вы хотите локализованный разделитель имени кроме запятой.
Для получения дополнительной информации см.
@see
, @since
, @deprecated
, {@link}
, {@linkplain}
, и {@docroot}
.overview.html
). Как в любых других комментариях для документации, эти теги должны появиться после основного описания. ОТМЕТЬТЕ - {@link}
у тега есть ошибка в документах краткого обзора в версии 1.2 – текст появляется должным образом, но не имеет никакой ссылки. {@docRoot}
тег в настоящий момент не работает в документах краткого обзора.
Теги краткого обзора |
---|
@see |
@since |
@author |
@version |
{@link} |
{@linkplain} |
{@docRoot} |
package.html
или package-info.java
). @serial
тег может только использоваться здесь с include
или exclude
параметр. Теги пакета |
---|
@see |
@since |
@serial |
@author |
@version |
{@link} |
{@linkplain} |
{@docRoot} |
@serial
тег может только использоваться здесь с include
или exclude
параметр. Теги класса/Интерфейса |
---|
@see |
@since |
@deprecated |
@serial |
@author |
@version |
{@link} |
{@linkplain} |
{@docRoot} |
/** * A class representing a window on the screen. * For example: * <pre> * Window win = new Window(parent); * win.show(); * </pre> * * @author Sami Shaio * @version 1.15, 13 Dec 2006 * @see java.awt.BaseWindow * @see java.awt.Button */ class Window extends BaseWindow { ... }
Полевые Теги |
---|
@see |
@since |
@deprecated |
@serial |
@serialField |
{@link} |
{@linkplain} |
{@docRoot} |
{@value} |
/** * The X-coordinate of the component. * * @see #getLocation() */ int x = 1263732;
@return
, который не может появиться в конструкторе, и {@inheritDoc}
, у которого есть определенные ограничения. @serialData
тег может только использоваться в комментарии документа для определенных методов сериализации. Теги метода/Конструктора |
---|
@see |
@since |
@deprecated |
@param |
@return |
@throws и @exception |
@serialData |
{@link} |
{@linkplain} |
{@inheritDoc} |
{@docRoot} |
/** * 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) { ... }
Опции:
overview-summary.html
). Путь/имя файла относительно текущего каталога. В то время как можно использовать любое имя, Вы хотите для имени файла и помещаете его куда угодно, Вы хотите для пути, типичная вещь сделать состоит в том, чтобы назвать его overview.html
и поместите это в исходное дерево в каталоге, который содержит самые верхние каталоги пакета. В этом расположении никакой путь не необходим, документируя пакеты с тех пор -sourcepath
укажет на этот файл. Например, если исходное дерево для java.lang
пакет C:\src\classes\java\lang\
, тогда Вы могли поместить файл краткого обзора в C:\src\classes\overview.html
. См. Пример Реального мира.
Для получения информации о файле, определенном путем/именем файла, см. файл комментария краткого обзора.
Отметьте, что страница краткого обзора создается, только если Вы передаете в javadoc два или больше имени пакета. Для дальнейшего объяснения см. Фреймы HTML.)
title на странице краткого обзора устанавливается -doctitle
.
-doclet
опция не используется, javadoc использует стандарт doclet для того, чтобы генерировать формат HTML значения по умолчанию. Этот class должен содержать start(Root)
метод. Путь к этому запуску class определяется -docletpath
опция. Например, чтобы вызвать MIF doclet, используйте:
-doclet com.sun.tools.doclets.mif.MIFDoclet
Для полных, рабочих примеров выполнения определенного doclet см.
-doclet
опция), и любые файлы фляги это зависит от. Если запускающийся файл class находится в файле фляги, то это определяет путь к тому файлу фляги, как показано в примере ниже. Можно определить абсолютный путь или путь относительно текущего каталога. Если classpathlist содержит разнообразные пути или файлы фляги, они должны быть разделены двоеточием (:) на Солярисе и точке с запятой (;) на Windows. Эта опция не необходима, если doclet запускающийся class уже находится в пути поиска. Пример пути к файлу фляги, который содержит запуск doclet файл class. Заметьте, что имя файла фляги включается.
-docletpath C:\user\mifdoclet\lib\mifdoclet.jarПример пути к запуску doclet файл class. Заметьте, что имя файла class опускается.
-docletpath C:\user\mifdoclet\classes\com\sun\tools\doclets\mif\Для полных, рабочих примеров выполнения определенного doclet см.
Значение выпуска | Примечания |
---|---|
1.5 | javadoc принимает код, содержащий обобщения и другие функции языка, представленные в JDK 1.5. Значения по умолчанию компилятора к 1.5 поведениям, если - исходный флаг не используется. |
1.4 | javadoc принимает код, содержащий утверждения, которые были представлены в JDK 1.4. |
1.3 | javadoc не поддерживает утверждения, обобщения, или другие функции языка, представленные после JDK 1.3. |
Используйте значение выпуска, соответствующего используемому, компилируя код с javac.
.java
) передавая имена пакета или -subpackages
в javadoc
команда. sourcepathlist может содержать разнообразные пути, разделяя их точкой с запятой (;
). Инструмент Javadoc будет искать во всех подкаталогах указанных путей. Отметьте, что эта опция не только используется, чтобы определить местоположение исходных файлов, задокументированных, но также и найти исходные файлы, которые не документируются, но чьи комментарии наследованы задокументированными исходными файлами. Отметьте, что можно использовать -sourcepath
опция только, передавая пакет называет в javadoc команду – это не будет располагаться .java
файлы, которые передают в javadoc
команда. (Чтобы расположиться .java
файлы, cd к тому каталогу или включают путь перед каждым файлом, как показано при Документировании Того или Большего количества Классов.), Если -sourcepath
опускается, javadoc использует путь class, чтобы найти исходные файлы (см. - путь к классу). Поэтому, значение по умолчанию-sourcepath является значением пути class. Если - путь к классу опускается, и Вы передаете имена пакета в javadoc, это смотрит в текущем каталоге (и подкаталоги) для исходных файлов.
Установите sourcepathlist в корневой каталог исходного дерева для пакета, который Вы документируете. Например, предположите, что Вы хотите задокументировать вызванный пакет com.mypackage
чьи исходные файлы располагаются в:
C:\user\src\com\mypackage\*.javaВ этом случае Вы определили бы
sourcepath
к C:\user\src
, каталог, который содержит com\mypackage
, и затем предоставьте имя пакета com.mypackage
: C:> javadoc -sourcepath C:\user\src com.mypackageЭто легко помнить, замечая, что, если Вы связываете значение sourcepath и имени пакета вместе и изменяете точку на наклонную черту влево "\", Вы заканчиваете с полным путем к пакету:
C:\user\src\com\mypackage
. Указать на два исходных пути:
C:> javadoc -sourcepath C:\user1\src;C:\user2\src com.mypackage
.class
файлы) – они - задокументированные классы плюс любые классы, на которые ссылаются те классы. classpathlist может содержать разнообразные пути, разделяя их точкой с запятой (;
). Инструмент Javadoc будет искать во всех подкаталогах указанных путей. Следуйте инструкциям в документации пути class для того, чтобы определить classpathlist. Если -sourcepath
опускается, использование инструмента Javadoc -classpath
найти исходные файлы так же как файлы class (для обратной совместимости). Поэтому, если Вы хотите искать источник и файлы class в отдельных путях, используйте обоих -sourcepath
и -classpath
.
Например, если Вы хотите задокументировать com.mypackage
, чьи исходные файлы находятся в каталоге C:\user\src\com\mypackage
, и если этот пакет полагается на библиотеку в C:\user\lib
, Вы определили бы:
C:> javadoc -classpath \user\lib -sourcepath \user\src com.mypackageКак с другими инструментами, если Вы не определяете
-classpath
, инструмент Javadoc использует переменную окружения ПУТИ К КЛАССУ, если это устанавливается. Если оба не устанавливаются, инструмент Javadoc ищет классы из текущего каталога. Для всестороннего описания того, как инструмент Javadoc использует -classpath
чтобы найти пользовательские классы, поскольку это касается классов расширения и классов начальной загрузки, см., Как Классы Находятся.
Как специальное удобство, элемент пути class, содержащий базовое имя *
считается эквивалентным определению списка всех файлов в каталоге с расширением .jar
или .JAR
(программа java не может сказать различие между этими двумя вызовами).
Например, если каталог foo
содержит a.jar
и b.JAR
, тогда элемент пути class foo/*
расширяется до a A.jar:b.JAR
, за исключением того, что порядок файлов фляги является неуказанным. Все файлы фляги в указанном каталоге, даже скрытых, включаются в список. Запись пути к классу, состоящая просто из *
расширяется до списка всех файлов фляги в текущем каталоге. CLASSPATH
переменная окружения, где определено, будет так же расширена. Любое подстановочное расширение пути к классу происходит прежде, чем виртуальная машина Java запускается – никакая программа Java никогда не будет видеть нерасширенные подстановочные знаки кроме, запрашивая среду. Например; вызывая System.getenv("CLASSPATH").
java
) или полностью определенный пакет (такой как javax.swing
) это не должно содержать исходные файлы. Параметры разделяются двоеточиями (на всей работе systmes). Подстановочные знаки не необходимы или позволяются. Использовать -sourcepath
определить, где найти пакеты. Эта опция умна о не обработке исходных файлов, которые находятся в исходном дереве, но не принадлежат пакетам, как описано при обработке исходных файлов. Например:
C:> javadoc -d docs -sourcepath C:\user\src -subpackages java:javax.swingЭта команда генерирует документацию для пакетов, названных "java" и "javax.swing" и всеми их подпакетами.
Можно использовать -subpackages
в соединении с -exclude
исключить определенные пакеты.
-subpackages
. Это исключает те пакеты, даже если они были бы иначе включены некоторыми предыдущими или позже -subpackages
опция. Например: C:> javadoc -sourcepath C:\user\src -subpackages java -exclude java.net:java.langвключал бы
java.io
, java.util
, и java.math
(среди других), но исключил бы пакеты, базированные в java.net
и java.lang
. Заметьте, что это исключает java.lang.ref
, подпакет java.lang
).
-classpath
(выше) для большего количества деталей. Отдельные каталоги в dirlist с точками с запятой (;).
java.text.BreakIterator
определить конец первого предложения для английского языка (все другие локали уже используют BreakIterator
), а не английский язык, специфичный для локали алгоритм. Первым предложением мы имеем в виду первое предложение в основном описании пакета, class или элемента. Это предложение копируется в пакет, class или задействованная сводка, и в алфавитное индексируют. От JDK 1.2 прямой, BreakIterator class уже используется, чтобы определить конец предложения для всех языков, но английского языка. Поэтому, -breakiterator
опция не имеет никакого эффекта за исключением английского языка от 1.2 вперед. У английского языка есть свой собственный алгоритм значения по умолчанию:
<P>
.-locale
опция должна быть помещена вперед (налево) любых возможностей, предоставленных стандартом doclet или любым другим doclet. Иначе, панели навигации появятся на английском языке. Это - единственный параметр командной строки, который зависим от порядка. Определяет локаль, которую javadoc использует, генерируя документацию. Параметром является имя локали, как описано в java.util. Документация локали, такой как en_US
(Английский язык, Соединенные Штаты) или en_US_WIN
(Разновидность Windows).
Определение локали заставляет javadoc выбирать файлы ресурсов той локали для сообщений (строки в панели навигации, заголовках для списков и таблиц, содержания справочного файла, комментариев в stylesheet.css, и т.д). Это также определяет порядок сортировки для списков, сортированных в алфавитном порядке, и разделитель предложения, чтобы определить конец первого предложения. Это не определяет локаль текста комментария документа, определенного в исходных файлах задокументированных классов.
EUCJIS/SJIS
. Если эта опция не определяется, преобразователь значения по умолчанию платформы используется. Также см.-docencoding и - набор символов.
J
и флаг. Например, если Вы должны гарантировать, что система откладывает 32 мегабайта памяти, в которой можно обработать сгенерированную документацию, тогда Вы вызвали бы -Xmx
опция java следующим образом (-Xms
является дополнительным, поскольку это только устанавливает размер начальной памяти, которая полезна, если Вы знаете минимальное количество требуемой памяти): C:> javadoc -J-Xmx32m -J-Xms32m com.mypackageЧтобы сказать, какую версию javadoc Вы используете, вызовите"
-version
"опция java: C:> javadoc -J-version java version "1.2" Classic VM (build JDK-1.2-V, green threads, sunwjit)(Номер версии стандарта doclet появляется в его потоке вывода.)
Например, следующее генерирует документацию для пакета com.mypackage
и сохраняет результаты в C:\user\doc\
каталог:
C:> javadoc -d \user\doc com.mypackage
Например, давайте смотреть на то, что могло бы появиться на странице "Использования" для Строки. getName()
метод в java.awt.Font
class возвращает тип String
. Поэтому, getName()
использование String
, и Вы найдете что метод на странице "Использования" для String
.
Отметьте, что это документирует только использование API, не реализацию. Если метод использует String
в его реализации, но не берет строку в качестве параметра или возвращает строку, которую не считают "использованием" String
.
Можно получить доступ к сгенерированной странице "Использования" первым движением к class или пакету, затем щелкая по ссылке "Использования" в панели навигации.
-J-version
опция.
C:> javadoc -windowtitle "Java SE Platform" com.mypackage
C:> javadoc -doctitle "Java™" com.mypackage
-doctitle
. Эта опция переименовывается, чтобы прояснить, что она определяет документ title, а не окно title.
C:> javadoc -header "<b>Java 2 Platform </b><br>v1.4" com.mypackage
-linkoffline
). Инструмент Javadoc читает имена пакета из package-list
файл и затем соединяется с теми пакетами в том URL. Когда инструмент Javadoc выполняется, значение extdocURL копируется буквально в <A HREF>
ссылки, которые создаются. Поэтому, extdocURL должен быть URL к каталогу, не к файлу. Можно использовать абсолютную ссылку для extdocURL, чтобы позволить Вашим документам соединиться с документом о любом веб-сайте, или можно использовать относительную ссылку, чтобы соединиться только с относительным расположением. Если родственник, значение, в котором Вы передаете, должен быть относительным путем из целевого каталога (определенный с -d
) к каталогу, содержащему пакеты, соединяемые с.
Определяя абсолютную ссылку Вы обычно используете http:
ссылка. Однако, если Вы хотите соединиться с файловой системой, у которой нет никакого веб-сервера, можно использовать a file:
ссылка – однако, сделайте это, только если все желающие получить доступ к сгенерированной документации совместно используют ту же самую файловую систему.
Во всех случаях, и на всех операционных системах, следует использовать наклонную черту вправо в качестве разделителя, является ли URL абсолютным или относительным, и "http:" или "файл:" базируемый (как определено в
-link http://<host>/<directory>/<directory>/.../<name>
-link file://<host>/<directory>/<directory>/.../<name>
-link <directory>/<directory>/.../<name>
Можно определить многократный
-link
опции в данном javadoc, выполненном, чтобы соединиться с многократными документами.
-link
: -linkoffline
:
Пример используя абсолютные ссылки к внешним документам - Позволял нам говорить, что Вы хотите соединиться с java.lang
, java.io
и другой Java пакеты Платформы SE в http://docs.oracle.com/javase/7/docs/api/
com.mypackage
со ссылками к Java пакеты Платформы SE. Сгенерированная документация будет содержать ссылки к Object
class, например, в деревьях class. (Другие опции, такой как -sourcepath
и -d
, не показываются.)
C:> javadoc -link http://docs.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, работая: C:> 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 снова на другом наборе пакетов, создавая ссылки оба пути между обоими наборами.
Как на Класс Нужно Сослаться - Для ссылки к внешнему class, на который ссылаются, чтобы фактически появиться (и не только его текстовая метка), на class нужно сослаться следующим образом. Не достаточно для этого быть сосланным в теле метода. На это нужно сослаться в любом import
оператор или в объявлении. Вот примеры как class java.io.File
может быть сослан:
import
оператор: подстановочным импортом, импорт явно по имени, или автоматически импортируют для java.lang.*
. Например, это было бы достаточно:import java.io.*;
java.lang.*
.void foo(File f) {}
implements
, extends
или throws
оператор.Важное заключение - это, когда Вы используете -link
опция, может быть много ссылок, которые неумышленно не появляются из-за этого ограничения. (Текст появился бы без гипертекстовой ссылки.) Можно обнаружить их предупреждениями, которые они испускают. Самый безвредный способ должным образом сослаться на class и таким образом добавить ссылку состоял бы в том, чтобы импортировать тот class, как показано выше.
Список пакета - -link
опция требует что названный файл package-list
, который сгенерирован инструментом Javadoc, существуйте в URL, с которым Вы определяете -link
. package-list
файл является простым текстовым файлом, который перечисляет имена пакетов, задокументированных в том расположении. В более раннем примере инструмент Javadoc ищет названный файл package-list
в данном URL, чтениях на имена пакета и затем соединяется с теми пакетами в том URL.
Например, список пакета для Java API SE располагается в http://docs.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
опция, когда это встречается с именем, которое принадлежит внешнему class, на который ссылаются, он печатает имя без ссылки. Однако, когда -link
опция используется, инструмент Javadoc ищет package-list
файл в указанном extdocURL расположении для того имени пакета. Если это находит имя пакета, это префиксы имя с extdocURL.
Для там, чтобы быть никакими неработающими ссылками, вся документация для внешних ссылок должна существовать в указанных URL. Инструмент Javadoc не будет проверять, что эти страницы существуют – только, что список пакета существует.
Многократные Ссылки - можно предоставить многократный -link
опции, чтобы соединиться с любым числом внешних сгенерированных документов. У Javadoc 1.2 есть известная ошибка, которая препятствует тому, чтобы Вы предоставили больше чем один -link
команда. Это было фиксировано в 1.2.2.
Определите различную опцию ссылки для каждого внешнего документа, чтобы соединиться с:
C:> javadoc -link
extdocURL1 -link
extdocURL2
... -link
extdocURLn
com.mypackage
где extdocURL1, extdocURL2 ... extdocURLn указывают соответственно на корни внешних документов, каждый из которых содержит названный файл package-list
.
Перекрестные ссылки - Примечание, что "начальная загрузка" может требоваться, перекрестный соединяя два или больше документа, которые не были ранее сгенерированы. Другими словами, если package-list
не существует ни для одного документа, когда Вы выполняете инструмент Javadoc на первом документе, package-list
еще не будет существовать для второго документа. Поэтому, чтобы создать внешние ссылки, следует регенерировать первый документ после генерирования второго документа.
В этом случае цель первого генерирования документа состоит в том, чтобы создать package-list
(или можно создать это вручную это, если Вы уверены в именах пакета). Затем генерируйте второй документ с его внешними ссылками. Инструмент Javadoc печатает предупреждение если необходимое внешнее package-list
файл не существует.
-link
; они оба создают ссылки к javadoc-сгенерированной документации для внешних классов, на которые ссылаются. Используйте -linkoffline
опция, соединяясь с документом о сети, когда инструмент самого Javadoc является "офлайновым" – то есть, он не может получить доступ к документу посредством веб-подключения. Более определенно использовать -linkoffline
если внешний документ package-list
файл не доступен или не существует в extdocURL расположении, но действительно существует в различном расположении, которое может быть определено packageListLoc (обычно локальный). Таким образом, если extdocURL доступен только во всемирной паутине, -linkoffline
удаляет ограничение, что у инструмента Javadoc есть веб-подключение, генерируя документацию.
Другое использование как "взлом", чтобы обновить документы: После того, как Вы выполнили javadoc на полном комплекте пакетов, тогда можно выполнить javadoc снова на onlya меньшем наборе измененных пакетов, так, чтобы обновленные файлы могли быть вставлены назад в исходный набор. Примеры даются ниже.
-linkoffline
опция берет два параметра – первое для строки, которая будет встроена в <a href>
ссылки, второе сообщение этого, где найти package-list
:
-d
) к корню пакетов, соединяемых с. Для получения дополнительной информации см. extdocURL в -link
опция.package-list
файл для внешней документации. Это может быть URL (http: или файл:) или путь к файлу, и может быть абсолютным или относительным. Если родственник, сделайте это относительно текущего каталога от того, куда javadoc был выполнен. Не включайте package-list
имя файла.Можно определить многократный
-linkoffline
опции в данном javadoc работают. (До 1.2.2, это могло быть определено только однажды.)
Пример используя абсолютные ссылки к внешним документам - Позволял нам говорить, что Вы хотите соединиться с java.lang
, java.io
и другой Java пакеты Платформы SE в http://docs.oracle.com/javase/7/docs/api/
package-list
файл в браузере в http://docs.oracle.com/javase/7/docs/api/package-list
.
". Следующая команда генерирует документацию для пакета com.mypackage
со ссылками к Java пакеты Платформы SE. Сгенерированная документация будет содержать ссылки к Object
class, например, в деревьях class. (Другие необходимые опции, такой как -sourcepath
, не показываются.)
C:> javadoc -linkoffline http://docs.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
однажды для каждого сгенерированного документа Вы хотите обратиться к (каждый вариант показывается на отдельной строке для ясности):
C:> javadoc -linkoffline
extdocURL1 packagelistLoc1 \
extdocURL2 packagelistLoc2
-linkoffline\
...
Обновление документов - Другое использование для -linkoffline
опция полезна, если у Вашего проекта есть десятки или сотни пакетов, если Вы уже выполнили javadoc на всем дереве, и теперь, в отдельном выполнении, Вы хотите быстро сделать некоторые небольшие изменения и запустить повторно javadoc на только небольшой части исходного дерева. Это - своего рода взлом, в котором это работает должным образом, только если Ваши изменения только к комментариям документа а не к объявлениям. Если Вы должны были добавить, удалить или изменить какие-либо объявления от исходного кода, то неработающие ссылки могли обнаружиться в индексировании, дереве пакета, наследованных списках элементов, используйте страницу, и другие места.
Во-первых, Вы создаете новый целевой каталог (вызовите его update
) для этого нового маленького выполнения. Скажем, исходный целевой каталог назвали html
. В самом простом примере, cd к родителю html
. Установите первый параметр -linkoffline
к текущему каталогу "." и набору второй параметр относительному пути к html
, где это может найти package-list
, и передача на только имена пакета пакетов Вы хотите обновить:
C:> javadoc -d update -linkoffline . html com.mypackageКогда инструмент Javadoc делается, скопируйте, они генерировали страницы class в
update\com\package
(не краткий обзор или индексируют), по исходным файлам в html\com\package
.
Эта опция представляет все частные детали реализации во включенных исходных файлах, включая частные классы, частные поля, и тела закрытых методов, независимо от -public
, -package
, -protected
и -private
опции. Если Вы также не используете -private
опция, не все частные классы или интерфейсы обязательно будут доступны через ссылки.
Каждая ссылка появляется на имени идентификатора в его объявлении. Например, ссылка к исходному коду Button
class был бы на слове "Button":
public class Button extends Component implements Accessibleи ссылка к исходному коду
getLabel()
метод в Кнопке class был бы на слове "getLabel": public String getLabel()
:
packagepattern:
...-group
опция. Группы появляются на странице в порядке, определенном на командной строке; пакеты располагаются в алфавитном порядке в пределах группы. Для данного -group
опция, пакеты, соответствующие список выражений packagepattern, появляется в таблице с возглавляющим groupheading. *
). Звездочка является подстановочным знаком, означающим "соответствие любые символы". Это - единственный позволенный подстановочный знак. Многократные образцы могут быть включены в группу, разделяя их с двоеточиями (:
)."java.lang*:java.util"
Если Вы не предоставляете никого -group
опция, все пакеты помещаются в одну группу с возглавляющими "Пакетами". Если все группы не включают все задокументированные пакеты, любые оставшиеся пакеты появляются в разделять группе с заголовком "Других Пакетов".
Например, следующая опция разделяет четыре задокументированных пакета на ядро, расширение и другие пакеты. Заметьте, что запаздывающая "точка" не появляется в "java.lang *" – включая точку, такой, поскольку "java.lang. *" опустил бы java.lang пакет.
C:> 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
-nonavbar
опция полезна, когда Вы интересуетесь только контентом и не имеете никакой потребности в навигации, такой как преобразование файлов к PostScript или PDF для печати только.
help-doc.html
это трудно кодируется в инструменте Javadoc. Эта опция позволяет Вам переопределить это значение по умолчанию. Имя файла может быть любым именем и не ограничивается help-doc.html
– инструмент Javadoc скорректирует ссылки в панели навигации соответственно. Например: C:> javadoc -helpfile C:\user\myhelp.html java.awt
stylesheet.css
это трудно кодируется в инструменте Javadoc. Эта опция позволяет Вам переопределить это значение по умолчанию. Имя файла может быть любым именем и не ограничивается stylesheet.css
. Например: C:> javadoc -stylesheetfile C:\user\mystylesheet.css com.mypackage
writeExternal
методы.
C:> javadoc -charset "iso-8859-1" mypackageвставил бы следующую строку в главу каждой сгенерированной страницы:
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">Этот тег МЕТЫ описывается в
Также см. - кодирование и-docencoding.
% javadoc -docencoding "ISO-8859-1" mypackageТакже см. - кодирование и - набор символов.
Теги meta включают полностью определенное имя class и неполные имена полей и методов. Конструкторы не включаются, потому что они идентичны имени class. Например, Строка class запускается с этих ключевых слов:
<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()">
:Xaoptcmf:"
taghead"
@
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.Эта строка произвела бы, выводит что-то как:
To Do: 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
. Sun будет продолжать создавать стандартные теги, имена которых не содержат точки. Любой тег, который Вы создаете, переопределит поведение тега тем же самым именем, определенным Sun. Другими словами, если Вы создаете тег или taglet @todo
, у этого всегда будет то же самое поведение, которое Вы определяете, даже если Sun позже создает стандартный тег того же самого имени.
Аннотации по сравнению с Тегами Javadoc - Вообще, если разметка Вы хотите добавить, предназначаются, чтобы влиять или произвести документацию, это должен, вероятно, быть тег javadoc; иначе, это должна быть аннотация. См.
Можно также создать более сложные метки блока, или пользовательские встроенные теги с-taglet опцией.
Taglets полезны для блока или встраивают теги. Они могут иметь любое число параметров и реализовать пользовательское поведение, такое как создание текста полужирные, форматирующие маркеры, выписывание текст к файлу, или запуск других процессов.
Taglets может только определить, где тег должен появиться и в какой форма. Все другие решения принимаются doclet. Таким образом, taglet не может сделать вещей тех, которые удаляют имя class из списка включенных классов. Однако, это может выполнить побочные эффекты, такие как печать текста тега к файлу или инициированию другого процесса.
Используйте -tagletpath
опция, чтобы определить путь к taglet. Вот пример, который вставляет, "Чтобы Сделать" taglet после "Параметров" и перед "Бросками" в сгенерированных страницах:
-taglet com.sun.tools.doclets.ToDoTaglet -tagletpath /home/taglets -tag return -tag param -tag todo -tag throws -tag see
Альтернативно, можно использовать -taglet
опция вместо -tag
опция, но это может быть более трудно считать.
:
). Инструмент Javadoc будет искать во всех подкаталогах указанных путей.
doc-files
"каталоги. Другими словами подкаталоги и все содержание рекурсивно копируются в место назначения. Например, каталог doc-files/example/images
и все его содержание было бы теперь скопировано. Есть также опция, чтобы исключить подкаталоги.
doc-files
"подкаталоги с именами. Это предотвращает копирование SCCS и других подкаталогов управления исходным кодом.
all
| packagename1:packagename2:...-noqualifier
любой"all
"(все спецификаторы пакета опускаются), или отдельный от двоеточия список пакетов, с подстановочными знаками, чтобы быть удаленным как спецификаторы. Имя пакета удаляется из мест, где class или имена интерфейса появляются. Следующий пример опускает все спецификаторы пакета:
-noqualifier allСледующий пример опускает "java.lang" и "java.io" спецификаторы пакета:
-noqualifier java.lang:java.ioСледующий пример опускает спецификаторы пакета, запускающиеся с "java", и "com.sun" подпакетов (но не "javax"):
-noqualifier java.*:com.sun.*Где спецификатор пакета появился бы из-за вышеупомянутого поведения, имя может быть соответственно сокращено – видят, Как имя выводится на экран. Это правило состоит в действительности в том действительно ли
-noqualifier
используется.
<!-- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 -->
javadoc
команда (кроме -J
опции). Это позволяет Вам создать javadoc команды любой длины на любой операционной системе. Файл параметра может включать javadoc опции и исходные имена файлов в любой комбинации. Параметры в пределах файла могут быть разделены пробелом или разделены от новой строки. Если имя файла содержит встроенные пробелы, помещало целое имя файла в двойные кавычки, и удваивает каждую наклонную черту влево ("My Files\\Stuff.java"
).
Имена файлов в пределах файла параметра относительно текущего каталога, не расположения файла параметра. Подстановочные знаки (*) не позволяются в этих списках (такой что касается определения *.java
). Использование символа '@', чтобы рекурсивно интерпретировать файлы не поддерживается. -J
опции не поддерживаются, потому что их передают к средству запуска, которое не поддерживает файлы параметра.
Выполняясь javadoc, передайте в пути и имени каждого файла параметра с '@' ведущий символ. Когда javadoc встречается с параметром, начинающимся с символьного `@', он разворачивает содержание того файла в список параметров.
argfile
"чтобы содержать все параметры Javadoc: C:> javadoc @argfileЭтот файл параметра мог содержать содержание обоих файлов, показанных в следующем примере.
Создайте файл, названный"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 © 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 с:
C:> javadoc @options @packages
path1
или path2
): C:> 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 © 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 с:
C:> javadoc -bottom @bottom @packagesИли Вы могли включать
-bottom
опция в начале файла параметра, и затем только выполненный это как: C:> javadoc @bottom @packages
-quiet
. Общедоступный программируемый интерфейс - Чтобы вызвать инструмент Javadoc изнутри программ, записанных на языке Java. Этот интерфейс находится в com.sun.tools.javadoc.Main
(и javadoc повторно используем). Для получения дополнительной информации см. Стандартный Doclet.
Выполняя Doclets - инструкции, данные ниже, для того, чтобы вызвать стандартный HTML doclet. Чтобы вызвать пользовательский doclet, используйте-doclet и-docletpath опции. Для полных, рабочих примеров выполнения определенного doclet см.
C:\home\src\java\awt\*java
. Целевой каталог C:\home\html
.
*.java
) поскольку тот пакет должен быть расположен в каталоге, имеющем то же самое имя как пакет. Если имя пакета составляется из нескольких идентификаторов (разделенный точками, такой как java.awt.color
), каждый последующий идентификатор должен соответствовать более глубокому подкаталогу (такой как java/awt/color
). Можно разделить исходные файлы для единственного пакета среди двух таких деревьев каталогов, расположенных в различных местах, пока -sourcepath
точки им обоим – например src1\java\awt\color
и src2\java\awt\color
. Можно выполнить javadoc любой, изменяя каталоги (с cd
) или при использовании -sourcepath
опция. Примеры ниже иллюстрируют обе альтернативы.
java
каталог, исключая пакеты базировался в java.net
и java.lang
. Заметьте, что это исключает java.lang.ref
, подпакет java.lang
). % javadoc -d \home\html -sourcepath \home\src -subpackages java -exclude java.net:java.lang
Чтобы также пересечь вниз другие деревья пакета, добавьте их имена к -subpackages
параметр, такой как java:javax:org.xml.sax
.
C:> cd C:\home\src\ C:> javadoc -d C:\home\html java.awt java.awt.event
-sourcepath
с родительским каталогом высокоуровневого пакета, и именами предоставления одного или более пакетов Вы хотите задокументировать: C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event
-sourcepath
с путем к (разделенному от двоеточия) корню каждого дерева и имена предоставления одного или более пакетов Вы хотите задокументировать. Все исходные файлы для данного пакета не должны быть расположены под единственным корневым каталогом – они только должны быть найдены где-нибудь вдоль sourcepath. C:> javadoc -d C:\home\html -sourcepath C:\home\src1;C:\home\src2 java.awt java.awt.event
java.awt
и java.awt.event
и сохраните файлы HTML в указанном целевом каталоге (C:\home\html
). Поскольку два или больше пакета сгенерированы, у документа есть три фрейма HTML – для списка пакетов, списка классов, и основных страниц class.
.java
). Можно выполнить javadoc любой из следующих двух путей – изменяя каталоги (с cd
) или полностью определяющим путь к .java
файлы. Относительные пути относительно текущего каталога. -sourcepath
опция игнорируется, передавая в исходных файлах. Можно использовать подстановочные знаки командной строки, такие как звездочка (*), чтобы определить группы классов. .java
файлы. Затем выполненный javadoc, предоставляя имена одного или более исходных файлов Вы хотите задокументировать. C:> cd C:\home\src\java\awt C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.javaЭтот пример генерирует отформатированную HTML документацию для классов
Button
, Canvas
и начинающиеся классы Graphics
. Поскольку в исходных файлах, а не именах пакета передали как параметры javadoc, у документа есть два фрейма – для списка классов и основной страницы.C:> cd C:\home\src C:> javadoc -d \home\html java\awt\Button.java java\applet\Applet.javaЭтот пример генерирует отформатированную HTML документацию для классов
Button
и Applet
..java
файлы Вы хотите задокументировать. C:> javadoc -d C:\home\html C:\home\src\java\awt\Button.java C:\home\src\java\awt\Graphics*.javaЭтот пример генерирует отформатированную HTML документацию для class
Button
и начинающиеся классы Graphics
.-sourcepath
для пути к пакетам, но не для пути к отдельным классам. C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt C:\home\src\java\applet\Applet.javaЭтот пример генерирует отформатированную HTML документацию для пакета
java.awt
и class Applet
. (Инструмент Javadoc определяет имя пакета для Applet
от объявления пакета, если таковые вообще имеются, в Applet.java
исходный файл.)Тот же самый пример показывают дважды – сначала столь же выполняемый на командной строке, затем как выполняющийся от make-файла. Это использует абсолютные пути в параметрах опции, который включает тому же самому javadoc
команда, которая будет выполнена из любого каталога.
C:\> 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 © 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
опция.) См. другие упомянутые ниже примечания.
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™ Platform, Standard Edition 6 API Specification' DOCTITLE = 'Java™ Platform, Standard Edition 6 API Specification' HEADER = '<b>Java™ Platform, Standard Edition 6' BOTTOM = '<font size="-1"> <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/> Copyright © 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-файла.
ПРИМЕЧАНИЯ
-windowtitle
опция, инструмент Javadoc копирует документ title в окно title. -windowtitle
текст является в основном тем же самым как -doctitle
но без HTML-тэгов, чтобы препятствовать тому, чтобы те теги казались как необработанный текст в окне title.-footer
опция, как сделано здесь, инструмент Javadoc копирует текст заголовка в нижний колонтитул.classpath
и -link
."error: cannot read: Class1.java"
инструмент Javadoc пытается загрузить class Class1.java в текущем каталоге. Имя class показывают с его путем (абсолютный или относительный), который в этом случае является тем же самым как ./Class1.java
.CLASSPATH
-classpath
опция. Разделите каталоги точкой с запятой, например: