Quality Outreach Heads-up - JDK 28: Rich JavaDoc Notes

The OpenJDK Quality Group is promoting the testing of FOSS projects with OpenJDK builds as a way to improve the overall quality of the release. This heads-up is part of a Quality Outreach update sent to the projects involved. To learn more about the program, and how-to join, please check here.

The New @note Tag

A new JavaDoc tag, @note, is being proposed to highlight useful tips or warnings for developers using an API. For example:

/**
 * Determine the maximum foo in a list of bars.
 *
 * {@note There is always a maximum foo, even if the list is empty.}
 *
 * The arguments to this method must be non-null.
 */

It would be rendered as:

Determine the maximum foo in a list of bars.

Note: There is always a maximum foo, even if the list is empty.

The arguments to this method must be non-null.

Rendering

For both inline and block notes, the note body is rendered as a text block with a header that defaults to Note:. Inline notes are displayed with a vertical bar on the left side to make them stand out against the surrounding text:

Block notes with the default style are displayed with a small header and indented text, using the same layout as other block tags:

The top-level HTML element generated for a block note uses the CSS class block-note, while the top-level element for an inline note uses the CSS class inline-note. Additional CSS classes can be added using attributes or custom note tags as discussed below.

Attributes of the @note Tag

Additional details can be provided as attributes: name=value pairs enclosed in parentheses after the tag name and before the note body, as shown in this example:

{@note (name=value) ...}

Some attributes are recognized by the @note tag in the Standard Doclet. These attributes include header, for updating the heading of a note, kind, which is encoded as an additional CSS class, and id for adding an id attribute to an HTML element. Here is an example of using the header attribute to change the heading of a @note to warn a developer about a potential issue:

/**
* {@note (header='Caution:') Untrusted input must be verified!}
*/

Would be rendered as:

Caution: Untrusted input must be verified!

Creating a Custom @note Tag

A custom @note tag can be defined using the javadoc -tag option. javadoc -tag will be extended to allow for aliasing of the @note tag. Here is an example of creating a @warning tag that is an alias of @tag:

javadoc -tag 'warning:A:Warning:' ...

This could then be used as:

/**
* {@warning Remember to flush the cache before syncing.}
*/

And would be rendered as:

Warning: Remember to flush the cache before syncing.

Additional customization options for @note are offered; check JDK-8363700 for details.

Call to Action

Feedback is also welcome through the javadoc-dev mailing list (registration required). For more details on this proposed change, check JDK-8363700.