RFR: 8346109: Create JDK taglet for additional preview notes
Hannes Wallnöfer
hannesw at openjdk.org
Mon Apr 7 18:08:02 UTC 2025
On Fri, 31 Jan 2025 16:58:08 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 94:
>
>> 92: if (tag.getKind() == UNKNOWN_INLINE_TAG) {
>> 93: UnknownInlineTagTree inlineTag = (UnknownInlineTagTree) tag;
>> 94: String[] content = inlineTag.getContent().toString().trim().split("\\s+", 2);
>
> Just curious, does `getContent()` translate nested tags like nested `{@code}` or `{@link}`? I know the inline return tag translates those.
Because of how `DocCommentParser` is implemented, we don't have support for parsing (and rendering) nested tags in unknown inline tags (which means all inline tags using the public doclet/taglet API registered via javadoc `-taglet` option). So taglet content will only ever contain a single string of unparsed content.
The alternative would have been to build the taglet into the inernal Standard Doclet, along with its own doc comment parser, but I considered this too much effort for an internal feature with limited scope. The comments in the JBS issue have more details on this.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/23395#discussion_r1939162842
More information about the build-dev
mailing list