Taglets Collection

This section of the user guide describes the default configuration of the Taglets Collection.

If you are using the canned version of the Taglets Collection the configuration, tags and shutdown taglets described here are available without further tweaking.

Configuration Files

The taglets configuration uses a nested configuration that is built using configuration files and the system properties in the following order of preference:

1. System properties

   Specify either with -J-DTaglets.<property>=<value> on the command line to the JavaDoc executable or using the the attribute 'additionalparam' in your ant javadoc tag: additionalparam="-J-DTaglets.<property>=<value>".

   System properties have the highest preference and are therefore handy to quickly override a setting to test things.

2. User configuration file Taglets.ConfigurationFile

   Specify the file location of the property file using the system property Taglets.ConfigurationFile (see above).

   This configuration will be read in addition to the default configuration, but any values specified will override the default values.

3. Classpath user configuration file /taglets.properties

   If the file /taglets.properties can be found on the taglet classpath (i.e. the classpath of the taglets collection) it will be read.

   A simple method to configure the taglets collection is to specify the JavaDoc taglet classpath to include the taglets.jar archive as well as configuration directory containing the taglets.properties file.

4. Default configuration file /META-INF/taglets-default.properties

   The default configuration file is included in the taglets.jar archive.

   Use of the default configuration can be disabled by specifying the system property Taglets.NoDefaultConfiguration with a value of true.

   Of course you can also include a custom default configuration in the classpath as /META-INF/taglets-default.properties, just make sure it is listed on the classpath before taglets.jar.

Taglet Driver Configuration

The Taglets Collection uses so called configuration drivers that mitigate between "Simple Taglets" and JavaDoc.

Due to differences in various JavaDoc versions the Taglets Collection can handle a list of configuration drivers that get searched for a suitable driver.

The configuration driver classes need to be included on the taglets classpath, however to simplify handling the Taglets Collection is able to configuration drivers from JAR files that are included in other JAR files (i.e. taglets.jar contains JAR archives of the various drivers).

The configuration entry Taglets.drivers specifies a search path for configuration drivers. The search path is a comma separated value that contains path locations to driver archives. The driver archives are first searched in the classpath and then on the file system. Slashes (/) in the path name are converted to the file separator character of the executing OS.

The default configuration included in taglets.jar is:

Taglets.drivers= drivers/j2se15.jar, drivers/j2se14.jar

Taglet Output Configuration

The following configuration entries determine the verbosity level of the Taglets Collection, best use them as a System Property in case of unexpected behaviour when fiddling with new tags.

The entries determine if the taglets engine prints a "splash" message and if the taglets should produce verbose output during execution. Set debug to true to enable debug messages of the engine itself.

Taglets.splash= true
Taglets.verbose= false
Taglets.debug= false

Tag Ordering

The tag ordering configuration describes how the default tags provided by the standard doclet are ordered.

Syntax is either Taglets.tag.<tagname>.before= <next-tagname> or Taglets.tag.<tagname>.after= <previous-tagname> and indicates that the the tag denoted by <tagname> should either appear before <next-tagname> or after <previous-tagname>.

There is also a syntax that combines before and after that has a similar effect as listing both at the same time: Taglets.tag.<tagname>.between= <previous-tagname>, <next-tagname>.

Ordering is only relevant for block tags.

Example: At the time of this writing the default ordering of the standard tags is as follows:

Taglets.tag.param.before= return
Taglets.tag.return.before= throws
Taglets.tag.throws.before= exception
Taglets.tag.see.before= since
Taglets.tag.exception.before= since
Taglets.tag.since.after= version
Taglets.tag.version.before= author
Taglets.tag.author.before= serialData
Taglets.tag.serialData.before= factory
Taglets.tag.factory.before= see

Check out the META-INF/taglets-default.properties included in taglets.jar for the preconfigured ordering.

Imports

A taglet configuration file can include another configuration file. The included file is searched relative to the location of the file that includes it.

Syntax of the include statement is as follows:

Taglets.import.<name>= <property-file>

At the time of this writing the following default includes are used to provide support for 3rd party tools:

Taglets.import.ejbgen= ejbgen.properties
Taglets.import.emf= emf.properties
Taglets.import.xdoclet= xdoclet.properties

Check out the corresponding properties file in the META-INF folder of the taglets.jar to see a list of tags contributed.