| # Taglet Overview |

## Contents

- Taglet API
- Writing a Taglet
- Example - A Simple Block Taglet
- Example - A Block Taglet That Handles Inline Tags
- 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 support both block tags, such as `@todo`, and inline tags, such as `{@underline}`. (See block and inline tags.) The Taglet API consists of one interface and two abstract classes:

- Taglet API - ADD LINK TO OVERVIEW - ARE THERE ANY OTHER CLASSES WE SHOULD ADD?
  `Taglet` Interface
    Implement when writing a block taglet that does not need to support inline tags, or when writing a general inline tag
  `BaseExecutableMemberTaglet` class
    Extend when writing a block taglet that supports inline tags
  `BaseInlineTaglet` class
    Extends when writing an inline tag that needs access to the HtmlStandardWriter and/or the doc object

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

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

## Writing a Taglet

Choose which type of taglet you want to write, and implement the appropriate interface or extend the appropriate abstract class:

- Block taglets
  - that support inline tags - extend `BaseExecutableMemberTaglet`
  - that do not support inline tags - implement `Taglet`
- Inline taglets
  - general inline tags - implement `Taglet`
  - that need access to the HtmlStandardWriter or Doc object - extend `BaseInlineTag`

The `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:

1. Write the Java program that constitutes your taglet. Include import statements appropriate to the taglet you're writing. For example, if extending `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.

2. In addition to the requirements of the interface you are implementing or abstract class you are extending, your program must implement the following static method. Then enables the taglet to be loaded at runtime. See the example below.

           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)

3. Compile your doclet. Use javac compiler version 1.4.0 (or later) in the Java 2 SDK. The required class files are in the `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

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:\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 !!!!!!!!!!!!!!

## Example - A Simple 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.

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

> If the file `Test.java` contains the following doc comment:

>         /**
>          * @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.

## Example - A Block Taglet That Handles Inline Tags

> The source code for an example of a block taglet implementing `@todo` is included at:
> - `ToDoTagletWithInline.java`
> 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.java

> If the file `Test.java` contains the following doc comment:

>         /**
>          * @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.

## Example - An Inline Taglet

> 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.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 © 2001 Sun Microsystems, Inc. All Rights Reserved. |