What is a Taglet?

A taglet is simply put a handler for a Javadoc tag, such as @author, @since and @param.

/**
 * @since 1.2
 * @author Me
 */

The taglet is then responsible for formatting the tag in the HTML output.

How Do I Use It?

We will go through the options below, but in short: 

javadoc 
    -J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=. 
    -tagletpath commons-attributes-compiler-2.2.jar
    -taglet org.apache.commons.attributes.javadoc.CATaglet 
    [source files]

From top to bottom, then, are the options specific for the Commons-Attributes taglet:

-J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources

Due to the way tags are used by Commons-Attributes, the Taglet must know which Java files it will run on. This is caused by the Taglet API, which requires the Taglet to specify exactly which tags it will handle. Since @@MyAttr() and @@MyOtherAttr() are considered two different tags, the taglet must first scan the source files and compile a list of all potential tag names.

This parameter is a semi-colon (Win32) or colon (Unix) separated list of files or directories that will be used to create Javadocs. If you specify a directory, then all .java files in that directory and any subdirectories are included.

Example: 

javadoc 
    -J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=/home/leo/java 
    -tagletpath commons-attributes-compiler-2.2.jar
    -taglet org.apache.commons.attributes.javadoc.CATaglet 
    [source files]

-tagletpath

This is simply the classpath for taglets. Include the commons-attributes-compiler JAR.

Example: 

javadoc 
    -J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=/home/leo/java
    -tagletpath commons-attributes-compiler-2.2.jar
    -taglet org.apache.commons.attributes.javadoc.CATaglet 
    [source files]

-taglet

The fully-qualified class name of the taglet.

Example: 

javadoc 
    -J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=/home/leo/java
    -tagletpath commons-attributes-compiler-2.2.jar
    -taglet org.apache.commons.attributes.javadoc.CATaglet 
    [source files]

Ant Usage

Ant usage is similar to command line usage. 

<javadoc 
    destdir="${basedir}/javadoc/"
    additionalparam="-J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=${basedir}">
    <taglet
        name="org.apache.commons.attributes.javadoc.CATaglet"
        path="${ant.home}/lib/commons-attributes-compiler-2.2.jar"
    />
    <fileset dir="${basedir}/" includes="**/*.java" />
</javadoc>

Note the need to:

  • Include an additionalparam option to specify location of source files.

  • Specify the path to the attribute compiler jar when specifying the taglet. (Javadoc is a separate JVM and does not share classpaths with Ant.)

After you've run the Ant Demo, you can also type: 

# ant javadoc

To generate Javadocs for the demo.