From jjg at openjdk.org  Fri Mar  1 21:49:29 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 1 Mar 2024 21:49:29 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v44]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <SkISirX7Jo5gm9fNBMlLH-Zd0yYFp_8m4mBF8IMFJ28=.c06cf879-240a-42d7-ba4f-5f34474aa93c@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  Revise `Markdown.update` to better handle container blocks.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/398f93fc..0b4d9b3c

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=43
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=42-43

  Stats: 348 lines in 3 files changed: 226 ins; 43 del; 79 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From prappo at openjdk.org  Mon Mar  4 14:43:03 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 4 Mar 2024 14:43:03 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v44]
In-Reply-To: <SkISirX7Jo5gm9fNBMlLH-Zd0yYFp_8m4mBF8IMFJ28=.c06cf879-240a-42d7-ba4f-5f34474aa93c@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <SkISirX7Jo5gm9fNBMlLH-Zd0yYFp_8m4mBF8IMFJ28=.c06cf879-240a-42d7-ba4f-5f34474aa93c@github.com>
Message-ID: <0Ni2FJg13P97mkOqv-C_J-i2pyHagmCc5wrcXuzNYMw=.d3d617eb-42dc-4e54-93fb-2afe679202c8@github.com>

On Fri, 1 Mar 2024 21:49:29 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Revise `Markdown.update` to better handle container blocks.

I have a test case to report. The following results in no `@param` information being rendered, which I think is a bug:

    /// Hello, _Markdown_ world!
    ///
    /// <p>
    /// @param <T> hello
    /// </p>
    ///
    public class C<T> { }

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

PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-1976734010

From prappo at openjdk.org  Mon Mar  4 15:19:05 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 4 Mar 2024 15:19:05 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v44]
In-Reply-To: <0Ni2FJg13P97mkOqv-C_J-i2pyHagmCc5wrcXuzNYMw=.d3d617eb-42dc-4e54-93fb-2afe679202c8@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <SkISirX7Jo5gm9fNBMlLH-Zd0yYFp_8m4mBF8IMFJ28=.c06cf879-240a-42d7-ba4f-5f34474aa93c@github.com>
 <0Ni2FJg13P97mkOqv-C_J-i2pyHagmCc5wrcXuzNYMw=.d3d617eb-42dc-4e54-93fb-2afe679202c8@github.com>
Message-ID: <zqK5wmk_PMqGBfZDXDFc-FvAJAsSHhy9Eg_kVzvzNGc=.a7b02cc2-4a50-49ad-bedd-359d6d6e5ce5@github.com>

On Mon, 4 Mar 2024 14:40:06 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> I have a test case to report. The following results in no `@param` information being rendered, which I think is a bug:
> 
> ```
> /// Hello, _Markdown_ world!
> ///
> /// <p>
> /// @param <T> hello
> /// </p>
> ///
> public class C<T> { }
> ```

Scratch that. After experimenting a bit more with **traditional** javadoc comments, I realised that it might be expected that `@param` would be lost in that `<p>...</p>` block; okay.

Still, I find it surprising that the description of the `@param` tag in the above comment, hosted in `///` or `/**...*/`, is a single node of type `RawText` with the following content:

    hello
    </p>

(Note, the content includes `</p>`.)

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

PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-1976818803

From jjg at openjdk.org  Mon Mar  4 21:32:20 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 4 Mar 2024 21:32:20 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v45]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <ZwSjIzkY9xAM-O8PhzUOyFOeSaZf9o0B_lwdC5H5Amw=.6bd5ee4d-80c9-4ecb-af99-b29ead71f40f@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 63 commits:

 - fix test after merge
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - Revise `Markdown.update` to better handle container blocks.
 - Refactor most of TestMarkdown.java into separate tests, grouped by functionality
 - add support for (top-level) trailing code blocks
   add simple test case with tabs
   add TestMarkdownCodeBlocks.testTypical
 - fix whitespace
 - fix Markdown.update for new POST_LIST_INDENT test case given in review feedback
 - refactor tests for Markdown headings into a separate test class.
 - update DocCommentParser and tests to improve handling of code blocks and code spans in Markdown documentation comments
 - fix indentation, for consistency
 - ... and 53 more: https://git.openjdk.org/jdk/compare/6f8d351e...292ff0f1

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=44
  Stats: 23548 lines in 205 files changed: 22863 ins; 252 del; 433 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From jjg at openjdk.org  Tue Mar  5 19:08:59 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 5 Mar 2024 19:08:59 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v44]
In-Reply-To: <zqK5wmk_PMqGBfZDXDFc-FvAJAsSHhy9Eg_kVzvzNGc=.a7b02cc2-4a50-49ad-bedd-359d6d6e5ce5@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <SkISirX7Jo5gm9fNBMlLH-Zd0yYFp_8m4mBF8IMFJ28=.c06cf879-240a-42d7-ba4f-5f34474aa93c@github.com>
 <0Ni2FJg13P97mkOqv-C_J-i2pyHagmCc5wrcXuzNYMw=.d3d617eb-42dc-4e54-93fb-2afe679202c8@github.com>
 <zqK5wmk_PMqGBfZDXDFc-FvAJAsSHhy9Eg_kVzvzNGc=.a7b02cc2-4a50-49ad-bedd-359d6d6e5ce5@github.com>
Message-ID: <7j2wY4Kerf2flBeZbxOeSz35u0VYgKsctgcDvui1Ctk=.abd1e15b-861e-4e7e-a86e-e7451e47d8c9@github.com>

On Mon, 4 Mar 2024 15:16:32 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> > I have a test case to report. The following results in no `@param` information being rendered, which I think is a bug:
> > ```
> > /// Hello, _Markdown_ world!
> > ///
> > /// <p>
> > /// @param <T> hello
> > /// </p>
> > ///
> > public class C<T> { }
> > ```
> 
> Scratch that. After experimenting a bit more with **traditional** javadoc comments, I realised that it might be expected that `@param` would be lost in that `<p>...</p>` block; okay.
> 
> Still, I find it surprising that the description of the `@param` tag in the above comment, hosted in `///` or `/**...*/`, is a single node of type `RawText` with the following content:
> 
> ```
> hello
> </p>
> ```
> 
> (Note, the content includes `</p>`.)

The Markdown aspect of this is behaving about as well as can be expected.  But the generated form is certainly confusing and can be considered a less-than-optimal presentation of a paragraph within a definition list.   You can see the same behavior in a traditional comment with `@param <T> <p>hello</p>`.  Ideally, we could/should tweak the CSS for this situation, in a separate changeset.

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

PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-1979452615

From duke at openjdk.org  Wed Mar  6 09:28:52 2024
From: duke at openjdk.org (psoujany)
Date: Wed, 6 Mar 2024 09:28:52 GMT
Subject: RFR: JDK-8325690: The scrollable element <div> with
 non-interactive content is not tabbable [v2]
In-Reply-To: <dwPOD67DiQK-Oqgf2ezu2B9n_2luaF-Arv8uHF1Lh88=.83094723-6000-4a0d-a2f2-bca0d263a7e6@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
 <HpxOh4XSFGGOEFr4DxOl1AXbD5Znd9yeVTqcDFB8jCA=.9354c297-f8f5-4059-94d9-3561716b0f16@github.com>
 <tUEHAxBL7OGBnJk5IuJITsbhIYCXa3PE51yKcK0K3us=.8b7514b5-ee54-4b8e-8b29-bc47c1b84900@github.com>
 <dwPOD67DiQK-Oqgf2ezu2B9n_2luaF-Arv8uHF1Lh88=.83094723-6000-4a0d-a2f2-bca0d263a7e6@github.com>
Message-ID: <6gVDntiPajQqNjqbrXd2U1l2lGn32H-xgXE8Bwp6hgI=.7498b6fb-0424-4570-9d60-413243d4ac6d@github.com>

On Wed, 21 Feb 2024 14:41:29 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> API doc(.html) generated using this stylesheet.css didn't had overflow: auto applied from .summary-table > div element but overflow been applied from .col-first, .col-second, .col-constructor-name which caused our achecker failure. .summary-table doesn't have affect.
>> 
>> Please find the below stylesheet.css used in one of our javadoc generated failed API doc
>> 
>> .summary-table > div, .details-table > div {
>>     text-align:left;
>>     padding: 8px 3px 3px 7px;
>> }
>> .col-first, .col-second, .col-last, .col-constructor-name, .col-summary-item-name {
>>     vertical-align:top;
>>     padding-right:0;
>>     padding-top:8px;
>>     padding-bottom:3px;
>> }
>> .table-header {
>>     background:#dee3e9;
>>     font-weight: bold;
>> }
>> .col-first, .col-first {
>>     font-size:13px;
>> }
>> .col-second, .col-second, .col-last, .col-constructor-name, .col-summary-item-name, .col-last {
>>     font-size:13px;
>> }
>> .col-first, .col-second, .col-constructor-name {
>>     vertical-align:top;
>>     overflow: auto;
>> }
>
> The current stylesheet has the following rule at line 688:
> 
> 
> .summary-table > div, .details-table > div {
>     text-align:left;
>     padding: 8px 3px 3px 7px;
>     overflow: auto hidden;
>     scrollbar-width: thin;
> }
> 
> 
> Granted, the `overflow` declaration was added relatively recently (October or last year). Does the problem still persist with this?

@hns Could you please validate my comment. Thank you.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17819#discussion_r1514122784

From hannesw at openjdk.org  Wed Mar  6 16:27:48 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 6 Mar 2024 16:27:48 GMT
Subject: RFR: JDK-8325690: The scrollable element <div> with
 non-interactive content is not tabbable [v2]
In-Reply-To: <6gVDntiPajQqNjqbrXd2U1l2lGn32H-xgXE8Bwp6hgI=.7498b6fb-0424-4570-9d60-413243d4ac6d@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
 <HpxOh4XSFGGOEFr4DxOl1AXbD5Znd9yeVTqcDFB8jCA=.9354c297-f8f5-4059-94d9-3561716b0f16@github.com>
 <tUEHAxBL7OGBnJk5IuJITsbhIYCXa3PE51yKcK0K3us=.8b7514b5-ee54-4b8e-8b29-bc47c1b84900@github.com>
 <dwPOD67DiQK-Oqgf2ezu2B9n_2luaF-Arv8uHF1Lh88=.83094723-6000-4a0d-a2f2-bca0d263a7e6@github.com>
 <6gVDntiPajQqNjqbrXd2U1l2lGn32H-xgXE8Bwp6hgI=.7498b6fb-0424-4570-9d60-413243d4ac6d@github.com>
Message-ID: <7W9x4XR3rzFE6vyjfPOEEUN6mEYyNSq7-GbIt6bqSH0=.129ad201-8550-439f-93ad-4dbc1714ac7b@github.com>

On Wed, 6 Mar 2024 09:25:51 GMT, psoujany <duke at openjdk.org> wrote:

>> The current stylesheet has the following rule at line 688:
>> 
>> 
>> .summary-table > div, .details-table > div {
>>     text-align:left;
>>     padding: 8px 3px 3px 7px;
>>     overflow: auto hidden;
>>     scrollbar-width: thin;
>> }
>> 
>> 
>> Granted, the `overflow` declaration was added relatively recently (October or last year). Does the problem still persist with this?
>
> @hns Could you please validate my comment. Thank you.

After having spent spent some time researching the problem and the proposed solution, I find that the premise of this issue is wrong. With current versions of supported browsers on my computer (Firefox, Chrome, Safari) the scrollable tabs can be focused using the tab key (in Safari the "press tab to highlight items" option has to be enabled in the advanced settings). It may be that this is a new addition in Chrome and Safari, and that they did not support this at the time when the issue was detected and filed.

Apart from that, I don't think that the proposed change would be a good fix for the problem. By removing the `overflow: auto` declarations in the given `<div>s`, overflow becomes invisible, or overflows the layout in the case of the rightmost column. Making content inaccessible for all users is not a good solution for the problem of content being inaccessible to keyboard users, and breaking the layout of the page is not desirable either.

Given that mainstream browsers seem to have followed Firefox and converted on making scrollable elements tabbable I would not consider this a problem in our documentation.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17819#discussion_r1514789084

From jjg at openjdk.org  Wed Mar  6 22:23:24 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 6 Mar 2024 22:23:24 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v46]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <eEp5MeoftULUFhUbOq4VFunz1k45Zrz-LqbBaIFDtfc=.7f4ba2c8-3324-403e-bd0e-3ec6c3136d06@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:

 - fix `textOf` method to accommodate Markdown content.
 - avoid relying on unspecified behavior `List.toString`

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/292ff0f1..fc76e8c7

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=45
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=44-45

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

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

From hannesw at openjdk.org  Thu Mar  7 14:35:01 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 7 Mar 2024 14:35:01 GMT
Subject: RFR: JDK-8326332: Unclosed inline tags cause misalignment in summary
 tables
Message-ID: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>

Please review a simple fix to make sure inline tags are always closed in summary tables, even when the tags are closed after the first sentence in the original doc comment. 

I decided to colocate the functionality to track open inline tags with the existing `ignoreNonInlineTag` method that filters out non-inline elements because there is a lot of common functionality, such as retrieving the name and kind of an HTML tag. I considered giving the method a name that describes the additional functionality, but couldn't find one that wasn't comically long. Suggestions are welcome of course.

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

Commit messages:
 - JDK-8326332: Unclosed inline tags cause misalignment in summary tables

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

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

From bmarwell at apache.org  Fri Mar  1 20:34:01 2024
From: bmarwell at apache.org (Benjamin Marwell)
Date: Fri, 1 Mar 2024 21:34:01 +0100
Subject: [JEP 467] Markdown -- is this a final decision yet?
Message-ID: <CAKZnr+x_9s6HL6CX+8DkwzXEk1jAv99hjL8S_amHqYG3S11XqQ@mail.gmail.com>

Hi everyone!

Due a post on Twitter[2], few other Java users like me got aware of JDK-8298405.
However, from all the comments, commentators asked why AsciiDoctor
wasn't proposed instead of Markdown[2].
There are a few reasons, mainly a better (single!) specification and a
more readable, approachable syntax.
Or how Brian Goetz often puts it [1]: Reading code is unquestionably
more important than writing code.

The JEP doesn't even mention why Markdown was chosen (or chosen over AsciiDoc).
Other JEPs often state alternatives or discarded ideas, this one does not.

I did a quick search through the mailing list archives and couldn't
find anything.

Thanks in advance!

[1]: https://twitter.com/BrianGoetz/status/1256652011136827393
[2]: https://x.com/gunnarmorling/status/1762719948709806338

From jjg at openjdk.org  Thu Mar  7 23:32:23 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 7 Mar 2024 23:32:23 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v47]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <f-VCU0Zgr8bMPAl9qMTEq_Ssye-Q37I7sRosuR95VwM=.bb82526f-fe75-48e2-83c6-e930a6372f02@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  add test cases for links to anchors

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/fc76e8c7..8dfd9e08

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=46
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=45-46

  Stats: 60 lines in 1 file changed: 60 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From gli at openjdk.org  Fri Mar  8 10:19:55 2024
From: gli at openjdk.org (Guoxiong Li)
Date: Fri, 8 Mar 2024 10:19:55 GMT
Subject: RFR: JDK-8326332: Unclosed inline tags cause misalignment in
 summary tables
In-Reply-To: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
References: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
Message-ID: <oSDmzfqV5UOfxW6QgtNHBKnpvOOAQkry-1sLpS6CXqg=.391242fa-4737-4f82-9bc5-1219d1d373fe@github.com>

On Thu, 7 Mar 2024 14:29:39 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a simple fix to make sure inline tags are always closed in summary tables, even when the tags are closed after the first sentence in the original doc comment. 
> 
> I decided to colocate the functionality to track open inline tags with the existing `ignoreNonInlineTag` method that filters out non-inline elements because there is a lot of common functionality, such as retrieving the name and kind of an HTML tag. I considered giving the method a name that describes the additional functionality, but couldn't find one that wasn't comically long. Suggestions are welcome of course.

test/langtools/jdk/javadoc/doclet/testBreakIterator/TestBreakIterator.java line 83:

> 81:                 """
> 82:                     <div class="block">Inline tags <i><a href="../index-all.html">extending
> 83:                      beyond the first sentence.</a></i></div>""");

I have a question:
Why doesn't it include ` Tags are closed here`? Is it intentional or a bug?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18154#discussion_r1517523761

From hannesw at openjdk.org  Fri Mar  8 11:12:52 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 8 Mar 2024 11:12:52 GMT
Subject: RFR: JDK-8326332: Unclosed inline tags cause misalignment in
 summary tables
In-Reply-To: <oSDmzfqV5UOfxW6QgtNHBKnpvOOAQkry-1sLpS6CXqg=.391242fa-4737-4f82-9bc5-1219d1d373fe@github.com>
References: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
 <oSDmzfqV5UOfxW6QgtNHBKnpvOOAQkry-1sLpS6CXqg=.391242fa-4737-4f82-9bc5-1219d1d373fe@github.com>
Message-ID: <TpI0AS99QPXmJyUcSWMs6XGzWjCU2BH9IlSAux4aFnk=.0281deca-ee44-40d3-9eac-9269fee78760@github.com>

On Fri, 8 Mar 2024 10:16:51 GMT, Guoxiong Li <gli at openjdk.org> wrote:

>> Please review a simple fix to make sure inline tags are always closed in summary tables, even when the tags are closed after the first sentence in the original doc comment. 
>> 
>> I decided to colocate the functionality to track open inline tags with the existing `ignoreNonInlineTag` method that filters out non-inline elements because there is a lot of common functionality, such as retrieving the name and kind of an HTML tag. I considered giving the method a name that describes the additional functionality, but couldn't find one that wasn't comically long. Suggestions are welcome of course.
>
> test/langtools/jdk/javadoc/doclet/testBreakIterator/TestBreakIterator.java line 83:
> 
>> 81:                 """
>> 82:                     <div class="block">Inline tags <i><a href="../index-all.html">extending
>> 83:                      beyond the first sentence.</a></i></div>""");
> 
> I have a question:
> Why doesn't it include ` Tags are closed here`? Is it intentional or a bug?

This piece of HTML is from the method summary table which only displays the first sentence of the doc comment (which is the root of the problem fixed by this PR).

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18154#discussion_r1517580631

From gli at openjdk.org  Fri Mar  8 15:34:54 2024
From: gli at openjdk.org (Guoxiong Li)
Date: Fri, 8 Mar 2024 15:34:54 GMT
Subject: RFR: JDK-8326332: Unclosed inline tags cause misalignment in
 summary tables
In-Reply-To: <TpI0AS99QPXmJyUcSWMs6XGzWjCU2BH9IlSAux4aFnk=.0281deca-ee44-40d3-9eac-9269fee78760@github.com>
References: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
 <oSDmzfqV5UOfxW6QgtNHBKnpvOOAQkry-1sLpS6CXqg=.391242fa-4737-4f82-9bc5-1219d1d373fe@github.com>
 <TpI0AS99QPXmJyUcSWMs6XGzWjCU2BH9IlSAux4aFnk=.0281deca-ee44-40d3-9eac-9269fee78760@github.com>
Message-ID: <Fdg04T3IqDCwCezl7HxqTktfXFvQdZ2QwAmd5JZKTwk=.4005473c-ec06-4854-8c23-0b5912bc97f3@github.com>

On Fri, 8 Mar 2024 11:09:50 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> test/langtools/jdk/javadoc/doclet/testBreakIterator/TestBreakIterator.java line 83:
>> 
>>> 81:                 """
>>> 82:                     <div class="block">Inline tags <i><a href="../index-all.html">extending
>>> 83:                      beyond the first sentence.</a></i></div>""");
>> 
>> I have a question:
>> Why doesn't it include ` Tags are closed here`? Is it intentional or a bug?
>
> This piece of HTML is from the method summary table which only displays the first sentence of the doc comment (which is the root of the problem fixed by this PR).

Got it. Thanks for your answer.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18154#discussion_r1517872886

From gli at openjdk.org  Fri Mar  8 15:47:54 2024
From: gli at openjdk.org (Guoxiong Li)
Date: Fri, 8 Mar 2024 15:47:54 GMT
Subject: RFR: JDK-8326332: Unclosed inline tags cause misalignment in
 summary tables
In-Reply-To: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
References: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
Message-ID: <3hTqd26dVRvVlR1HuN_pP5pNA4em_A1fEoP3-45wmq4=.48343792-54a0-4f72-ae99-4c89b3810675@github.com>

On Thu, 7 Mar 2024 14:29:39 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a simple fix to make sure inline tags are always closed in summary tables, even when the tags are closed after the first sentence in the original doc comment. 
> 
> I decided to colocate the functionality to track open inline tags with the existing `ignoreNonInlineTag` method that filters out non-inline elements because there is a lot of common functionality, such as retrieving the name and kind of an HTML tag. I considered giving the method a name that describes the additional functionality, but couldn't find one that wasn't comically long. Suggestions are welcome of course.

LGTM.

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

Marked as reviewed by gli (Committer).

PR Review: https://git.openjdk.org/jdk/pull/18154#pullrequestreview-1925164311

From jjg at openjdk.org  Fri Mar  8 19:22:53 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 8 Mar 2024 19:22:53 GMT
Subject: RFR: JDK-8326332: Unclosed inline tags cause misalignment in
 summary tables
In-Reply-To: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
References: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
Message-ID: <_b9_J2jCkdotHifs1CkEfwNfsvAKTxKtOvkGhA-0T54=.23bdaafd-3e0a-4396-be95-c8dafffabf5e@github.com>

On Thu, 7 Mar 2024 14:29:39 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a simple fix to make sure inline tags are always closed in summary tables, even when the tags are closed after the first sentence in the original doc comment. 
> 
> I decided to colocate the functionality to track open inline tags with the existing `ignoreNonInlineTag` method that filters out non-inline elements because there is a lot of common functionality, such as retrieving the name and kind of an HTML tag. I considered giving the method a name that describes the additional functionality, but couldn't find one that wasn't comically long. Suggestions are welcome of course.

Nice.  

I like that you managed this without needing to build anything resembling an HTML conformance checker or even to extend existing support for HTML tags.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1191:

> 1189:                 }
> 1190:                 // Keep track of open inline tags that need to be closed, see 8326332
> 1191:                 if (kind == START_ELEMENT && htmlTag.endKind == HtmlTag.EndKind.REQUIRED) {

Clever use of `endKind` -- I would not have thought of that.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1268:

> 1266:         configuration.tagletManager.checkTags(element, trees);
> 1267:         commentRemoved = false;
> 1268:         ArrayList<Name> openTags = new ArrayList<>();

Suggest either using `var` or just `List<Name>`.

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

Marked as reviewed by jjg (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18154#pullrequestreview-1925669369
PR Review Comment: https://git.openjdk.org/jdk/pull/18154#discussion_r1518188269
PR Review Comment: https://git.openjdk.org/jdk/pull/18154#discussion_r1518188994

From jjg at openjdk.org  Fri Mar  8 19:27:52 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 8 Mar 2024 19:27:52 GMT
Subject: RFR: JDK-8326332: Unclosed inline tags cause misalignment in
 summary tables
In-Reply-To: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
References: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
Message-ID: <E1mqQgzmLp_Uu0Sl799Ejs6NS41ovQDSbRJXE6pWmKA=.98c09cf0-519c-437b-b202-8c11f6b34e8b@github.com>

On Thu, 7 Mar 2024 14:29:39 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a simple fix to make sure inline tags are always closed in summary tables, even when the tags are closed after the first sentence in the original doc comment. 
> 
> I decided to colocate the functionality to track open inline tags with the existing `ignoreNonInlineTag` method that filters out non-inline elements because there is a lot of common functionality, such as retrieving the name and kind of an HTML tag. I considered giving the method a name that describes the additional functionality, but couldn't find one that wasn't comically long. Suggestions are welcome of course.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1185:

> 1183: 
> 1184:         if (name != null) {
> 1185:             HtmlTag htmlTag = HtmlTag.get(name);

minor P5 suggestion to consider in future:
maybe add convenience forms for `HtmlTag.of` that accept a `DocTree`.


HtmlTree htmlTag = HtmlTree.of(tree);



HtmlTree of(DocTree dtree) {
    return switch (tree.getKind()) {
        case START_ELEMENT -> of(((StartElementTree)dtree).getName());
        case END_ELEMENT -> of(((StartElementTree)dtree).getName());
        default -> throw new IllegalArgumentException(tree.getKind().toString());
    }
}

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18154#discussion_r1518202125

From hannesw at openjdk.org  Fri Mar  8 20:57:17 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 8 Mar 2024 20:57:17 GMT
Subject: RFR: JDK-8326332: Unclosed inline tags cause misalignment in
 summary tables [v2]
In-Reply-To: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
References: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
Message-ID: <8vBO90EmPgRG-X6C4Klp5w70OZw6F3jMhYBgspxKIS0=.99257533-eb26-4e3e-b89f-d10b5adf44c7@github.com>

> Please review a simple fix to make sure inline tags are always closed in summary tables, even when the tags are closed after the first sentence in the original doc comment. 
> 
> I decided to colocate the functionality to track open inline tags with the existing `ignoreNonInlineTag` method that filters out non-inline elements because there is a lot of common functionality, such as retrieving the name and kind of an HTML tag. I considered giving the method a name that describes the additional functionality, but couldn't find one that wasn't comically long. Suggestions are welcome of course.

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/18154/files
  - new: https://git.openjdk.org/jdk/pull/18154/files/9353d1ea..e0205c4d

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

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/18154.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18154/head:pull/18154

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

From hannesw at openjdk.org  Fri Mar  8 21:01:56 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 8 Mar 2024 21:01:56 GMT
Subject: Integrated: JDK-8326332: Unclosed inline tags cause misalignment in
 summary tables
In-Reply-To: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
References: <9OnZS91iauN2U4RyVxetc_Q5VW1l-I_ugQZhbpMjATY=.526fd896-72d3-48b7-87f1-7234f0f4790b@github.com>
Message-ID: <GXhmzxiidWnMwutXGiEanHSrSRC9B0CJg0VRBtW1GHA=.b61ea34d-1d77-401f-bdb7-cd9453d2db27@github.com>

On Thu, 7 Mar 2024 14:29:39 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a simple fix to make sure inline tags are always closed in summary tables, even when the tags are closed after the first sentence in the original doc comment. 
> 
> I decided to colocate the functionality to track open inline tags with the existing `ignoreNonInlineTag` method that filters out non-inline elements because there is a lot of common functionality, such as retrieving the name and kind of an HTML tag. I considered giving the method a name that describes the additional functionality, but couldn't find one that wasn't comically long. Suggestions are welcome of course.

This pull request has now been integrated.

Changeset: a6dc4bc2
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/a6dc4bc2b83c7240e573ac43f9b7a10191c58ed3
Stats:     39 lines in 3 files changed: 26 ins; 1 del; 12 mod

8326332: Unclosed inline tags cause misalignment in summary tables

Reviewed-by: gli, jjg

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

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

From liach at openjdk.org  Sun Mar 10 20:25:12 2024
From: liach at openjdk.org (Chen Liang)
Date: Sun, 10 Mar 2024 20:25:12 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
Message-ID: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>

Please review this patch that fixes the issue where type annotations on primitive types are not linked.

Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java

import java.lang.annotation.*;

public class ArrayAnno {
	@Retention(RetentionPolicy.RUNTIME)
	@Target(ElementType.TYPE_USE)
	@Documented
	public @interface Anno { int value(); }

	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
}

JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html

Note that a bug within javac causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)

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

Commit messages:
 - 8325433: Type annotations on primitive types are not linked

Changes: https://git.openjdk.org/jdk/pull/18179/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18179&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325433
  Stats: 61 lines in 5 files changed: 52 ins; 0 del; 9 mod
  Patch: https://git.openjdk.org/jdk/pull/18179.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18179/head:pull/18179

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

From gli at openjdk.org  Mon Mar 11 06:44:53 2024
From: gli at openjdk.org (Guoxiong Li)
Date: Mon, 11 Mar 2024 06:44:53 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
In-Reply-To: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
Message-ID: <6YmlyWLdhn1-zAxW5fZQcvtPBR_VMhXO2lUn5txfv3k=.484e407a-1f67-4bba-a1a0-aeb0caa10104@github.com>

On Sun, 10 Mar 2024 20:19:44 GMT, Chen Liang <liach at openjdk.org> wrote:

> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
> 
> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
> 
> import java.lang.annotation.*;
> 
> public class ArrayAnno {
> 	@Retention(RetentionPolicy.RUNTIME)
> 	@Target(ElementType.TYPE_USE)
> 	@Documented
> 	public @interface Anno { int value(); }
> 
> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
> }
> 
> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
> 
> Note that a bug within javac causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)

Changes requested by gli (Committer).

test/langtools/jdk/javadoc/doclet/testTypeAnnotations/typeannos/Fields.java line 72:

> 70: 
> 71:     public final @FldA int primitive = 0;
> 72:     public final @FldA int @FldB [] primitiveArray1Deep = null;

These two fields have not been verified?

test/langtools/jdk/javadoc/doclet/testTypeAnnotations/typeannos/MethodReturnType.java line 54:

> 52: 
> 53:     @MRtnA int primitive() { return 0; }
> 54:     @MRtnA int @MRtnB [] primitiveArray1Deep() { return null; }

These two fields have not been verified?

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

PR Review: https://git.openjdk.org/jdk/pull/18179#pullrequestreview-1927016081
PR Review Comment: https://git.openjdk.org/jdk/pull/18179#discussion_r1519212039
PR Review Comment: https://git.openjdk.org/jdk/pull/18179#discussion_r1519212869

From gli at openjdk.org  Mon Mar 11 06:51:53 2024
From: gli at openjdk.org (Guoxiong Li)
Date: Mon, 11 Mar 2024 06:51:53 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
In-Reply-To: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
Message-ID: <KQ0TC8afZKioD84CXNaQJuadvPfukGQHwkoOoze1fEw=.81154f11-b07b-49fc-945b-ac7630803251@github.com>

On Sun, 10 Mar 2024 20:19:44 GMT, Chen Liang <liach at openjdk.org> wrote:

> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java

This test case has a two-dimensional array with annotations. But the tests of your patch don't have such case. It is good to add it.

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

PR Comment: https://git.openjdk.org/jdk/pull/18179#issuecomment-1987734454

From liach at openjdk.org  Mon Mar 11 13:15:54 2024
From: liach at openjdk.org (Chen Liang)
Date: Mon, 11 Mar 2024 13:15:54 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
In-Reply-To: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
Message-ID: <UAkLbT5JbYjoDm2mEtGB6PvvJITN7UbgAo2LCJ89RkE=.fba79f84-8c21-4f1a-9d2b-a15fbd01df34@github.com>

On Sun, 10 Mar 2024 20:19:44 GMT, Chen Liang <liach at openjdk.org> wrote:

> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
> 
> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
> 
> import java.lang.annotation.*;
> 
> public class ArrayAnno {
> 	@Retention(RetentionPolicy.RUNTIME)
> 	@Target(ElementType.TYPE_USE)
> 	@Documented
> 	public @interface Anno { int value(); }
> 
> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
> }
> 
> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
> 
> Note that a bug within javac causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)

The 2-D array case is broken: currently source code `@A int @B [] @C []` is compiled to `@A int @C [] @B []` in both class file and javadoc output, so I don't want to add a buggy case that needs to be updated if this annotation placement bug is fixed.

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

PR Comment: https://git.openjdk.org/jdk/pull/18179#issuecomment-1988412676

From liach at openjdk.org  Mon Mar 11 13:15:55 2024
From: liach at openjdk.org (Chen Liang)
Date: Mon, 11 Mar 2024 13:15:55 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
In-Reply-To: <6YmlyWLdhn1-zAxW5fZQcvtPBR_VMhXO2lUn5txfv3k=.484e407a-1f67-4bba-a1a0-aeb0caa10104@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <6YmlyWLdhn1-zAxW5fZQcvtPBR_VMhXO2lUn5txfv3k=.484e407a-1f67-4bba-a1a0-aeb0caa10104@github.com>
Message-ID: <tb0mEXt8t0VZbF3u_LjJPmpHuRvBAkyKFHUcTs9VmCE=.574fc89e-f324-46a3-a3ab-633259c24b63@github.com>

On Mon, 11 Mar 2024 06:35:27 GMT, Guoxiong Li <gli at openjdk.org> wrote:

>> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
>> 
>> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
>> 
>> import java.lang.annotation.*;
>> 
>> public class ArrayAnno {
>> 	@Retention(RetentionPolicy.RUNTIME)
>> 	@Target(ElementType.TYPE_USE)
>> 	@Documented
>> 	public @interface Anno { int value(); }
>> 
>> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
>> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
>> }
>> 
>> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
>> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
>> 
>> Note that a bug within javac causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)
>
> test/langtools/jdk/javadoc/doclet/testTypeAnnotations/typeannos/Fields.java line 72:
> 
>> 70: 
>> 71:     public final @FldA int primitive = 0;
>> 72:     public final @FldA int @FldB [] primitiveArray1Deep = null;
> 
> These two fields have not been verified?

I shall remove these fields; they serve no real purpose here indeed.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18179#discussion_r1519693430

From gli at openjdk.org  Mon Mar 11 13:24:53 2024
From: gli at openjdk.org (Guoxiong Li)
Date: Mon, 11 Mar 2024 13:24:53 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
In-Reply-To: <UAkLbT5JbYjoDm2mEtGB6PvvJITN7UbgAo2LCJ89RkE=.fba79f84-8c21-4f1a-9d2b-a15fbd01df34@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <UAkLbT5JbYjoDm2mEtGB6PvvJITN7UbgAo2LCJ89RkE=.fba79f84-8c21-4f1a-9d2b-a15fbd01df34@github.com>
Message-ID: <iGJWwjMFeDJEjuAEggWBMwYoyqeSARE7drZJAxSa698=.5d7eb6ed-7674-45f5-a12d-a28784a00a94@github.com>

On Mon, 11 Mar 2024 13:13:07 GMT, Chen Liang <liach at openjdk.org> wrote:

> The 2-D array case is broken: currently source code `@A int @B [] @C []` is compiled to `@A int @C [] @B []` in both class file and javadoc output, so I don't want to add a buggy case that needs to be updated if this annotation placement bug is fixed.

I know what you mean now. You found a compiler bug when solving this issue.

The description you wrote are almost about the new bug you found. It is not so good actually. You can file a corresponding issue (then link them in JBS),  or report the bug in the maillist.

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

PR Comment: https://git.openjdk.org/jdk/pull/18179#issuecomment-1988428100

From liach at openjdk.org  Mon Mar 11 13:31:06 2024
From: liach at openjdk.org (Chen Liang)
Date: Mon, 11 Mar 2024 13:31:06 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v2]
In-Reply-To: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
Message-ID: <OSBz-i6A3CaJaM6JWfHhvU2lrX9GxZfZkiaS-8JXtrI=.8b7e47a7-26d4-4831-ba0d-baf8c0c69ede@github.com>

> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
> 
> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
> 
> import java.lang.annotation.*;
> 
> public class ArrayAnno {
> 	@Retention(RetentionPolicy.RUNTIME)
> 	@Target(ElementType.TYPE_USE)
> 	@Documented
> 	public @interface Anno { int value(); }
> 
> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
> }
> 
> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
> 
> Note that a bug within javac causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)

Chen Liang has updated the pull request incrementally with one additional commit since the last revision:

  Removed unused methods

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18179/files
  - new: https://git.openjdk.org/jdk/pull/18179/files/e33b685f..c7de229e

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

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

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

From liach at openjdk.org  Mon Mar 11 13:42:55 2024
From: liach at openjdk.org (Chen Liang)
Date: Mon, 11 Mar 2024 13:42:55 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v2]
In-Reply-To: <6YmlyWLdhn1-zAxW5fZQcvtPBR_VMhXO2lUn5txfv3k=.484e407a-1f67-4bba-a1a0-aeb0caa10104@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <6YmlyWLdhn1-zAxW5fZQcvtPBR_VMhXO2lUn5txfv3k=.484e407a-1f67-4bba-a1a0-aeb0caa10104@github.com>
Message-ID: <Px7SXWmW2qJWZwL8LE8Hhg3MUTNLe82jaWn4DuZfECI=.30f62d0c-69d3-4927-bdad-3a191ba5fac0@github.com>

On Mon, 11 Mar 2024 06:36:49 GMT, Guoxiong Li <gli at openjdk.org> wrote:

>> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Removed unused methods
>
> test/langtools/jdk/javadoc/doclet/testTypeAnnotations/typeannos/MethodReturnType.java line 54:
> 
>> 52: 
>> 53:     @MRtnA int primitive() { return 0; }
>> 54:     @MRtnA int @MRtnB [] primitiveArray1Deep() { return null; }
> 
> These two fields have not been verified?

I'm pretty sure the default scoped one is verified. I've removed the unused modified scoped ones.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18179#discussion_r1519736994

From hannesw at openjdk.org  Mon Mar 11 13:43:03 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 11 Mar 2024 13:43:03 GMT
Subject: RFR: JDK-8325874: Improve checkbox-based interface in summary pages
Message-ID: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>

Please review a change to improve the user experience and implementation for the checkbox-based interface to selectively display content on API summary pages:

 - Add a checkbox to toggle (select/unselect) all checkboxes in the page.
 - Remove the `Table.setAlwaysShowDefaultTab(boolean)` setter as it is redundant and can be replaced by `!renderTabs`.
 - Consolidate the code to generate checkboxes into a new protected `SummaryListWriter.getCheckbox` method.

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

Commit messages:
 - Add bug id to tests
 - JDK-8325874: Improve checkbox-based interface in summary pages

Changes: https://git.openjdk.org/jdk/pull/18194/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18194&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325874
  Stats: 140 lines in 9 files changed: 55 ins; 52 del; 33 mod
  Patch: https://git.openjdk.org/jdk/pull/18194.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18194/head:pull/18194

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

From gli at openjdk.org  Mon Mar 11 13:48:55 2024
From: gli at openjdk.org (Guoxiong Li)
Date: Mon, 11 Mar 2024 13:48:55 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v2]
In-Reply-To: <OSBz-i6A3CaJaM6JWfHhvU2lrX9GxZfZkiaS-8JXtrI=.8b7e47a7-26d4-4831-ba0d-baf8c0c69ede@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <OSBz-i6A3CaJaM6JWfHhvU2lrX9GxZfZkiaS-8JXtrI=.8b7e47a7-26d4-4831-ba0d-baf8c0c69ede@github.com>
Message-ID: <mFBGlo0HntSvWX566Vw1B1NlSP0yM1d0cmxvo7j1w8U=.3ee9335d-9a34-4fdd-90a1-52d0188ac2b8@github.com>

On Mon, 11 Mar 2024 13:31:06 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
>> 
>> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
>> 
>> import java.lang.annotation.*;
>> 
>> public class ArrayAnno {
>> 	@Retention(RetentionPolicy.RUNTIME)
>> 	@Target(ElementType.TYPE_USE)
>> 	@Documented
>> 	public @interface Anno { int value(); }
>> 
>> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
>> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
>> }
>> 
>> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
>> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
>> 
>> Note that a bug within javac (reported in https://bugs.openjdk.org/browse/JDK-8327824) causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Removed unused methods

Changes requested by gli (Committer).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java line 31:

> 29: import java.util.EnumSet;
> 30: import java.util.List;
> 31: import java.util.Locale;

I can't find the code which uses `Locale`. Is it redundant?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java line 41:

> 39: import javax.lang.model.type.ArrayType;
> 40: import javax.lang.model.type.DeclaredType;
> 41: import javax.lang.model.type.PrimitiveType;

`PrimitiveType` seems redundant as above.

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

PR Review: https://git.openjdk.org/jdk/pull/18179#pullrequestreview-1927874148
PR Review Comment: https://git.openjdk.org/jdk/pull/18179#discussion_r1519746786
PR Review Comment: https://git.openjdk.org/jdk/pull/18179#discussion_r1519747314

From liach at openjdk.org  Mon Mar 11 13:57:23 2024
From: liach at openjdk.org (Chen Liang)
Date: Mon, 11 Mar 2024 13:57:23 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v3]
In-Reply-To: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
Message-ID: <9uS8IS4OAvvhV-mEZcs3-Q3eyjpxuG76ae6VAKwbZ1s=.473d253f-5213-4eda-bfd5-b25086fb04f4@github.com>

> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
> 
> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
> 
> import java.lang.annotation.*;
> 
> public class ArrayAnno {
> 	@Retention(RetentionPolicy.RUNTIME)
> 	@Target(ElementType.TYPE_USE)
> 	@Documented
> 	public @interface Anno { int value(); }
> 
> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
> }
> 
> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
> 
> Note that a bug within javac (reported in https://bugs.openjdk.org/browse/JDK-8327824) causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)

Chen Liang has updated the pull request incrementally with one additional commit since the last revision:

  Redundant imports

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18179/files
  - new: https://git.openjdk.org/jdk/pull/18179/files/c7de229e..d4fc545a

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

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

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

From gli at openjdk.org  Mon Mar 11 13:57:23 2024
From: gli at openjdk.org (Guoxiong Li)
Date: Mon, 11 Mar 2024 13:57:23 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v3]
In-Reply-To: <9uS8IS4OAvvhV-mEZcs3-Q3eyjpxuG76ae6VAKwbZ1s=.473d253f-5213-4eda-bfd5-b25086fb04f4@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <9uS8IS4OAvvhV-mEZcs3-Q3eyjpxuG76ae6VAKwbZ1s=.473d253f-5213-4eda-bfd5-b25086fb04f4@github.com>
Message-ID: <oo6zOYpNn_VziG6zmTH-u2ROdFzFT7eJ59myTFye234=.b11b2978-1e43-4a5f-8257-54c63e44d739@github.com>

On Mon, 11 Mar 2024 13:53:57 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
>> 
>> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
>> 
>> import java.lang.annotation.*;
>> 
>> public class ArrayAnno {
>> 	@Retention(RetentionPolicy.RUNTIME)
>> 	@Target(ElementType.TYPE_USE)
>> 	@Documented
>> 	public @interface Anno { int value(); }
>> 
>> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
>> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
>> }
>> 
>> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
>> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
>> 
>> Note that a bug within javac (reported in https://bugs.openjdk.org/browse/JDK-8327824) causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Redundant imports

Marked as reviewed by gli (Committer).

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

PR Review: https://git.openjdk.org/jdk/pull/18179#pullrequestreview-1927898081

From liach at openjdk.org  Mon Mar 11 13:57:23 2024
From: liach at openjdk.org (Chen Liang)
Date: Mon, 11 Mar 2024 13:57:23 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v2]
In-Reply-To: <OSBz-i6A3CaJaM6JWfHhvU2lrX9GxZfZkiaS-8JXtrI=.8b7e47a7-26d4-4831-ba0d-baf8c0c69ede@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <OSBz-i6A3CaJaM6JWfHhvU2lrX9GxZfZkiaS-8JXtrI=.8b7e47a7-26d4-4831-ba0d-baf8c0c69ede@github.com>
Message-ID: <DUEGEQanwQEw8t7ibbFm248P0cxM-o9PlTn4dJyjOI8=.93761554-0a3d-4dcb-8b5b-d633447ed83b@github.com>

On Mon, 11 Mar 2024 13:31:06 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
>> 
>> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
>> 
>> import java.lang.annotation.*;
>> 
>> public class ArrayAnno {
>> 	@Retention(RetentionPolicy.RUNTIME)
>> 	@Target(ElementType.TYPE_USE)
>> 	@Documented
>> 	public @interface Anno { int value(); }
>> 
>> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
>> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
>> }
>> 
>> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
>> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
>> 
>> Note that a bug within javac (reported in https://bugs.openjdk.org/browse/JDK-8327824) causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Removed unused methods

Fixed imports, and the javac bug with path assignment for type annotation on array is reported as https://bugs.openjdk.org/browse/JDK-8327824.

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

PR Comment: https://git.openjdk.org/jdk/pull/18179#issuecomment-1988494667

From liach at openjdk.org  Mon Mar 11 13:57:23 2024
From: liach at openjdk.org (Chen Liang)
Date: Mon, 11 Mar 2024 13:57:23 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v2]
In-Reply-To: <mFBGlo0HntSvWX566Vw1B1NlSP0yM1d0cmxvo7j1w8U=.3ee9335d-9a34-4fdd-90a1-52d0188ac2b8@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <OSBz-i6A3CaJaM6JWfHhvU2lrX9GxZfZkiaS-8JXtrI=.8b7e47a7-26d4-4831-ba0d-baf8c0c69ede@github.com>
 <mFBGlo0HntSvWX566Vw1B1NlSP0yM1d0cmxvo7j1w8U=.3ee9335d-9a34-4fdd-90a1-52d0188ac2b8@github.com>
Message-ID: <W9oAFQPRHD4ccxdCcHxMbJnT_cBtelHoBdTJ2PRiPpQ=.ad3af296-bfc4-4574-9d4d-ae4c6e2402cb@github.com>

On Mon, 11 Mar 2024 13:45:19 GMT, Guoxiong Li <gli at openjdk.org> wrote:

>> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Removed unused methods
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java line 31:
> 
>> 29: import java.util.EnumSet;
>> 30: import java.util.List;
>> 31: import java.util.Locale;
> 
> I can't find the code which uses `Locale`. Is it redundant?

Was trying to add a visitor override for PrimitiveType and doing `primitiveType.getKind().toString().toLowerCase(Locale.ROOT)` but discovered `utils.getTypeSignature` was already doing the same; forgot to remove imports.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18179#discussion_r1519754693

From prappo at openjdk.org  Mon Mar 11 17:15:54 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 11 Mar 2024 17:15:54 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v3]
In-Reply-To: <9uS8IS4OAvvhV-mEZcs3-Q3eyjpxuG76ae6VAKwbZ1s=.473d253f-5213-4eda-bfd5-b25086fb04f4@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <9uS8IS4OAvvhV-mEZcs3-Q3eyjpxuG76ae6VAKwbZ1s=.473d253f-5213-4eda-bfd5-b25086fb04f4@github.com>
Message-ID: <YcoE1SdNx89H_w0VsyCt0E1039qIyPoazE387Ty2seI=.7cc1cf61-24d2-4dcd-8586-b06b7445916a@github.com>

On Mon, 11 Mar 2024 13:57:23 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
>> 
>> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
>> 
>> import java.lang.annotation.*;
>> 
>> public class ArrayAnno {
>> 	@Retention(RetentionPolicy.RUNTIME)
>> 	@Target(ElementType.TYPE_USE)
>> 	@Documented
>> 	public @interface Anno { int value(); }
>> 
>> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
>> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
>> }
>> 
>> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
>> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
>> 
>> Note that a bug within javac (reported in https://bugs.openjdk.org/browse/JDK-8327824) causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Redundant imports

Thanks for taking care of it. The approach seems good. I've submitted this change to our CI system. Once the results are back, I'll let you know.

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

PR Comment: https://git.openjdk.org/jdk/pull/18179#issuecomment-1988996333

From prappo at openjdk.org  Mon Mar 11 18:11:55 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 11 Mar 2024 18:11:55 GMT
Subject: RFR: JDK-8325874: Improve checkbox-based interface in summary
 pages
In-Reply-To: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
References: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
Message-ID: <fAsuzjQ63aITEfYpdmEfSmN7YkvpvG-0d6YqekhTUgY=.d783f52e-0364-4c9f-93d3-747dba8fca39@github.com>

On Mon, 11 Mar 2024 13:37:54 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to improve the user experience and implementation for the checkbox-based interface to selectively display content on API summary pages:
> 
>  - Add a checkbox to toggle (select/unselect) all checkboxes in the page.
>  - Remove the `Table.setAlwaysShowDefaultTab(boolean)` setter as it is redundant and can be replaced by `!renderTabs`.
>  - Consolidate the code to generate checkboxes into a new protected `SummaryListWriter.getCheckbox` method.

It'd work for a few more years, but it doesn't scale well. On the other hand, it is very simple:

<img width="850" alt="image" src="https://github.com/openjdk/jdk/assets/32523691/26919228-db98-4041-833f-f01c34125331">

Nit: if you check "all" and then uncheck something else, then "all" will remain selected. That is a confusing state.

<img width="846" alt="image" src="https://github.com/openjdk/jdk/assets/32523691/49c1d803-57b3-483b-857f-64781bf96ce0">

I'll have a look at the code change a bit later. Thanks.

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

PR Comment: https://git.openjdk.org/jdk/pull/18194#issuecomment-1989120925

From jjg at openjdk.org  Mon Mar 11 22:02:30 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 11 Mar 2024 22:02:30 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v48]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <IU2t-TZP7AiriOnwvxe-St0O5e_Bdp1RhcNDJk17ySU=.d8ada146-ea32-4e53-930e-923f6ada652f@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  improve first-sentence break in Markdown comments

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/8dfd9e08..81279a74

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=47
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=46-47

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

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

From prappo at openjdk.org  Mon Mar 11 23:11:14 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 11 Mar 2024 23:11:14 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v3]
In-Reply-To: <9uS8IS4OAvvhV-mEZcs3-Q3eyjpxuG76ae6VAKwbZ1s=.473d253f-5213-4eda-bfd5-b25086fb04f4@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <9uS8IS4OAvvhV-mEZcs3-Q3eyjpxuG76ae6VAKwbZ1s=.473d253f-5213-4eda-bfd5-b25086fb04f4@github.com>
Message-ID: <D4jSgDs01zWqmfphQu_pBCFMvdCG9l5PrNyyBm3A8Uk=.b2654bb6-2086-49a9-9cc5-eb263852b9b9@github.com>

On Mon, 11 Mar 2024 13:57:23 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
>> 
>> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
>> 
>> import java.lang.annotation.*;
>> 
>> public class ArrayAnno {
>> 	@Retention(RetentionPolicy.RUNTIME)
>> 	@Target(ElementType.TYPE_USE)
>> 	@Documented
>> 	public @interface Anno { int value(); }
>> 
>> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
>> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
>> }
>> 
>> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
>> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
>> 
>> Note that a bug within javac (reported in https://bugs.openjdk.org/browse/JDK-8327824) causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Redundant imports

Marked as reviewed by prappo (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/18179#pullrequestreview-1929754322

From jjg at openjdk.org  Mon Mar 11 23:53:33 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 11 Mar 2024 23:53:33 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v49]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <JyCGk29VravqxsKAnrUaQY4TSkoI9W4txjz6JhpxZ9I=.1c8eae34-3e96-4f3c-8270-6b6e428232a3@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 68 commits:

 - Merge with upstream/master
 - improve first-sentence break in Markdown comments
 - add test cases for links to anchors
 - fix `textOf` method to accommodate Markdown content.
 - avoid relying on unspecified behavior `List.toString`
 - fix test after merge
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - Revise `Markdown.update` to better handle container blocks.
 - Refactor most of TestMarkdown.java into separate tests, grouped by functionality
 - add support for (top-level) trailing code blocks
   add simple test case with tabs
   add TestMarkdownCodeBlocks.testTypical
 - ... and 58 more: https://git.openjdk.org/jdk/compare/586396cb...76eccbf4

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=48
  Stats: 23757 lines in 208 files changed: 23030 ins; 281 del; 446 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From liach at openjdk.org  Tue Mar 12 04:18:23 2024
From: liach at openjdk.org (Chen Liang)
Date: Tue, 12 Mar 2024 04:18:23 GMT
Subject: RFR: 8327824: Type annotation placed on incorrect array nesting levels
Message-ID: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>

Please review this patch that fixes placement of type annotations on array types in Javadoc output. This oversight seems to have existed since JDK 8 but was never noticed or reported.

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

Commit messages:
 - Fix whitespace
 - Make sure varargs work too
 - Fix bugs, add tests, fix wrong anticipated test results
 - 8327824: Type annotation placed on incorrect array nesting levels

Changes: https://git.openjdk.org/jdk/pull/18211/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18211&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8327824
  Stats: 128 lines in 3 files changed: 102 ins; 1 del; 25 mod
  Patch: https://git.openjdk.org/jdk/pull/18211.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18211/head:pull/18211

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

From prappo at openjdk.org  Tue Mar 12 12:01:15 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 12 Mar 2024 12:01:15 GMT
Subject: RFR: 8327824: Type annotation placed on incorrect array nesting
 levels
In-Reply-To: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
References: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
Message-ID: <168JlD_8EW0chuVPIQ8cyxcpnK9VlgoIZTe47rV44BI=.663e58e1-b603-42bf-b381-1aa4941d30c0@github.com>

On Tue, 12 Mar 2024 03:33:38 GMT, Chen Liang <liach at openjdk.org> wrote:

> Please review this patch that fixes placement of type annotations on array types in Javadoc output. This oversight seems to have existed since JDK 8 but was never noticed or reported.

I've read your discussion with @cushon in the comment section for [the bug](https://bugs.openjdk.org/browse/JDK-8327824) and I agree that type annotations on arrays are unintuitive. Welp, we should make sure they are documented correctly.

Do you know if there's a test that exercises this particularly surprising bit from [Example 10.2-2. Array Variables and Array Types](https://docs.oracle.com/javase/specs/jls/se21/html/jls-10.html#d5e20110)?

> And perhaps surprisingly, the following field declarations have the same array type:
>
>     int @A [] f @B [];
>     int @B [] @A [] g;

If there isn't, we should add it.

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

PR Comment: https://git.openjdk.org/jdk/pull/18211#issuecomment-1991487157

From liach at openjdk.org  Tue Mar 12 12:10:17 2024
From: liach at openjdk.org (Chen Liang)
Date: Tue, 12 Mar 2024 12:10:17 GMT
Subject: RFR: 8325433: Type annotations on primitive types are not linked
 [v3]
In-Reply-To: <9uS8IS4OAvvhV-mEZcs3-Q3eyjpxuG76ae6VAKwbZ1s=.473d253f-5213-4eda-bfd5-b25086fb04f4@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
 <9uS8IS4OAvvhV-mEZcs3-Q3eyjpxuG76ae6VAKwbZ1s=.473d253f-5213-4eda-bfd5-b25086fb04f4@github.com>
Message-ID: <lFZCsLz2bOFZhhMxf7Pt5PYgxVelc1eDzUr9xU9nfAc=.b3e5517a-caa8-445e-aab2-5e4153f62e5a@github.com>

On Mon, 11 Mar 2024 13:57:23 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
>> 
>> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
>> 
>> import java.lang.annotation.*;
>> 
>> public class ArrayAnno {
>> 	@Retention(RetentionPolicy.RUNTIME)
>> 	@Target(ElementType.TYPE_USE)
>> 	@Documented
>> 	public @interface Anno { int value(); }
>> 
>> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
>> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
>> }
>> 
>> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
>> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
>> 
>> Note that a bug within javac (reported in https://bugs.openjdk.org/browse/JDK-8327824) causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Redundant imports

Assuming this passes tests, at least it passes tier1 on GitHub.

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

PR Comment: https://git.openjdk.org/jdk/pull/18179#issuecomment-1991502789

From liach at openjdk.org  Tue Mar 12 12:15:20 2024
From: liach at openjdk.org (Chen Liang)
Date: Tue, 12 Mar 2024 12:15:20 GMT
Subject: Integrated: 8325433: Type annotations on primitive types are not
 linked
In-Reply-To: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
References: <f-TcoLyVtmyUYpnYswyv7HUYThmdTxYliR5tWSPGmEQ=.1c3b91d6-5272-4b62-ba6d-952c2e897770@github.com>
Message-ID: <0D_7RAsflwuU__wuBTDo7wVhp7cdY16Z7dyHrUUBZa4=.65171100-66bf-4b8a-a6fd-6e79d7b9929b@github.com>

On Sun, 10 Mar 2024 20:19:44 GMT, Chen Liang <liach at openjdk.org> wrote:

> Please review this patch that fixes the issue where type annotations on primitive types are not linked.
> 
> Tested with file https://cr.openjdk.org/~liach/8325433-arrayanno/ArrayAnno.java
> 
> import java.lang.annotation.*;
> 
> public class ArrayAnno {
> 	@Retention(RetentionPolicy.RUNTIME)
> 	@Target(ElementType.TYPE_USE)
> 	@Documented
> 	public @interface Anno { int value(); }
> 
> 	public void method(@Anno(1) int @Anno(2) [] @Anno(3) [] arg) {}
> 	public void method(@Anno(1) String @Anno(2) [] @Anno(3) [] arg) {}
> }
> 
> JDK 21: https://cr.openjdk.org/~liach/8325433-arrayanno/old/ArrayAnno.html
> This patch: https://cr.openjdk.org/~liach/8325433-arrayanno/new/ArrayAnno.html
> 
> Note that a bug within javac (reported in https://bugs.openjdk.org/browse/JDK-8327824) causes the annotations to become `@Anno(1) String @Anno(3) [] @Anno(2) []` in the output files; this bug also affects output class files so I assume this is a bug within javac's tree building. (Intersting, the buggy javadoc output was copied wholesale in the original `TestTypeAnnotations` output for `array2Deep` cases, but no one paid attention to it)

This pull request has now been integrated.

Changeset: 2cf35246
Author:    Chen Liang <liach at openjdk.org>
Committer: Pavel Rappo <prappo at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/2cf35246e6041e3c721efc24441545deb7a671a8
Stats:     53 lines in 5 files changed: 44 ins; 0 del; 9 mod

8325433: Type annotations on primitive types are not linked

Reviewed-by: gli, prappo

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

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

From jjg at openjdk.org  Tue Mar 12 20:14:20 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 12 Mar 2024 20:14:20 GMT
Subject: RFR: JDK-8328006: refactor large anonymous inner class in
 HtmlDocletWriter
Message-ID: <YC6JUZU5xXGkJT2xsG5U7Pup9RHZtvQbSivKo5mXfck=.f3f4f55b-2dd6-40d3-aafb-dc3001c7b428@github.com>

Please review a conceptually simple change, to move a large anonymous inner class to be a named inner class.

While most of the code is simply moved, two simple changes were necessary.  In `visitEscape` and `visitText` the variable `result` from the enclosing lexical scope was accessed directly. The change is simply to use the equivalent value `content` which is passed to each `visit...` call.

No tests needed updating. All javadoc tests pass.

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

Commit messages:
 - JDK-8328006: refactor large anonymous inner class in HtmlDocletWriter

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

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

From prappo at openjdk.org  Tue Mar 12 20:55:12 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 12 Mar 2024 20:55:12 GMT
Subject: RFR: 8327824: Type annotation placed on incorrect array nesting
 levels
In-Reply-To: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
References: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
Message-ID: <wLzN-UjcS-aZvSwqBrE4UHO9lf2gnb-dpl6qYQTnG7c=.09bdc715-833d-4f2f-9c9c-bc32a1dcad38@github.com>

On Tue, 12 Mar 2024 03:33:38 GMT, Chen Liang <liach at openjdk.org> wrote:

> Please review this patch that fixes placement of type annotations on array types in Javadoc output. This oversight seems to have existed since JDK 8 but was never noticed or reported.

I looked into it; that wasn't easy ?.

7 years ago a seemingly similar bug, <https://bugs.openjdk.org/browse/JDK-8068737>, was fixed in _javac_. It's only now that javadoc is catching up.

Your change seems to be correct, but it disrupts the visitor's pattern. On the other hand, maybe keeping the change confined to `visitArray` is for the better here.

Here's what's left to be done:

- resolve merge conflicts due to recently integrated https://github.com/openjdk/jdk/pull/18179
- add a couple more test cases; for example, the JLS one that I mentioned earlier and maybe extract something from JBS-8068737

Thanks for doing it.

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

PR Review: https://git.openjdk.org/jdk/pull/18211#pullrequestreview-1932537513

From cushon at openjdk.org  Tue Mar 12 21:52:13 2024
From: cushon at openjdk.org (Liam Miller-Cushon)
Date: Tue, 12 Mar 2024 21:52:13 GMT
Subject: RFR: 8327824: Type annotation placed on incorrect array nesting
 levels
In-Reply-To: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
References: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
Message-ID: <7YmVaUd88gsoI3w6L_67B1h9-3SOoRVNeiNOoU4XakU=.9e87ad9f-b4df-4fd3-9e7f-b9d3fd3ab61a@github.com>

On Tue, 12 Mar 2024 03:33:38 GMT, Chen Liang <liach at openjdk.org> wrote:

> Please review this patch that fixes placement of type annotations on array types in Javadoc output. This oversight seems to have existed since JDK 8 but was never noticed or reported.

Thanks for this! The changes look good to me overall.

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

PR Comment: https://git.openjdk.org/jdk/pull/18211#issuecomment-1992644475

From liach at openjdk.org  Tue Mar 12 22:06:35 2024
From: liach at openjdk.org (Chen Liang)
Date: Tue, 12 Mar 2024 22:06:35 GMT
Subject: RFR: 8327824: Type annotation placed on incorrect array nesting
 levels [v2]
In-Reply-To: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
References: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
Message-ID: <t3SvcVcY5ZXa-r15KQIxoGKv-yGKluLroh0HaakpX30=.667d0e30-90b1-4c06-8a69-e9559ffde37c@github.com>

> Please review this patch that fixes placement of type annotations on array types in Javadoc output. This oversight seems to have existed since JDK 8 but was never noticed or reported.

Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains seven commits:

 - Check output from body instead of summary, summary changes css class when new members are added
 - Add test case for JLS example 10.2-2
 - Merge branch 'master' of https://github.com/openjdk/jdk into fix/jd-array-anno-order
 - Fix whitespace
 - Make sure varargs work too
 - Fix bugs, add tests, fix wrong anticipated test results
 - 8327824: Type annotation placed on incorrect array nesting levels

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

Changes: https://git.openjdk.org/jdk/pull/18211/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18211&range=01
  Stats: 128 lines in 3 files changed: 103 ins; 1 del; 24 mod
  Patch: https://git.openjdk.org/jdk/pull/18211.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18211/head:pull/18211

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

From liach at openjdk.org  Tue Mar 12 22:06:35 2024
From: liach at openjdk.org (Chen Liang)
Date: Tue, 12 Mar 2024 22:06:35 GMT
Subject: RFR: 8327824: Type annotation placed on incorrect array nesting
 levels
In-Reply-To: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
References: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
Message-ID: <elFpyN8lX0dF2JLymqqLMgB6_tYUWNzYHAnjKxsPoME=.1f28836f-8156-4c06-a7e6-166eaa5ba02e@github.com>

On Tue, 12 Mar 2024 03:33:38 GMT, Chen Liang <liach at openjdk.org> wrote:

> Please review this patch that fixes placement of type annotations on array types in Javadoc output. This oversight seems to have existed since JDK 8 but was never noticed or reported.

Now fixed merge conflict and added a test case for JLS 10.2-2, with the 2 styles of declarations present in the parameter and the return type respectively.

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

PR Comment: https://git.openjdk.org/jdk/pull/18211#issuecomment-1992660784

From hannesw at openjdk.org  Wed Mar 13 07:59:14 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 13 Mar 2024 07:59:14 GMT
Subject: RFR: JDK-8328006: refactor large anonymous inner class in
 HtmlDocletWriter
In-Reply-To: <YC6JUZU5xXGkJT2xsG5U7Pup9RHZtvQbSivKo5mXfck=.f3f4f55b-2dd6-40d3-aafb-dc3001c7b428@github.com>
References: <YC6JUZU5xXGkJT2xsG5U7Pup9RHZtvQbSivKo5mXfck=.f3f4f55b-2dd6-40d3-aafb-dc3001c7b428@github.com>
Message-ID: <KBFfDI6Vo3lOlN8sDUuM2vUOhU17eyRrk9QzEtZ99yE=.5a9ec333-ab88-4314-8825-cb988563372d@github.com>

On Tue, 12 Mar 2024 20:09:37 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a conceptually simple change, to move a large anonymous inner class to be a named inner class.
> 
> While most of the code is simply moved, two simple changes were necessary.  In `visitEscape` and `visitText` the variable `result` from the enclosing lexical scope was accessed directly. The change is simply to use the equivalent value `content` which is passed to each `visit...` call.
> 
> No tests needed updating. All javadoc tests pass.

Looks good except for a duplicate semicolon.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1295:

> 1293:             }
> 1294: 
> 1295:             var docTreeVisitor = new InlineVisitor(element, tag, isLastNode, context, ch, trees);;

Duplicate semicolon

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

Marked as reviewed by hannesw (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18252#pullrequestreview-1933364693
PR Review Comment: https://git.openjdk.org/jdk/pull/18252#discussion_r1522689134

From prappo at openjdk.org  Wed Mar 13 13:25:13 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 13 Mar 2024 13:25:13 GMT
Subject: RFR: JDK-8325874: Improve checkbox-based interface in summary
 pages
In-Reply-To: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
References: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
Message-ID: <D1wEKIE-ksLEn_m9xEJletwDA-uwxjTFa0i22J2hhuA=.1fc0a21b-0618-4881-9e01-bbe360129b36@github.com>

On Mon, 11 Mar 2024 13:37:54 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to improve the user experience and implementation for the checkbox-based interface to selectively display content on API summary pages:
> 
>  - Add a checkbox to toggle (select/unselect) all checkboxes in the page.
>  - Remove the `Table.setAlwaysShowDefaultTab(boolean)` setter as it is redundant and can be replaced by `!renderTabs`.
>  - Consolidate the code to generate checkboxes into a new protected `SummaryListWriter.getCheckbox` method.

Looks okay.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/NewAPIListWriter.java line 86:

> 84:             Content tabs = HtmlTree.DIV(HtmlStyle.checkboxes,
> 85:                     contents.getContent("doclet.New_API_Checkbox_Label"));
> 86:             // Table column ids are 1-based

On line 82, which I cannot add a comment to on GitHub, there's this:

    List<String> releases = configuration.newAPIPageBuilder.releases;

It might be better to change it to this:

    List<String> releases = builder.releases;

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

Marked as reviewed by prappo (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18194#pullrequestreview-1934169258
PR Review Comment: https://git.openjdk.org/jdk/pull/18194#discussion_r1523251733

From hannesw at openjdk.org  Wed Mar 13 14:32:13 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 13 Mar 2024 14:32:13 GMT
Subject: RFR: JDK-8325874: Improve checkbox-based interface in summary
 pages
In-Reply-To: <fAsuzjQ63aITEfYpdmEfSmN7YkvpvG-0d6YqekhTUgY=.d783f52e-0364-4c9f-93d3-747dba8fca39@github.com>
References: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
 <fAsuzjQ63aITEfYpdmEfSmN7YkvpvG-0d6YqekhTUgY=.d783f52e-0364-4c9f-93d3-747dba8fca39@github.com>
Message-ID: <z4FVnXi5155gbd7LV1XbCST8E4dYHKtCqp6-SXvw32E=.5a27cd33-a183-43d0-8d4d-60cbc1aaef00@github.com>

On Mon, 11 Mar 2024 18:09:41 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> if you check "all" and then uncheck something else, then "all" will remain selected. That is a confusing state.

I agree, but I think the behavior of the checkbox is as it should be, and it's the label that is slightly misleading. The intended behavior of the checkbox is set all other checkboxes to a unified state which can be either "on" or "off", not to reflect the state of other checkboxes. 

So maybe the correct label would be "toggle all" rather than just "all". Admittedly I have used the shorter "all" label to limit the length of the already long line of checkboxes. Do you think using "toggle all" as label would make things better?

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

PR Comment: https://git.openjdk.org/jdk/pull/18194#issuecomment-1994536241

From prappo at openjdk.org  Wed Mar 13 14:55:14 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 13 Mar 2024 14:55:14 GMT
Subject: RFR: JDK-8325874: Improve checkbox-based interface in summary
 pages
In-Reply-To: <z4FVnXi5155gbd7LV1XbCST8E4dYHKtCqp6-SXvw32E=.5a27cd33-a183-43d0-8d4d-60cbc1aaef00@github.com>
References: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
 <fAsuzjQ63aITEfYpdmEfSmN7YkvpvG-0d6YqekhTUgY=.d783f52e-0364-4c9f-93d3-747dba8fca39@github.com>
 <z4FVnXi5155gbd7LV1XbCST8E4dYHKtCqp6-SXvw32E=.5a27cd33-a183-43d0-8d4d-60cbc1aaef00@github.com>
Message-ID: <pdaSwbVPVsvSfgfZe9KnWnsxkC3SZU_FJQ4h5NGoMA8=.491d580f-8aba-4c5d-94c8-b8727a69dc3b@github.com>

On Wed, 13 Mar 2024 14:30:01 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> > if you check "all" and then uncheck something else, then "all" will remain selected. That is a confusing state.
> 
> I agree, but I think the behavior of the checkbox is as it should be, and it's the label that is slightly misleading. The intended behavior of the checkbox is set all other checkboxes to a unified state which can be either "on" or "off", not to reflect the state of other checkboxes.
> 
> So maybe the correct label would be "toggle all" rather than just "all". Admittedly I have used the shorter "all" label to limit the length of the already long line of checkboxes. Do you think using "toggle all" as label would make things better?

No, I don't think that "toggle all" would be better. It's the checkbox that slightly bothers me, not that checkbox's label.

One minimalistic, consistent approach that comes to mind is a stateless button that inverts selection. But admittedly, your suggestion is already implemented and is _less nerdy_. Don't bother changing it; it is a nit.

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

PR Comment: https://git.openjdk.org/jdk/pull/18194#issuecomment-1994584561

From hannesw at openjdk.org  Wed Mar 13 15:02:24 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 13 Mar 2024 15:02:24 GMT
Subject: RFR: JDK-8325874: Improve checkbox-based interface in summary
 pages [v2]
In-Reply-To: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
References: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
Message-ID: <GuQpmxSlFvGBt1prRHoEmTm_sAvjZWrUTw6mnIv4nQg=.e77efdac-c51d-4b41-8dfa-2fb2252b721c@github.com>

> Please review a change to improve the user experience and implementation for the checkbox-based interface to selectively display content on API summary pages:
> 
>  - Add a checkbox to toggle (select/unselect) all checkboxes in the page.
>  - Remove the `Table.setAlwaysShowDefaultTab(boolean)` setter as it is redundant and can be replaced by `!renderTabs`.
>  - Consolidate the code to generate checkboxes into a new protected `SummaryListWriter.getCheckbox` method.

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/18194/files
  - new: https://git.openjdk.org/jdk/pull/18194/files/cb37764d..d7460e8d

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

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

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

From prappo at openjdk.org  Wed Mar 13 15:15:15 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 13 Mar 2024 15:15:15 GMT
Subject: RFR: 8327824: Type annotation placed on incorrect array nesting
 levels [v2]
In-Reply-To: <t3SvcVcY5ZXa-r15KQIxoGKv-yGKluLroh0HaakpX30=.667d0e30-90b1-4c06-8a69-e9559ffde37c@github.com>
References: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
 <t3SvcVcY5ZXa-r15KQIxoGKv-yGKluLroh0HaakpX30=.667d0e30-90b1-4c06-8a69-e9559ffde37c@github.com>
Message-ID: <b060r7BzGJF2FGFy9lcCIy1c019ZlEPpVv-B9P-GZYo=.752cd2ca-001c-4933-ba3e-fe02fdd18a41@github.com>

On Tue, 12 Mar 2024 22:06:35 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Please review this patch that fixes placement of type annotations on array types in Javadoc output. This oversight seems to have existed since JDK 8 but was never noticed or reported.
>
> Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains seven commits:
> 
>  - Check output from body instead of summary, summary changes css class when new members are added
>  - Add test case for JLS example 10.2-2
>  - Merge branch 'master' of https://github.com/openjdk/jdk into fix/jd-array-anno-order
>  - Fix whitespace
>  - Make sure varargs work too
>  - Fix bugs, add tests, fix wrong anticipated test results
>  - 8327824: Type annotation placed on incorrect array nesting levels

This PR passes our CI and looks good; thanks.

test/langtools/jdk/javadoc/doclet/testTypeAnnotations/typeannos/DeepArrays.java line 34:

> 32:     @ArrA ArrParameterized<@ArrC String @ArrA [] @ArrB []> @ArrC [] @ArrD [] manyNested() { return null; }
> 33:     void varargs(@ArrA String @ArrB [] @ArrC [] @ArrD ... arg) {}
> 34:     int @ArrA [] mixedStyles(int @ArrB [] @ArrA [] arg) @ArrB [] { return null; } // JLS example 10.2-2

Took me a second or so to remind myself that this is a valid method declaration with the return type `int[][]`:

    int[] mixedStyles(int[][] arg) []

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

Marked as reviewed by prappo (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18211#pullrequestreview-1933913639
PR Review Comment: https://git.openjdk.org/jdk/pull/18211#discussion_r1523088118

From hannesw at openjdk.org  Wed Mar 13 15:16:22 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 13 Mar 2024 15:16:22 GMT
Subject: Integrated: JDK-8325874: Improve checkbox-based interface in summary
 pages
In-Reply-To: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
References: <rMKnNNno-nk5YJrs5CAulLM6ChdHG0f0BKQSSY7LYAs=.fe64ecb9-af5b-4e81-b830-b66018f1e77c@github.com>
Message-ID: <0MeX10JuNKsqFuKkilbRwPeUVmAa-OFIfVYIRvtGXUs=.9a20e472-0da0-43cc-93f3-c7d0592fb72d@github.com>

On Mon, 11 Mar 2024 13:37:54 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to improve the user experience and implementation for the checkbox-based interface to selectively display content on API summary pages:
> 
>  - Add a checkbox to toggle (select/unselect) all checkboxes in the page.
>  - Remove the `Table.setAlwaysShowDefaultTab(boolean)` setter as it is redundant and can be replaced by `!renderTabs`.
>  - Consolidate the code to generate checkboxes into a new protected `SummaryListWriter.getCheckbox` method.

This pull request has now been integrated.

Changeset: 03532450
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/035324503f5e04b53d99573a664fd1367b7ccf30
Stats:     142 lines in 9 files changed: 55 ins; 52 del; 35 mod

8325874: Improve checkbox-based interface in summary pages

Reviewed-by: prappo

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

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

From liach at openjdk.org  Wed Mar 13 16:48:21 2024
From: liach at openjdk.org (Chen Liang)
Date: Wed, 13 Mar 2024 16:48:21 GMT
Subject: Integrated: 8327824: Type annotation placed on incorrect array nesting
 levels
In-Reply-To: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
References: <WUgAMd_qyFkfuz_Tk9bgWHOne3_WDBTz2Hmr8ZOYLlA=.6def7959-b6da-4e8a-ba06-7ba952b85453@github.com>
Message-ID: <eI9KeXgnLmbI8zaOMStbbQ9fsqNmZ-eRh59ilvl91yc=.8abf37fb-be1a-48cf-a477-36600fa6e67e@github.com>

On Tue, 12 Mar 2024 03:33:38 GMT, Chen Liang <liach at openjdk.org> wrote:

> Please review this patch that fixes placement of type annotations on array types in Javadoc output. This oversight seems to have existed since JDK 8 but was never noticed or reported.

This pull request has now been integrated.

Changeset: 35b00e64
Author:    Chen Liang <liach at openjdk.org>
Committer: Pavel Rappo <prappo at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/35b00e640b7b3f29796433aee86838ae46167419
Stats:     128 lines in 3 files changed: 103 ins; 1 del; 24 mod

8327824: Type annotation placed on incorrect array nesting levels

Reviewed-by: prappo

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

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

From jjg at openjdk.org  Sat Mar 16 22:25:06 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Sat, 16 Mar 2024 22:25:06 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v50]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <5iwOoEAgMLQAlSM2lel0c_hb0eV_rI0pRA1H4FTFpk0=.67fa5f21-25b3-417a-b9fc-ae31695708b7@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 69 commits:

 - Merge with upstream/master
 - Merge with upstream/master
 - improve first-sentence break in Markdown comments
 - add test cases for links to anchors
 - fix `textOf` method to accommodate Markdown content.
 - avoid relying on unspecified behavior `List.toString`
 - fix test after merge
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - Revise `Markdown.update` to better handle container blocks.
 - Refactor most of TestMarkdown.java into separate tests, grouped by functionality
 - ... and 59 more: https://git.openjdk.org/jdk/compare/65a84c26...635af77d

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=49
  Stats: 23526 lines in 208 files changed: 22955 ins; 228 del; 343 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From prappo at openjdk.org  Mon Mar 18 14:58:46 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 18 Mar 2024 14:58:46 GMT
Subject: RFR: 8297879: javadoc link to preview JEP 1000 has grouping character
 comma
Message-ID: <1_igawz8T_HtBuu7XHnp5a7MdBKn1faVA5zBCr2T9bU=.dc2b11f7-84db-4db8-9752-9fd4eb4bd695@github.com>

Please review this simple bugfix to properly construct links to preview JEPs.

The most straightforward fix I could think of was to pass `String` rather than `int` (`Integer`) to a method, which eventually calls `java.text.MessageFormat.format(String, Object...)`.

For the test, I decided to be ~lazy~ practical and piggyback on the existing infrastructure. The alternatives were:

 1. slap `noreg-hard` on the JBS bug and skip testing
 2. create a sophisticated test that dynamically adds a constant into the `PreviewFeature.Feature` enum, annotates some class with `PreviewFeature` with that constant, and finally documents that class with `PreviewFeature` patched into `java.base`

While (1) is insufficient, (2) seems overkill in this case.

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

Commit messages:
 - Initial commit

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

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

From jjg at openjdk.org  Mon Mar 18 15:11:28 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 18 Mar 2024 15:11:28 GMT
Subject: RFR: 8297879: javadoc link to preview JEP 1000 has grouping
 character comma
In-Reply-To: <1_igawz8T_HtBuu7XHnp5a7MdBKn1faVA5zBCr2T9bU=.dc2b11f7-84db-4db8-9752-9fd4eb4bd695@github.com>
References: <1_igawz8T_HtBuu7XHnp5a7MdBKn1faVA5zBCr2T9bU=.dc2b11f7-84db-4db8-9752-9fd4eb4bd695@github.com>
Message-ID: <nz7v-V_AlDkkcna0QR1eJ--P4xgHYqHXAwvd36SHXro=.6daad643-a58a-4bbc-a4b2-d5143da5f096@github.com>

On Mon, 18 Mar 2024 14:53:44 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Please review this simple bugfix to properly construct links to preview JEPs.
> 
> The most straightforward fix I could think of was to pass `String` rather than `int` (`Integer`) to a method, which eventually calls `java.text.MessageFormat.format(String, Object...)`.
> 
> For the test, I decided to be ~lazy~ practical and piggyback on the existing infrastructure. The alternatives were:
> 
>  1. slap `noreg-hard` on the JBS bug and skip testing
>  2. create a sophisticated test that dynamically adds a constant into the `PreviewFeature.Feature` enum, annotates some class with `PreviewFeature` with that constant, and finally documents that class with `PreviewFeature` patched into `java.base`
> 
> While (1) is insufficient, (2) seems overkill in this case.

Marked as reviewed by jjg (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/18350#pullrequestreview-1943374124

From prappo at openjdk.org  Mon Mar 18 15:11:29 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 18 Mar 2024 15:11:29 GMT
Subject: RFR: 8297879: javadoc link to preview JEP 1000 has grouping
 character comma
In-Reply-To: <1_igawz8T_HtBuu7XHnp5a7MdBKn1faVA5zBCr2T9bU=.dc2b11f7-84db-4db8-9752-9fd4eb4bd695@github.com>
References: <1_igawz8T_HtBuu7XHnp5a7MdBKn1faVA5zBCr2T9bU=.dc2b11f7-84db-4db8-9752-9fd4eb4bd695@github.com>
Message-ID: <k2e-QoOnPN-te3njlg3g3erUO-Uiw8qwVmWRf-QXPjI=.8ccb39a3-ea8b-4ec2-90ed-96ffe70c1ae6@github.com>

On Mon, 18 Mar 2024 14:53:44 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Please review this simple bugfix to properly construct links to preview JEPs.
> 
> The most straightforward fix I could think of was to pass `String` rather than `int` (`Integer`) to a method, which eventually calls `java.text.MessageFormat.format(String, Object...)`.
> 
> For the test, I decided to be ~lazy~ practical and piggyback on the existing infrastructure. The alternatives were:
> 
>  1. slap `noreg-hard` on the JBS bug and skip testing
>  2. create a sophisticated test that dynamically adds a constant into the `PreviewFeature.Feature` enum, annotates some class with `PreviewFeature` with that constant, and finally documents that class with `PreviewFeature` patched into `java.base`
> 
> While (1) is insufficient, (2) seems overkill in this case.

Hm... it's surprising to see that the Skara bots consider that src/java.base/share/classes/jdk/internal/javac/PreviewFeature.java belongs to core-libs, but not to compiler. Let me manually add it.

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

PR Comment: https://git.openjdk.org/jdk/pull/18350#issuecomment-2004168270

From vromero at openjdk.org  Mon Mar 18 16:28:27 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Mon, 18 Mar 2024 16:28:27 GMT
Subject: RFR: 8297879: javadoc link to preview JEP 1000 has grouping
 character comma
In-Reply-To: <1_igawz8T_HtBuu7XHnp5a7MdBKn1faVA5zBCr2T9bU=.dc2b11f7-84db-4db8-9752-9fd4eb4bd695@github.com>
References: <1_igawz8T_HtBuu7XHnp5a7MdBKn1faVA5zBCr2T9bU=.dc2b11f7-84db-4db8-9752-9fd4eb4bd695@github.com>
Message-ID: <Z6jHQE1QMiG7a6IX3zt3X-3oe9r25rI0CSi0JsnaV6E=.92574e35-a1bd-460b-ad9b-cfd86393a768@github.com>

On Mon, 18 Mar 2024 14:53:44 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Please review this simple bugfix to properly construct links to preview JEPs.
> 
> The most straightforward fix I could think of was to pass `String` rather than `int` (`Integer`) to a method, which eventually calls `java.text.MessageFormat.format(String, Object...)`.
> 
> For the test, I decided to be ~lazy~ practical and piggyback on the existing infrastructure. The alternatives were:
> 
>  1. slap `noreg-hard` on the JBS bug and skip testing
>  2. create a sophisticated test that dynamically adds a constant into the `PreviewFeature.Feature` enum, annotates some class with `PreviewFeature` with that constant, and finally documents that class with `PreviewFeature` patched into `java.base`
> 
> While (1) is insufficient, (2) seems overkill in this case.

lgtm

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18350#pullrequestreview-1943594610

From jjg at openjdk.org  Mon Mar 18 18:44:53 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 18 Mar 2024 18:44:53 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v51]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <pBm1kOwbWt6xCqLXjaNsguzi5vT_WNThuSbRkoV52_k=.f147f30f-8d01-4ae8-9c69-d03491e67a50@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 71 commits:

 - update man page
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - Merge with upstream/master
 - Merge with upstream/master
 - improve first-sentence break in Markdown comments
 - add test cases for links to anchors
 - fix `textOf` method to accommodate Markdown content.
 - avoid relying on unspecified behavior `List.toString`
 - fix test after merge
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - ... and 61 more: https://git.openjdk.org/jdk/compare/c901da48...03652d2f

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=50
  Stats: 23609 lines in 209 files changed: 22986 ins; 254 del; 369 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From prappo at openjdk.org  Tue Mar 19 15:25:26 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 19 Mar 2024 15:25:26 GMT
Subject: Integrated: 8297879: javadoc link to preview JEP 1000 has grouping
 character comma
In-Reply-To: <1_igawz8T_HtBuu7XHnp5a7MdBKn1faVA5zBCr2T9bU=.dc2b11f7-84db-4db8-9752-9fd4eb4bd695@github.com>
References: <1_igawz8T_HtBuu7XHnp5a7MdBKn1faVA5zBCr2T9bU=.dc2b11f7-84db-4db8-9752-9fd4eb4bd695@github.com>
Message-ID: <7PArJXG1ZKRHbwf2SBnuB6z1YIOC9iYcMgHNX_MHmSI=.aa8998d0-08ec-44de-88e1-781df1a695ae@github.com>

On Mon, 18 Mar 2024 14:53:44 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Please review this simple bugfix to properly construct links to preview JEPs.
> 
> The most straightforward fix I could think of was to pass `String` rather than `int` (`Integer`) to a method, which eventually calls `java.text.MessageFormat.format(String, Object...)`.
> 
> For the test, I decided to be ~lazy~ practical and piggyback on the existing infrastructure. The alternatives were:
> 
>  1. slap `noreg-hard` on the JBS bug and skip testing
>  2. create a sophisticated test that dynamically adds a constant into the `PreviewFeature.Feature` enum, annotates some class with `PreviewFeature` with that constant, and finally documents that class with `PreviewFeature` patched into `java.base`
> 
> While (1) is insufficient, (2) seems overkill in this case.

This pull request has now been integrated.

Changeset: f140eb4c
Author:    Pavel Rappo <prappo at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/f140eb4c3a47e1479d62fe1eef16bbbea92892bc
Stats:     5 lines in 3 files changed: 0 ins; 0 del; 5 mod

8297879: javadoc link to preview JEP 1000 has grouping character comma

Reviewed-by: jjg, vromero

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

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

From hannesw at openjdk.org  Wed Mar 20 15:54:12 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 20 Mar 2024 15:54:12 GMT
Subject: RFR: JDK-8324774: Add DejaVu web fonts [v2]
In-Reply-To: <Lk548ptvKbRVcPbOKEcIS8DyDR5xp27xWEjkXzSKkjA=.7de8ac81-2ead-4842-9fb3-e724d4b9afff@github.com>
References: <Lk548ptvKbRVcPbOKEcIS8DyDR5xp27xWEjkXzSKkjA=.7de8ac81-2ead-4842-9fb3-e724d4b9afff@github.com>
Message-ID: <wy8eX1J8ktdIgTBRGOgYFIsAt6ygXVZXQXAL2NjCre0=.b76dbe1c-fba6-429d-94be-b01a500eb975@github.com>

> This change adds the DejaVu web fonts that were previously maintained externally to the open repository so they are available both in JDK API documentation and any API documentation generated with the `javadoc` tool. All files added in this PR are the same as the ones previously maintained externally, with the exception of added license and name/version comments in `dejavu.css`.
> 
> Copying of font files to the generated documentation is done by looking for font file names in `dejavu.css`, so font file names can be changed without changing the code. However, the font file list is hard-coded in `APITest.java`. `CheckLibraryVersions.java` is updated to make sure the name and version in the legal file matches the one in the stylesheet. Of course I also performed manual tests to make sure the font and legal files are copied to the output tree and used correctly in browsers.
> 
> Once #17411 is integrated, `dejavu.css` should also be added to the list of files checked by the new "pass-through" test.

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

 - JDK-8327385: Add JavaDoc option to exclude web fonts from generated documentation
 - Merge try-with-resource statements

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17633/files
  - new: https://git.openjdk.org/jdk/pull/17633/files/2c6e2163..9f77de97

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

  Stats: 188 lines in 7 files changed: 174 ins; 2 del; 12 mod
  Patch: https://git.openjdk.org/jdk/pull/17633.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17633/head:pull/17633

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

From jjg at openjdk.org  Wed Mar 20 19:08:40 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 20 Mar 2024 19:08:40 GMT
Subject: RFR: JDK-8324342: doclet should default @since for a nested class to
 that of its enclosing class
Message-ID: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>

Please review changes to the support for `since`, `author`, and `version` tags, such that if there are no such tags on a nested class, the doclet will look for any such tags in enclosing classes.

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

Commit messages:
 - JDK-8324342: doclet should default @since for a nested class to that of its enclosing class

Changes: https://git.openjdk.org/jdk/pull/18407/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18407&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8324342
  Stats: 189 lines in 6 files changed: 155 ins; 4 del; 30 mod
  Patch: https://git.openjdk.org/jdk/pull/18407.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18407/head:pull/18407

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

From jjg at openjdk.org  Thu Mar 21 22:02:41 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 21 Mar 2024 22:02:41 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v52]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <NSPkDBClzLjaMLW6Vd9ZT4FcHJela5N8routLU2pWsA=.f4977218-144b-4059-b586-7230569953ac@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with three additional commits since the last revision:

 - Merge pull request #3 from lahodaj/fix-positions-replacement
   
   Fixing positions when transforming javadoc text with replacement characters.
 - Merge branch '8298405.doclet-markdown-v3' into fix-positions-replacement
 - Fixing positions when transforming javadoc text with replacement characters.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/03652d2f..477fb155

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=51
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=50-51

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

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

From jjg at openjdk.org  Thu Mar 21 22:22:47 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 21 Mar 2024 22:22:47 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v53]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <879IOXARfX5wvr3xTdwX5kChGG4v3yFNfRLZZXs0t3c=.776ba5e1-fcb8-43aa-b90c-94c2173dc15a@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 76 commits:

 - Merge branch '8298405.doclet-markdown-v3' of https://github.com/jonathan-gibbons/jdk into 8298405.doclet-markdown-v3
 - Merge pull request #3 from lahodaj/fix-positions-replacement
   
   Fixing positions when transforming javadoc text with replacement characters.
 - Merge branch '8298405.doclet-markdown-v3' into fix-positions-replacement
 - Fixing positions when transforming javadoc text with replacement characters.
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - update man page
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - Merge with upstream/master
 - Merge with upstream/master
 - improve first-sentence break in Markdown comments
 - ... and 66 more: https://git.openjdk.org/jdk/compare/3f2e849c...a8ea1c72

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=52
  Stats: 23635 lines in 209 files changed: 23012 ins; 254 del; 369 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From martin.desruisseaux at geomatys.com  Sat Mar 23 10:59:10 2024
From: martin.desruisseaux at geomatys.com (Martin Desruisseaux)
Date: Sat, 23 Mar 2024 11:59:10 +0100
Subject: Inaccuracy in the documentation of the -group option?
Message-ID: <10d039fb-cee7-424d-9143-091bae7dc33a@geomatys.com>

Hello

The documentation for the Javadoc tools [1] documents the -group option 
as below:

    -group name p1,p2...
     ??? Group the specified packages together in the Overview page.

However, when documenting a project using Module Source Hierarchy, this 
option appears to group modules instead of packages. Should the 
documentation be updated? Also, grouping modules is great, but is there 
a way to also group packages in a multi-modules project?

 ??? Thanks,

 ??? ??? Martin

[1]https://docs.oracle.com/en/java/javase/22/docs/specs/man/javadoc.html#standard-options-for-the-standard-doclet
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20240323/0337e923/attachment.htm>

From jonathan.gibbons at oracle.com  Sat Mar 23 15:17:26 2024
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Sat, 23 Mar 2024 08:17:26 -0700
Subject: Inaccuracy in the documentation of the -group option?
In-Reply-To: <10d039fb-cee7-424d-9143-091bae7dc33a@geomatys.com>
References: <10d039fb-cee7-424d-9143-091bae7dc33a@geomatys.com>
Message-ID: <24097d09-5d5b-4873-b3e4-35b6747185a4@oracle.com>

Martin,

Thank you for the report. I have filed JDK-8328848 to fix the documentation.

There is currently no way to also group packages in a multi-modules project.

-- Jon

https://bugs.openjdk.org/browse/JDK-8328848


On 3/23/24 3:59 AM, Martin Desruisseaux wrote:
>
> Hello
>
> The documentation for the Javadoc tools [1] documents the -group 
> option as below:
>
>     -group name p1,p2...
>      ??? Group the specified packages together in the Overview page.
>
> However, when documenting a project using Module Source Hierarchy, 
> this option appears to group modules instead of packages. Should the 
> documentation be updated? Also, grouping modules is great, but is 
> there a way to also group packages in a multi-modules project?
>
> ??? Thanks,
>
> ??? ??? Martin
>
> [1]https://docs.oracle.com/en/java/javase/22/docs/specs/man/javadoc.html#standard-options-for-the-standard-doclet
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20240323/c903654a/attachment-0001.htm>

From jlahoda at openjdk.org  Mon Mar 25 20:06:33 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Mon, 25 Mar 2024 20:06:33 GMT
Subject: RFR: 8325168: JShell should support Markdown comments
Message-ID: <lgOTJzXSIjOcHAZp2SpQ96tEKpnwqGDP0jtIXVU9PEo=.ae8137ed-882c-4146-a4f9-68de26b03ef0@github.com>

This is an attempt to add Markdown support in documentation comments to JShell.

It works by converting the Markdown text to HTML during the process of resolving `{@inheritDoc}` tags.

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

Depends on: https://git.openjdk.org/jdk/pull/16388

Commit messages:
 - Cleanup.
 - Preventing a NPE.
 - Fixing test.
 - Merge branch '8298405.doclet-markdown-v3' into JDK-8298405
 - Cleanup.
 - Merge branch '8298405.doclet-markdown-v3' into JDK-8298405
 - Cleanup.
 - Merge branch '8298405.doclet-markdown-v3' into JDK-8298405
 - Removing ToHTMLMarkdownTransformer, as suggested
 - Adding forgotten class.
 - ... and 3 more: https://git.openjdk.org/jdk/compare/a8ea1c72...0ba0fffd

Changes: https://git.openjdk.org/jdk/pull/17686/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17686&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325168
  Stats: 1825 lines in 8 files changed: 977 ins; 842 del; 6 mod
  Patch: https://git.openjdk.org/jdk/pull/17686.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17686/head:pull/17686

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

From jjg at openjdk.org  Mon Mar 25 20:06:33 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 25 Mar 2024 20:06:33 GMT
Subject: RFR: 8325168: JShell should support Markdown comments
In-Reply-To: <lgOTJzXSIjOcHAZp2SpQ96tEKpnwqGDP0jtIXVU9PEo=.ae8137ed-882c-4146-a4f9-68de26b03ef0@github.com>
References: <lgOTJzXSIjOcHAZp2SpQ96tEKpnwqGDP0jtIXVU9PEo=.ae8137ed-882c-4146-a4f9-68de26b03ef0@github.com>
Message-ID: <c8N21cqMSMcDU-wuzfEnDvmNn0adC2gVop2NphfmROE=.304acd83-1c89-4f49-ac85-6d62adee64a8@github.com>

On Fri, 2 Feb 2024 14:02:28 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> This is an attempt to add Markdown support in documentation comments to JShell.
> 
> It works by converting the Markdown text to HTML during the process of resolving `{@inheritDoc}` tags.

Changes requested by jjg (Reviewer).

Compared to the previous PR, which was reasonably simple and quite elegant,
this one seems unduly complicated and somewhat invasive. It is also using
the transformer mechanism in a way that is not as intended. 

The `jdk.internal.md` module is intended to be for JDK support for Markdown.
As such, it has an imported copy of `commonmark-java` and now the new transformer
support, which is just intended to be used to support any JDK extensions to Markdown,
such as the new support for reference links for program elements. (There are 
suggestions for other future features in the JEP.) As such, I would 
expect all JDK clients to use the existing "standard" transformer, and to not 
substitute their own.  Ideally, the "standard" transformer would be used
by default, but I wanted to avoid an unconditional dependency from `jdk.compiler`
to `jdk.internal.md` -- so hence the use of the service provider mechanism.
(I guess I could update `jdk.compiler` to use `requires static` to establish
a compile-time dependency on the `jdk.internal.md` module, and then try
and install the standard transformer, which would always be available if we
put a hard dependency in modules like `jdk.javadoc` and `jdk.jshell`.)

Your previous PR was pretty good (although I accept we did not get as far as
a full review and approval.)  The recent changes the overall Markdown work
were made with that PR in mind.  As such, the intention was that only two
fairly small changes would be required.

1. Change the means to detect Markdown comments, from looking for `/**md`
   to using the new `CommentKind` support in `DocTrees`.
2. Install the 'standard' transformer, to enable the JDK extensions to
   Markdown

With those two changes, you can use the previous technique to parse and 
render a Markdown doc comment as before.

src/jdk.compiler/share/classes/jdk/internal/shellsupport/doc/JavadocHelper.java line 95:

> 93: import com.sun.tools.javac.util.DefinedBy.Api;
> 94: import com.sun.tools.javac.util.Pair;
> 95: import java.util.ServiceLoader;

out of order; suggest moving to be with other `java.*` imports

src/jdk.compiler/share/classes/jdk/internal/shellsupport/doc/JavadocHelper.java line 261:

> 259:                 @Override
> 260:                 public Void scan(Iterable<? extends DocTree> nodes, Void p) {
> 261:                     return super.scan(nodes, p); // Generated from nbfs://nbhost/SystemFileSystem/Templates/Classes/Code/OverriddenMethodBody

I'm not sure what to do with that comment.

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

PR Review: https://git.openjdk.org/jdk/pull/17686#pullrequestreview-1860164867
PR Comment: https://git.openjdk.org/jdk/pull/17686#issuecomment-1927843621
PR Review Comment: https://git.openjdk.org/jdk/pull/17686#discussion_r1476580909
PR Review Comment: https://git.openjdk.org/jdk/pull/17686#discussion_r1476583652

From jlahoda at openjdk.org  Mon Mar 25 20:06:33 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Mon, 25 Mar 2024 20:06:33 GMT
Subject: RFR: 8325168: JShell should support Markdown comments
In-Reply-To: <lgOTJzXSIjOcHAZp2SpQ96tEKpnwqGDP0jtIXVU9PEo=.ae8137ed-882c-4146-a4f9-68de26b03ef0@github.com>
References: <lgOTJzXSIjOcHAZp2SpQ96tEKpnwqGDP0jtIXVU9PEo=.ae8137ed-882c-4146-a4f9-68de26b03ef0@github.com>
Message-ID: <FjDUieHQtjB6XDyYxa6wYiWoxnHIKSOq88KIZiIvjYE=.cd13e6bd-a8b5-4f07-8b48-7d04efd2555b@github.com>

On Fri, 2 Feb 2024 14:02:28 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> This is an attempt to add Markdown support in documentation comments to JShell.
> 
> It works by converting the Markdown text to HTML during the process of resolving `{@inheritDoc}` tags.

Thanks for the comments! I've dropped the `ToHTML` transformer, and made the transformations easier. Sadly, the standard transformer seems to break raw text tree positions, so it is not currently possible to properly replace the Markdown text with the Javadoc text when the transformer is installed. Please see:
https://github.com/openjdk/jdk/pull/16388#discussion_r1479306878
for more details. Once that is solved, it should be possible to merge the newest changes in the Markdown branch.

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

PR Comment: https://git.openjdk.org/jdk/pull/17686#issuecomment-1928909938

From jjg at openjdk.org  Wed Mar 27 00:46:38 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 27 Mar 2024 00:46:38 GMT
Subject: RFR: JDK-8324774: Add DejaVu web fonts [v2]
In-Reply-To: <wy8eX1J8ktdIgTBRGOgYFIsAt6ygXVZXQXAL2NjCre0=.b76dbe1c-fba6-429d-94be-b01a500eb975@github.com>
References: <Lk548ptvKbRVcPbOKEcIS8DyDR5xp27xWEjkXzSKkjA=.7de8ac81-2ead-4842-9fb3-e724d4b9afff@github.com>
 <wy8eX1J8ktdIgTBRGOgYFIsAt6ygXVZXQXAL2NjCre0=.b76dbe1c-fba6-429d-94be-b01a500eb975@github.com>
Message-ID: <W9v-lCmjm-fO2V9SyO8qNmzWauy3OHW0hHPdNxlEgDA=.53a362d5-46ac-4736-84bd-50713ba3a5c3@github.com>

On Wed, 20 Mar 2024 15:54:12 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This change adds the DejaVu web fonts that were previously maintained externally to the open repository so they are available both in JDK API documentation and any API documentation generated with the `javadoc` tool. All files added in this PR are the same as the ones previously maintained externally, with the exception of added license and name/version comments in `dejavu.css`.
>> 
>> Copying of font files to the generated documentation is done by looking for font file names in `dejavu.css`, so font file names can be changed without changing the code. However, the font file list is hard-coded in `APITest.java`. `CheckLibraryVersions.java` is updated to make sure the name and version in the legal file matches the one in the stylesheet. Of course I also performed manual tests to make sure the font and legal files are copied to the output tree and used correctly in browsers.
>> 
>> Once #17411 is integrated, `dejavu.css` should also be added to the list of files checked by the new "pass-through" test.
>
> Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - JDK-8327385: Add JavaDoc option to exclude web fonts from generated documentation
>  - Merge try-with-resource statements

Marked as reviewed by jjg (Reviewer).

I like the new stuff for `JavadocTester` wrapped up in this work.

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

PR Review: https://git.openjdk.org/jdk/pull/17633#pullrequestreview-1962024918
PR Comment: https://git.openjdk.org/jdk/pull/17633#issuecomment-2021719299

From duke at openjdk.org  Wed Mar 27 09:39:25 2024
From: duke at openjdk.org (psoujany)
Date: Wed, 27 Mar 2024 09:39:25 GMT
Subject: RFR: JDK-8325690: The scrollable element <div> with
 non-interactive content is not tabbable [v2]
In-Reply-To: <7W9x4XR3rzFE6vyjfPOEEUN6mEYyNSq7-GbIt6bqSH0=.129ad201-8550-439f-93ad-4dbc1714ac7b@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
 <HpxOh4XSFGGOEFr4DxOl1AXbD5Znd9yeVTqcDFB8jCA=.9354c297-f8f5-4059-94d9-3561716b0f16@github.com>
 <tUEHAxBL7OGBnJk5IuJITsbhIYCXa3PE51yKcK0K3us=.8b7514b5-ee54-4b8e-8b29-bc47c1b84900@github.com>
 <dwPOD67DiQK-Oqgf2ezu2B9n_2luaF-Arv8uHF1Lh88=.83094723-6000-4a0d-a2f2-bca0d263a7e6@github.com>
 <6gVDntiPajQqNjqbrXd2U1l2lGn32H-xgXE8Bwp6hgI=.7498b6fb-0424-4570-9d60-413243d4ac6d@github.com>
 <7W9x4XR3rzFE6vyjfPOEEUN6mEYyNSq7-GbIt6bqSH0=.129ad201-8550-439f-93ad-4dbc1714ac7b@github.com>
Message-ID: <Fl48Ly8kE_iPxYlm2pr0CCC2-jj4bjTUUwSxpn0t0w0=.cdf1fe8a-930e-4356-9409-9c61615b33df@github.com>

On Wed, 6 Mar 2024 16:25:39 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> @hns Could you please validate my comment. Thank you.
>
> After having spent spent some time researching the problem and the proposed solution, I find that the premise of this issue is wrong. With current versions of supported browsers on my computer (Firefox, Chrome, Safari) the scrollable tabs can be focused using the tab key (in Safari the "press tab to highlight items" option has to be enabled in the advanced settings). It may be that this is a new addition in Chrome and Safari, and that they did not support this at the time when the issue was detected and filed.
> 
> Apart from that, I don't think that the proposed change would be a good fix for the problem. By removing the `overflow: auto` declarations in the given `<div>s`, overflow becomes invisible, or overflows the layout in the case of the rightmost column. Making content inaccessible for all users is not a good solution for the problem of content being inaccessible to keyboard users, and breaking the layout of the page is not desirable either.
> 
> Given that mainstream browsers seem to have followed Firefox and converted on making scrollable elements tabbable I would not consider this a problem in our documentation.

@hns Thank You for reviewing the change. We tested our change by adding/removing `overflow:auto` by feeding the `<div>`s with larger data and found column had expanded without scroll in both the cases and data was not stripped. After your review we extended our testing and found giving larger string in a line got stripped when there's no `overflow:auto`. Larger string was clearly visible with `overflow:auto` as it added horizontal scroll. 

We've fixed the issue by adding `tabindex=0` to the grid elements. We're testing the fix in various scenarios. Thank you.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17819#discussion_r1540754342

From hannesw at openjdk.org  Wed Mar 27 12:23:28 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 27 Mar 2024 12:23:28 GMT
Subject: Integrated: JDK-8324774: Add DejaVu web fonts
In-Reply-To: <Lk548ptvKbRVcPbOKEcIS8DyDR5xp27xWEjkXzSKkjA=.7de8ac81-2ead-4842-9fb3-e724d4b9afff@github.com>
References: <Lk548ptvKbRVcPbOKEcIS8DyDR5xp27xWEjkXzSKkjA=.7de8ac81-2ead-4842-9fb3-e724d4b9afff@github.com>
Message-ID: <bvE54Cwxq_9ua3-0TMHufX4V0xvSCv7CLymB1-kwoZg=.a471a789-2101-4321-9288-bbfbdc46c378@github.com>

On Tue, 30 Jan 2024 16:13:42 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This change adds the DejaVu web fonts that were previously maintained externally to the open repository so they are available both in JDK API documentation and any API documentation generated with the `javadoc` tool. All files added in this PR are the same as the ones previously maintained externally, with the exception of added license and name/version comments in `dejavu.css`.
> 
> Copying of font files to the generated documentation is done by looking for font file names in `dejavu.css`, so font file names can be changed without changing the code. However, the font file list is hard-coded in `APITest.java`. `CheckLibraryVersions.java` is updated to make sure the name and version in the legal file matches the one in the stylesheet. Of course I also performed manual tests to make sure the font and legal files are copied to the output tree and used correctly in browsers.
> 
> Once #17411 is integrated, `dejavu.css` should also be added to the list of files checked by the new "pass-through" test.

This pull request has now been integrated.

Changeset: d0a26503
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/d0a265039a36292d87b249af0e8977982e5acc7b
Stats:     546 lines in 38 files changed: 533 ins; 0 del; 13 mod

8324774: Add DejaVu web fonts
8327385: Add JavaDoc option to exclude web fonts from generated documentation

Reviewed-by: ihse, jjg

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

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

From prappo at openjdk.org  Wed Mar 27 17:23:36 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 27 Mar 2024 17:23:36 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
Message-ID: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>

Creating a link to a constructor or a method or comparing constructors or methods __does not__ factor in type parameters. When constructors or methods are overloaded and differ only in type parameters -- a situation which is absent in JDK API, but present elsewhere -- that causes significant defects, such as:

  - missing entries in summary tables, lists and indexes,
  - duplicating links in the table of contents.

This PR fixes those defects, and the fix is two-fold. Firstly, we update comparators to consider type parameters. That takes care of missing constructors and methods. Secondly, we update id (anchor) and link generation to always use the "erased" notation. That takes care of duplicating links.

What's the "erased" notation? Suppose we have the following method:

    <T extends String> T m(T arg)

The current notation refers to it as `m(T)`. That works fine until there's no other method, such as

    <T> T m(T arg)

In which case, the current notation will produce a collision: `m(T)`. By contrast, the erased notation for those two methods is `m(java.lang.String)` and `m(java.lang.Object)` respectively. No collision.

While longer, I believe that the erased notation is collision-proof. Why? Because [JLS 8.4.2][] says that "it is a compile-time error to declare two methods with override-equivalent signatures in a class". Which means that for any two constructors or methods the erasure of their signatures must differ, or else it won't compile.

The change is pretty straightforward, except for some test fallout that required attention.

[JLS 8.4.2]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-8.html#jls-8.4.2

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

Commit messages:
 - Update copyright years
 - Add more tests
 - Add test
 - Fix links from index and TOC
 - Fix index order
 - Fix summary table

Changes: https://git.openjdk.org/jdk/pull/18519/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18519&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325088
  Stats: 554 lines in 17 files changed: 420 ins; 61 del; 73 mod
  Patch: https://git.openjdk.org/jdk/pull/18519.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18519/head:pull/18519

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

From prappo at openjdk.org  Wed Mar 27 17:33:22 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 27 Mar 2024 17:33:22 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
In-Reply-To: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
Message-ID: <gKeKdA03g4ti8ifylxofYRGw5BrQ-IB_9zkJI6k4HfY=.399e8c5e-6b8f-400c-8da2-b2e5d74d148a@github.com>

On Wed, 27 Mar 2024 17:19:35 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Creating a link to a constructor or a method or comparing constructors or methods __does not__ factor in type parameters. When constructors or methods are overloaded and differ only in type parameters -- a situation which is absent in JDK API, but present elsewhere -- that causes significant defects, such as:
> 
>   - missing entries in summary tables, lists and indexes,
>   - duplicating links in the table of contents.
> 
> This PR fixes those defects, and the fix is two-fold. Firstly, we update comparators to consider type parameters. That takes care of missing constructors and methods. Secondly, we update id (anchor) and link generation to always use the "erased" notation. That takes care of duplicating links.
> 
> What's the "erased" notation? Suppose we have the following method:
> 
>     <T extends String> T m(T arg)
> 
> The current notation refers to it as `m(T)`. That works fine until there's no other method, such as
> 
>     <T> T m(T arg)
> 
> In which case, the current notation will produce a collision: `m(T)`. By contrast, the erased notation for those two methods is `m(java.lang.String)` and `m(java.lang.Object)` respectively. No collision.
> 
> While longer, I believe that the erased notation is collision-proof. Why? Because [JLS 8.4.2][] says that "it is a compile-time error to declare two methods with override-equivalent signatures in a class". Which means that for any two constructors or methods the erasure of their signatures must differ, or else it won't compile.
> 
> The change is pretty straightforward, except for some test fallout that required attention.
> 
> [JLS 8.4.2]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-8.html#jls-8.4.2

Let me note that it's a separate issue to (i) disambiguate link _labels_ in index, search, and TOC, and (ii) to ensure that `@link`, `@see`, etc. are capable of processing the erased notation.

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

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2023377778

From jjg at openjdk.org  Wed Mar 27 17:41:10 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 27 Mar 2024 17:41:10 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v54]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <XmFhnWo4YbN7e-C0lsCqjbMGOkYzByhW-IW8GAvEco0=.765b5ab5-6960-4179-b0bb-e77aec893f6a@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  add support for `--disable-line-doc-comments`

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/a8ea1c72..37646287

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=53
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=52-53

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

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

From jjg at openjdk.org  Wed Mar 27 18:58:24 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 27 Mar 2024 18:58:24 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
In-Reply-To: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
Message-ID: <1ZBdaVrfVHZr0998-n8L6PqgUa6BqHr8X5YK8l4U2-w=.41253741-7701-4d99-8b2d-6a47b29671d8@github.com>

On Wed, 27 Mar 2024 17:19:35 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Creating a link to a constructor or a method or comparing constructors or methods __does not__ factor in type parameters. When constructors or methods are overloaded and differ only in type parameters -- a situation which is absent in JDK API, but present elsewhere -- that causes significant defects, such as:
> 
>   - missing entries in summary tables, lists and indexes,
>   - duplicating links in the table of contents.
> 
> This PR fixes those defects, and the fix is two-fold. Firstly, we update comparators to consider type parameters. That takes care of missing constructors and methods. Secondly, we update id (anchor) and link generation to always use the "erased" notation. That takes care of duplicating links.
> 
> What's the "erased" notation? Suppose we have the following method:
> 
>     <T extends String> T m(T arg)
> 
> The current notation refers to it as `m(T)`. That works fine until there's no other method, such as
> 
>     <T> T m(T arg)
> 
> In which case, the current notation will produce a collision: `m(T)`. By contrast, the erased notation for those two methods is `m(java.lang.String)` and `m(java.lang.Object)` respectively. No collision.
> 
> While longer, I believe that the erased notation is collision-proof. Why? Because [JLS 8.4.2][] says that "it is a compile-time error to declare two methods with override-equivalent signatures in a class". Which means that for any two constructors or methods the erasure of their signatures must differ, or else it won't compile.
> 
> The change is pretty straightforward, except for some test fallout that required attention.
> 
> [JLS 8.4.2]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-8.html#jls-8.4.2

Generally, great work!

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 173:

> 171:      */
> 172:     HtmlId forMember(TypeElement typeElement, ExecutableElement member) {
> 173:         return HtmlId.of(forErasure(typeElement, member).replaceAll("\\s", ""));

I suggest adding something like an `@apiNote` to explain why the `typeElement` may not be the same as the enclosing element, if the enclosing element is not documented.   The hint is there in your use of the word `documented` -- and while that's true, it's also very subtle.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 215:

> 213:         var parameterTypes = ((ExecutableType) utils.typeUtils
> 214:                 .erasure(utils.asInstantiatedMethodType(site, executable)))
> 215:                 .getParameterTypes();

Cool expression!

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 216:

> 214:                 .erasure(utils.asInstantiatedMethodType(site, executable)))
> 215:                 .getParameterTypes();
> 216:         var stv = new SimpleTypeVisitor9<String, Void>() {

It's conventional to use the latest visitor, which in this case is `SimpleTypeVisitor14`, but that being said, there seems to be no obvious difference between 9 and 14.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 219:

> 217:             @Override
> 218:             public String visitArray(ArrayType t, Void p) {
> 219:                 return visit(t.getComponentType()) + utils.getDimension(t);

Obviously, `utils.getDimension()` harkens back to the old (JDK 8-era) doclet, but even the current implementation of that method could use some TLC. But that's not your problem here.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 233:

> 231:         };
> 232:         return executable.getSimpleName() + parameterTypes.stream()
> 233:                 .map(stv::visit)

Why do you need this (`stv::visit`) -- does the normal `.toString` for an array type not do the right thing?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 442:

> 440:     public HtmlId forPreviewSection(Element el) {
> 441:         return HtmlId.of("preview-" + switch (el.getKind()) {
> 442:             case CONSTRUCTOR, METHOD -> forMember((TypeElement) el.getEnclosingElement(), (ExecutableElement) el).name(); // fixme?

what needs fixing?

test/langtools/jdk/javadoc/doclet/testErasure/TestErasure.java line 70:

> 68:                     public abstract <T extends X> T m(T arg);
> 69:                     public abstract <T extends Y> T m(T arg);
> 70:                 }

Nice example

test/langtools/jdk/javadoc/doclet/testErasure/TestErasure.java line 81:

> 79:         checkExit(Exit.OK);
> 80:         // constructors
> 81:         checkOutput("Foo.html", true, """

This is not wrong, and so does not need to be changed, but situations like this are why `checkOrder` was added -- so that you can "spot check" the significant parts of the summary table (such as the links to the detail entries), without all the surrounding table-related stuff.

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

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2023718905
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1541583038
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1541810596
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1541759579
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1541826582
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1541830699
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1541828519
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1541573333
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1541838818

From liach at openjdk.org  Wed Mar 27 21:59:33 2024
From: liach at openjdk.org (Chen Liang)
Date: Wed, 27 Mar 2024 21:59:33 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
In-Reply-To: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
Message-ID: <X0udKzDzZDd9dK3E3UjXBHoFs5I22iuTnJU0O9ZrxTI=.b9ae3117-5449-49d3-ab1e-1a78ee79a53d@github.com>

On Wed, 27 Mar 2024 17:19:35 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Creating a link to a constructor or a method or comparing constructors or methods __does not__ factor in type parameters. When constructors or methods are overloaded and differ only in type parameters -- a situation which is absent in JDK API, but present elsewhere -- that causes significant defects, such as:
> 
>   - missing entries in summary tables, lists and indexes,
>   - duplicating links in the table of contents.
> 
> This PR fixes those defects, and the fix is two-fold. Firstly, we update comparators to consider type parameters. That takes care of missing constructors and methods. Secondly, we update id (anchor) and link generation to always use the "erased" notation. That takes care of duplicating links.
> 
> What's the "erased" notation? Suppose we have the following method:
> 
>     <T extends String> T m(T arg)
> 
> The current notation refers to it as `m(T)`. That works fine until there's no other method, such as
> 
>     <T> T m(T arg)
> 
> In which case, the current notation will produce a collision: `m(T)`. By contrast, the erased notation for those two methods is `m(java.lang.String)` and `m(java.lang.Object)` respectively. No collision.
> 
> While longer, I believe that the erased notation is collision-proof. Why? Because [JLS 8.4.2][] says that "it is a compile-time error to declare two methods with override-equivalent signatures in a class". Which means that for any two constructors or methods the erasure of their signatures must differ, or else it won't compile.
> 
> The change is pretty straightforward, except for some test fallout that required attention.
> 
> [JLS 8.4.2]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-8.html#jls-8.4.2

A compatibility problem is that if library C wants to link to library A on Java 17 with generic anchors and library B on 23 with erased anchors. Is there a way for Javadoc to generate the correct link to both older versions, such as by detecting which anchor format was used by scanning index.html?

A similar problem occured before when Javadoc changed `--` around method parameters to `()`.

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

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2024059820

From jjg at openjdk.org  Wed Mar 27 22:08:57 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 27 Mar 2024 22:08:57 GMT
Subject: RFR: JDK-8303689: javac -Xlint could/should report on "dangling" doc
 comments
Message-ID: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>

Please review the updates to support a proposed new `-Xlint:dangling-doc-comments` option.

The work can be thought of as in 3 parts:

1. An update to the `javac` internal class `DeferredLintHandler` so that it is possible to specify the appropriately configured `Lint` object when it is time to consider whether to generate the diagnostic or not.

2. Updates to the `javac` front end to record "dangling docs comments" found near the beginning of a declaration, and to report them using an instance of `DeferredLintHandler`. This allows the warnings to be enabled or disabled using the standard mechanisms for `-Xlint` and `@SuppressWarnings`.  The procedure for handling dangling doc comments is described in this comment in `JavacParser`.

     *  Dangling documentation comments are handled as follows.
     *  1. {@code Scanner} adds all doc comments to a queue of
     *     recent doc comments. The queue is flushed whenever
     *     it is known that the recent doc comments should be
     *     ignored and should not cause any warnings.
     *  2. The primary documentation comment is the one obtained
     *     from the first token of any declaration.
     *     (using {@code token.getDocComment()}.
     *  3. At the end of the "signature" of the declaration
     *     (that is, before any initialization or body for the
     *     declaration) any other "recent" comments are saved
     *     in a map using the primary comment as a key,
     *     using this method, {@code saveDanglingComments}.
     *  4. When the tree node for the declaration is finally
     *     available, and the primary comment, if any,
     *     is "attached", (in {@link #attach}) any related
     *     dangling comments are also attached to the tree node
     *     by registering them using the {@link #deferredLintHandler}.
     *  5. (Later) Warnings may be genereated for the dangling
     *     comments, subject to the {@code -Xlint} and
     *     {@code @SuppressWarnings}.


3.  Updates to the make files to disable the warnings in modules for which the 
warning is generated.  This is often because of the confusing use of `/**` to
create box or other standout comments.

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

Commit messages:
 - JDK-8303689: javac -Xlint could/should report on "dangling" doc comments

Changes: https://git.openjdk.org/jdk/pull/18527/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8303689
  Stats: 477 lines in 60 files changed: 368 ins; 5 del; 104 mod
  Patch: https://git.openjdk.org/jdk/pull/18527.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527

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

From prappo at openjdk.org  Wed Mar 27 22:44:31 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 27 Mar 2024 22:44:31 GMT
Subject: RFR: JDK-8303689: javac -Xlint could/should report on "dangling"
 doc comments
In-Reply-To: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
References: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
Message-ID: <7vkdZb7QDt106_k7_i7PrYzCYuEwTT-P2l4VxDOrNQk=.e98a3d16-8be0-4194-acd5-94eff555adce@github.com>

On Wed, 27 Mar 2024 22:04:30 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review the updates to support a proposed new `-Xlint:dangling-doc-comments` option.
> 
> The work can be thought of as in 3 parts:
> 
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it is possible to specify the appropriately configured `Lint` object when it is time to consider whether to generate the diagnostic or not.
> 
> 2. Updates to the `javac` front end to record "dangling docs comments" found near the beginning of a declaration, and to report them using an instance of `DeferredLintHandler`. This allows the warnings to be enabled or disabled using the standard mechanisms for `-Xlint` and `@SuppressWarnings`.  The procedure for handling dangling doc comments is described in this comment in `JavacParser`.
> 
>      *  Dangling documentation comments are handled as follows.
>      *  1. {@code Scanner} adds all doc comments to a queue of
>      *     recent doc comments. The queue is flushed whenever
>      *     it is known that the recent doc comments should be
>      *     ignored and should not cause any warnings.
>      *  2. The primary documentation comment is the one obtained
>      *     from the first token of any declaration.
>      *     (using {@code token.getDocComment()}.
>      *  3. At the end of the "signature" of the declaration
>      *     (that is, before any initialization or body for the
>      *     declaration) any other "recent" comments are saved
>      *     in a map using the primary comment as a key,
>      *     using this method, {@code saveDanglingComments}.
>      *  4. When the tree node for the declaration is finally
>      *     available, and the primary comment, if any,
>      *     is "attached", (in {@link #attach}) any related
>      *     dangling comments are also attached to the tree node
>      *     by registering them using the {@link #deferredLintHandler}.
>      *  5. (Later) Warnings may be genereated for the dangling
>      *     comments, subject to the {@code -Xlint} and
>      *     {@code @SuppressWarnings}.
> 
> 
> 3.  Updates to the make files to disable the warnings in modules for which the 
> warning is generated.  This is often because of the confusing use of `/**` to
> create box or other standout comments.

Would this be the first lint -- not doclint -- warning related to comments, let alone doc comments?

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

PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2024106466

From prappo at openjdk.org  Wed Mar 27 22:55:32 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 27 Mar 2024 22:55:32 GMT
Subject: RFR: JDK-8303689: javac -Xlint could/should report on "dangling"
 doc comments
In-Reply-To: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
References: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
Message-ID: <WsC10GQD9Q9xTXY9eY2_v5C91f8J5WKuRlRwmP4jElw=.b13568b0-44c3-470e-a8e4-aa27833ecd28@github.com>

On Wed, 27 Mar 2024 22:04:30 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review the updates to support a proposed new `-Xlint:dangling-doc-comments` option.
> 
> The work can be thought of as in 3 parts:
> 
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it is possible to specify the appropriately configured `Lint` object when it is time to consider whether to generate the diagnostic or not.
> 
> 2. Updates to the `javac` front end to record "dangling docs comments" found near the beginning of a declaration, and to report them using an instance of `DeferredLintHandler`. This allows the warnings to be enabled or disabled using the standard mechanisms for `-Xlint` and `@SuppressWarnings`.  The procedure for handling dangling doc comments is described in this comment in `JavacParser`.
> 
>      *  Dangling documentation comments are handled as follows.
>      *  1. {@code Scanner} adds all doc comments to a queue of
>      *     recent doc comments. The queue is flushed whenever
>      *     it is known that the recent doc comments should be
>      *     ignored and should not cause any warnings.
>      *  2. The primary documentation comment is the one obtained
>      *     from the first token of any declaration.
>      *     (using {@code token.getDocComment()}.
>      *  3. At the end of the "signature" of the declaration
>      *     (that is, before any initialization or body for the
>      *     declaration) any other "recent" comments are saved
>      *     in a map using the primary comment as a key,
>      *     using this method, {@code saveDanglingComments}.
>      *  4. When the tree node for the declaration is finally
>      *     available, and the primary comment, if any,
>      *     is "attached", (in {@link #attach}) any related
>      *     dangling comments are also attached to the tree node
>      *     by registering them using the {@link #deferredLintHandler}.
>      *  5. (Later) Warnings may be genereated for the dangling
>      *     comments, subject to the {@code -Xlint} and
>      *     {@code @SuppressWarnings}.
> 
> 
> 3.  Updates to the make files to disable the warnings in modules for which the 
> warning is generated.  This is often because of the confusing use of `/**` to
> create box or other standout comments.

Javadoc changes look trivially good. I only note that the javadoc man page diff contains some unrelated changes.

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

PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2024116236

From prappo at openjdk.org  Wed Mar 27 22:59:34 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 27 Mar 2024 22:59:34 GMT
Subject: RFR: JDK-8303689: javac -Xlint could/should report on "dangling"
 doc comments
In-Reply-To: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
References: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
Message-ID: <CR1gXDa9g51mJiCtmPnP6-P-eT_71xIppMf2ND8axQ0=.bc1e2507-9973-498a-b6c4-159732c2e406@github.com>

On Wed, 27 Mar 2024 22:04:30 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review the updates to support a proposed new `-Xlint:dangling-doc-comments` option.
> 
> The work can be thought of as in 3 parts:
> 
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it is possible to specify the appropriately configured `Lint` object when it is time to consider whether to generate the diagnostic or not.
> 
> 2. Updates to the `javac` front end to record "dangling docs comments" found near the beginning of a declaration, and to report them using an instance of `DeferredLintHandler`. This allows the warnings to be enabled or disabled using the standard mechanisms for `-Xlint` and `@SuppressWarnings`.  The procedure for handling dangling doc comments is described in this comment in `JavacParser`.
> 
>      *  Dangling documentation comments are handled as follows.
>      *  1. {@code Scanner} adds all doc comments to a queue of
>      *     recent doc comments. The queue is flushed whenever
>      *     it is known that the recent doc comments should be
>      *     ignored and should not cause any warnings.
>      *  2. The primary documentation comment is the one obtained
>      *     from the first token of any declaration.
>      *     (using {@code token.getDocComment()}.
>      *  3. At the end of the "signature" of the declaration
>      *     (that is, before any initialization or body for the
>      *     declaration) any other "recent" comments are saved
>      *     in a map using the primary comment as a key,
>      *     using this method, {@code saveDanglingComments}.
>      *  4. When the tree node for the declaration is finally
>      *     available, and the primary comment, if any,
>      *     is "attached", (in {@link #attach}) any related
>      *     dangling comments are also attached to the tree node
>      *     by registering them using the {@link #deferredLintHandler}.
>      *  5. (Later) Warnings may be genereated for the dangling
>      *     comments, subject to the {@code -Xlint} and
>      *     {@code @SuppressWarnings}.
> 
> 
> 3.  Updates to the make files to disable the warnings in modules for which the 
> warning is generated.  This is often because of the confusing use of `/**` to
> create box or other standout comments.

src/jdk.javadoc/share/man/javadoc.1 line 111:

> 109: source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more
> 110: specifically, \f[V]-Xlint:dangling-doc-comments\f[R].
> 111: Within a source file, you may use suppress any warnings generated by

Typo?
Suggestion:

Within a source file, you may suppress any warnings generated by

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18527#discussion_r1542131487

From jjg at openjdk.org  Wed Mar 27 23:39:32 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 27 Mar 2024 23:39:32 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
In-Reply-To: <X0udKzDzZDd9dK3E3UjXBHoFs5I22iuTnJU0O9ZrxTI=.b9ae3117-5449-49d3-ab1e-1a78ee79a53d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <X0udKzDzZDd9dK3E3UjXBHoFs5I22iuTnJU0O9ZrxTI=.b9ae3117-5449-49d3-ab1e-1a78ee79a53d@github.com>
Message-ID: <3dELnd_IvA4ulpukiIJP63fSTCjPejckgbKZlMlzgW0=.05787ac9-7113-4d43-91ed-4b854a362353@github.com>

On Wed, 27 Mar 2024 21:56:48 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Creating a link to a constructor or a method or comparing constructors or methods __does not__ factor in type parameters. When constructors or methods are overloaded and differ only in type parameters -- a situation which is absent in JDK API, but present elsewhere -- that causes significant defects, such as:
>> 
>>   - missing entries in summary tables, lists and indexes,
>>   - duplicating links in the table of contents.
>> 
>> This PR fixes those defects, and the fix is two-fold. Firstly, we update comparators to consider type parameters. That takes care of missing constructors and methods. Secondly, we update id (anchor) and link generation to always use the "erased" notation. That takes care of duplicating links.
>> 
>> What's the "erased" notation? Suppose we have the following method:
>> 
>>     <T extends String> T m(T arg)
>> 
>> The current notation refers to it as `m(T)`. That works fine until there's no other method, such as
>> 
>>     <T> T m(T arg)
>> 
>> In which case, the current notation will produce a collision: `m(T)`. By contrast, the erased notation for those two methods is `m(java.lang.String)` and `m(java.lang.Object)` respectively. No collision.
>> 
>> While longer, I believe that the erased notation is collision-proof. Why? Because [JLS 8.4.2][] says that "it is a compile-time error to declare two methods with override-equivalent signatures in a class". Which means that for any two constructors or methods the erasure of their signatures must differ, or else it won't compile.
>> 
>> The change is pretty straightforward, except for some test fallout that required attention.
>> 
>> [JLS 8.4.2]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-8.html#jls-8.4.2
>
> A compatibility problem is that if library C wants to link to library A on Java 17 with generic anchors and library B on 23 with erased anchors. Is there a way for Javadoc to generate the correct link to both older versions, such as by detecting which anchor format was used by scanning index.html?
> 
> A similar problem occured before when Javadoc changed `--` around method parameters to `()`.

@liach Thank you for reporting this issue.  The problem of linking to the API for different libraries generated with different versions of `javadoc` is indeed a difficult one.

I think the solution should be conceptually similar to the earlier problem you mentioned, addressed in [JDK-8297437](https://bugs.openjdk.org/browse/JDK-8297437).  In other words, the problem is not in the new-style ids, so much as in any links to pages with old(er)-style ids.

That being said, it would not be appropriate/reasonable for `javadoc` to scan HTML files to infer the style of `id` -- but there is an easier solution, which is to leverage the `element-list` file. (Previously, we leveraged the distinction between `package-list` and `element-list`).  The `element-list` file does not currently have any version or option info in it, implying any such files  it can be taken as implying version 1. Going forward, we can adapt the file to have a new kind of line as the first line, giving any extra info we need.

Links to other pages are generally handled by `HtmlLinkFactory` which eventually delegates to `Extern`.  `Extern` contains `boolean Extern.Item.useOldFormId` which I suspect should evolve from a `boolean` to an `enum` value or  `Set<Flag>` or something like that.

That being said, the current problem is slightly harder, because before, the problem was "just" about encoding the desired id into a form that was suitable for HTML 4.  Here, the choice is to use a completely different id. I suspect that the `memberName` parameter for `Extern.getExternalLink` may have to evolve from a `String` to something else -- maybe the underlying member `Element`, so that depending on the version of the remote library, we can generate the appropriate `id`.

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

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2024156429

From jjg at openjdk.org  Wed Mar 27 23:47:32 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 27 Mar 2024 23:47:32 GMT
Subject: RFR: JDK-8303689: javac -Xlint could/should report on "dangling"
 doc comments
In-Reply-To: <7vkdZb7QDt106_k7_i7PrYzCYuEwTT-P2l4VxDOrNQk=.e98a3d16-8be0-4194-acd5-94eff555adce@github.com>
References: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
 <7vkdZb7QDt106_k7_i7PrYzCYuEwTT-P2l4VxDOrNQk=.e98a3d16-8be0-4194-acd5-94eff555adce@github.com>
Message-ID: <VBk0641TIJuEE_Ez3MN1g9kd8v7zpjiBY4wdBvzaQP8=.9e11bd0d-14e8-4c9f-ac2c-72d0b77daeae@github.com>

On Wed, 27 Mar 2024 22:41:33 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Would this be the first lint -- not doclint -- warning related to comments, let alone doc comments?

No. `-Xlint:dep-ann` correlates `@Deprecated` annotations with `@deprecated` tags in doc comments.

> src/jdk.javadoc/share/man/javadoc.1 line 111:
> 
>> 109: source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more
>> 110: specifically, \f[V]-Xlint:dangling-doc-comments\f[R].
>> 111: Within a source file, you may use suppress any warnings generated by
> 
> Typo?
> Suggestion:
> 
> Within a source file, you may suppress any warnings generated by

Thanks; I'll check the underlying original.

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

PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2024162355
PR Review Comment: https://git.openjdk.org/jdk/pull/18527#discussion_r1542157047

From prappo at openjdk.org  Thu Mar 28 12:56:33 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 28 Mar 2024 12:56:33 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
In-Reply-To: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
Message-ID: <gWY5ClbHzuastUFrchlaSuNLVsHQGeLn0LyBYmn-bHU=.06a819ae-7f79-49a7-8751-43d187b5f7b4@github.com>

On Wed, 27 Mar 2024 17:19:35 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Creating a link to a constructor or a method or comparing constructors or methods __does not__ factor in type parameters. When constructors or methods are overloaded and differ only in type parameters -- a situation which is absent in JDK API, but present elsewhere -- that causes significant defects, such as:
> 
>   - missing entries in summary tables, lists and indexes,
>   - duplicating links in the table of contents.
> 
> This PR fixes those defects, and the fix is two-fold. Firstly, we update comparators to consider type parameters. That takes care of missing constructors and methods. Secondly, we update id (anchor) and link generation to always use the "erased" notation. That takes care of duplicating links.
> 
> What's the "erased" notation? Suppose we have the following method:
> 
>     <T extends String> T m(T arg)
> 
> The current notation refers to it as `m(T)`. That works fine until there's no other method, such as
> 
>     <T> T m(T arg)
> 
> In which case, the current notation will produce a collision: `m(T)`. By contrast, the erased notation for those two methods is `m(java.lang.String)` and `m(java.lang.Object)` respectively. No collision.
> 
> While longer, I believe that the erased notation is collision-proof. Why? Because [JLS 8.4.2][] says that "it is a compile-time error to declare two methods with override-equivalent signatures in a class". Which means that for any two constructors or methods the erasure of their signatures must differ, or else it won't compile.
> 
> The change is pretty straightforward, except for some test fallout that required attention.
> 
> [JLS 8.4.2]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-8.html#jls-8.4.2

While I've been working with javadoc for the last five years, somehow I've never had to deal with composability functionality provided by `link` and `linkoffline`. These options have been there since at least 1998: the earliest bug I found to mention them is https://bugs.openjdk.org/browse/JDK-4065454. Wow.

Back to the compatibility problem at hand. So we want to be able to link from the new output to the old output. Linking from the old output to the new output is out of the question, I suppose. After examining `Extern` briefly, I agree with Jon, in that the problem is not about transforming one string into another, but about mapping an element to a string.

I'll see what I can minimally do to support that.

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

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2025117217

From jjg at openjdk.org  Thu Mar 28 17:08:31 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 28 Mar 2024 17:08:31 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
In-Reply-To: <gWY5ClbHzuastUFrchlaSuNLVsHQGeLn0LyBYmn-bHU=.06a819ae-7f79-49a7-8751-43d187b5f7b4@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <gWY5ClbHzuastUFrchlaSuNLVsHQGeLn0LyBYmn-bHU=.06a819ae-7f79-49a7-8751-43d187b5f7b4@github.com>
Message-ID: <b387jG84afQRYQ4HMxRV4fHx7YjD_dCOnq5tfWq2roo=.e9722dca-0a25-46c7-8171-529b8a791aea@github.com>

On Thu, 28 Mar 2024 12:54:10 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> While I've been working with javadoc for the last five years, somehow I've never had to deal with composability functionality provided by `link` and `linkoffline`. These options have been there since at least 1998: the earliest bug I found to mention them is https://bugs.openjdk.org/browse/JDK-4065454. Wow.
> 
> Back to the compatibility problem at hand. So we want to be able to link from the new output to the old output. Linking from the old output to the new output is out of the question, I suppose. After examining `Extern` briefly, I agree with Jon, in that the problem is not about transforming one string into another, but about mapping an element to a string.
> 
> I'll see what I can minimally do to support that.

Some of us are in the privileged position of being at the bottom of the software stack, and so we rarely if ever need to create documentation to other libraries.  That being said, I notice that is an issue for some users, so much so that it was an external contribution to address the previous instance of this kind of problem.

> Linking from the old output to the new output is out of the question, I suppose. 

Yes.

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

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2025702997

From prappo at openjdk.org  Thu Mar 28 17:30:32 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 28 Mar 2024 17:30:32 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
In-Reply-To: <b387jG84afQRYQ4HMxRV4fHx7YjD_dCOnq5tfWq2roo=.e9722dca-0a25-46c7-8171-529b8a791aea@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <gWY5ClbHzuastUFrchlaSuNLVsHQGeLn0LyBYmn-bHU=.06a819ae-7f79-49a7-8751-43d187b5f7b4@github.com>
 <b387jG84afQRYQ4HMxRV4fHx7YjD_dCOnq5tfWq2roo=.e9722dca-0a25-46c7-8171-529b8a791aea@github.com>
Message-ID: <-vUJSA93tGM0AJgWSV9GHBlV5PnucujGOXbw3kqLc9Y=.33ad92df-cbae-4b53-8f9b-02678d4c5e43@github.com>

On Thu, 28 Mar 2024 17:03:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Some of us are in the privileged position of being at the bottom of the software stack, and so we rarely if ever need to create documentation to other libraries.

That paragraph of mine (that you are likely replying to) was about the fact that I was unfamiliar with that part of javadoc, not that I find it unimportant. Hence, I didn't envision any issues like the one raised by Chen.

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

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2025750358

From jjg at openjdk.org  Thu Mar 28 17:51:48 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 28 Mar 2024 17:51:48 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v43]
In-Reply-To: <GBCHPcPnrmMHP5Lv6OmpYTZYNv1mUDoSa_0LL0RNbyg=.1bdb3a33-ed23-470a-8157-a2c142a65712@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>
 <x_vvLqu7UsQHMlQCynTzD0ddhHvg2glkHXblCujUCrQ=.62b4b088-e12c-45fc-b974-bd83812d0c9e@github.com>
 <k4yPloMAtTmkzn54pzlVhTpBRq6dVGJxmFg1YVgAQVk=.5089ccc6-c675-4933-a8e8-633d6162984d@github.com>
 <GBCHPcPnrmMHP5Lv6OmpYTZYNv1mUDoSa_0LL0RNbyg=.1bdb3a33-ed23-470a-8157-a2c142a65712@github.com>
Message-ID: <ljbe7cYjSZ9UEz_xfex628-6_jQ5a_HC2wbSSdYszaY=.b125204f-d18c-4c80-908c-c2373a7512c4@github.com>

On Thu, 29 Feb 2024 11:39:41 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Setext headings only come in "level 1" and "level 2" flavors.
>> And, at the time the renderer sees the AST, the difference between ATX and setext headings is erased. They're just "headings".
>> 
>> I also think it is better to have a simple rule than an "adaptive" rule.  If you start doing a more complex rule, you have to consider the effect on subheadings as well.
>
> I suspected it was about the limited range of Setext headings. Yesterday my proposal was intentionally vague, but thinking about this again I think we should actually do the simplest and least intrusive thing possible:
> 
>     // minLevel is 4 for members, 2 for page-level elements, 1 for doc files
>     "h" + Math.max(heading.getLevel(), minLevel);
> 
> This arguably generates the correct heading for most simple use cases. What it doesn't do is to translate whole hierarchies of headings, but I would argue that few people people need this and those who do should figure out the rules and use the correct ATX headings.

Generally, I disagree with the policy here.
 
In particular, this suggestion "squashes"/"merges" heading levels at the more significant end of the range (i.e. h1, h2) and not at the least significant end of the range (i.e. h5, h6).  And, while we do specify the required heading levels in "traditional" doc comments, that seems less than optimal. (I note in times past we had to _modify_ the headings in doc comments as a result of the policy).  

Given all that, it seems better/simpler to specify that an author should start the headings in any comment at level 1 and have the tool adjust the level as needed.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1543389787

From prappo at openjdk.org  Thu Mar 28 19:09:31 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 28 Mar 2024 19:09:31 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
In-Reply-To: <X0udKzDzZDd9dK3E3UjXBHoFs5I22iuTnJU0O9ZrxTI=.b9ae3117-5449-49d3-ab1e-1a78ee79a53d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <X0udKzDzZDd9dK3E3UjXBHoFs5I22iuTnJU0O9ZrxTI=.b9ae3117-5449-49d3-ab1e-1a78ee79a53d@github.com>
Message-ID: <j0EXgAGb3EkJXYduP4ZrofC82kb7LkbEU1bC4WHPCP0=.e714821c-4bf0-4150-a8b7-8d3470e41715@github.com>

On Wed, 27 Mar 2024 21:56:48 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Creating a link to a constructor or a method or comparing constructors or methods __does not__ factor in type parameters. When constructors or methods are overloaded and differ only in type parameters -- a situation which is absent in JDK API, but present elsewhere -- that causes significant defects, such as:
>> 
>>   - missing entries in summary tables, lists and indexes,
>>   - duplicating links in the table of contents.
>> 
>> This PR fixes those defects, and the fix is two-fold. Firstly, we update comparators to consider type parameters. That takes care of missing constructors and methods. Secondly, we update id (anchor) and link generation to always use the "erased" notation. That takes care of duplicating links.
>> 
>> What's the "erased" notation? Suppose we have the following method:
>> 
>>     <T extends String> T m(T arg)
>> 
>> The current notation refers to it as `m(T)`. That works fine until there's no other method, such as
>> 
>>     <T> T m(T arg)
>> 
>> In which case, the current notation will produce a collision: `m(T)`. By contrast, the erased notation for those two methods is `m(java.lang.String)` and `m(java.lang.Object)` respectively. No collision.
>> 
>> While longer, I believe that the erased notation is collision-proof. Why? Because [JLS 8.4.2][] says that "it is a compile-time error to declare two methods with override-equivalent signatures in a class". Which means that for any two constructors or methods the erasure of their signatures must differ, or else it won't compile.
>> 
>> The change is pretty straightforward, except for some test fallout that required attention.
>> 
>> [JLS 8.4.2]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-8.html#jls-8.4.2
>
> A compatibility problem is that if library C wants to link to library A on Java 17 with generic anchors and library B on 23 with erased anchors. Is there a way for Javadoc to generate the correct link to both older versions, such as by detecting which anchor format was used by scanning index.html?
> 
> A similar problem occured before when Javadoc changed `--` around method parameters to `()`.

@liach, after a chat to Jon elsewhere, I'm unarchiving my previous solution, which solved another issue, but might also help with the issue you raised. Stay tuned.

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

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2025917914

From vromero at openjdk.org  Fri Mar 29 01:22:45 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Fri, 29 Mar 2024 01:22:45 GMT
Subject: RFR: 8325217: MethodSymbol.getModifiers() returns SEALED for
 restricted methods
Message-ID: <wTLUHdPYB5g7ataiX3pb2T4y9jSut5N-6KfsZz6PcrM=.8e0566cd-d875-454b-93d1-0bb5dd9ae14e@github.com>

Please review this simple fix, basically javadoc is showing the `sealed` modifier for methods annotated with the `jdk.internal.javac.Restricted` annotation. This is because the `SEALED` and `RESTRICTED` flags share the same bit. The proposed solution is to drop the `RESTRICTED` flag at MethodSymbol::getModifiers before converting the flags to modifiers,

TIA,
Vicente

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

Commit messages:
 - 8325217: MethodSymbol.getModifiers() returns SEALED for restricted methods

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

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

From vromero at openjdk.org  Fri Mar 29 03:07:32 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Fri, 29 Mar 2024 03:07:32 GMT
Subject: RFR: JDK-8303689: javac -Xlint could/should report on "dangling"
 doc comments
In-Reply-To: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
References: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
Message-ID: <GAZpxf-ZJzNHTZxqSFBUfMxBextCyxBNuNrINXTddyw=.8d42905b-1d96-49d8-992b-8edd48ae8a9b@github.com>

On Wed, 27 Mar 2024 22:04:30 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review the updates to support a proposed new `-Xlint:dangling-doc-comments` option.
> 
> The work can be thought of as in 3 parts:
> 
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it is possible to specify the appropriately configured `Lint` object when it is time to consider whether to generate the diagnostic or not.
> 
> 2. Updates to the `javac` front end to record "dangling docs comments" found near the beginning of a declaration, and to report them using an instance of `DeferredLintHandler`. This allows the warnings to be enabled or disabled using the standard mechanisms for `-Xlint` and `@SuppressWarnings`.  The procedure for handling dangling doc comments is described in this comment in `JavacParser`.
> 
>      *  Dangling documentation comments are handled as follows.
>      *  1. {@code Scanner} adds all doc comments to a queue of
>      *     recent doc comments. The queue is flushed whenever
>      *     it is known that the recent doc comments should be
>      *     ignored and should not cause any warnings.
>      *  2. The primary documentation comment is the one obtained
>      *     from the first token of any declaration.
>      *     (using {@code token.getDocComment()}.
>      *  3. At the end of the "signature" of the declaration
>      *     (that is, before any initialization or body for the
>      *     declaration) any other "recent" comments are saved
>      *     in a map using the primary comment as a key,
>      *     using this method, {@code saveDanglingComments}.
>      *  4. When the tree node for the declaration is finally
>      *     available, and the primary comment, if any,
>      *     is "attached", (in {@link #attach}) any related
>      *     dangling comments are also attached to the tree node
>      *     by registering them using the {@link #deferredLintHandler}.
>      *  5. (Later) Warnings may be genereated for the dangling
>      *     comments, subject to the {@code -Xlint} and
>      *     {@code @SuppressWarnings}.
> 
> 
> 3.  Updates to the make files to disable the warnings in modules for which the 
> warning is generated.  This is often because of the confusing use of `/**` to
> create box or other standout comments.

lgtm

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18527#pullrequestreview-1967750057