Interface Taglet

public interface Taglet

The interface for a custom taglet supported by doclets such as the standard doclet. Custom taglets are used to handle custom tags in documentation comments; custom tags can be instantiated individually as either block tags, which appear at the end of a comment, or inline tags, which can appear within the main body of a documentation comment.

Each implementation of a taglet must provide a public no-argument constructor to be used by doclets to instantiate the taglet. A doclet will interact with classes implementing this interface as follows:

The doclet will create an instance of a taglet using the no-arg constructor of the taglet class.
Next, the doclet calls the init method with an appropriate environment and doclet.
Afterwards, the doclet calls getName, getAllowedLocations, and isInlineTag, to determine the characteristics of the tags supported by the taglet.
As appropriate, the doclet calls the toString method on the taglet object, giving it a list of tags, the element whose documentation comment contains the tags, and the root URI of the generated output, from which the taglet can determine the string to be included in the documentation. The doclet will typically specify any requirements on the contents of the string that is returned.

If a taglet object is created and used without the above protocol being followed, then the taglet's behavior is not defined by this interface specification.

API Note:

It is typical for a taglet to be designed to work in conjunction with a specific doclet.

Since:

See Also:

Nested Class Summary

Modifier and Type	Interface	Description
`static enum`	`Taglet.Location`	The kind of location in which a tag may be used.

Method Summary

Modifier and Type	Method	Description
`Set<Taglet.Location>`	`getAllowedLocations()`	Returns the set of supported locations for block tags.
`String`	`getName()`	Returns the name of the tag supported by this taglet.
`default void`	`init(DocletEnvironment env, Doclet doclet)`	Initializes this taglet with the given doclet environment and doclet.
`default boolean`	`isBlockTag()`	Indicates whether this taglet supports block tags.
`boolean`	`isInlineTag()`	Indicates whether this taglet supports inline tags.
`String`	`toString(List<? extends DocTree> tags, Element element)`	Returns the string representation of the specified instances of this tag to be included in the generated output.
`default String`	`toString(List<? extends DocTree> tags, Element element, URI docRoot)`	Returns the string representation of the specified instances of this tag to be included in the generated output.

Method Details

getAllowedLocations

Set<Taglet.Location> getAllowedLocations()

Returns the set of supported locations for block tags.

Returns:: the set of supported locations for block tags

isInlineTag

boolean isInlineTag()

Indicates whether this taglet supports inline tags.

Returns:: true if this taglet supports inline tags

isBlockTag

default boolean isBlockTag()

Indicates whether this taglet supports block tags.

Implementation Requirements:: This implementation returns the inverse result to isInlineTag.
Returns:: true if this taglet supports block tags
Since:: 15

getName

String getName()

Returns the name of the tag supported by this taglet.

Returns:: the name of this tag

init

default void init(DocletEnvironment env, Doclet doclet)

Initializes this taglet with the given doclet environment and doclet.

API Note:: The environment may be used to access utility classes for elements and types if needed.
Implementation Requirements:: This implementation does nothing.
Parameters:: env - the environment in which the doclet and taglet are running; doclet - the doclet that instantiated this taglet

toString

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

Returns the string representation of the specified instances of this tag to be included in the generated output.

If this taglet supports inline tags, this method will be called once per instance of the inline tag, each time with a singleton list. If this taglet supports block tags, it will be called once for each comment containing instances of block tags, with a list of all the instances of the block tag in that comment.

API Note:

Taglets that do not need the root URI of the generated output may implement this method only. Taglets that require the root URI to link to other doclet-generated resources should override toString(List, Element, URI), and optionally throw an exception in the implementation of this method.

Parameters:

tags - the list of instances of this tag

element - the element to which the enclosing comment belongs

Returns:

the string representation of the tags to be included in the generated output

Throws:

UnsupportedOperationException - if toString(List, Element, URI) should be invoked instead

See Also:

toString

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

Returns the string representation of the specified instances of this tag to be included in the generated output.

The docRoot argument identifies the root of the generated output as seen by the current resource, and may be used to resolve links to other resources generated by the doclet.

API Note:

The exact form of docRoot is doclet-specific. For the standard doclet, it is a relative URI from the current resource to the root directory of the generated output. Taglets intended for use with other doclets should check the validity of the docRoot argument as appropriate.

Implementation Requirements:

The default implementation invokes toString(tags, element).

Parameters:

tags - the list of instances of this tag

element - the element to which the enclosing comment belongs

docRoot - the root URI of the generated output

Returns:

the string representation of the tags to be included in the generated output

Throws:

IllegalArgumentException - if docRoot is not a valid URI

Since:

See Also:

© 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.