Taglet Overview

Contents

Taglet API

Taglets are programs written in the Java™ programming
language that implement the Taglet API. Taglets can be written as
either block tags, such as @todo, or inline tags, such
as {@underline}. Block taglets do not currently
support inline tags in their text. (See block and
inline tags.) The Taglet API consists of one interface:

The com.sun.javadoc classes must be imported for the
Tag interface used in toString(Tag).

Your class must implement the requirements of the interface it
extends. The toString method is where all of the
custom work is implemented to modify, format or redirect the text
argument passed in to your custom tag.

public String toString(Tag tag)

In addition to the requirements of the interface you are
implementing, your program must implement the following static
method. Then enables the taglet to be loaded at runtime. See the
source code in the example below.

public static void register(Map tagletMap)

Compile your doclet. Use javac compiler version 1.4.0 (or
later) in the JDK. The required class files are in the
lib\tools.jar file in the JDK. For the first example
below, assuming the JDK is installed at C:\Program
Files\j2sdk1.4.1.

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:\taglets\com\sun\Taglet.class, then you should
set tagletpath to C:\taglets. This example calls
javadoc on package com.package1,
including ToDoTaglet tags:

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

The following examples are of block and inline taglets.

Example - A Block Taglet

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

Implementation Description

To make this a block 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()).

It is not possible to have an array of inline tags to process, like
it is with block 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.