Javadoc Programming

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

• Javadoc Tool Home Page
• The Standard Doclet
• Javadoc FAQ – Customizing the Javadoc Tool
• Java 2 SDK 1.4 Source Code Release
• Doclet.com