Taglet Overview





Documentation Contents



Taglet Overview



 








Contents

Taglet API
Writing a Taglet
Example - A Block Taglet
Example - An Inline Taglet
Handling Errors and Warnings



Taglet API

Taglets are programs written in the JavaTM
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:


Taglet interface


A taglet can modify and format the text argument of a custom tag,
and do other things, such as redirect the text to a file or other stream.
A taglet can override a standard tag.


Taglets are the foundation beneath the
-tag
option. When you use the -tag option, it uses
a built-in taglet to generate default HTML formatting that
is similar to that generated for @return.




Writing a Taglet



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

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

javac -classpath "C:\Program Files\j2sdk1.4.1\lib\tools.jar" ToDoTaglet.java



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:

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!
*/


then the ToDo taglet formats the HTML output as follows:



To Do:
Fix this!





Implementation Description

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


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


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()).


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.

The register method

/**
* Register this Taglet.
* @param tagletMap the map to register this tag to.
*/
public static void register(Map tagletMap) {
ToDoTaglet tag = new ToDoTaglet();
Taglet t = (Taglet) tagletMap.get(tag.getName());
if (t != null) {
tagletMap.remove(tag.getName());
}
tagletMap.put(tag.getName(), tag);
}







Example - An Inline Taglet



Unlike block 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 Description


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 block tag,
you set isInlineTag to return true:


public boolean isInlineTag() {
return true;
}



The methods inField, inMethod,
inConstructor, inType,
inPackage and inOverview
apply only to block 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 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.













Copyright © 1995-2010 Sun Microsystems, Inc. All Rights Reserved. Please send comments using this Feedback page.

Java Technology