HomeDownloadsUser GuideDevelopmentLegal

User Guide: Default Configuration

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.


Any configuration read is resolved in the above order of preference. All configurations found will be merged and evaluated in the given order.

Java Property Files

Since Java property files are easy to write and maintain the Taglets Collection uses them exclusively for its configuration, we have considered using XML Files, but it just isn't worth the trouble...

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


Refer to the development section and the source distribution to learn more about creating a new driver.

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


Taglets will issue a warning if you create a cycle that cannot be resolved.


There is currently no way to set the ordering of the Specified by: and Overrides: tags as their output is hard-coded to be in front of any other tags in JavaDoc.

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


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.


Since the default includes contribute close to 500 (!) tags they are all included with a tag implementation that ignores their occurence in a JavaDoc comment. If you would like to see a specific tool tag override it in a custom configuration file.