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 thecom.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 theisInlineTag()
method if the tag is an inline tag. Otherwise, returnfalse
.Return
true
orfalse
as applicable frominConstructor()
,inField()
,inMethod()
,inOverview()
,inPackage()
, andinType()
.Implement the formatting code in
toString(Tag tag)
andtoString(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 calltoString(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
This article was originally published on October 1, 2003