|
Taglet Overview |
@todo, and
inline tags, such as {@underline}. (See
block
and inline tags.) The Taglet API consists of one interface
and two abstract classes:
Taglet Interface
BaseExecutableMemberTaglet class
BaseInlineTaglet class
Taglets 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.
BaseExecutableMemberTaglet
Taglet
Taglet
BaseInlineTag
BaseExecutableMemberTaglet 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 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.
YET TO UPDATE BELOW HERE !!!!!!!!!!!!!!
The source code for an example of a block taglet implementing@todois included at: The corresponding class fileToDoTaglet.classis already compiled and saved in the same directory as this source file.To run the doclet, include the
-tagletpathand-tagletoptions. Assuming theToDoTaglet.classis located in/home/user/taglet, and the@todotag is located in theTest.javafile:% javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet ./Test.javaIf the fileTest.javacontains the following doc comment:/** * @todo Fix this! */then theToDotaglet 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 setisInlineTagto return false:public boolean isInlineTag() { return false; }There are other methodsinField,inMethod,inType,inPackageandinOverviewthat you specifytrueorfalseto 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 bytag.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, thetoString(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@todois included at: The corresponding class fileToDoTaglet.classis already compiled and saved in the same directory as this source file.To run the doclet, include the
-tagletpathand-tagletoptions. Assuming theToDoTaglet.classis located in/home/user/taglet, and the@todotag is located in theTest.javafile:% javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet ./Test.javaIf the fileTest.javacontains the following doc comment:/** * @todo Fix this! */then theToDotaglet 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 setisInlineTagto return false:public boolean isInlineTag() { return false; }There are other methodsinField,inMethod,inType,inPackageandinOverviewthat you specifytrueorfalseto 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 bytag.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, thetoString(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-tagoption). This is because there is no default behavior for inline tags.The source code for an example of an inline taglet implementing
The corresponding class file{@underline}is included at:UnderlineTaglet.classis 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 setisInlineTagto return true:public boolean isInlineTag() { return true; }The methods
inField,inMethod,inConstructor,inType,inPackageandinOverviewapply 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, thetoString(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 callingSystem.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 theSimpleTagletprints warnings, which is the default taglet for the-tagoption.
|
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved. Please send comments to: javadoc-tool@sun.com |
|