RFR: 8346109: Create JDK taglet for additional preview notes

[Hannes Wallnöfer]

On Mon, 7 Apr 2025 18:32:55 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Please review a patch to add a JavaDoc Taglet to the JDK build system that allows to add preview-related notes to non-preview API elements, as well as a hidden javadoc option to add elements with preview notes to the preview summary page.
>> 
>> The {@previewNote} tag uses the following syntax:
>> 
>> 
>> {@previewNote <jep-number> [preview note title]}
>> preview note text
>> {@previewNote}
>> ``` 
>> 
>> Elements with preview notes are listed in a separate table titled "Elements containing Preview Notes" in the preview summary page. 
>> 
>> To support the feature, the algorithm in `PreviewAPIListBuilder.java` was changed to retrieve the preview JEP info in advance before looping through API elements. While this is not strictly necessary, it makes the code a bit nicer, and it also allows us to avoid checking for preview API elements when processing non-JDK code.
>
> make/jdk/src/classes/build/tools/taglet/PreviewNote.java line 112:
> 
>> 110:                             """);
>> 111:                     return sb.toString();
>> 112:                 } else {
> 
> What does this else block do? In what case can the JEP number be blank?

The else block generates the closing tag for the note. As you see in the PR description, the tag syntax resembles HTML open/close tags. This is a compromise to be able to locate the note within the description (which isn't possible with block tags), and being able to use rich content in the note without being required to writing a dedicated tag parser and rendering code. (I also happen to find this syntax easier to read than a custom inline tag, which would require additional rules to separate meta data from note content.)

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/23395#discussion_r2032506967