Module jdk.javadoc
Package jdk.javadoc.doclet

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 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:

  1. The doclet will create an instance of a taglet using the no-arg constructor of the taglet class.
  2. Next, the doclet calls the init method with an appropriate environment and doclet.
  3. Afterwards, the doclet calls getName, getAllowedLocations, and isInlineTag, to determine the characteristics of the tags supported by the taglet.
  4. As appropriate, the doclet calls the toString method on the taglet object, giving it a list of tags and the element for which the tags are part of the element's documentation comment, 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:
9
See Also:
User-Defined Taglets for the Standard Doclet

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Interface Description
    static class  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 locations in which a tag may be used.
    String getName()
    Returns the name of the tag.
    default void init​(DocletEnvironment env, Doclet doclet)
    Initializes this taglet with the given doclet environment and doclet.
    boolean isInlineTag()
    Indicates whether this taglet is for inline tags or not.
    String toString​(List<? extends DocTree> tags, Element element)
    Returns the string representation of a series of instances of this tag to be included in the generated output.

  • Method Details

    • getAllowedLocations

      Set<Taglet.Location> getAllowedLocations()
      Returns the set of locations in which a tag may be used.
      Returns:
      the set of locations in which a tag may be used

    • isInlineTag

      boolean isInlineTag()
      Indicates whether this taglet is for inline tags or not.
      Returns:
      true if this taglet is for an inline tag, and false otherwise

    • getName

      String getName()
      Returns the name of the tag.
      Returns:
      the name of this custom 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 a series of instances of this tag to be included in the generated output.

      If this taglet is for an inline tag it will be called once per instance of the tag, each time with a singleton list. Otherwise, if this tag is a block tag, it will be called once per comment, with a list of all the instances of the tag in a comment.

      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
      See Also:
      User-Defined Taglets for the Standard Doclet