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 theisInlineTag()
method if the
tag is an inline tag. Otherwise, returnfalse
. -
Return
true
orfalse
as applicable from
inConstructor()
,inField()
,
inMethod()
,inOverview()
,
inPackage()
, andinType()
. -
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 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, likethis.
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
. This method will be called when the doclet is
start(RootDoc)
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.