` tags. The new `--syntax-highlight` option uses the [highlight.js] JavaScript library and supports Java, Properties, XML, HTML and JSON. The option is enabled in the JDK API docs target, [generated output is available here](https://cr.openjdk.org/~hannesw/8348282/api.00/index.html).

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

Commit messages:
 - Remove trailing spaces
 - Brigthen variable color
 - Fix regular expression for type arguments
 - 8348282: Add option for syntax highlighting in javadoc snippets

Changes: https://git.openjdk.org/jdk/pull/24417/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24417&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8348282
  Stats: 3531 lines in 13 files changed: 3516 ins; 3 del; 12 mod
  Patch: https://git.openjdk.org/jdk/pull/24417.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24417/head:pull/24417

PR: https://git.openjdk.org/jdk/pull/24417

From erikj at openjdk.org  Fri Apr  4 07:05:48 2025
From: erikj at openjdk.org (Erik Joelsson)
Date: Fri, 4 Apr 2025 07:05:48 GMT
Subject: RFR: 8348282: Add option for syntax highlighting in javadoc
 snippets
In-Reply-To: 
References: 
Message-ID: <1kQUIpj2OOMVzOyNh97h8jXzQO23bx_5WOwaGD7tqtI=.d7deb172-37c5-4be6-a9d8-d9cfd4b5d00f@github.com>

On Thu, 3 Apr 2025 14:48:58 GMT, Hannes Walln?fer  wrote:

> Please review a change to add a `javadoc` option to enable syntax highlighting for code fragments in snippets and  `` tags. The new `--syntax-highlight` option uses the [highlight.js] JavaScript library and supports Java, Properties, XML, HTML and JSON. The option is enabled in the JDK API docs target, [generated output is available here](https://cr.openjdk.org/~hannesw/8348282/api.00/index.html).

Build change looks trivially good.

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

Marked as reviewed by erikj (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24417#pullrequestreview-2741999660

From hannesw at openjdk.org  Fri Apr  4 14:32:45 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 4 Apr 2025 14:32:45 GMT
Subject: RFR: 8254622: Hide superclasses from conditionally exported packages
Message-ID: 

Please review an enhancement to treat classes and interfaces that are not included and not unconditionally exported as hidden. This means they do not show up in the generated documentation even if they are implemented or extended by a documented type. 

This change makes the `@hidden` JavaDoc tag unnecessary in two internal base classes that previously used it, `jdk.internal.vm.vector.VectorSupport` and `jdk.internal.event.Event`. The generated documentation is unchanged.

The change also adds support for the `@hidden` JavaDoc tag in interfaces, which was previously missing, and adds coverage to `TestHiddenTag.java`.

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

Commit messages:
 - Remove whitespace
 - Update copyright headers
 - Add test, support hidden interfaces
 - Merge branch 'master' into JDK-8254622
 - Tweak comments
 - 8254622: Hide superclasses from conditionally exported packages

Changes: https://git.openjdk.org/jdk/pull/24446/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24446&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8254622
  Stats: 382 lines in 19 files changed: 326 ins; 15 del; 41 mod
  Patch: https://git.openjdk.org/jdk/pull/24446.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24446/head:pull/24446

PR: https://git.openjdk.org/jdk/pull/24446

From nbenalla at openjdk.org  Fri Apr  4 15:40:49 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Fri, 4 Apr 2025 15:40:49 GMT
Subject: RFR: 8338554: Fix inconsistencies in
 javadoc/doclet/testLinkOption/TestRedirectLinks.java [v2]
In-Reply-To: 
References: 

Message-ID: 

On Wed, 2 Apr 2025 01:41:27 GMT, Jaikiran Pai  wrote:

>> Can I please get a review of this test-only change which proposes to clean up some issues noticed in the `TestRedirectLinks.java` test?
>> 
>> The `javadoc/doclet/testLinkOption/TestRedirectLinks.java` test has been failing intermittently in our CI. The root cause of those failures isn't yet clear and those failures are being tracked in https://bugs.openjdk.org/browse/JDK-8338439.
>> 
>> While investigating those failures, it was noticed that this test had some issues that could be addressed separately to rule out their role in the intermittent failures. 
>> 
>> The commit in this PR updates the test to using existing test library classes to construct the request URL as well as for constructing the SSLContext. The test is also updated to use the correct value to represent "no response body" when calling the `sendResponseHeaders()` method.
>> 
>> The test continues to pass with this change. We will continue investigating the intermittent failure if/when it occurs again after this change.
>
> Jaikiran Pai has updated the pull request incrementally with one additional commit since the last revision:
> 
>   address review comment in test

I see that the use of `InetSocketAddress::toString` was dropped as it's not recommended when building URL strings.

Changes look good, thanks Jaikiran.

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

Marked as reviewed by nbenalla (Committer).

PR Review: https://git.openjdk.org/jdk/pull/24359#pullrequestreview-2743450925

From nbenalla at openjdk.org  Fri Apr  4 17:16:04 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Fri, 4 Apr 2025 17:16:04 GMT
Subject: RFR: 8350920: Allow inherited member summaries to be viewed inline
 [v3]
In-Reply-To: 
References: 

Message-ID: 

On Tue, 25 Mar 2025 04:35:19 GMT, Hannes Walln?fer  wrote:

>> Please review an enhancement to allow switching between the traditional condensed footnote-style summary and the summary table format for inherited members (types, fields, methods and properties) that are inherited from included types. You can test the feature in [the doc bundle I uploaded][apidocs] or watch the short screencast below.
>> 
>> [apidocs]: https://cr.openjdk.org/~hannesw/8350920/api.00/java.base/module-summary.html
>> 
>> https://github.com/user-attachments/assets/0aaa1f8b-c18b-4922-b704-2b2cdc05ca79
>> 
>> I added two new protected methods to the `AbstractMemberWriter` class, `createInheritedSummaryTable` and `getInheritedSummaryId`. Otherwise this is mostly reusing existing functionality (we already had the feature to display the signature of an inherited method in the context of the current class).
>> 
>> The writers for non-inheritable members such as constructors or enum constants were simplified a bit by implementing formerly abstract methods in `AbstractMemberWriter` as concrete methods throwing `UnsupportedOperationException` so they don't have to be implemented as empty methods in these writers.
>> 
>> The UI to switch between member list presentations is implemented in `script.js.template`. If no summary list presentation is available (because the supertype is not part of the documentation bundle) nothing changes in the UI.
>> 
>> I added a `stripTags()` method to `Content` to return the plain text content with HTML tags stripped that could be used in a few other places. The patch also adds two new vector graphics files called right.svg and down.svg for the right and downwards pointing angle.
>
> Hannes Walln?fer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains four commits:
> 
>  - Merge branch 'master' into JDK-8350920
>  - Merge branch 'master' into JDK-8350920
>  - Add svg files
>  - 8350920: Allow inherited member summaries to be viewed inline

Looks good, I think this a great addition to javadoc. I left a small comment regarding `stripTags` but it's not necessary.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java line 253:

> 251:             var table = getSummaryTable();
> 252:             for (Element member : members) {
> 253:                 addMemberSummaryTableRow(typeElement, member, table, pHelper);

I was going to suggest verifying that `table` is not null but it seems like it's not needed. The implementation of `getSummaryTable` doesn't return null (if the summary table doesn't exist, it will attempt to create one).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/RawHtml.java line 162:

> 160:     @Override
> 161:     public Content stripTags() {
> 162:         return Text.of(rawHtmlContent.replaceAll("<[^>]*>", ""));

nit: we use this same transformation `"<[^>]*>"` -> `""` in other places (IndexTaglet and SpecTaglet), could we replace those ad-hoc uses with this method?

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

Marked as reviewed by nbenalla (Committer).

PR Review: https://git.openjdk.org/jdk/pull/23967#pullrequestreview-2743625416
PR Review Comment: https://git.openjdk.org/jdk/pull/23967#discussion_r2029168515
PR Review Comment: https://git.openjdk.org/jdk/pull/23967#discussion_r2029145572

From liach at openjdk.org  Sat Apr  5 00:37:48 2025
From: liach at openjdk.org (Chen Liang)
Date: Sat, 5 Apr 2025 00:37:48 GMT
Subject: RFR: 8254622: Hide superclasses from conditionally exported
 packages
In-Reply-To: 
References: 
Message-ID: <3TeN5yxeLsHqA9fv2BBz4ErEn0y8zXfHuct9uvc6cak=.19223c83-732e-4ead-82fb-b5f0bb422e02@github.com>

On Fri, 4 Apr 2025 13:36:19 GMT, Hannes Walln?fer  wrote:

> Please review an enhancement to treat classes and interfaces that are not included and not unconditionally exported as hidden. This means they do not show up in the generated documentation even if they are implemented or extended by a documented type. 
> 
> This change makes the `@hidden` JavaDoc tag unnecessary in two internal base classes that previously used it, `jdk.internal.vm.vector.VectorSupport` and `jdk.internal.event.Event`. The generated documentation is unchanged.
> 
> The change also adds support for the `@hidden` JavaDoc tag in interfaces, which was previously missing, and adds coverage to `TestHiddenTag.java`.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Signatures.java line 165:

> 163:                     for (TypeMirror type : interfaces) {
> 164:                         TypeElement tDoc = utils.asTypeElement(type);
> 165:                         if (!(utils.isPublic(tDoc) || utils.isLinkable(tDoc)) || utils.isHidden(tDoc)) {

This `(!isPublicOrProtected && !isLinkable) || isHidden` trio appears a few times. The conditions are negated and wrapped in parentheses so it is easily confusing on the web; can we extract this check into a new utils method?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24446#discussion_r2029581822

From jpai at openjdk.org  Sat Apr  5 01:15:06 2025
From: jpai at openjdk.org (Jaikiran Pai)
Date: Sat, 5 Apr 2025 01:15:06 GMT
Subject: RFR: 8338554: Fix inconsistencies in
 javadoc/doclet/testLinkOption/TestRedirectLinks.java [v2]
In-Reply-To: 
References: 

Message-ID: 

On Wed, 2 Apr 2025 01:41:27 GMT, Jaikiran Pai  wrote:

>> Can I please get a review of this test-only change which proposes to clean up some issues noticed in the `TestRedirectLinks.java` test?
>> 
>> The `javadoc/doclet/testLinkOption/TestRedirectLinks.java` test has been failing intermittently in our CI. The root cause of those failures isn't yet clear and those failures are being tracked in https://bugs.openjdk.org/browse/JDK-8338439.
>> 
>> While investigating those failures, it was noticed that this test had some issues that could be addressed separately to rule out their role in the intermittent failures. 
>> 
>> The commit in this PR updates the test to using existing test library classes to construct the request URL as well as for constructing the SSLContext. The test is also updated to use the correct value to represent "no response body" when calling the `sendResponseHeaders()` method.
>> 
>> The test continues to pass with this change. We will continue investigating the intermittent failure if/when it occurs again after this change.
>
> Jaikiran Pai has updated the pull request incrementally with one additional commit since the last revision:
> 
>   address review comment in test

Thank you Chen and Nizar for the reviews.

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

PR Comment: https://git.openjdk.org/jdk/pull/24359#issuecomment-2780079107

From jpai at openjdk.org  Sat Apr  5 01:15:06 2025
From: jpai at openjdk.org (Jaikiran Pai)
Date: Sat, 5 Apr 2025 01:15:06 GMT
Subject: Integrated: 8338554: Fix inconsistencies in
 javadoc/doclet/testLinkOption/TestRedirectLinks.java
In-Reply-To: 
References: 
Message-ID: 

On Tue, 1 Apr 2025 16:25:58 GMT, Jaikiran Pai  wrote:

> Can I please get a review of this test-only change which proposes to clean up some issues noticed in the `TestRedirectLinks.java` test?
> 
> The `javadoc/doclet/testLinkOption/TestRedirectLinks.java` test has been failing intermittently in our CI. The root cause of those failures isn't yet clear and those failures are being tracked in https://bugs.openjdk.org/browse/JDK-8338439.
> 
> While investigating those failures, it was noticed that this test had some issues that could be addressed separately to rule out their role in the intermittent failures. 
> 
> The commit in this PR updates the test to using existing test library classes to construct the request URL as well as for constructing the SSLContext. The test is also updated to use the correct value to represent "no response body" when calling the `sendResponseHeaders()` method.
> 
> The test continues to pass with this change. We will continue investigating the intermittent failure if/when it occurs again after this change.

This pull request has now been integrated.

Changeset: 9bb804b1
Author:    Jaikiran Pai 
URL:       https://git.openjdk.org/jdk/commit/9bb804b14e164982860db6323c7db33214cd0d36
Stats:     99 lines in 1 file changed: 26 ins; 61 del; 12 mod

8338554: Fix inconsistencies in javadoc/doclet/testLinkOption/TestRedirectLinks.java

Reviewed-by: liach, nbenalla

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

PR: https://git.openjdk.org/jdk/pull/24359

From aturbanov at openjdk.org  Sat Apr  5 16:48:47 2025
From: aturbanov at openjdk.org (Andrey Turbanov)
Date: Sat, 5 Apr 2025 16:48:47 GMT
Subject: RFR: 8348282: Add option for syntax highlighting in javadoc
 snippets
In-Reply-To: 
References: 
Message-ID: 

On Thu, 3 Apr 2025 14:48:58 GMT, Hannes Walln?fer  wrote:

> Please review a change to add a `javadoc` option to enable syntax highlighting for code fragments in snippets and  `` tags. The new `--syntax-highlight` option uses the [highlight.js] JavaScript library and supports Java, Properties, XML, HTML and JSON. The option is enabled in the JDK API docs target, [generated output is available here](https://cr.openjdk.org/~hannesw/8348282/api.00/index.html).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlOptions.java line 433:

> 431:                 new Option(resources, "--syntax-highlight") {
> 432:                     @Override
> 433:                     public boolean process(String opt,  List args) {

Suggestion:

                    public boolean process(String opt, List args) {

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24417#discussion_r2029915493

From hannesw at openjdk.org  Mon Apr  7 18:08:02 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 7 Apr 2025 18:08:02 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
Message-ID: 

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

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

Commit messages:
 - Add test for hidden --preview-note-tag option
 - Avoid NPE and unnecessary work
 - Merge branch 'master' into JDK-8346109
 - Minor Cleanup
 - Add PreviewNote taglet and hidden --preview-note-tag option

Changes: https://git.openjdk.org/jdk/pull/23395/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23395&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8346109
  Stats: 357 lines in 8 files changed: 297 ins; 39 del; 21 mod
  Patch: https://git.openjdk.org/jdk/pull/23395.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23395/head:pull/23395

PR: https://git.openjdk.org/jdk/pull/23395

From liach at openjdk.org  Mon Apr  7 18:08:02 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 7 Apr 2025 18:08:02 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 
Message-ID: 

On Fri, 31 Jan 2025 16:19:17 GMT, Hannes Walln?fer  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  [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.

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

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

From hannesw at openjdk.org  Mon Apr  7 18:08:02 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 7 Apr 2025 18:08:02 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 

Message-ID: 

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

From liach at openjdk.org  Mon Apr  7 18:08:02 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 7 Apr 2025 18:08:02 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 

Message-ID: 

On Mon, 3 Feb 2025 10:41:17 GMT, Hannes Walln?fer  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

From liach at openjdk.org  Mon Apr  7 18:38:24 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 7 Apr 2025 18:38:24 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 
Message-ID: 

On Fri, 31 Jan 2025 16:19:17 GMT, Hannes Walln?fer  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  [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?

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

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

From hannesw at openjdk.org  Tue Apr  8 06:54:15 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 06:54:15 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 

Message-ID: 

On Mon, 7 Apr 2025 18:32:55 GMT, Chen Liang  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  [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

From hannesw at openjdk.org  Tue Apr  8 09:02:25 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 09:02:25 GMT
Subject: RFR: 8254622: Hide superclasses from conditionally exported
 packages [v2]
In-Reply-To: 
References: 
Message-ID: 

> Please review an enhancement to treat classes and interfaces that are not included and not unconditionally exported as hidden. This means they do not show up in the generated documentation even if they are implemented or extended by a documented type. 
> 
> This change makes the `@hidden` JavaDoc tag unnecessary in two internal base classes that previously used it, `jdk.internal.vm.vector.VectorSupport` and `jdk.internal.event.Event`. The generated documentation is unchanged.
> 
> The change also adds support for the `@hidden` JavaDoc tag in interfaces, which was previously missing, and adds coverage to `TestHiddenTag.java`.

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Review feedback: add Utils.isVisible(TypeElement) method

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24446/files
  - new: https://git.openjdk.org/jdk/pull/24446/files/6e83725e..682e1ebe

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24446&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24446&range=00-01

  Stats: 61 lines in 10 files changed: 26 ins; 14 del; 21 mod
  Patch: https://git.openjdk.org/jdk/pull/24446.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24446/head:pull/24446

PR: https://git.openjdk.org/jdk/pull/24446

From hannesw at openjdk.org  Tue Apr  8 09:07:27 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 09:07:27 GMT
Subject: RFR: 8254622: Hide superclasses from conditionally exported
 packages [v2]
In-Reply-To: <3TeN5yxeLsHqA9fv2BBz4ErEn0y8zXfHuct9uvc6cak=.19223c83-732e-4ead-82fb-b5f0bb422e02@github.com>
References: 
 <3TeN5yxeLsHqA9fv2BBz4ErEn0y8zXfHuct9uvc6cak=.19223c83-732e-4ead-82fb-b5f0bb422e02@github.com>
Message-ID: 

On Sat, 5 Apr 2025 00:35:35 GMT, Chen Liang  wrote:

>> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Review feedback: add Utils.isVisible(TypeElement) method
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Signatures.java line 165:
> 
>> 163:                     for (TypeMirror type : interfaces) {
>> 164:                         TypeElement tDoc = utils.asTypeElement(type);
>> 165:                         if (!(utils.isPublic(tDoc) || utils.isLinkable(tDoc)) || utils.isHidden(tDoc)) {
> 
> This `(!isPublicOrProtected && !isLinkable) || isHidden` trio appears a few times. The conditions are negated and wrapped in parentheses so it is easily confusing on the web; can we extract this check into a new utils method?

That's a very good suggestion. In 682e1eb I added a new `Utils.isVisible(TypeElement)` method which returns true if the argument is not hidden and either public or (externally or internally) linkable. 

I found a few places that only had the public/linkable part but should also have the hidden check (`LinkTaglet` and `AbstractTreeWriter`). I updated these places to use the new method and enhanced `TestHiddenTag` to cover these cases.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24446#discussion_r2032742066

From hannesw at openjdk.org  Tue Apr  8 09:45:45 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 09:45:45 GMT
Subject: RFR: 8350920: Allow inherited member summaries to be viewed inline
 [v4]
In-Reply-To: 
References: 
Message-ID: 

> Please review an enhancement to allow switching between the traditional condensed footnote-style summary and the summary table format for inherited members (types, fields, methods and properties) that are inherited from included types. You can test the feature in [the doc bundle I uploaded][apidocs] or watch the short screencast below.
> 
> [apidocs]: https://cr.openjdk.org/~hannesw/8350920/api.00/java.base/module-summary.html
> 
> https://github.com/user-attachments/assets/0aaa1f8b-c18b-4922-b704-2b2cdc05ca79
> 
> I added two new protected methods to the `AbstractMemberWriter` class, `createInheritedSummaryTable` and `getInheritedSummaryId`. Otherwise this is mostly reusing existing functionality (we already had the feature to display the signature of an inherited method in the context of the current class).
> 
> The writers for non-inheritable members such as constructors or enum constants were simplified a bit by implementing formerly abstract methods in `AbstractMemberWriter` as concrete methods throwing `UnsupportedOperationException` so they don't have to be implemented as empty methods in these writers.
> 
> The UI to switch between member list presentations is implemented in `script.js.template`. If no summary list presentation is available (because the supertype is not part of the documentation bundle) nothing changes in the UI.
> 
> I added a `stripTags()` method to `Content` to return the plain text content with HTML tags stripped that could be used in a few other places. The patch also adds two new vector graphics files called right.svg and down.svg for the right and downwards pointing angle.

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Review feedback: replace local implementations of Content.stripTags()

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23967/files
  - new: https://git.openjdk.org/jdk/pull/23967/files/f43e735b..a25cd03d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23967&range=03
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23967&range=02-03

  Stats: 42 lines in 2 files changed: 1 ins; 37 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/23967.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23967/head:pull/23967

PR: https://git.openjdk.org/jdk/pull/23967

From hannesw at openjdk.org  Tue Apr  8 09:56:02 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 09:56:02 GMT
Subject: RFR: 8350920: Allow inherited member summaries to be viewed inline
 [v5]
In-Reply-To: 
References: 
Message-ID: 

> Please review an enhancement to allow switching between the traditional condensed footnote-style summary and the summary table format for inherited members (types, fields, methods and properties) that are inherited from included types. You can test the feature in [the doc bundle I uploaded][apidocs] or watch the short screencast below.
> 
> [apidocs]: https://cr.openjdk.org/~hannesw/8350920/api.00/java.base/module-summary.html
> 
> https://github.com/user-attachments/assets/0aaa1f8b-c18b-4922-b704-2b2cdc05ca79
> 
> I added two new protected methods to the `AbstractMemberWriter` class, `createInheritedSummaryTable` and `getInheritedSummaryId`. Otherwise this is mostly reusing existing functionality (we already had the feature to display the signature of an inherited method in the context of the current class).
> 
> The writers for non-inheritable members such as constructors or enum constants were simplified a bit by implementing formerly abstract methods in `AbstractMemberWriter` as concrete methods throwing `UnsupportedOperationException` so they don't have to be implemented as empty methods in these writers.
> 
> The UI to switch between member list presentations is implemented in `script.js.template`. If no summary list presentation is available (because the supertype is not part of the documentation bundle) nothing changes in the UI.
> 
> I added a `stripTags()` method to `Content` to return the plain text content with HTML tags stripped that could be used in a few other places. The patch also adds two new vector graphics files called right.svg and down.svg for the right and downwards pointing angle.

Hannes Walln?fer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains six commits:

 - Merge branch 'master' into JDK-8350920
 - Review feedback: replace local implementations of Content.stripTags()
 - Merge branch 'master' into JDK-8350920
 - Merge branch 'master' into JDK-8350920
 - Add svg files
 - 8350920: Allow inherited member summaries to be viewed inline

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

Changes: https://git.openjdk.org/jdk/pull/23967/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23967&range=04
  Stats: 563 lines in 29 files changed: 410 ins; 92 del; 61 mod
  Patch: https://git.openjdk.org/jdk/pull/23967.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23967/head:pull/23967

PR: https://git.openjdk.org/jdk/pull/23967

From hannesw at openjdk.org  Tue Apr  8 09:58:18 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 09:58:18 GMT
Subject: RFR: 8350920: Allow inherited member summaries to be viewed inline
 [v3]
In-Reply-To: 
References: 

Message-ID: 

On Fri, 4 Apr 2025 16:51:24 GMT, Nizar Benalla  wrote:

>> Hannes Walln?fer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains four commits:
>> 
>>  - Merge branch 'master' into JDK-8350920
>>  - Merge branch 'master' into JDK-8350920
>>  - Add svg files
>>  - 8350920: Allow inherited member summaries to be viewed inline
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/RawHtml.java line 162:
> 
>> 160:     @Override
>> 161:     public Content stripTags() {
>> 162:         return Text.of(rawHtmlContent.replaceAll("<[^>]*>", ""));
> 
> nit: we use this same transformation `"<[^>]*>"` -> `""` in other places (IndexTaglet and SpecTaglet), could we replace those ad-hoc uses with this method?

Thanks @nizarbenalla, I replaced the two local implementations of this functionality in `IndexTaglet` and `SpecTaglet`.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23967#discussion_r2032835110

From nbenalla at openjdk.org  Tue Apr  8 12:19:27 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 8 Apr 2025 12:19:27 GMT
Subject: RFR: 8350920: Allow inherited member summaries to be viewed inline
 [v5]
In-Reply-To: 
References: 

Message-ID: 

On Tue, 8 Apr 2025 09:56:02 GMT, Hannes Walln?fer  wrote:

>> Please review an enhancement to allow switching between the traditional condensed footnote-style summary and the summary table format for inherited members (types, fields, methods and properties) that are inherited from included types. You can test the feature in [the doc bundle I uploaded][apidocs] or watch the short screencast below.
>> 
>> [apidocs]: https://cr.openjdk.org/~hannesw/8350920/api.00/java.base/module-summary.html
>> 
>> https://github.com/user-attachments/assets/0aaa1f8b-c18b-4922-b704-2b2cdc05ca79
>> 
>> I added two new protected methods to the `AbstractMemberWriter` class, `createInheritedSummaryTable` and `getInheritedSummaryId`. Otherwise this is mostly reusing existing functionality (we already had the feature to display the signature of an inherited method in the context of the current class).
>> 
>> The writers for non-inheritable members such as constructors or enum constants were simplified a bit by implementing formerly abstract methods in `AbstractMemberWriter` as concrete methods throwing `UnsupportedOperationException` so they don't have to be implemented as empty methods in these writers.
>> 
>> The UI to switch between member list presentations is implemented in `script.js.template`. If no summary list presentation is available (because the supertype is not part of the documentation bundle) nothing changes in the UI.
>> 
>> I added a `stripTags()` method to `Content` to return the plain text content with HTML tags stripped that could be used in a few other places. The patch also adds two new vector graphics files called right.svg and down.svg for the right and downwards pointing angle.
>
> Hannes Walln?fer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains six commits:
> 
>  - Merge branch 'master' into JDK-8350920
>  - Review feedback: replace local implementations of Content.stripTags()
>  - Merge branch 'master' into JDK-8350920
>  - Merge branch 'master' into JDK-8350920
>  - Add svg files
>  - 8350920: Allow inherited member summaries to be viewed inline

Thanks for the update, this looks good.

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

Marked as reviewed by nbenalla (Committer).

PR Review: https://git.openjdk.org/jdk/pull/23967#pullrequestreview-2749765869

From liach at openjdk.org  Tue Apr  8 17:26:23 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 8 Apr 2025 17:26:23 GMT
Subject: RFR: 8352389: Remove incidental whitespace in pre/code content
 [v3]
In-Reply-To: 
References: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>

Message-ID: 

On Thu, 20 Mar 2025 07:27:39 GMT, Hannes Walln?fer  wrote:

>> Please review a change to remove incidental whitespace commonly found at the beginning of `` tags in API documentation. 
>> 
>> In a nutshell, using `\n` or `{@code\n` adds an extra empty line at the beginning of the content, compared to just using `\n`. This is due to [HTML syntax](https://html.spec.whatwg.org/#the-pre-element:the-pre-element), which ignores a leading `\n` only if it immediately follows the opening `` tag. It causes leading blank lines in several hundred JDK code samples, such as [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/stream/package-summary.html#Reduction) and [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/Map.html#computeIfAbsent(K,java.util.function.Function)).
>> 
>> What makes the problem a bit more complicated is that we also need to remove any horizontal whitespace between the `` and `` tags, as that would otherwise add to the first content line line. 
>> 
>> The feature is implemented in `DocCommentParser` by parsing content of `` elements into a separate list buffer, and filtering the content when we encounter the `` close tag. This approach allows us to keep the logic in a single `normalizePreContent` method instead of spreading it all over `DocCommentParser`. The method uses a `DocTreeVisitor` in combination with a `State` enum to make sure pre content is only modified if all conditions are met (which involves inspecting up to the first three DocTrees).
>> 
>> Normalization is also performed for `{@literal\n`. Although `{@literal}` by itself does not cause the problem described above as it does not produce an HTML tag, any horizontal whitespace between `` and `{@literal` will cause the problem, so we err on the side of caution. 
>> 
>> This change solves the leading blank line issue in a lot of JDK code fragments, and probably many more in 3rd party Java code.
>
> Hannes Walln?fer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 14 commits:
> 
>  - Merge branch 'master' into JDK-8352389
>  - Improve test
>  - Add comment
>  - 8352389: Remove incidental whitespace in pre/code content
>  - Whitespace normalization in PrettyCheck becomes simpler
>  - Rename method
>  - Update comment
>  - Clean up code, add comments, tests and @bug id
>  - Updated copyright year in testSourceTab breaks test
>  - Update remaining doctree tests & copyright headers
>  - ... and 4 more: https://git.openjdk.org/jdk/compare/fb210e3a...5ec3bc04

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 503:

> 501:         if (mainTrees != null) {
> 502:             mainTrees.addAll(trees);
> 503:             trees = mainTrees;

Should we add `mainTrees = null;` after this line?

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1224:

> 1222:     /**
> 1223:      * Removes a newline character following a , {@code or {@literal tag at the
> 1224:      * beginning of  element content, as well as any space/tabs between the pre

Consider converting this to a plain comment as these are not valid javadoc

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1309:

> 1307:         for (var tree : trees) {
> 1308:             var visited = visitor.visit(tree, cx);
> 1309:             if (visited != null) {

Should we just fail if `visited == null`? Can it happen with any user input?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24112#discussion_r2033694953
PR Review Comment: https://git.openjdk.org/jdk/pull/24112#discussion_r2033696724
PR Review Comment: https://git.openjdk.org/jdk/pull/24112#discussion_r2033700330

From hannesw at openjdk.org  Tue Apr  8 17:53:14 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 17:53:14 GMT
Subject: RFR: 8352389: Remove incidental whitespace in pre/code content
 [v3]
In-Reply-To: 
References: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>

Message-ID: 

On Tue, 8 Apr 2025 17:22:24 GMT, Chen Liang  wrote:

>> Hannes Walln?fer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 14 commits:
>> 
>>  - Merge branch 'master' into JDK-8352389
>>  - Improve test
>>  - Add comment
>>  - 8352389: Remove incidental whitespace in pre/code content
>>  - Whitespace normalization in PrettyCheck becomes simpler
>>  - Rename method
>>  - Update comment
>>  - Clean up code, add comments, tests and @bug id
>>  - Updated copyright year in testSourceTab breaks test
>>  - Update remaining doctree tests & copyright headers
>>  - ... and 4 more: https://git.openjdk.org/jdk/compare/fb210e3a...5ec3bc04
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1309:
> 
>> 1307:         for (var tree : trees) {
>> 1308:             var visited = visitor.visit(tree, cx);
>> 1309:             if (visited != null) {
> 
> Should we just fail if `visited == null`? Can it happen with any user input?

I should have added a comment here: returning `null` from the visitor method means this tree should be dropped from the result. This happens for whitespace-only text between `` and `` and is part of successful normalization.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24112#discussion_r2033743314

From liach at openjdk.org  Tue Apr  8 18:11:21 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 8 Apr 2025 18:11:21 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 

Message-ID: 

On Tue, 8 Apr 2025 06:51:20 GMT, Hannes Walln?fer  wrote:

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

Such usage should be reflected in `testPreviewNoteTag`, which currently does not use it as open/close tags.

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

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

From hannesw at openjdk.org  Tue Apr  8 18:14:53 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 18:14:53 GMT
Subject: RFR: 8352389: Remove incidental whitespace in pre/code content
 [v4]
In-Reply-To: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>
References: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>
Message-ID: 

> Please review a change to remove incidental whitespace commonly found at the beginning of `` tags in API documentation. 
> 
> In a nutshell, using `\n` or `{@code\n` adds an extra empty line at the beginning of the content, compared to just using `\n`. This is due to [HTML syntax](https://html.spec.whatwg.org/#the-pre-element:the-pre-element), which ignores a leading `\n` only if it immediately follows the opening `` tag. It causes leading blank lines in several hundred JDK code samples, such as [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/stream/package-summary.html#Reduction) and [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/Map.html#computeIfAbsent(K,java.util.function.Function)).
> 
> What makes the problem a bit more complicated is that we also need to remove any horizontal whitespace between the `` and `` tags, as that would otherwise add to the first content line line. 
> 
> The feature is implemented in `DocCommentParser` by parsing content of `` elements into a separate list buffer, and filtering the content when we encounter the `` close tag. This approach allows us to keep the logic in a single `normalizePreContent` method instead of spreading it all over `DocCommentParser`. The method uses a `DocTreeVisitor` in combination with a `State` enum to make sure pre content is only modified if all conditions are met (which involves inspecting up to the first three DocTrees).
> 
> Normalization is also performed for `{@literal\n`. Although `{@literal}` by itself does not cause the problem described above as it does not produce an HTML tag, any horizontal whitespace between `` and `{@literal` will cause the problem, so we err on the side of caution. 
> 
> This change solves the leading blank line issue in a lot of JDK code fragments, and probably many more in 3rd party Java code.

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Review feedback

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24112/files
  - new: https://git.openjdk.org/jdk/pull/24112/files/5ec3bc04..69584152

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24112&range=03
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24112&range=02-03

  Stats: 8 lines in 1 file changed: 2 ins; 4 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/24112.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24112/head:pull/24112

PR: https://git.openjdk.org/jdk/pull/24112

From hannesw at openjdk.org  Tue Apr  8 18:22:12 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 18:22:12 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 

Message-ID: 

On Tue, 8 Apr 2025 18:08:57 GMT, Chen Liang  wrote:

>> 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.)
>
> Such usage should be reflected in `testPreviewNoteTag`, which currently does not use it as open/close tags.

The problem is the Taglet class is part of the build system, and I don't think we have a way to test these build classes (I coulndn't find any tests for the other build Taglets). I could replicate the Taglet class in the test, but that doesn't seem like a good solution either.

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

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

From liach at openjdk.org  Tue Apr  8 18:35:11 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 8 Apr 2025 18:35:11 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 

Message-ID: <3g1znPCkrXwFs7KpaCvr6A6bfVyt68phdhDnNZRmluU=.61114b79-03ff-4be4-a0a0-f92c985eb3e2@github.com>

On Tue, 8 Apr 2025 18:19:21 GMT, Hannes Walln?fer  wrote:

>> Such usage should be reflected in `testPreviewNoteTag`, which currently does not use it as open/close tags.
>
> The problem is the Taglet class is part of the build system, and I don't think we have a way to test these build classes (I coulndn't find any tests for the other build Taglets). I could replicate the Taglet class in the test, but that doesn't seem like a good solution either.

Can we have a usage example of this tag somewhere then?

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

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

From liach at openjdk.org  Tue Apr  8 18:35:18 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 8 Apr 2025 18:35:18 GMT
Subject: RFR: 8352389: Remove incidental whitespace in pre/code content
 [v4]
In-Reply-To: 
References: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>

Message-ID: 

On Tue, 8 Apr 2025 18:14:53 GMT, Hannes Walln?fer  wrote:

>> Please review a change to remove incidental whitespace commonly found at the beginning of `` tags in API documentation. 
>> 
>> In a nutshell, using `\n` or `{@code\n` adds an extra empty line at the beginning of the content, compared to just using `\n`. This is due to [HTML syntax](https://html.spec.whatwg.org/#the-pre-element:the-pre-element), which ignores a leading `\n` only if it immediately follows the opening `` tag. It causes leading blank lines in several hundred JDK code samples, such as [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/stream/package-summary.html#Reduction) and [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/Map.html#computeIfAbsent(K,java.util.function.Function)).
>> 
>> What makes the problem a bit more complicated is that we also need to remove any horizontal whitespace between the `` and `` tags, as that would otherwise add to the first content line line. 
>> 
>> The feature is implemented in `DocCommentParser` by parsing content of `` elements into a separate list buffer, and filtering the content when we encounter the `` close tag. This approach allows us to keep the logic in a single `normalizePreContent` method instead of spreading it all over `DocCommentParser`. The method uses a `DocTreeVisitor` in combination with a `State` enum to make sure pre content is only modified if all conditions are met (which involves inspecting up to the first three DocTrees).
>> 
>> Normalization is also performed for `{@literal\n`. Although `{@literal}` by itself does not cause the problem described above as it does not produce an HTML tag, any horizontal whitespace between `` and `{@literal` will cause the problem, so we err on the side of caution. 
>> 
>> This change solves the leading blank line issue in a lot of JDK code fragments, and probably many more in 3rd party Java code.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Review feedback

LGTM

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24112#pullrequestreview-2751060111

From hannesw at openjdk.org  Tue Apr  8 18:49:28 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 8 Apr 2025 18:49:28 GMT
Subject: Integrated: 8352389: Remove incidental whitespace in pre/code content
In-Reply-To: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>
References: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>
Message-ID: 

On Wed, 19 Mar 2025 11:26:32 GMT, Hannes Walln?fer  wrote:

> Please review a change to remove incidental whitespace commonly found at the beginning of `` tags in API documentation. 
> 
> In a nutshell, using `\n` or `{@code\n` adds an extra empty line at the beginning of the content, compared to just using `\n`. This is due to [HTML syntax](https://html.spec.whatwg.org/#the-pre-element:the-pre-element), which ignores a leading `\n` only if it immediately follows the opening `` tag. It causes leading blank lines in several hundred JDK code samples, such as [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/stream/package-summary.html#Reduction) and [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/Map.html#computeIfAbsent(K,java.util.function.Function)).
> 
> What makes the problem a bit more complicated is that we also need to remove any horizontal whitespace between the `` and `` tags, as that would otherwise add to the first content line line. 
> 
> The feature is implemented in `DocCommentParser` by parsing content of `` elements into a separate list buffer, and filtering the content when we encounter the `` close tag. This approach allows us to keep the logic in a single `normalizePreContent` method instead of spreading it all over `DocCommentParser`. The method uses a `DocTreeVisitor` in combination with a `State` enum to make sure pre content is only modified if all conditions are met (which involves inspecting up to the first three DocTrees).
> 
> Normalization is also performed for `{@literal\n`. Although `{@literal}` by itself does not cause the problem described above as it does not produce an HTML tag, any horizontal whitespace between `` and `{@literal` will cause the problem, so we err on the side of caution. 
> 
> This change solves the leading blank line issue in a lot of JDK code fragments, and probably many more in 3rd party Java code.

This pull request has now been integrated.

Changeset: 24ff96af
Author:    Hannes Walln?fer 
URL:       https://git.openjdk.org/jdk/commit/24ff96afe41b62275fe8635e477ecc04bff93123
Stats:     352 lines in 7 files changed: 340 ins; 3 del; 9 mod

8352389: Remove incidental whitespace in pre/code content

Reviewed-by: liach

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

PR: https://git.openjdk.org/jdk/pull/24112

From hannesw at openjdk.org  Wed Apr  9 00:49:45 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 9 Apr 2025 00:49:45 GMT
Subject: RFR: 8348282: Add option for syntax highlighting in javadoc
 snippets [v2]
In-Reply-To: 
References: 
Message-ID: 

> Please review a change to add a `javadoc` option to enable syntax highlighting for code fragments in snippets and  `` tags. The new `--syntax-highlight` option uses the [highlight.js] JavaScript library and supports Java, Properties, XML, HTML and JSON. The option is enabled in the JDK API docs target, [generated output is available here](https://cr.openjdk.org/~hannesw/8348282/api.00/index.html).

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Adjust CSS spacings, remove whitespace

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24417/files
  - new: https://git.openjdk.org/jdk/pull/24417/files/dd766914..2700131d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24417&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24417&range=00-01

  Stats: 3 lines in 2 files changed: 0 ins; 0 del; 3 mod
  Patch: https://git.openjdk.org/jdk/pull/24417.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24417/head:pull/24417

PR: https://git.openjdk.org/jdk/pull/24417

From hannesw at openjdk.org  Wed Apr  9 01:00:56 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 9 Apr 2025 01:00:56 GMT
Subject: RFR: 8348282: Add option for syntax highlighting in javadoc
 snippets [v3]
In-Reply-To: 
References: 
Message-ID: 

> Please review a change to add a `javadoc` option to enable syntax highlighting for code fragments in snippets and  `` tags. The new `--syntax-highlight` option uses the [highlight.js] JavaScript library and supports Java, Properties, XML, HTML and JSON. The option is enabled in the JDK API docs target, [generated output is available here](https://cr.openjdk.org/~hannesw/8348282/api.00/index.html).

Hannes Walln?fer has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains six additional commits since the last revision:

 - Merge branch 'master' into JDK-8348282
 - Adjust CSS spacings, remove whitespace
 - Remove trailing spaces
 - Brigthen variable color
 - Fix regular expression for type arguments
 - 8348282: Add option for syntax highlighting in javadoc snippets

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24417/files
  - new: https://git.openjdk.org/jdk/pull/24417/files/2700131d..af50d173

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24417&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24417&range=01-02

  Stats: 21918 lines in 734 files changed: 15501 ins; 4680 del; 1737 mod
  Patch: https://git.openjdk.org/jdk/pull/24417.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24417/head:pull/24417

PR: https://git.openjdk.org/jdk/pull/24417

From hannesw at openjdk.org  Wed Apr  9 04:15:20 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 9 Apr 2025 04:15:20 GMT
Subject: RFR: 8348282: Add option for syntax highlighting in javadoc
 snippets [v4]
In-Reply-To: 
References: 
Message-ID: 

> Please review a change to add a `javadoc` option to enable syntax highlighting for code fragments in snippets and  `` tags. The new `--syntax-highlight` option uses the [highlight.js] JavaScript library and supports Java, Properties, XML, HTML and JSON. The option is enabled in the JDK API docs target, [generated output is available here](https://cr.openjdk.org/~hannesw/8348282/api.00/index.html).

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Adjust color palette

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24417/files
  - new: https://git.openjdk.org/jdk/pull/24417/files/af50d173..05fc1a4a

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24417&range=03
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24417&range=02-03

  Stats: 3 lines in 2 files changed: 0 ins; 0 del; 3 mod
  Patch: https://git.openjdk.org/jdk/pull/24417.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24417/head:pull/24417

PR: https://git.openjdk.org/jdk/pull/24417

From ihse at openjdk.org  Wed Apr  9 10:43:42 2025
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Wed, 9 Apr 2025 10:43:42 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 
Message-ID: 

On Fri, 31 Jan 2025 16:19:17 GMT, Hannes Walln?fer  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  [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.

Build change look trivially fine.

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

Marked as reviewed by ihse (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23395#pullrequestreview-2753024152

From ihse at openjdk.org  Wed Apr  9 15:09:58 2025
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Wed, 9 Apr 2025 15:09:58 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v6]
In-Reply-To: 
References: <0MB7FLFNfaGEWssr9X54UJ_iZNFWBJkxQ1yusP7fsuY=.3f9f3de5-fe84-48e6-9449-626cac42da0b@github.com>

Message-ID: <_YOUyzMbSEXFduCKVgyis37kwTlGSjBbP8VlFu3xQpU=.9b668e2a-8f91-476d-8914-13dc33a0b9e5@github.com>

On Thu, 11 May 2023 20:21:57 GMT, Justin Lu  wrote:

>> This PR converts Unicode sequences to UTF-8 native in .properties file. (Excluding the Unicode space and tab sequence). The conversion was done using native2ascii.
>> 
>> In addition, the build logic is adjusted to support reading in the .properties files as UTF-8 during the conversion from .properties file to .java ListResourceBundle file.
>
> Justin Lu has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 16 commits:
> 
>  - Convert the merged master changes to UTF-8
>  - Merge master and fix conflicts
>  - Close streams when finished loading into props
>  - Adjust CF test to read in with UTF-8 to fix failing test
>  - Reconvert CS.properties to UTF-8
>  - Revert all changes to CurrencySymbols.properties
>  - Bug6204853 should not be converted
>  - Copyright year for CompileProperties
>  - Redo translation for CS.properties
>  - Spot convert CurrencySymbols.properties
>  - ... and 6 more: https://git.openjdk.org/jdk/compare/4386d42d...f15b373a

src/java.xml/share/classes/com/sun/org/apache/xml/internal/serializer/Encodings.properties line 22:

> 20: # Peter Smolik
> 21: Cp1250 WINDOWS-1250 0x00FF
> 22: # Patch attributed to havardw at underdusken.no (H?vard Wigtil)

This does not seem to have been a correct conversion.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/12726#discussion_r2035582242

From rriggs at openjdk.org  Wed Apr  9 15:48:40 2025
From: rriggs at openjdk.org (Roger Riggs)
Date: Wed, 9 Apr 2025 15:48:40 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 
Message-ID: 

On Fri, 31 Jan 2025 16:19:17 GMT, Hannes Walln?fer  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  [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.

For methods that have "@PreviewFeature(feature = PreviewFeature.Feature.VALUE_OBJECTS, reflective=true)" annotations
the first (summary) line in the list of methods is "Preview." without any decoration. Is that intended?

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

PR Comment: https://git.openjdk.org/jdk/pull/23395#issuecomment-2790167667

From hannesw at openjdk.org  Wed Apr  9 17:26:50 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 9 Apr 2025 17:26:50 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 

Message-ID: 

On Wed, 9 Apr 2025 15:45:41 GMT, Roger Riggs  wrote:

> For methods that have "@PreviewFeature(feature = PreviewFeature.Feature.VALUE_OBJECTS, reflective=true)" annotations the first (summary) line in the list of methods is "Preview." without any decoration. Is that intended?

Yes, that's intended. Not very pretty, but hard to miss.

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

PR Comment: https://git.openjdk.org/jdk/pull/23395#issuecomment-2790448425

From rriggs at openjdk.org  Wed Apr  9 17:58:44 2025
From: rriggs at openjdk.org (Roger Riggs)
Date: Wed, 9 Apr 2025 17:58:44 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 
Message-ID: 

On Fri, 31 Jan 2025 16:19:17 GMT, Hannes Walln?fer  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  [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.

Yuck.  It would, IMHO, look better if it was a BOLD prefix of the first sentence. i.e.

**Preview Feature:** Checks that the specified object reference is an identity object.

$.02

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

PR Comment: https://git.openjdk.org/jdk/pull/23395#issuecomment-2790517937

From jlu at openjdk.org  Wed Apr  9 21:28:41 2025
From: jlu at openjdk.org (Justin Lu)
Date: Wed, 9 Apr 2025 21:28:41 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v6]
In-Reply-To: <_YOUyzMbSEXFduCKVgyis37kwTlGSjBbP8VlFu3xQpU=.9b668e2a-8f91-476d-8914-13dc33a0b9e5@github.com>
References: <0MB7FLFNfaGEWssr9X54UJ_iZNFWBJkxQ1yusP7fsuY=.3f9f3de5-fe84-48e6-9449-626cac42da0b@github.com>

 <_YOUyzMbSEXFduCKVgyis37kwTlGSjBbP8VlFu3xQpU=.9b668e2a-8f91-476d-8914-13dc33a0b9e5@github.com>
Message-ID: 

On Wed, 9 Apr 2025 15:06:32 GMT, Magnus Ihse Bursie  wrote:

>> Justin Lu has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 16 commits:
>> 
>>  - Convert the merged master changes to UTF-8
>>  - Merge master and fix conflicts
>>  - Close streams when finished loading into props
>>  - Adjust CF test to read in with UTF-8 to fix failing test
>>  - Reconvert CS.properties to UTF-8
>>  - Revert all changes to CurrencySymbols.properties
>>  - Bug6204853 should not be converted
>>  - Copyright year for CompileProperties
>>  - Redo translation for CS.properties
>>  - Spot convert CurrencySymbols.properties
>>  - ... and 6 more: https://git.openjdk.org/jdk/compare/4386d42d...f15b373a
>
> src/java.xml/share/classes/com/sun/org/apache/xml/internal/serializer/Encodings.properties line 22:
> 
>> 20: # Peter Smolik
>> 21: Cp1250 WINDOWS-1250 0x00FF
>> 22: # Patch attributed to havardw at underdusken.no (H?vard Wigtil)
> 
> This does not seem to have been a correct conversion.

Right, that `?` looks to have been incorrectly converted during the ISO-8859-1 to UTF-8 conversion. (I can't find the script used for conversion as this change is from some time ago.)

Since the change occurs in a comment (thankfully), it should be harmless and the next upstream update of this file would overwrite this incorrect change. However, this file does not seem to be updated that often, so I can also file an issue to correct this if you would prefer that.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/12726#discussion_r2036165417

From ihse at openjdk.org  Thu Apr 10 07:34:37 2025
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Thu, 10 Apr 2025 07:34:37 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v6]
In-Reply-To: 
References: <0MB7FLFNfaGEWssr9X54UJ_iZNFWBJkxQ1yusP7fsuY=.3f9f3de5-fe84-48e6-9449-626cac42da0b@github.com>

 <_YOUyzMbSEXFduCKVgyis37kwTlGSjBbP8VlFu3xQpU=.9b668e2a-8f91-476d-8914-13dc33a0b9e5@github.com>

Message-ID: 

On Thu, 10 Apr 2025 07:31:37 GMT, Magnus Ihse Bursie  wrote:

>> Right, that `?` looks to have been incorrectly converted during the ISO-8859-1 to UTF-8 conversion. (I can't find the script used for conversion as this change is from some time ago.)
>> 
>> Since the change occurs in a comment (thankfully), it should be harmless and the next upstream update of this file would overwrite this incorrect change. However, this file does not seem to be updated that often, so I can also file an issue to correct this if you would prefer that.
>
> You don't have to do that, I'm working on an omnibus UTF-8 fixing PR right now, where I will include a fix for this as well.

If anything, I might be a bit worried that there are more incorrect conversions stemming from this PR, that my automated tools and manual scanning has not revealed.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/12726#discussion_r2036696723

From ihse at openjdk.org  Thu Apr 10 07:34:37 2025
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Thu, 10 Apr 2025 07:34:37 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v6]
In-Reply-To: 
References: <0MB7FLFNfaGEWssr9X54UJ_iZNFWBJkxQ1yusP7fsuY=.3f9f3de5-fe84-48e6-9449-626cac42da0b@github.com>

 <_YOUyzMbSEXFduCKVgyis37kwTlGSjBbP8VlFu3xQpU=.9b668e2a-8f91-476d-8914-13dc33a0b9e5@github.com>

Message-ID: 

On Wed, 9 Apr 2025 21:26:15 GMT, Justin Lu  wrote:

>> src/java.xml/share/classes/com/sun/org/apache/xml/internal/serializer/Encodings.properties line 22:
>> 
>>> 20: # Peter Smolik
>>> 21: Cp1250 WINDOWS-1250 0x00FF
>>> 22: # Patch attributed to havardw at underdusken.no (H?vard Wigtil)
>> 
>> This does not seem to have been a correct conversion.
>
> Right, that `?` looks to have been incorrectly converted during the ISO-8859-1 to UTF-8 conversion. (I can't find the script used for conversion as this change is from some time ago.)
> 
> Since the change occurs in a comment (thankfully), it should be harmless and the next upstream update of this file would overwrite this incorrect change. However, this file does not seem to be updated that often, so I can also file an issue to correct this if you would prefer that.

You don't have to do that, I'm working on an omnibus UTF-8 fixing PR right now, where I will include a fix for this as well.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/12726#discussion_r2036695622

From eirbjo at openjdk.org  Thu Apr 10 08:10:42 2025
From: eirbjo at openjdk.org (Eirik =?UTF-8?B?QmrDuHJzbsO4cw==?=)
Date: Thu, 10 Apr 2025 08:10:42 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v6]
In-Reply-To: 
References: <0MB7FLFNfaGEWssr9X54UJ_iZNFWBJkxQ1yusP7fsuY=.3f9f3de5-fe84-48e6-9449-626cac42da0b@github.com>

 <_YOUyzMbSEXFduCKVgyis37kwTlGSjBbP8VlFu3xQpU=.9b668e2a-8f91-476d-8914-13dc33a0b9e5@github.com>

Message-ID: <6c6DqyCqyPonBZgUU8BpYJR3JQvMXjWm9ulq4SN25Do=.77775825-716d-4908-ae24-c4cf1ead78a5@github.com>

On Thu, 10 Apr 2025 07:32:18 GMT, Magnus Ihse Bursie  wrote:

>> You don't have to do that, I'm working on an omnibus UTF-8 fixing PR right now, where I will include a fix for this as well.
>
> If anything, I might be a bit worried that there are more incorrect conversions stemming from this PR, that my automated tools and manual scanning has not revealed.

Some observations: 

1: This PR seems to have been abondoned, so perhaps this discussion belongs in #15694 ?

2: The `?` (Unicode 'Latin small letter a with ring above' U+00E5) was correctly encoded as 0xEF in ISO-8859-1 previous to this change.

3: The conversion changed this `0xEF` to the three-byte sequence `ef bf bd`

4: This is as-if the file was incorrctly decoded using UTF-8, then encoded using UTF-8:

byte[] origBytes = "?".getBytes(StandardCharsets.ISO_8859_1);
String decoded = new String(origBytes, StandardCharsets.UTF_8);
byte[] encoded = decoded.getBytes(StandardCharsets.UTF_8);
String hex = HexFormat.of().formatHex(encoded);
assertEquals("efbfbd", hex);
``` 

Like @magicus I'm worried that similar incorrect decoding could have been introduced by the same script in other files.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/12726#discussion_r2036767319

From ihse at openjdk.org  Thu Apr 10 08:38:38 2025
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Thu, 10 Apr 2025 08:38:38 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v6]
In-Reply-To: <6c6DqyCqyPonBZgUU8BpYJR3JQvMXjWm9ulq4SN25Do=.77775825-716d-4908-ae24-c4cf1ead78a5@github.com>
References: <0MB7FLFNfaGEWssr9X54UJ_iZNFWBJkxQ1yusP7fsuY=.3f9f3de5-fe84-48e6-9449-626cac42da0b@github.com>

 <_YOUyzMbSEXFduCKVgyis37kwTlGSjBbP8VlFu3xQpU=.9b668e2a-8f91-476d-8914-13dc33a0b9e5@github.com>

 <6c6DqyCqyPonBZgUU8BpYJR3JQvMXjWm9ulq4SN25Do=.77775825-716d-4908-ae24-c4cf1ead78a5@github.com>
Message-ID: 

On Thu, 10 Apr 2025 08:08:02 GMT, Eirik Bj?rsn?s  wrote:

>> If anything, I might be a bit worried that there are more incorrect conversions stemming from this PR, that my automated tools and manual scanning has not revealed.
>
> Some observations: 
> 
> 1: This PR seems to have been abondoned, so perhaps this discussion belongs in #15694 ?
> 
> 2: The `?` (Unicode 'Latin small letter a with ring above' U+00E5) was correctly encoded as 0xEF in ISO-8859-1 previous to this change.
> 
> 3: The conversion changed this `0xEF` to the three-byte sequence `ef bf bd`
> 
> 4: This is as-if the file was incorrctly decoded using UTF-8, then encoded using UTF-8:
> 
> 
> byte[] origBytes = "?".getBytes(StandardCharsets.ISO_8859_1);
> String decoded = new String(origBytes, StandardCharsets.UTF_8);
> byte[] encoded = decoded.getBytes(StandardCharsets.UTF_8);
> String hex = HexFormat.of().formatHex(encoded);
> assertEquals("efbfbd", hex);
> ``` 
> 
> Like @magicus I'm worried that similar incorrect decoding could have been introduced by the same script in other files.

> This PR seems to have been abondoned, so perhaps this discussion belongs in https://github.com/openjdk/jdk/pull/15694 ?

Oh, I didn't notice this was supplanted by another PR. It might be better to continue there, yes. Even if closed PRs seldom are the best places to conduct discussions, I think it might be a good idea to scrutinize all files modified by this script.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/12726#discussion_r2036820765

From ihse at openjdk.org  Thu Apr 10 08:41:45 2025
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Thu, 10 Apr 2025 08:41:45 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v2]
In-Reply-To: 
References: 

Message-ID: 

On Wed, 13 Sep 2023 17:38:28 GMT, Justin Lu  wrote:

>> JDK .properties files still use ISO-8859-1 encoding with escape sequences. It would improve readability to see the native characters instead of escape sequences (especially for the L10n process). The majority of files changed are localized resource files.
>> 
>> This change converts the Unicode escape sequences in the JDK .properties files (both in src and test) to UTF-8 native characters. Additionally, the build logic is adjusted to read the .properties files in UTF-8 while generating the ListResourceBundle files.
>> 
>> The only escape sequence not converted was `\u0020` as this is used to denote intentional trailing white space. (E.g. `key=This is the value:\u0020`)
>> 
>> The conversion was done using native2ascii with options `-reverse -encoding UTF-8`.
>> 
>> If this PR is integrated, the IDE default encoding for .properties files need to be updated to UTF-8. (IntelliJ IDEA locks .properties files as ISO-8859-1 unless manually changed).
>
> Justin Lu has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Replace InputStreamReader with BufferedReader

Continuing the discussion that was started at a predecessor to this PR, https://github.com/openjdk/jdk/pull/12726#discussion_r2035582242. At least one incorrect conversion has been found in this PR. It might be worthwhile to double- and triple-check all the other conversions as well.

As part of https://bugs.openjdk.org/browse/JDK-8301971 I am trying various ways of detecting files without UTF-8 encoding, but it is still a bit of hit and miss, since there are no surefire way of telling which encoding a file has, only heuristics. So finding and following up potential sources of error is important.

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

PR Comment: https://git.openjdk.org/jdk/pull/15694#issuecomment-2791991649
PR Comment: https://git.openjdk.org/jdk/pull/15694#issuecomment-2791997157

From eirbjo at openjdk.org  Thu Apr 10 08:48:37 2025
From: eirbjo at openjdk.org (Eirik =?UTF-8?B?QmrDuHJzbsO4cw==?=)
Date: Thu, 10 Apr 2025 08:48:37 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v2]
In-Reply-To: 
References: 

Message-ID: <0q0gTsqIsYtmzAfNYbBXksUXKdZh2uzQ9yvSETKAP88=.137372e6-d63e-4539-b196-4bd9ef1ddd16@github.com>

On Wed, 13 Sep 2023 17:38:28 GMT, Justin Lu  wrote:

>> JDK .properties files still use ISO-8859-1 encoding with escape sequences. It would improve readability to see the native characters instead of escape sequences (especially for the L10n process). The majority of files changed are localized resource files.
>> 
>> This change converts the Unicode escape sequences in the JDK .properties files (both in src and test) to UTF-8 native characters. Additionally, the build logic is adjusted to read the .properties files in UTF-8 while generating the ListResourceBundle files.
>> 
>> The only escape sequence not converted was `\u0020` as this is used to denote intentional trailing white space. (E.g. `key=This is the value:\u0020`)
>> 
>> The conversion was done using native2ascii with options `-reverse -encoding UTF-8`.
>> 
>> If this PR is integrated, the IDE default encoding for .properties files need to be updated to UTF-8. (IntelliJ IDEA locks .properties files as ISO-8859-1 unless manually changed).
>
> Justin Lu has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Replace InputStreamReader with BufferedReader

FWIW, I checked out the revision of the commit previous to this change and found the following:

% git checkout b55e418a077791b39992042411cde97f68dc39fe^ 
% find src -name "*.properties" | xargs file | grep -v ASCII
src/java.xml/share/classes/com/sun/org/apache/xml/internal/serializer/Encodings.properties: 
  ISO-8859 text
src/java.xml.crypto/share/classes/com/sun/org/apache/xml/internal/security/resource/xmlsecurity_de.properties:
  Unicode text, UTF-8 text, with very long lines (322)

Which indicates that that this is the only non-ASCII, non-UTF-8 property file. So we may be lucky.

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

PR Comment: https://git.openjdk.org/jdk/pull/15694#issuecomment-2792014164

From hannesw at openjdk.org  Thu Apr 10 09:29:32 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 10 Apr 2025 09:29:32 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 

Message-ID: 

On Wed, 9 Apr 2025 17:55:26 GMT, Roger Riggs  wrote:

> It would, IMHO, look better if it was a BOLD prefix of the first sentence. 

I partly agree, but I also think the stamp-like nature serves a purpose. Note that deprecated members and restricted methods use the same format, sometimes adding a full sentence:

https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/Runtime.html#method-summary
https://docs.oracle.com/en/java/javase/24/docs/api/java.desktop/java/applet/Applet.html#method-summary 

So I think it could be improved, but should be part of an effort to improve marking of "special" elements in general.

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

PR Comment: https://git.openjdk.org/jdk/pull/23395#issuecomment-2792128552

From ihse at openjdk.org  Thu Apr 10 09:45:56 2025
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Thu, 10 Apr 2025 09:45:56 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v2]
In-Reply-To: 
References: 

Message-ID: 

On Wed, 13 Sep 2023 17:38:28 GMT, Justin Lu  wrote:

>> JDK .properties files still use ISO-8859-1 encoding with escape sequences. It would improve readability to see the native characters instead of escape sequences (especially for the L10n process). The majority of files changed are localized resource files.
>> 
>> This change converts the Unicode escape sequences in the JDK .properties files (both in src and test) to UTF-8 native characters. Additionally, the build logic is adjusted to read the .properties files in UTF-8 while generating the ListResourceBundle files.
>> 
>> The only escape sequence not converted was `\u0020` as this is used to denote intentional trailing white space. (E.g. `key=This is the value:\u0020`)
>> 
>> The conversion was done using native2ascii with options `-reverse -encoding UTF-8`.
>> 
>> If this PR is integrated, the IDE default encoding for .properties files need to be updated to UTF-8. (IntelliJ IDEA locks .properties files as ISO-8859-1 unless manually changed).
>
> Justin Lu has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Replace InputStreamReader with BufferedReader

Thanks for checking!

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

PR Comment: https://git.openjdk.org/jdk/pull/15694#issuecomment-2792170460

From hannesw at openjdk.org  Thu Apr 10 13:05:36 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 10 Apr 2025 13:05:36 GMT
Subject: RFR: 8348282: Add option for syntax highlighting in javadoc
 snippets [v4]
In-Reply-To: 
References: 

Message-ID: 

On Wed, 9 Apr 2025 04:15:20 GMT, Hannes Walln?fer  wrote:

>> Please review a change to add a `javadoc` option to enable syntax highlighting for code fragments in snippets and  `` tags. The new `--syntax-highlight` option uses the [highlight.js] JavaScript library and supports Java, Properties, XML, HTML and JSON. The option is enabled in the JDK API docs target, [generated output is available here](https://cr.openjdk.org/~hannesw/8348282/api.00/index.html).
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Adjust color palette

Here's a selection of code fragments from the sample docs using syntax highlighting:

 - [Thread example](https://cr.openjdk.org/~hannesw/8348282/api.00/java.base/java/lang/Thread.html#snippet-java.lang.Thread1)
 - [Doclet example](https://cr.openjdk.org/~hannesw/8348282/api.00/jdk.javadoc/jdk/javadoc/doclet/package-summary.html#example-heading)
 - [PropertyResourceBundle](https://cr.openjdk.org/~hannesw/8348282/api.00/java.base/java/util/PropertyResourceBundle.html#snippet-java.util.PropertyResourceBundle1)
- [ListResourceBundle](https://cr.openjdk.org/~hannesw/8348282/api.00/java.base/java/util/ListResourceBundle.html#snippet-java.util.ListResourceBundle1)
- [ClassFile example](https://cr.openjdk.org/~hannesw/8348282/api.00/java.base/java/lang/classfile/attribute/package-summary.html#snippet-java.lang.classfile.attribute1)
- [MethodHandles example](https://cr.openjdk.org/~hannesw/8348282/api.00/java.base/java/lang/invoke/MethodHandles.html#snippet-collectArguments(java.lang.invoke.MethodHandle,int,java.lang.invoke.MethodHandle)1)

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

PR Comment: https://git.openjdk.org/jdk/pull/24417#issuecomment-2792716273

From liach at openjdk.org  Thu Apr 10 15:58:30 2025
From: liach at openjdk.org (Chen Liang)
Date: Thu, 10 Apr 2025 15:58:30 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 
Message-ID: 

On Fri, 31 Jan 2025 16:19:17 GMT, Hannes Walln?fer  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  [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.

The code here and the usage example look good. We might integrate once Roger thinks the format looks good.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23395#pullrequestreview-2757371812

From jlu at openjdk.org  Thu Apr 10 18:47:53 2025
From: jlu at openjdk.org (Justin Lu)
Date: Thu, 10 Apr 2025 18:47:53 GMT
Subject: RFR: 8301991: Convert l10n properties resource bundles to UTF-8
 native [v2]
In-Reply-To: <0q0gTsqIsYtmzAfNYbBXksUXKdZh2uzQ9yvSETKAP88=.137372e6-d63e-4539-b196-4bd9ef1ddd16@github.com>
References: 

 <0q0gTsqIsYtmzAfNYbBXksUXKdZh2uzQ9yvSETKAP88=.137372e6-d63e-4539-b196-4bd9ef1ddd16@github.com>
Message-ID: <9aQcWun5KNgHgELVwkc3478_RtqfhRL1Cxvyn2Yl0Nw=.07ee596f-e738-4796-8d27-14621ed8860c@github.com>

On Thu, 10 Apr 2025 08:44:28 GMT, Eirik Bj?rsn?s  wrote:

>> Justin Lu has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Replace InputStreamReader with BufferedReader
>
> FWIW, I checked out the revision of the commit previous to this change and found the following:
> 
> 
> % git checkout b55e418a077791b39992042411cde97f68dc39fe^ 
> % find src -name "*.properties" | xargs file | grep -v ASCII
> src/java.xml/share/classes/com/sun/org/apache/xml/internal/serializer/Encodings.properties: 
>   ISO-8859 text
> src/java.xml.crypto/share/classes/com/sun/org/apache/xml/internal/security/resource/xmlsecurity_de.properties:
>   Unicode text, UTF-8 text, with very long lines (322)
> 
> 
> Which indicates that that this is the only non-ASCII, non-UTF-8 property file. So we may be lucky.

This conversion was performed under the assumption of ASCII set and Unicode escape sequences, which is the format we expect for the translation process for .properties files. That file should have been omitted from this change. Thank you @eirbjo and @magicus for the analysis and checking!

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

PR Comment: https://git.openjdk.org/jdk/pull/15694#issuecomment-2794828598

From rriggs at openjdk.org  Thu Apr 10 19:29:26 2025
From: rriggs at openjdk.org (Roger Riggs)
Date: Thu, 10 Apr 2025 19:29:26 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 
Message-ID: 

On Fri, 31 Jan 2025 16:19:17 GMT, Hannes Walln?fer  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  [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.

The format and presentation looks fine. 
I did not review the implementation.

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

Marked as reviewed by rriggs (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23395#pullrequestreview-2758114095

From hannesw at openjdk.org  Fri Apr 11 13:28:38 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 11 Apr 2025 13:28:38 GMT
Subject: Integrated: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 
Message-ID: 

On Fri, 31 Jan 2025 16:19:17 GMT, Hannes Walln?fer  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  [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.

This pull request has now been integrated.

Changeset: 2321722a
Author:    Hannes Walln?fer 
URL:       https://git.openjdk.org/jdk/commit/2321722a45c0ae8a2fd0aabfa2aa01d3b801c832
Stats:     357 lines in 8 files changed: 297 ins; 39 del; 21 mod

8346109: Create JDK taglet for additional preview notes

Reviewed-by: ihse, liach, rriggs

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

PR: https://git.openjdk.org/jdk/pull/23395

From hannesw at openjdk.org  Fri Apr 11 13:36:31 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 11 Apr 2025 13:36:31 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: 
References: 
Message-ID: 

On Fri, 31 Jan 2025 16:19:17 GMT, Hannes Walln?fer  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  [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.

I went ahead and integtated the PR. We can improve the feature based on how it works out in actual use.

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

PR Comment: https://git.openjdk.org/jdk/pull/23395#issuecomment-2796934892

From hannesw at openjdk.org  Fri Apr 11 13:36:32 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 11 Apr 2025 13:36:32 GMT
Subject: RFR: 8346109: Create JDK taglet for additional preview notes
In-Reply-To: <3g1znPCkrXwFs7KpaCvr6A6bfVyt68phdhDnNZRmluU=.61114b79-03ff-4be4-a0a0-f92c985eb3e2@github.com>
References: 

 <3g1znPCkrXwFs7KpaCvr6A6bfVyt68phdhDnNZRmluU=.61114b79-03ff-4be4-a0a0-f92c985eb3e2@github.com>
Message-ID: 

On Tue, 8 Apr 2025 18:32:16 GMT, Chen Liang  wrote:

>> The problem is the Taglet class is part of the build system, and I don't think we have a way to test these build classes (I coulndn't find any tests for the other build Taglets). I could replicate the Taglet class in the test, but that doesn't seem like a good solution either.
>
> Can we have a usage example of this tag somewhere then?

There is a usage example in the Taglet class comment.

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

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

From kcr at openjdk.org  Fri Apr 11 18:43:28 2025
From: kcr at openjdk.org (Kevin Rushforth)
Date: Fri, 11 Apr 2025 18:43:28 GMT
Subject: RFR: 8254622: Hide superclasses from conditionally exported
 packages [v2]
In-Reply-To: 
References: 

Message-ID: 

On Tue, 8 Apr 2025 09:02:25 GMT, Hannes Walln?fer  wrote:

>> Please review an enhancement to treat classes and interfaces that are not included and not unconditionally exported as hidden. This means they do not show up in the generated documentation even if they are implemented or extended by a documented type. 
>> 
>> This change makes the `@hidden` JavaDoc tag unnecessary in two internal base classes that previously used it, `jdk.internal.vm.vector.VectorSupport` and `jdk.internal.event.Event`. The generated documentation is unchanged.
>> 
>> The change also adds support for the `@hidden` JavaDoc tag in interfaces, which was previously missing, and adds coverage to `TestHiddenTag.java`.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Review feedback: add Utils.isVisible(TypeElement) method

I didn't review the code changes, but I did test this by building the JDK with this fix and using the javadoc tool from that JDK to build the JavaFX docs. The non-exported intermediate classes that we currently see (without this PR) in the class hierarchy are now elided from the docs as expected.

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

Marked as reviewed by kcr (Author).

PR Review: https://git.openjdk.org/jdk/pull/24446#pullrequestreview-2761262117

From liach at openjdk.org  Fri Apr 11 19:44:31 2025
From: liach at openjdk.org (Chen Liang)
Date: Fri, 11 Apr 2025 19:44:31 GMT
Subject: RFR: 8254622: Hide superclasses from conditionally exported
 packages [v2]
In-Reply-To: 
References: 

Message-ID: 

On Tue, 8 Apr 2025 09:02:25 GMT, Hannes Walln?fer  wrote:

>> Please review an enhancement to treat classes and interfaces that are not included and not unconditionally exported as hidden. This means they do not show up in the generated documentation even if they are implemented or extended by a documented type. 
>> 
>> This change makes the `@hidden` JavaDoc tag unnecessary in two internal base classes that previously used it, `jdk.internal.vm.vector.VectorSupport` and `jdk.internal.event.Event`. The generated documentation is unchanged.
>> 
>> The change also adds support for the `@hidden` JavaDoc tag in interfaces, which was previously missing, and adds coverage to `TestHiddenTag.java`.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Review feedback: add Utils.isVisible(TypeElement) method

The new isHidden utility looks good. Sorry for a late review.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24446#pullrequestreview-2761437931

From hannesw at openjdk.org  Sun Apr 13 10:11:33 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Sun, 13 Apr 2025 10:11:33 GMT
Subject: Integrated: 8254622: Hide superclasses from conditionally exported
 packages
In-Reply-To: 
References: 
Message-ID: <4FHbUdiOmwnhm63fitmIRgCo-EIzL3fhtwyzbF1ttEw=.4e6a260a-19f2-4dec-b046-62f8161233b2@github.com>

On Fri, 4 Apr 2025 13:36:19 GMT, Hannes Walln?fer  wrote:

> Please review an enhancement to treat classes and interfaces that are not included and not unconditionally exported as hidden. This means they do not show up in the generated documentation even if they are implemented or extended by a documented type. 
> 
> This change makes the `@hidden` JavaDoc tag unnecessary in two internal base classes that previously used it, `jdk.internal.vm.vector.VectorSupport` and `jdk.internal.event.Event`. The generated documentation is unchanged.
> 
> The change also adds support for the `@hidden` JavaDoc tag in interfaces, which was previously missing, and adds coverage to `TestHiddenTag.java`.

This pull request has now been integrated.

Changeset: 5d976089
Author:    Hannes Walln?fer 
URL:       https://git.openjdk.org/jdk/commit/5d9760897014c9a2cf0813af3ffbfb358ef55e31
Stats:     436 lines in 21 files changed: 352 ins; 29 del; 55 mod

8254622: Hide superclasses from conditionally exported packages

Reviewed-by: kcr, liach

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

PR: https://git.openjdk.org/jdk/pull/24446

From nbenalla at openjdk.org  Mon Apr 14 12:53:26 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Mon, 14 Apr 2025 12:53:26 GMT
Subject: RFR: 8346785: Potential infinite loop in JavadocTokenizer.ensures
Message-ID: 

Please review this patch to fix a potential infinite loop in `JavadocTokenizer.ensure` when `map.length` and `size + need` approach Interger.MAX_VALUE.

While I couldn't reproduce the issue even with large inputs (~1.9GB java file where almost the entire file is one javadoc comment), the fix is about correctness and prevention of UB in extreme cases.

TIA

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

Commit messages:
 - fix JdT.ensure

Changes: https://git.openjdk.org/jdk/pull/24620/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24620&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8346785
  Stats: 4 lines in 1 file changed: 0 ins; 0 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/24620.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24620/head:pull/24620

PR: https://git.openjdk.org/jdk/pull/24620

From liach at openjdk.org  Mon Apr 14 19:13:43 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 14 Apr 2025 19:13:43 GMT
Subject: RFR: 8346785: Potential infinite loop in JavadocTokenizer.ensures
In-Reply-To: 
References: 
Message-ID: 

On Mon, 14 Apr 2025 10:59:48 GMT, Nizar Benalla  wrote:

> Please review this patch to fix a potential infinite loop in `JavadocTokenizer.ensure` when `map.length` and `size + need` approach Interger.MAX_VALUE.
> 
> While I couldn't reproduce the issue even with large inputs (~1.9GB java file where almost the entire file is one javadoc comment), the fix is about correctness and prevention of UB in extreme cases.
> 
> TIA

Consider if `grow == 0`, the while loop still stalls infinitely. I think the best solution is, after `grow <<= 1;`, add a check in the loop like `if (grow <= 0) throw new IndexOutOfBoundsException();` and keeping everything else as-is.

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

Changes requested by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24620#pullrequestreview-2765418753

From vromero at openjdk.org  Tue Apr 15 14:15:50 2025
From: vromero at openjdk.org (Vicente Romero)
Date: Tue, 15 Apr 2025 14:15:50 GMT
Subject: RFR: 8346785: Potential infinite loop in JavadocTokenizer.ensures
In-Reply-To: 
References: 
Message-ID: <_rNiXjHMipmL0oEl3i4ZzsYHdXDj40Y45uGN6asFxhU=.2aac1d09-0295-4bb1-ac98-26094af6e509@github.com>

On Mon, 14 Apr 2025 10:59:48 GMT, Nizar Benalla  wrote:

> Please review this patch to fix a potential infinite loop in `JavadocTokenizer.ensure` when `map.length` and `size + need` approach Interger.MAX_VALUE.
> 
> While I couldn't reproduce the issue even with large inputs (~1.9GB java file where almost the entire file is one javadoc comment), the fix is about correctness and prevention of UB in extreme cases.
> 
> TIA

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavadocTokenizer.java line 309:

> 307: 
> 308:             while (need > grow && grow <= Integer.MAX_VALUE/2) {
> 309:                 grow <<= 1;

I wonder why `map` is not an `ArrayList` which already have a grow strategy. If this is because of performance issues I think that stop growing the array as soon as `grow > Integer.MAX_VALUE / 2` is a bit premature as there is still plenty of room for a less aggressive growing strategy

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24620#discussion_r2044679939

From syan at openjdk.org  Wed Apr 16 04:08:20 2025
From: syan at openjdk.org (SendaoYan)
Date: Wed, 16 Apr 2025 04:08:20 GMT
Subject: RFR: 8354766: Test TestUnexported.java javac build fails
Message-ID: 

Hi all,

The newly added test jdk/javadoc/doclet/testUnexported/TestUnexported.java javac build fails. This PR add depedencies to make javac build success. Test-fix only, change has been verified locally, no risk.

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

Commit messages:
 - 8354766: Test TestUnexported.java javac build fails

Changes: https://git.openjdk.org/jdk/pull/24673/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24673&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8354766
  Stats: 2 lines in 1 file changed: 2 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/24673.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24673/head:pull/24673

PR: https://git.openjdk.org/jdk/pull/24673

From nbenalla at openjdk.org  Wed Apr 16 18:01:55 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 16 Apr 2025 18:01:55 GMT
Subject: RFR: 8354766: Test TestUnexported.java javac build fails
In-Reply-To: 
References: 
Message-ID: <7I5GIWX3RgHlWfFXHT_msq1XCh-ayJILAT2LCoBBp6k=.77031105-4a99-4b86-a1b6-5da0f8486de6@github.com>

On Wed, 16 Apr 2025 04:03:24 GMT, SendaoYan  wrote:

> Hi all,
> 
> The newly added test jdk/javadoc/doclet/testUnexported/TestUnexported.java javac build fails. This PR add depedencies to make javac build success. Test-fix only, change has been verified locally, no risk.

Thank you Sendao, I can confirm that the test passes locally with these changes.

I will do a bit more testing before approving the PR.

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

PR Comment: https://git.openjdk.org/jdk/pull/24673#issuecomment-2810314333

From nbenalla at openjdk.org  Thu Apr 17 09:48:52 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Thu, 17 Apr 2025 09:48:52 GMT
Subject: RFR: 8354766: Test TestUnexported.java javac build fails
In-Reply-To: 
References: 
Message-ID: <3d4Ha8JDjhobGaZcX5cdNjW86DDQhD0BiYhm0aSETPs=.a1eba83d-f823-45e3-a112-2c12b249d391@github.com>

On Wed, 16 Apr 2025 04:03:24 GMT, SendaoYan  wrote:

> Hi all,
> 
> The newly added test jdk/javadoc/doclet/testUnexported/TestUnexported.java javac build fails. This PR add depedencies to make javac build success. Test-fix only, change has been verified locally, no risk.

This looks good.

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

Marked as reviewed by nbenalla (Committer).

PR Review: https://git.openjdk.org/jdk/pull/24673#pullrequestreview-2775190742

From jpai at openjdk.org  Thu Apr 17 09:58:46 2025
From: jpai at openjdk.org (Jaikiran Pai)
Date: Thu, 17 Apr 2025 09:58:46 GMT
Subject: RFR: 8354766: Test TestUnexported.java javac build fails
In-Reply-To: 
References: 
Message-ID: 

On Wed, 16 Apr 2025 04:03:24 GMT, SendaoYan  wrote:

> Hi all,
> 
> The newly added test jdk/javadoc/doclet/testUnexported/TestUnexported.java javac build fails. This PR add depedencies to make javac build success. Test-fix only, change has been verified locally, no risk.

Hello @sendaoYan, can you share the command that you used to launch these tests? We haven't noticed this compilation error in our CI yet. So although the proposed change looks reasonable, it would be good to understand why this hasn't been caught in our setup.

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

PR Comment: https://git.openjdk.org/jdk/pull/24673#issuecomment-2812372444

From jpai at openjdk.org  Thu Apr 17 10:57:45 2025
From: jpai at openjdk.org (Jaikiran Pai)
Date: Thu, 17 Apr 2025 10:57:45 GMT
Subject: RFR: 8354766: Test TestUnexported.java javac build fails
In-Reply-To: 
References: 
Message-ID: 

On Wed, 16 Apr 2025 04:03:24 GMT, SendaoYan  wrote:

> Hi all,
> 
> The newly added test jdk/javadoc/doclet/testUnexported/TestUnexported.java javac build fails. This PR add depedencies to make javac build success. Test-fix only, change has been verified locally, no risk.

Marked as reviewed by jpai (Reviewer).

I spoke to Nizar and also looked at the linked JBS issue. What's happening here is that this test uses a test library `/tools/lib` and one of the classes `JavacTask` in the test library references an internal API `com.sun.tools.javac.api.JavacTool`. Depending on which test triggers the usage of this `JavacTask`, it can so happen that this test library class will get compiled with a different set of compilation options. I believe (and we experimented locally too), on our CI setup where we launch several tests, this test library `JavacTask` gets compiled when running a test which has the right set of compilation options (including the necessary `--add-exports`). Thus when this `TestUnexported` test gets run later, jtreg finds that the test library class `JavacTask` is already compiled and available in the one of the classpath directories of this test class. So it doesn't trigger a compilation of `JavacTask` and instead reuses the already compiled on. Thus we don't see this failure in t
 hose situations.

On setups where this is failing, including when you explicitly launch only the TestUnexported test (`make test TEST=test/langtools/jdk/javadoc/doclet/testUnexported/TestUnexported.java`), the test library class `JavacTask` hasn't already been compiled and thus jtreg triggers compilation of that class and since this specific test doesn't use a `@modules` for exporting those internal packages, the compilation command doesn't add the explicit `--add-exports` and thus the compilation fails for the test library `JavacTask` class.

The non-deterministic compilation of test library classes is a known issue in jtreg. The proposed fix in this PR to get past this issue is the right solution for now.

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

PR Review: https://git.openjdk.org/jdk/pull/24673#pullrequestreview-2775349147
PR Comment: https://git.openjdk.org/jdk/pull/24673#issuecomment-2812496384

From syan at openjdk.org  Thu Apr 17 12:10:59 2025
From: syan at openjdk.org (SendaoYan)
Date: Thu, 17 Apr 2025 12:10:59 GMT
Subject: RFR: 8354766: Test TestUnexported.java javac build fails
In-Reply-To: 
References: 

Message-ID: <0OyeE3E5n-ED9R-03ME4arx8kOeK3vkf1nV1uCoq1jM=.a82aa524-2c56-4b75-88fc-a5cfe6577094@github.com>

On Thu, 17 Apr 2025 09:55:41 GMT, Jaikiran Pai  wrote:

> Hello @sendaoYan, can you share the command that you used to launch these tests? We haven't noticed this compilation error in our CI yet. So although the proposed change looks reasonable, it would be good to understand why this hasn't been caught in our setup.

rm -rf tmp ; jtreg -v:fail,error -nr -w tmp -jdk:build/linux-x86_64-server-release/images/jdk/ test/langtools/jdk/javadoc/doclet/testUnexported/TestUnexported.java

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

PR Comment: https://git.openjdk.org/jdk/pull/24673#issuecomment-2812661039

From syan at openjdk.org  Thu Apr 17 12:29:47 2025
From: syan at openjdk.org (SendaoYan)
Date: Thu, 17 Apr 2025 12:29:47 GMT
Subject: RFR: 8354766: Test TestUnexported.java javac build fails
In-Reply-To: <7I5GIWX3RgHlWfFXHT_msq1XCh-ayJILAT2LCoBBp6k=.77031105-4a99-4b86-a1b6-5da0f8486de6@github.com>
References: 
 <7I5GIWX3RgHlWfFXHT_msq1XCh-ayJILAT2LCoBBp6k=.77031105-4a99-4b86-a1b6-5da0f8486de6@github.com>
Message-ID: <5k2rVy_2cAMHjQFUFLkbLa6EuelwXerzIiaExP_W2ZM=.7e2d7fad-158e-4dd0-aad9-45a2278447ef@github.com>

On Wed, 16 Apr 2025 17:59:18 GMT, Nizar Benalla  wrote:

>> Hi all,
>> 
>> The newly added test jdk/javadoc/doclet/testUnexported/TestUnexported.java javac build fails. This PR add depedencies to make javac build success. Test-fix only, change has been verified locally, no risk.
>
> Thank you Sendao, I can confirm that the test passes locally with these changes.
> 
> I will do a bit more testing before approving the PR.

Thanks @nizarbenalla @jaikiran

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

PR Comment: https://git.openjdk.org/jdk/pull/24673#issuecomment-2812709556

From syan at openjdk.org  Thu Apr 17 12:29:48 2025
From: syan at openjdk.org (SendaoYan)
Date: Thu, 17 Apr 2025 12:29:48 GMT
Subject: Integrated: 8354766: Test TestUnexported.java javac build fails
In-Reply-To: 
References: 
Message-ID: <5Cwy2v27Asrf4-v_IAfrKocFBUHnyrisLm3_WkJ3zUY=.3760dd99-af91-4b01-84af-29ce5d3095e0@github.com>

On Wed, 16 Apr 2025 04:03:24 GMT, SendaoYan  wrote:

> Hi all,
> 
> The newly added test jdk/javadoc/doclet/testUnexported/TestUnexported.java javac build fails. This PR add depedencies to make javac build success. Test-fix only, change has been verified locally, no risk.

This pull request has now been integrated.

Changeset: 9502ab0b
Author:    SendaoYan 
URL:       https://git.openjdk.org/jdk/commit/9502ab0bf5ce8623776d295ff5260d717dfb9467
Stats:     2 lines in 1 file changed: 2 ins; 0 del; 0 mod

8354766: Test TestUnexported.java javac build fails

Reviewed-by: nbenalla, jpai

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

PR: https://git.openjdk.org/jdk/pull/24673