Javadoc Programming

By Thornton Rose

The Javadoc Tool was originally designed to generate API documentation from Java source code. Now, it is not only a documentation generator, but an an extensible engine for processing Java source code. This article illustrates how to write programs for the Javadoc Tool.

Custom Tags

In Java 1.4 support for custom tags was added to the Javadoc Tool. Custom tags are specified with command-line options and can be handled by custom programs called taglets. If you want a one-argument block tag, which can occur anywhere after the main description in a javadoc comment, specify the tag using the "-tag" option. Javadoc will output the tag heading in bold, with the argument indented below it.

Here is a javadoc comment that includes the custom tag "@note":

/**
 * Quark represents a quark.
 *
 * @note If you spin a quark, it will spin forever!
 */
public class Quark {
}

To generate javadocs for the above, run javadoc like this:

javadoc -tag note:a:"Note:" Quark.java

The generated javadocs should look like Quark.html.

Taglets

If you want to customize the handling of a tag, you use a taglet. Taglets are specified with the "-taglet" option and can be used for both the standard taglets and custom taglets. Additionally, taglets can control the formatting of both block tags, which must occur at the beginning of a line, and inline tags, which can occur anywhere in text.

To create a taglet:

Import the com.sun.javadoc package and the com.sun.tools.doclets package.
Implement the interface com.sun.tools.doclets.Taglet.
Implement the register(Map tagletMap) method. This method will be called when the taglet is loaded by javadoc so that the taglet class can register with javadoc. This is done by adding an instance of the taglet class to the given map, which is a dictionary that javadoc uses to look up taglets by name.

Example:
```
public static void register(Map tagletMap) {
    tagletMap.put("strike", new StrikeTaglet());
}
```
Return the tag name from the getName() method. The tag name is what javadoc will look for in javadoc comments. For example, "note" is returned for the "@note" tag. If you want to customize the format of a standard tag, return its name. For example, return "author" for the "@author" tag.
Return true from the isInlineTag() method if the tag is an inline tag. Otherwise, return false.
Return true or false as applicable from inConstructor(), inField(), inMethod(), inOverview(), inPackage(), and inType().
Implement the formatting code in toString(Tag tag) and toString(Tag[] tags). The first method is called by javadoc to format an inline tag. The second method is called by javadoc to format one or more block tags. However, as you will see in the examples below, toString(Tag[] tags) can call toString(Tag tag) to format each tag in the given array.

Here are some examples of taglets:

AuthorTaglet - Formats "@author" tags as a comma-delimited list.
NoteTaglet - Formats "@note" tags in upper case.
StrikeTaglet - Formats "{@strike}" inline tags as striken text, like ~~this~~.

To compile the above taglets, include the Java library, tools.jar, in the classpath. To generate javadocs for Quark.java using the taglets, run javadoc like this:

javadoc -taglet StrikeTaglet -taglet NoteTaglet -taglet AuthorTaglet Quark.java

Alternatively, you could create a file that contains the taglet options, then run javdoc like this:

javadoc @taglets.opt Quark.java

The generated javadocs should look like Quark2.html.

Doclets

Doclets are programs that use the Doclet API to customize the output of the javadoc tool. They can be used to augment javadoc generation, to generate other files, or to do something completely different.

To create a doclet:

Import the package com.sun.javadoc.
Extend the class Doclet.
Implement the method public static boolean start(RootDoc). This method will be called when the doclet is started by javadoc. It should generate the output and return true upon successful completion.

MetricsDoclet is an example of doclet that generates metrics about the source files that are processed.

To compile MetricsDoclet, include the Java library, tools.jar, in your classpath. To run MetricsDoclet, run javadoc like this:

javadoc -doclet MetricsDoclet *.java

The output of MetricsDoclet should look like metrics.txt.

Customizing the Standard Doclet

If you want to generate HTML documents that are similar to the documents produced by javadoc, you can extend the standard doclet classes and override methods as necessary to produce the output that you want. The standard doclet classes are in the packages com.sun.tools.doclets.standard and com.sun.tools.doclets.standard.tags in tools.jar.

Alternatively, you can make a copy of the standard doclet and modify it. The source code is available from Sun in the Java 2 SDK 1.4 Source Code Release. (See "Resources" for a link.)

Command-line Options

Doclets can have command-line options. To do so, the doclet must have two methods:

public static int optionLength(String option)
public static boolean validOptions(String[][] options, DocErrorReporter reporter)

The optionLength method is called by javadoc to determine the length of the array that will contain a given option and its arguments. If the given option is one of the doclet options, this method should return one plus the number of arguments that the option takes. For example, for the option "-debug <n>", optionLength should return 2. If the given option is not one of the doclet options, optionLength should return 0.

The validOptions method is called by javadoc to validate the doclet options. This method should check the given options and return true if they are valid. If the options are not valid, this method should report any errors via reporter and return false.

To retrieve the validated options, call root.options(), where root is the instance of RootDoc that is passed to the start method.

OptionsDoclet illustrates using command-line options in a doclet.

To compile OptionsDoclet, include the Java library, tools.jar, in your classpath. To run OptionsDoclet, run javadoc like this:

javadoc -doclet OptionsDoclet -debug 1 -verbose Quark.java

The output of OptionsDoclet should look like options.txt.

Resources

This article was originally published on October 1, 2003

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.