Summary

Implement the @note standard tag and supporting APIs.

Problem

JavaDoc provides the -tag option to declare custom tags that allow to add notes to API documentation. However, custom tags have some significant limitations:

• They only support block tags, not inline tags
• They must be declared with a command line option
• They don't support class attributes and CSS
• They don't support id attributes
• They cannot contain meta data
• They are represented as UnknownBlockTagTree in the doctree API

Solution

JEP 8363700 (Rich Notes in Java API Documentation) introduces a framework for creating notes in API documentation that addresses all the issues mentioned above. It achieves this by introducing a new @note tag to the Standard Doclet, which can be used both inline and as a block tag, and provides a syntax for specifying attributes.

    {@note body}
    {@note [attributes] body}
    @note body
    @note [attributes] body

Attributes are supported in the form of name=value pairs placed inside a single pair of square brackets ([ ]) after the tag name. The @note tag recognizes the following standard attributes:

• header to provide a note header
• kind to provide a class attribute and custom CSS
• id to provide an id attribute

The existing functionality for custom tags is integrated with the new @note tag to provide command line option support for custom note tags. To make this possible, the @note tag has been designed to be backwards compatible with legacy custom tags. A note tag without attributes used as block tag produces markup that is visually indistinguishable from legacy custom tags.

Under the hood, custom tags receive upgrades such as modernized HTML markup and class and id attributes. Users of custom tags can also choose to make use of attributes, for example to provide a fixed id attribute, as the automatically generated id value may change over the evolution of the code.

Note tags can be used both as inline and block tags, while legacy custom tags are limited to block tag use. While this is generally an enhancement, there are use cases such as the JDK implementation and specification notes where limitation to either block or inline mode is required. To address this, two new character flags are introduced to the locations field of the tag option:

• B to only allow use as block tag
• I to only allow use as inline tag

An alternative solution we considered was to leave the -tag option unchanged and instead introduce a new option, such as -note, to allow command line configuration of custom @note tags. However, we found no good reason to preserve custom tags in their current state, and decided against the replication of code and options between what would have been very similar features.

The are a number of API changes required to support the @note tag. 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, while the changes to the Documentation Comment specification and javadoc man page are attached in zipped specdiff format.

Additionally, the latest versions of these diffs can be viewed here:

• apidiff output for API specification
• specdiff output for doc comment spec
• specdiff output for man page

The specdiff for the man page is difficult to read, as paragraphs were rewritten and rearranged. For convenience, the proposed text can be viewed here in HTML format.