RFR: 8346109: Create JDK taglet for additional preview notes

[Chen Liang]

On Mon, 3 Feb 2025 10:41:17 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> 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.

Sure; I think I have requested this feature via bugs.java.com long ago. It's just that people might start using nested tags like for inline return and be surprised to find them not working.

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

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