Интерфейс Taglet

public interface Taglet

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

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

Доклет создаёт экземпляр теглета с помощью конструктора класса теглета без аргументов.
Затем доклет вызывает метод init, передавая соответствующее окружение и доклет.
После этого доклет вызывает методы getName, getAllowedLocations и isInlineTag, чтобы определить характеристики тегов, поддерживаемых теглетом.
При необходимости доклет вызывает метод toString объекта теглета, передавая ему список тегов, элемент, комментарий документации которого содержит эти теги, и корневой URI сгенерированного вывода, по которому теглет может определить строку, включаемую в документацию. Доклет обычно указывает требования к содержимому возвращаемой строки.

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

Примечание к API:

Обычно теглет разрабатывается для совместной работы с конкретным доклетом.

С момента:

См. также:

Краткое описание вложенных классов

Модификатор и тип	Интерфейс	Описание
`static enum`	`Taglet.Location`	Тип расположения, в котором можно использовать тег.

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

Модификатор и тип	Метод	Описание
`Set<Taglet.Location>`	`getAllowedLocations()`	Возвращает набор расположений, поддерживаемых для блочных тегов.
`String`	`getName()`	Возвращает имя тега, поддерживаемого этим теглетом.
`default void`	`init(DocletEnvironment env, Doclet doclet)`	Инициализирует этот теглет с указанными окружением доклета и доклетом.
`default boolean`	`isBlockTag()`	Указывает, поддерживает ли этот теглет блочные теги.
`boolean`	`isInlineTag()`	Указывает, поддерживает ли этот теглет встроенные теги.
`String`	`toString(List<? extends DocTree> tags, Element element)`	Возвращает строковое представление указанных экземпляров этого тега для включения в сгенерированный вывод.
`default String`	`toString(List<? extends DocTree> tags, Element element, URI docRoot)`	Возвращает строковое представление указанных экземпляров этого тега для включения в сгенерированный вывод.

Подробное описание методов

getAllowedLocations

Set<Taglet.Location> getAllowedLocations()

Возвращает набор расположений, поддерживаемых для блочных тегов.

Возвращает:: набор расположений, поддерживаемых для блочных тегов

isInlineTag

boolean isInlineTag()

Указывает, поддерживает ли этот теглет встроенные теги.

Возвращает:: true, если этот теглет поддерживает встроенные теги

isBlockTag

default boolean isBlockTag()

Указывает, поддерживает ли этот теглет блочные теги.

Требования к реализации:: Эта реализация возвращает результат, обратный результату метода isInlineTag.
Возвращает:: true, если этот теглет поддерживает блочные теги
С момента:: 15

getName

String getName()

Возвращает имя тега, поддерживаемого этим теглетом.

Возвращает:: имя этого тега

init

default void init(DocletEnvironment env, Doclet doclet)

Инициализирует этот теглет с указанными окружением доклета и доклетом.

Примечание к API:: При необходимости окружение можно использовать для доступа к служебным классам elements и types.
Требования к реализации:: Эта реализация ничего не делает.
Параметры:: env — окружение, в котором выполняются доклет и теглет; doclet — доклет, создавший этот теглет

toString

String toString(List<? extends DocTree> tags, Element element)

Возвращает строковое представление указанных экземпляров этого тега для включения в сгенерированный вывод.

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

Примечание к API:

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

Параметры:

tags — список экземпляров этого тега

element — элемент, которому принадлежит содержащий его комментарий

Возвращает:

строковое представление тегов для включения в сгенерированный вывод

Выбрасывает:

UnsupportedOperationException — если вместо этого следует вызвать toString(List, Element, URI)

См. также:

toString

default String toString(List<? extends DocTree> tags, Element element, URI docRoot)

Аргумент docRoot задаёт корень сгенерированного вывода относительно текущего ресурса и может использоваться для разрешения ссылок на другие ресурсы, сгенерированные доклетом.

Примечание к API:

Точное представление docRoot зависит от доклета. Для стандартного доклета это относительный URI от текущего ресурса до корневого каталога сгенерированного вывода. Теглетам, предназначенным для использования с другими доклетами, следует при необходимости проверять допустимость аргумента docRoot.

Требования к реализации:

Реализация по умолчанию вызывает toString(tags, element).

Параметры:

tags — список экземпляров этого тега

element — элемент, которому принадлежит содержащий его комментарий

docRoot — корневой URI сгенерированного вывода

Возвращает:

строковое представление тегов для включения в сгенерированный вывод

Выбрасывает:

IllegalArgumentException — если docRoot не является допустимым URI

С момента:

См. также:

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.