Taglet Overview

Contents

• The Basics
• Example - A Standalone Taglet
• Example - An Inline Taglet
• Handling Errors and Warnings

The Basics

• Taglet API

Taglets are a variation on the -tag option. When you use the -tag option, it generates default HTML formatting that is similar to that generated for @return.

Taglets enable you to customize the text that is generated, as shown in the examples below.

Here are the basic steps you need to follow to create and use your own taglet:

1. Write the Java program that constitutes your taglet. Your program should import the following:

      import com.sun.tools.doclets.Taglet;    // Taglet API
      import com.sun.javadoc.*;               // Doclet API
      import java.util.Map;                   // Used in register(Map)
   

   The Tag interface used in toString(Tag) is part of the Doclet API.

2. Your program must implement the following method:

       public static void register(Map tagletMap)
   

3. Compile your doclet. You can use the javac compiler in the Java 2 SDK. The required class files are in the lib/tools.jar file in the SDK. (When you compile a taglet, the javac automatically loads tools.jar, so locating them with -classpath is not necessary.) For the first example below:

      javac ToDoTaglet.java
   

4. Run the javadoc tool using the -taglet and -tagletpath options. For example, if your taglet class file is defined to be in package com.sun and is stored in C:\bin\com\sun, then you should set tagletpath to C:\bin. This example calls javadoc on package com.package1, using ToDoTaglet:

         javadoc -taglet ToDoTaglet -tagletpath C:\bin com.package1
   

The following are examples of standalone and inline taglets.

Example - A Standalone Taglet

The source code for an example of a standalone taglet implementing @todo is included at:

• ToDoTaglet.java

The corresponding class file ToDoTaglet.class is already compiled and saved in the same directory as this source file.

This taglet formats the output for the @todo tag. A doc comment containing the following tag:

    /**
     * @todo Fix this!
     */

would be output in HTML as follows:

To Do:

Fix this!

Implementation

Let's look at the source code. To name the tag and define the header text, define two private fields:

    private String NAME = "todo";
    private String HEADER = "To Do:";

To make this a standalone tag rather than an inline tag, you set isInlineTag to return false:

    public boolean isInlineTag() {
        return false;
    }

There are other methods inField, inMethod, inType, inPackage and inOverview that you specify true or false to indicate in which doc comments in the source code this tag can be used.

The toString(Tag) method determines how the text is inserted into the output when a single {@todo} tag is encountered. This code creates a bold heading followed by a table with a yellow background that contains the text (specified by tag.text()).

    public String toString(Tag tag) {`
        return "<DT><B>" + HEADER + "</B><DD>"
               + "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">"
               + tag.text() 
               + "</td></tr></table></DD>\n";
    }

Similarly, the toString(Tag[]) method (which takes an array of tags) determines how the text is inserted into the output when multiple {@todo} tags are encountered.

Example - An Inline Taglet

Unline standalone tags, a custom inline tag can only be implemented using a taglet (rather than using the -tag option). This is because there is no default behavior for inline tags.

The source code for an example of an inline taglet implementing {@underline} is included at:

• UnderlineTaglet.java

The corresponding class file UnderlineTaglet.class is already compiled and saved in the same directory as this source file.

This taglet formats the output for the {@underline} tag. A doc comment containing the following tag:

    /**
     * Be sure to insert the value at the {@underline start} of the array.
     */

would be output in HTML as follows:

Be sure to insert the value at the start of the array.

Implementation

Let's look at how this source code differs from the previous example. Of course the tag name is different (and inline tags have no heading, so none is defined):

    private String NAME = "underline";

To define this as an inline tag rather than a standalone tag, you set isInlineTag to return true:

    public boolean isInlineTag() {
        return true;
    }

The methods inField, inMethod, inConstructor, inType, inPackage and inOverview apply only to standalone tags and must all be set to false for inline tags.

The toString(Tag) method determines how the text is inserted into the output when an {@underline} tag is encountered. This code creates surrounds the text with the HTML underline tags <ul> and </ul>.

    public String toString(Tag tag) {
        return "<u>" + tag.text() + "</u>";
    }

It is not possible to have an array of inline tags to process, like it is with standalone tags. Therefore, the toString(Tag[]) method (which takes an array of tags) is ignored for inline tags.

Handling Errors and Warnings

Errors - A taglet can report an error and stop the Javadoc tool by simply printing the error message and then calling System.exit().

Warnings - A taglet can report a warning using a MessageRetriever given to it by the Doclet instance. The MessageRetriever is obtained from the Configuration object. The Configuration object is obtained from the doclet. For example, if the Taglet is designed to be used with the Standard doclet, the Configuration can be retrieved using Standard.configuration(), a static method. As an example, this is how the SimpleTaglet prints warnings, which is the default taglet for the -tag option.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved. Please send comments to: javadoc-tool@sun.com