@todo, and inline tags, such as
{@underline}. (See block and
inline tags.) The Taglet API consists of one interface and two
abstract classes:
Taglet
InterfaceBaseExecutableMemberTaglet classBaseInlineTaglet classTaglets are a 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.
BaseExecutableMemberTagletTagletTagletBaseInlineTagBaseExecutableMemberTaglet class extends
Taglet to provide the additional functionality to
support inline tags. It supports both standard inline tags, such as
{@link} and {@docroot}, and custom inline
tags you might write.
If you write an inline tag that needs access to the
HtmlStandardWriter or the Doc object, it
should extend BaseInlineTag. For example, the
{@value} inline tag needs the Doc object
to retrieve the constant value from the field. Most tags only need
the HtmlStandardWriter to report errors using the
doclet error reporting methods.
Here are the basic steps you need to follow to create and use your own taglet:
BaseExecutableMemberTaglet, your
program should import the following:
import com.sun.tools.doclets.Taglet; // Taglet API import com.sun.tools.doclets.standard.tags.BaseExecutableMemberTaglet; // For inline tags import com.sun.tools.doclets.standard.HtmlStandardWriter; // For error reporting 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.
public static void register(Map tagletMap)
Your class must also implement the requirements of the interface it
extends or class it implements. 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.
toString(Doc, HtmlStandardWriter)
lib\tools.jar file in the SDK. For the first example
below, assuming the SDK is installed at C:\Program
Files\j2sdk1.4.0.
javac -classpath "C:\Program Files\j2sdk1.4.0\lib\tools.jar" ToDoTaglet.java
-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 are examples of block and inline taglets.
The source code for an example of a block taglet
implementing @todo is included at:
The corresponding class file ToDoTaglet.class is
already compiled and saved in the same directory as this source
file.
To run the doclet, include the -tagletpath and
-taglet options. Assuming the
ToDoTaglet.class is located in
/home/user/taglet, and the @todo tag is
located in the Test.java file:
% javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet ./Test.javaIf the file
Test.java contains the following doc
comment:
/**
* @todo Fix this!
*/
then the ToDo taglet formats the HTML output as
follows:
| Fix this! |
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 source code for an example of a block taglet
implementing @todo is included at:
ToDoTaglet.class is
already compiled and saved in the same directory as this source
file.
To run the doclet, include the -tagletpath and
-taglet options. Assuming the
ToDoTaglet.class is located in
/home/user/taglet, and the @todo tag is
located in the Test.java file:
% javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet ./Test.javaIf the file
Test.java contains the following doc
comment:
/**
* @todo Fix this!
*/
then the ToDo taglet formats the HTML output as
follows:
| Fix this! |
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.
Unline 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.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.
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.
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.