On Fri, 31 Jan 2025 16:58:08 GMT, Chen Liang <[email protected]> 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
