Summary

Provide a way to add preview-related notes to permanent APIs.

Problem

Preview features may affect the behaviour of permanent APIs in a way that needs be documented in the API docs. There is currently no way to document the effect of preview features on permanant APIs.

Solution

Provide a taglet in the OpenJDK build environment that supports preview-related notes for permanent API elements, and a hidden javadoc option that extends the top-level "PREVIEW" summary page to show permanent API elements which have such notes.

Because of limitations in the jdk.javadoc.doclet API which disallow Taglets to parse or render rich inline content, the Taglet uses an unconventional start and end tag syntax that encloses the content of the note and uses the start tag to encode metadata. This choice was made out of necessity to satisfy the requirements for this feature, and is considered acceptable given the tag's limited scope in permanent APIs affected by Java preview features. There are no plans to use this form in other JavaDoc tags. It may be revised at a future date if the limitations in the jdk.javadoc.doclet API are lifted.

Specification

The qualified name of the taglet is build.tools.taglet.PreviewNote. It is located in make/jdk/src/classes/ and activated with the following option:

-taglet build.tools.taglet.PreviewNote

The taglet defines an inline tag, previewNote, that allows preview-related notes to be positioned anywhere in the main description of an element. The tag uses an HTML-like start/end syntax that encloses the text of the note, as follows:

{@previewNote $JEP_NUMBER [$SECTION_TITLE]}
... Preview-related text goes here ...
{@previewNote}

The $JEP_NUMBER can be 0, indicating this note is not associated with a particular JEP.

2) The javadoc tool has a new hidden option, --preview-note-tag, that takes a single tag name as an argument:

--preview-note-tag previewNote

API elements whose doc comment contains the specified tag are listed in the top-level "PREVIEW" summary page, in a new section titled "Permanent APIs affected by Preview Features".