Taglets Collection

Using information obtained by the various @since tags used in the JavaDoc descriptions it would be easy to create a summary of revision changes.

Prerequisities:

• Mandatory use of @since.
• Multiple @since tags in JavaDoc for major changes.

At the moment the header and footer of the JavaDoc generated has to be specified on the commandline when invoking JavaDoc. The header and footer should be configured using the taglets properties for consistency and to simplify JavaDoc execution.

It would be nice to have an extended @param and @return syntax that allows to include common usage patterns like e.g.

/**
 * @param one "maybenull" the first parameter.
 * @param two "notnull,owner" the second parameter.
 * @return "clone" data.
 */

Possible values should include:

maybenull

Results in "one - the first parameter, may be null."

nonull

Results in "two - the second parameter, must not be null."

owner

Results in "two - the second parameter, ownership is passed to the callee."

clone

Results in "two - the second parameter, the callee keeps a clone of the parameter."

true

Used e.g. in return to create output like "true sometext, false otherwise."

Add a simple inline tag to create unordered and ordered lists:

/**
 * {@list [ordered]
 * - An item.
 * - Multiline
 *   item.
 */

Add a simple inline tag to create definition lists:

/**
 * {@definition <separator>
 * Topic: Description.
 * Multiline: Description line one.
 *   Description line two.
 * Another Topic:
 *   Description.
 */

Include PMD to audits.

Add a {@picture} inline tag that will automatically copy the picture referenced to the generated documentation directory.

In addition the {@picture} tag should support generation of thumbnails for large images and display them in a Lightbox.

Add a {@utility} inline tag that can be used in private constructors to indicate that the given final class is a utility class for which objects cannot be instantiated.

An {@abbr} tag should create abbreviations for ubiquitous language backed by a property file containing the definitions would come in handy.

See also the definition of Ubiquitous Language in the book Domain-Driven Design book by Eric Evans.

Add a mapper inline tag that maps values from a property file to translations in the JavaDoc. This will also replace the {@abbr} tag mentioned above.

The mapper inline tag should support the configuration parameter replacement that allows the use of the following parameters:

• ${key} the input value to the tag
• ${value} the mapping in the property file for the key
• ${value.<suffix> mapping in the property file for the key "${key}.<suffix>"

Example: replacement= <a href="${value.url}"><abbr title="${value}">${key}</abbr></a>
For the properties foo=bar and foo.url=http://www.foo.com/ should result in
<a href="http://www.foo.com/"><abbr title="bar">foo</abbr></a>: foo

The @{abbr} tag implementation mentioned above can be kept as a simple example to illustrate how to create custom tags.

It would be nice to have an Eclipse plugin that shows extended JavaDoc tags in the documentation popups.

Also a new page in the JavaDoc wizard to create the documentation and Ant files to configure taglets would be nice.

Create an XML file describing the default configuration and create the actual property file as well as the user guide documentation using XSLTs.

Add some simple demonstration sources instead of Regex Demo.

Release 1.9.2 includes a few simple Java sources to show off usage of the Taglets Collection.

The Regex Demo is no longer used but still included to fiddle around regex replacements as used by the regex filter.

Add a {@className} inline tag that will expand to the simple name of the class in a <code/> HTML tag.

Release 2.0.0 includes a {@className} tag that can be used without option to generate the simple class name (equivalent to {@className simple} or with option "qualified" to generate the fully qualified name: {@className qualified}.