A preview feature may affect the behavior of permanent APIs in the Java Platform. In this (rare) scenario, it is desirable to be able to add preview-related notes to the specification of a permanent API element.

This RFE provides (1) a taglet in the OpenJDK build environment that supports preview-related notes for permanent API elements, and (2) a javadoc option that extends the top-level "PREVIEW" summary page to show permanent API elements which have such notes.

1) 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 has an HTML-like begin/end syntax that encloses the text of the note, as follows:

    {@previewNote <jep-number> [preview note title]}
    preview note text
    {@previewNote}

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 "Elements containing Preview Notes".