Summary

Implement the @note standard tag and supporting APIs.

Problem

JavaDoc provides the -tag option to declare custom note tags for API documentation. However, custom notes are limited in several ways:

• They must be declared via command line option in order to be used
• They can only be used as block tags after the main description
• They do not support customization via CSS
• They cannot contain meta data

Solution

A new @note standard tag is added to the Standard Doclet that can be used to create notes either as inline or as block tags. The new tag supports rich content including nested HTML and inline tags, as well as attributes to allow its appearance to be customized.

The existing -tag option is adapted to create @note tag aliases. This is fully compatible with existing uses of custom tags while providing access to additional @note tag features.

A new interface com.sun.source.doctree.NoteTree is introduced to represent instances of @note tags. New methods are added to DocTreeVisitor and its subclasses to handle the new class.

Methods are added to class com.sun.source.util.DocTrees to register and query custom tags so they can be recognized by the doc comment parser.

Specification

The changes to the API specifications are attached in zipped apidiff format. Additionally, the apidiff can be viewed here:

• apidiff.00

Changes to the Documentation Comment specification and the javadoc man page are forthcoming.