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 |
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:
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.
public static void register(Map tagletMap)
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
-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.
The source code for an example of a standalone taglet implementing@todois included at: The corresponding class fileToDoTaglet.classis already compiled and saved in the same directory as this source file.This taglet formats the output for the
@todotag. 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 setisInlineTagto return false:public boolean isInlineTag() { return false; }There are other methodsinField,inMethod,inType,inPackageandinOverviewthat 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 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 inline taglet implementing{@underline}is included at: The corresponding class fileUnderlineTaglet.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.
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 setisInlineTagto return true:public boolean isInlineTag() { return true; }The methods
inField,inMethod,inType,inPackageandinOverviewmust 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 INPUTThe
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, thetoString(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 |
|