h36560 s 00105/00031/00323 d R 1.7 02/03/16 13:35:44 dkramer 8 7 c Made major revisions to include AbstractExecutableMemberTaglet and AbstractInlineTag c e s 00026/00000/00328 d R 1.6 01/10/14 22:34:03 dkramer 7 6 c Added warnings and errors c e s 00021/00000/00307 d R 1.5 01/09/24 15:56:46 dkramer 6 5 c Added a commented-out paragraph about links to standard taglets c e s 00013/00040/00294 d R 1.4 01/09/20 17:08:02 dkramer 5 4 c Fixed copyright date c e s 00034/00029/00300 d R 1.3 01/09/20 16:45:41 dkramer 4 3 c Updated with lots of input from Jamie c e s 00000/00000/00329 d D 1.2 01/09/18 20:45:32 dkramer 3 1 c Added the bulk of the documentation e s 00000/00000/00000 d R 1.2 70/01/01 00:00:02 Codemgr 2 1 c SunPro Code Manager data about conflicts, renames, etc... c Name history : 1 0 j2se/1.4/docs/tooldocs/javadoc/taglet/overview.html e s 00329/00000/00000 d D 1.1 01/09/18 20:43:47 dkramer 1 0 c CodeManager Uniquification: j2se/1.4.1/docs/tooldocs/javadoc/taglet/overview.html c e u U f b f e 0 t T I 1 Taglet Overview
Java

Taglet Overview

 

Contents

The Basics

Taglets are programs written in the JavaTM programming language that implement the A taglet modifies or redirects the text argument of a custom tag. A taglet can also override a standard tag.

Taglets are a variation on the -tag option. When you use the -tag option, it generates default HTML formatting that is similar to that generated for @return.

Taglets enable you to customize the text that is generated, as shown in the examples below.

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. Your program should import the following:
       import com.sun.tools.doclets.*;
       import com.sun.tools.doclets.standard.*;
       import com.sun.javadoc.*;
       import java.util.*;
    
    The Taglet class resides in com.sun.tools.doclets. The ? class is in com.sun.tools.doclets.standard. The ? class is part of the Doclet API, in com.sun.javadoc.* The ? class is part of java.util.

  2. Your program must implement the following method:
        public static void register(Map tagletMap)
    
  3. Compile your doclet. You can use the javac compiler in the Java 2 SDK. The required class files are in the lib/tools.jar file in the SDK. When you compile a taglet, the tools.jar must be on the class path. You can use the -classpath option on javac for this purpose. For the first example below:
       javac -classpath C:\jdk1.4\lib 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:\bin\com\sun, then you should set tagletpath to C:\bin:
          javadoc -taglet ToDoTaglet -tagletpath C:\bin com.package1
    

The following are examples of standalone and inline taglets.

Example - A Standalone Taglet

The source code for an example of a standalone 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.

This taglet formats the output for the @todo tag. A doc comment containing the following tag:

    /**
     * @todo Fix this!
     */
would be output in HTML as follows:
To Do:
Fix this!

Source Code

Let's look at the source code. To name the tag and define the header text, define two private fields:
    private String NAME = "todo";
    private String HEADER = "To Do:";
To make this a standalone 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 to determine where 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

The source code for an example of a inline taglet implementing {@underline} is included at: 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.

Source code

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 standalone tag, you set isInlineTag to return true:
    public boolean isInlineTag() {
        return true;
    }

The methods inField, inMethod, inType, inPackage and inOverview must be set to false for inline tags, because, by definition, inline tags can be used in any of these places. REWRITE THIS SENTENCE BASED ON JAMIE'S INPUT

The toString(Tag) method determines how the text is inserted into the output when a single SINGLE?? {@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>";
    }
Similarly, the toString(Tag[]) method (which takes an array of tags) determines how the text is inserted into the output when multiple {@underline} tags are encountered. I THINK THIS METHOD IS NOT CALLED WHEN isInlineTag() IS TRUE.


Copyright © 1995-98 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: javadoc-tool@sun.com
Sun
E 1