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.

Nested and Inner Type Summary

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

Method Summary

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

Method Detail

getAllowedLocations	back to summary
public Set<Taglet.Location> getAllowedLocations() Returns the set of supported locations for block tags. Returns:Set<Taglet.Location> the set of supported locations for block tags

getAllowedLocations

back to summary

public Set<Taglet.Location> getAllowedLocations()

Returns the set of supported locations for block tags.

Returns:Set<Taglet.Location>: the set of supported locations for block tags

getName	back to summary
public String getName() Returns the name of the tag supported by this taglet. Returns:String the name of this tag

getName

back to summary

public String getName()

Returns the name of the tag supported by this taglet.

Returns:String: the name of this tag

init back to summary

init	back to summary
public 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 Specification This implementation does nothing. Parameters env:DocletEnvironment the environment in which the doclet and taglet are running doclet:Doclet the doclet that instantiated this taglet

public 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 Specification

This implementation does nothing.

Parameters

env:DocletEnvironment: the environment in which the doclet and taglet are running
doclet:Doclet: the doclet that instantiated this taglet

isBlockTag back to summary

isBlockTag	back to summary
public default boolean isBlockTag() Indicates whether this taglet supports block tags. Implementation Specification This implementation returns the inverse result to `isInlineTag`. Returns:boolean true if this taglet supports block tags Since 15

public default boolean isBlockTag()

Indicates whether this taglet supports block tags.

Implementation Specification

This implementation returns the inverse result to isInlineTag.

Returns:boolean: true if this taglet supports block tags
Since: 15

isInlineTag	back to summary
public boolean isInlineTag() Indicates whether this taglet supports inline tags. Returns:boolean true if this taglet supports inline tags

isInlineTag

back to summary

public boolean isInlineTag()

Indicates whether this taglet supports inline tags.

Returns:boolean: true if this taglet supports inline tags

toString back to summary

toString	back to summary
public 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:List<? extends DocTree> the list of instances of this tag element:Element the element to which the enclosing comment belongs Returns:String the string representation of the tags to be included in the generated output Exceptions UnsupportedOperationException: if `toString(List, Element, URI)` should be invoked instead See Also User-Defined Taglets for the Standard Doclet, `toString(List, Element, URI)`

public 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:List<? extends DocTree>: the list of instances of this tag
element:Element: the element to which the enclosing comment belongs

Returns:String

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

Exceptions

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

toString back to summary

toString	back to summary
public 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. 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. 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 Specification The default implementation invokes `toString(tags, element)`. Parameters tags:List<? extends DocTree> the list of instances of this tag element:Element the element to which the enclosing comment belongs docRoot:URI the root URI of the generated output Returns:String the string representation of the tags to be included in the generated output Exceptions IllegalArgumentException: if `docRoot` is not a valid URI Since 27 See Also User-Defined Taglets for the Standard Doclet, `toString(List, Element)`

public 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 Specification

The default implementation invokes toString(tags, element).

Parameters

tags:List<? extends DocTree>: the list of instances of this tag
element:Element: the element to which the enclosing comment belongs
docRoot:URI: the root URI of the generated output

Returns:String

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

Exceptions

IllegalArgumentException:: if docRoot is not a valid URI

Since

jdk.javadoc.doclet back to summary

public final Enum Taglet.Location

Class Inheritance

extends Enum<Taglet.Location>

java.lang.Object
java.lang.Enum
jdk.javadoc.doclet.Taglet.Location

The kind of location in which a tag may be used.

Field Summary

Modifier and Type	Field and Description
public static final Taglet.Location	CONSTRUCTOR In the documentation for a constructor.
public static final Taglet.Location	FIELD In the documentation for a field.
public static final Taglet.Location	METHOD In the documentation for a method.
public static final Taglet.Location	MODULE In the documentation for a module.
public static final Taglet.Location	OVERVIEW In an Overview document.
public static final Taglet.Location	PACKAGE In the documentation for a package.
public static final Taglet.Location	TYPE In the documentation for a type, such as a class, interface or enum.

Constructor Summary

Access	Constructor and Description
private	Location()

Method Summary

Modifier and Type	Method and Description
public static Taglet.Location	valueOf(String name)
public static Taglet.Location[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

CONSTRUCTOR	back to summary
public static final Taglet.Location CONSTRUCTOR In the documentation for a constructor.

FIELD	back to summary
public static final Taglet.Location FIELD In the documentation for a field.

METHOD	back to summary
public static final Taglet.Location METHOD In the documentation for a method.

MODULE	back to summary
public static final Taglet.Location MODULE In the documentation for a module.

OVERVIEW	back to summary
public static final Taglet.Location OVERVIEW In an Overview document.

PACKAGE	back to summary
public static final Taglet.Location PACKAGE In the documentation for a package.

TYPE	back to summary
public static final Taglet.Location TYPE In the documentation for a type, such as a class, interface or enum.

Constructor Detail

Location	back to summary
private Location()

Method Detail

valueOf	back to summary
public static Taglet.Location valueOf(String name)

values	back to summary
public static Taglet.Location[] values()

public Interface Taglet

Nested and Inner Type Summary

Method Summary

Method Detail

public final Enum Taglet.Location

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail