Taglets Collection

This is pretty unfortunate, but by design of the JavaDoc taglet implementation.

It would be possible to work around this limitation by modifying the way current JavaDoc implementations work with a special driver. The drivers included do not try to work around this since we believe it is not worth the trouble.

Use different names for inline tags and block tags as we have decided to do for the default tags (e.g. {@stickyNote} vs. @note).

Even though we have tried to support all former 1.x style tags to simplify migration, some tags like e.g. @javaadm are no longer supported.

Upgrade the tags to 2.x style.
JSE 5 introduced some tags previously used by the Taglets Collection, so it is best to convert the sources anyway.

Since there is no way for the Taglets Collection to know when JavaDoc has finished its work, it uses a VM shutdown hook which gets called when the VM exits.

Newer JavaDoc versions support execution by method calls within the same VM. However due to memory leaks it is recommended to call JavaDoc in its own VM anyway, e.g. ANT already forks a VM (see also ANT JavaDoc Task).

Use Runtime.exec() to call JavaDoc to for a VM when used from a Java tool.

Using annotations in a source tag, is not possible:

/**
 * {@source
 * @myAnnotation
 * Object myAnnotatedObject;}
 */

The '@' sign gets interpreted by JavaDoc since it is possible to use embedded tags in an inline tag.

Escaping the '@' sign using @ does not yield the desired result since the {@source} taglet will simply escape the escape and produce @ again.

If upgrading is not an option then define a new inline tag and use that instead of the annotation directly:

The taglets.properties configuration for such a new inline tag looks as follows:

Taglets.taglet.annotation= \
	net.sourceforge.taglets.simple.inline.RegexInlineTaglet 
Taglets.taglet.annotation.regex.pattern= (.*) 
Taglets.taglet.annotation.regex.replacement= @${1!}

The sample above needs to be rewritten as follows:

/**
 * {@source
 * {@annotation myAnnotation}
 * Object myAnnotatedObject;}
 */

The {@annotation} inline tag is predefined as of version 2.0.3 of the Taglets Collection.

Declaring @foo as block tag and then using {@foo} in JavaDoc does not generate a warning.

There is no known workaround.

Use J2SE 1.4 to verify such problems if possible or use an auditing tool to check the JavaDoc contents.

Starting JavaDoc comments with {@inheritDoc} is known to cause problems.

Example: {@inheritDoc} {@stickyNote One. Two.} will report that the curly brace of {@stickyNote} is not closed. This is due to the fact that the first sentence is not calculated correctly.

Use JSE 5 or JSE 6 JavaDoc, or replace all periods except for the last one in the following tag by ..

In general, always be careful when using {@inheritDoc} at the start of a JavaDoc comment, esp. when the superclass is not included in source form.