RFR: 8376274: JSpec preview support and output enhancement [v2]

[Hannes Wallnöfer]

On Mon, 26 Jan 2026 18:07:28 GMT, Chen Liang <liach at openjdk.org> wrote:

>> We can enhance the `@jls` and `@jvms` tags in-place to support preview JLS/JVMS, such as in this PR:
>> 
>> 
>> @jls primitive-types-in-patterns-instanceof-switch-5.7.1 Exact Testing Conversions
>> 
>> 
>> Taglet now parses "primitive-types-in-patterns-instanceof-switch-" preview and links to `primitive-types-in-patterns-instanceof-switch-jls.html` where the 5.7.1 anchor exists.
>> 
>> As a side effect, I adjusted the output to remove the preview prefix, and discovered we can embellish the output more, in particular, including a section sign for inline tags and including a trailing dot for block tags.
>> 
>> I need this feature in project Valhalla, where there are JLS and JVMS for value-objects and strict-fields that we need to link to. Please help review!
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Remove redundant dot

The change looks technically good. I have some questions regarding formatting of link labels which I have commented inline.

make/jdk/src/classes/build/tools/taglet/JSpec.java line 198:

> 196:                         // Change whole text to "§chapter.x" in inline tags.
> 197:                         literal = sectionSign + chapter + section;
> 198:                     }

What is the rationale for only using the section sign when there is no title? If we render a title-less tag as `§1.2.34`, why not also render a titled tag as `§1.2.34 Section Title` (or vice versa)?

For preview spec links, should there be a marker to indicate the preview status? I'm thinking of adding something like `(preview feature)` after the link, or a superscript <sup>PREVIEW</sup> tag like we use in API references.

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

PR Review: https://git.openjdk.org/jdk/pull/29402#pullrequestreview-3709994788
PR Review Comment: https://git.openjdk.org/jdk/pull/29402#discussion_r2730997254