From duke at openjdk.org  Tue Apr  2 09:16:01 2024
From: duke at openjdk.org (ExE Boss)
Date: Tue, 2 Apr 2024 09:16:01 GMT
Subject: RFR: 8325217: MethodSymbol.getModifiers() returns SEALED for
 restricted methods
In-Reply-To: <wTLUHdPYB5g7ataiX3pb2T4y9jSut5N-6KfsZz6PcrM=.8e0566cd-d875-454b-93d1-0bb5dd9ae14e@github.com>
References: <wTLUHdPYB5g7ataiX3pb2T4y9jSut5N-6KfsZz6PcrM=.8e0566cd-d875-454b-93d1-0bb5dd9ae14e@github.com>
Message-ID: <jsrwiNu3wk3MB2gyml3J2a0clk_09pKwMCwVsiMypcU=.69d70861-49e3-49b1-a718-f49c22276c48@github.com>

On Fri, 29 Mar 2024 01:17:42 GMT, Vicente Romero <vromero at openjdk.org> wrote:

> 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

src/jdk.compiler/share/classes/com/sun/tools/javac/code/Symbol.java line 1999:

> 1997:             // just in case the method is restricted but that is not a modifier
> 1998:             long flags = flags() & ~RESTRICTED;
> 1999:             return Flags.asModifierSet((flags & DEFAULT) != 0 ? flags & ~ABSTRACT : flags);

Maybe?`Flags::asModifierSet` could?be?extended in?another?PR to?take a?parameter for?the?different modifier?kinds, which?would then?be?used to?disambiguate overloaded?`Flags`?bits.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18543#discussion_r1547464269

From vromero at openjdk.org  Tue Apr  2 15:04:00 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Tue, 2 Apr 2024 15:04:00 GMT
Subject: RFR: 8325217: MethodSymbol.getModifiers() returns SEALED for
 restricted methods
In-Reply-To: <jsrwiNu3wk3MB2gyml3J2a0clk_09pKwMCwVsiMypcU=.69d70861-49e3-49b1-a718-f49c22276c48@github.com>
References: <wTLUHdPYB5g7ataiX3pb2T4y9jSut5N-6KfsZz6PcrM=.8e0566cd-d875-454b-93d1-0bb5dd9ae14e@github.com>
 <jsrwiNu3wk3MB2gyml3J2a0clk_09pKwMCwVsiMypcU=.69d70861-49e3-49b1-a718-f49c22276c48@github.com>
Message-ID: <AdrJAhuHAavjv4Y_uGs6kauciaWex3gavJpZEkd2Pm4=.bed695f3-f96e-49c8-b08d-e3cb0bfdda2e@github.com>

On Tue, 2 Apr 2024 09:13:03 GMT, ExE Boss <duke at openjdk.org> wrote:

>> 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
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/code/Symbol.java line 1999:
> 
>> 1997:             // just in case the method is restricted but that is not a modifier
>> 1998:             long flags = flags() & ~RESTRICTED;
>> 1999:             return Flags.asModifierSet((flags & DEFAULT) != 0 ? flags & ~ABSTRACT : flags);
> 
> Maybe?`Flags::asModifierSet` could?be?extended in?another?PR to?take a?parameter for?the?different modifier?kinds, which?would then?be?used to?disambiguate overloaded?`Flags`?bits.

yep we could have other instances of this same issue in the future

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18543#discussion_r1548068147

From ihse at openjdk.org  Wed Apr  3 10:04:01 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Wed, 3 Apr 2024 10:04:01 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: <CJk_cgw_oK69SgmEsA7fC7wupoZ6Uc_MJ_vAEFUhMlc=.3b61473c-97e6-4a9a-b19b-e387ab9eb5ab@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.

The build changes look okay. 

Do you have any plan of going through all the Java modules and fixing the issues, or opening JBS issues to have them fixed? Or will these lint warnings remain disabled for the foreseeable future?

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

Marked as reviewed by ihse (Reviewer).

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

From prappo at openjdk.org  Wed Apr  3 11:55:45 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 3 Apr 2024 11:55:45 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v2]
In-Reply-To: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
Message-ID: <9anbfrbanT0iZFvywydmB99qGMjSUUaOUs8ZaSV-tIk=.94e188a3-e0a4-40be-9e23-3fd89a14eef3@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

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

 - Merge branch 'master' into 8325088
 - Update copyright years
   
   Note: any commit hashes below might be outdated due to subsequent
   history rewriting (e.g. git rebase).
   
    - revert src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testVisibleMembers/TestVisibleMembers.java as spurious
 - Use erased notation only when necessary
   
   Partially reverts 4f028269, which is the bulk of the previous solution,
   then adds a centralised ID registry for executable elements.
   
   The centralised registry is an alternative solution, which is more
   gentle and less disruptive to tests and composability (-link and
   -linkoffline).
 - Update copyright years
   
   Note: any commit hashes below might be outdated due to subsequent
   history rewriting (e.g. git rebase).
   
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testVisibleMembers/TestVisibleMembers.java due to 4f0282694fd
 - Add more tests
   
    - deprecated
    - preview
    - new
 - Add test
 - Fix links from index and TOC
   
   Also addresses some test fallout.
 - Fix index order
   
   Comparing type parameters as part of compareParameters disrupts the
   established sorting order in index.
 - Fix summary table

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18519/files
  - new: https://git.openjdk.org/jdk/pull/18519/files/57853bde..54b51ab7

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

  Stats: 10762 lines in 194 files changed: 3823 ins; 5052 del; 1887 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 jlahoda at openjdk.org  Wed Apr  3 15:25:09 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Wed, 3 Apr 2024 15:25:09 GMT
Subject: RFR: 8325217: MethodSymbol.getModifiers() returns SEALED for
 restricted methods
In-Reply-To: <wTLUHdPYB5g7ataiX3pb2T4y9jSut5N-6KfsZz6PcrM=.8e0566cd-d875-454b-93d1-0bb5dd9ae14e@github.com>
References: <wTLUHdPYB5g7ataiX3pb2T4y9jSut5N-6KfsZz6PcrM=.8e0566cd-d875-454b-93d1-0bb5dd9ae14e@github.com>
Message-ID: <iiRXncs4i5n17nAiz-QpkzSuGTxugxio9BEUamyF2F0=.93fde4aa-84bf-49fc-8965-71c74a323829@github.com>

On Fri, 29 Mar 2024 01:17:42 GMT, Vicente Romero <vromero at openjdk.org> wrote:

> 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

Looks good to me.

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

Marked as reviewed by jlahoda (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18543#pullrequestreview-1977176838

From vromero at openjdk.org  Wed Apr  3 15:59:04 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Wed, 3 Apr 2024 15:59:04 GMT
Subject: Integrated: 8325217: MethodSymbol.getModifiers() returns SEALED for
 restricted methods
In-Reply-To: <wTLUHdPYB5g7ataiX3pb2T4y9jSut5N-6KfsZz6PcrM=.8e0566cd-d875-454b-93d1-0bb5dd9ae14e@github.com>
References: <wTLUHdPYB5g7ataiX3pb2T4y9jSut5N-6KfsZz6PcrM=.8e0566cd-d875-454b-93d1-0bb5dd9ae14e@github.com>
Message-ID: <w7VhSdR0s6ua78lr7r68Co5g5CAfh0U05AQ8CR7Y22A=.6f190845-7b0c-4141-a946-71d0440cc69d@github.com>

On Fri, 29 Mar 2024 01:17:42 GMT, Vicente Romero <vromero at openjdk.org> wrote:

> 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

This pull request has now been integrated.

Changeset: 8dc43aa0
Author:    Vicente Romero <vromero at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/8dc43aa0fe8cdba2a2953258de02c6afa072987a
Stats:     10 lines in 2 files changed: 1 ins; 2 del; 7 mod

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

Reviewed-by: jlahoda

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

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

From prappo at openjdk.org  Wed Apr  3 18:14:39 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 3 Apr 2024 18:14:39 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
Message-ID: <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@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

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

 - Merge branch 'master' into 8325088
 - Remove registration phase
   
   Makes the code more robust and simple.
 - Merge branch 'master' into 8325088
 - Update copyright years
   
   Note: any commit hashes below might be outdated due to subsequent
   history rewriting (e.g. git rebase).
   
    - revert src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java as spurious
    - revert test/langtools/jdk/javadoc/doclet/testVisibleMembers/TestVisibleMembers.java as spurious
 - Use erased notation only when necessary
   
   Partially reverts 4f028269, which is the bulk of the previous solution,
   then adds a centralised ID registry for executable elements.
   
   The centralised registry is an alternative solution, which is more
   gentle and less disruptive to tests and composability (-link and
   -linkoffline).
 - Update copyright years
   
   Note: any commit hashes below might be outdated due to subsequent
   history rewriting (e.g. git rebase).
   
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java due to 4f0282694fd
    + update test/langtools/jdk/javadoc/doclet/testVisibleMembers/TestVisibleMembers.java due to 4f0282694fd
 - Add more tests
   
    - deprecated
    - preview
    - new
 - Add test
 - Fix links from index and TOC
   
   Also addresses some test fallout.
 - Fix index order
   
   Comparing type parameters as part of compareParameters disrupts the
   established sorting order in index.
 - ... and 1 more: https://git.openjdk.org/jdk/compare/eb4e76d7...b48eee11

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18519/files
  - new: https://git.openjdk.org/jdk/pull/18519/files/54b51ab7..b48eee11

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

  Stats: 769 lines in 73 files changed: 137 ins; 240 del; 392 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 Apr  3 18:20:02 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 3 Apr 2024 18:20:02 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
Message-ID: <iFhLZ8oEsN2fFTinxkYLKHnYcn3IpEOcuPH0k0xeJqY=.12894fd0-ac2a-4da0-86d0-2e6fe1f282de@github.com>

On Wed, 3 Apr 2024 18:14:39 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
>
> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 11 additional commits since the last revision:
> 
>  - Merge branch 'master' into 8325088
>  - Remove registration phase
>    
>    Makes the code more robust and simple.
>  - Merge branch 'master' into 8325088
>  - Update copyright years
>    
>    Note: any commit hashes below might be outdated due to subsequent
>    history rewriting (e.g. git rebase).
>    
>     - revert src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testVisibleMembers/TestVisibleMembers.java as spurious
>  - Use erased notation only when necessary
>    
>    Partially reverts 4f028269, which is the bulk of the previous solution,
>    then adds a centralised ID registry for executable elements.
>    
>    The centralised registry is an alternative solution, which is more
>    gentle and less disruptive to tests and composability (-link and
>    -linkoffline).
>  - Update copyright years
>    
>    Note: any commit hashes below might be outdated due to subsequent
>    history rewriting (e.g. git rebase).
>    
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 4f0282694fd
>     + update test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java due to 4f0282694fd
>     + update test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java due to 4f0282694fd
>     + update test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java due to 4f0282694fd
>     + update test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering....

Chen, Jon, I changed the solution to be less disruptive.

Erased id is now used only when necessary (which is never in the current JDK API Documentation or JDK tests that predate this PR). To determine if it is necessary to use the erased id for a constructor or method, simple ids for all executable elements of that type element are computed in order. If the simple id for an executable element `e` clashes with the simple id of some executable element computed before, the erased id for `e` is used.

This seems to work just fine. As a bonus, the overall size of the PR has been reduced. In addition to usual checks, I performed a few more. Here's the result:

  - there's no change in the JDK API documentation generated by `make docs-jdk-api`
  - there's no change in the output of tests generated by `jtreg -ea -esa -J-Djavatest.maxOutputSize=999999999 -retain:all <more options> test/langtools:langtools_javadoc`; the only difference was observed and expected in `testRedirectLinks`, which use ephemeral ports that leak to URIs
  - there's no significant difference in time it takes to generate either of the above

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

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

From liach at openjdk.org  Wed Apr  3 23:32:11 2024
From: liach at openjdk.org (Chen Liang)
Date: Wed, 3 Apr 2024 23:32:11 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
Message-ID: <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>

On Wed, 3 Apr 2024 18:14:39 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
>
> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 11 additional commits since the last revision:
> 
>  - Merge branch 'master' into 8325088
>  - Remove registration phase
>    
>    Makes the code more robust and simple.
>  - Merge branch 'master' into 8325088
>  - Update copyright years
>    
>    Note: any commit hashes below might be outdated due to subsequent
>    history rewriting (e.g. git rebase).
>    
>     - revert src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java as spurious
>     - revert test/langtools/jdk/javadoc/doclet/testVisibleMembers/TestVisibleMembers.java as spurious
>  - Use erased notation only when necessary
>    
>    Partially reverts 4f028269, which is the bulk of the previous solution,
>    then adds a centralised ID registry for executable elements.
>    
>    The centralised registry is an alternative solution, which is more
>    gentle and less disruptive to tests and composability (-link and
>    -linkoffline).
>  - Update copyright years
>    
>    Note: any commit hashes below might be outdated due to subsequent
>    history rewriting (e.g. git rebase).
>    
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 4f0282694fd
>     + update test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java due to 4f0282694fd
>     + update test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java due to 4f0282694fd
>     + update test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java due to 4f0282694fd
>     + update test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering....

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstructorWriter.java line 195:

> 193:         HtmlId erasureAnchor = htmlIds.forErasure(constructor);
> 194:         if (erasureAnchor != null
> 195:                 && !erasureAnchor.name().equals(memberAnchor.name())) {

Is this redundant now that the erasure handling is encapsulated within forMember?

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

> 560:                 && e.getKind() != ElementKind.METHOD)
> 561:             throw new IllegalArgumentException(String.valueOf(e.getKind()));
> 562:         var vmt = configuration.getVisibleMemberTable((TypeElement) e.getEnclosingElement());

Will the vmt differ if we specify `-private`? And say if we have 2 methods like:

private <T extends Runnable> void method(T arg) {}
public <T extends Number> void method(T arg) {}

Will the Number public method be consistently erased whether or not `-private` is set?

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

> 569:         var list = Stream.concat(Stream.concat(ctors.stream(), methods.stream()), otherMethods.stream())
> 570:                 .map(e1 -> (ExecutableElement) e1)
> 571:                 .toList();

We can maybe do something like:

record ErasureCheck(ExecutableElement element, HtmlId erasure) {}

// ...
    .map(e1 -> new ErasureCheck(e1, forErasure(e1)))
    .collect(Collectors.groupingBy(check -> check.erasure == null));

// 1. Map all elements that can _only_ be addressed by the simple id
for (var m : groups.get(true)) {...}

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1550637811
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1550635930
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1550643002

From prappo at openjdk.org  Thu Apr  4 11:44:03 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 4 Apr 2024 11:44:03 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
 <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
Message-ID: <KZUGyNVb8cnMPG3OIKK_6mER4xF0JT6Jnl66lnWJBDw=.13f73119-32f7-4001-ad5c-97fb6fc916f5@github.com>

On Wed, 3 Apr 2024 23:15:43 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 11 additional commits since the last revision:
>> 
>>  - Merge branch 'master' into 8325088
>>  - Remove registration phase
>>    
>>    Makes the code more robust and simple.
>>  - Merge branch 'master' into 8325088
>>  - Update copyright years
>>    
>>    Note: any commit hashes below might be outdated due to subsequent
>>    history rewriting (e.g. git rebase).
>>    
>>     - revert src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testVisibleMembers/TestVisibleMembers.java as spurious
>>  - Use erased notation only when necessary
>>    
>>    Partially reverts 4f028269, which is the bulk of the previous solution,
>>    then adds a centralised ID registry for executable elements.
>>    
>>    The centralised registry is an alternative solution, which is more
>>    gentle and less disruptive to tests and composability (-link and
>>    -linkoffline).
>>  - Update copyright years
>>    
>>    Note: any commit hashes below might be outdated due to subsequent
>>    history rewriting (e.g. git rebase).
>>    
>>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 4f0282694fd
>>     + update test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java due to 4f0282694fd
>>     + update test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java due to 4f0282694fd
>>     + update test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java due to 4f0282694...
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 562:
> 
>> 560:                 && e.getKind() != ElementKind.METHOD)
>> 561:             throw new IllegalArgumentException(String.valueOf(e.getKind()));
>> 562:         var vmt = configuration.getVisibleMemberTable((TypeElement) e.getEnclosingElement());
> 
> Will the vmt differ if we specify `-private`? And say if we have 2 methods like:
> 
> private <T extends Runnable> void method(T arg) {}
> public <T extends Number> void method(T arg) {}
> 
> Will the Number public method be consistently erased whether or not `-private` is set?

The answer to your latter question is no. The id that will be assigned to that public method do depend on whether the private overload positioned before it is documented. You cannot do much about it with the current design of `VisibleMemberTable` without unduly complicating this PR. On the bright side, I reckon such a case is extremely rare.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1551513544

From prappo at openjdk.org  Thu Apr  4 11:49:10 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 4 Apr 2024 11:49:10 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
 <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
Message-ID: <oanLqpiniZHdtVivplsQiRuElAOzOmA3cssfsmg4Ovc=.5be03c49-edfd-45a0-8f49-5c206213665e@github.com>

On Wed, 3 Apr 2024 23:19:29 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 11 additional commits since the last revision:
>> 
>>  - Merge branch 'master' into 8325088
>>  - Remove registration phase
>>    
>>    Makes the code more robust and simple.
>>  - Merge branch 'master' into 8325088
>>  - Update copyright years
>>    
>>    Note: any commit hashes below might be outdated due to subsequent
>>    history rewriting (e.g. git rebase).
>>    
>>     - revert src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testVisibleMembers/TestVisibleMembers.java as spurious
>>  - Use erased notation only when necessary
>>    
>>    Partially reverts 4f028269, which is the bulk of the previous solution,
>>    then adds a centralised ID registry for executable elements.
>>    
>>    The centralised registry is an alternative solution, which is more
>>    gentle and less disruptive to tests and composability (-link and
>>    -linkoffline).
>>  - Update copyright years
>>    
>>    Note: any commit hashes below might be outdated due to subsequent
>>    history rewriting (e.g. git rebase).
>>    
>>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 4f0282694fd
>>     + update test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java due to 4f0282694fd
>>     + update test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java due to 4f0282694fd
>>     + update test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java due to 4f0282694...
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstructorWriter.java line 195:
> 
>> 193:         HtmlId erasureAnchor = htmlIds.forErasure(constructor);
>> 194:         if (erasureAnchor != null
>> 195:                 && !erasureAnchor.name().equals(memberAnchor.name())) {
> 
> Is this redundant now that the erasure handling is encapsulated within forMember?

No, it's not redundant. `forMember` returns either the simple id or the erased id. `forErasure` always returns the erased id. Therefore, if `forMember` returns the erased id, there will be a duplicating id, which is a no-no.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1551518754

From prappo at openjdk.org  Thu Apr  4 12:28:23 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 4 Apr 2024 12:28:23 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v4]
In-Reply-To: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
Message-ID: <-zcgvN_KfqQhTaTptNv7m7HQk8-OZp2A1f1hDb1-x-0=.c532d836-80e2-42c5-b5b3-fe1dd5d7dda7@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

Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:

  Respond to feedback

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18519/files
  - new: https://git.openjdk.org/jdk/pull/18519/files/b48eee11..c7ea01c0

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

  Stats: 36 lines in 1 file changed: 9 ins; 5 del; 22 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  Thu Apr  4 12:31:13 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 4 Apr 2024 12:31:13 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
 <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
Message-ID: <op8AxxZs7xcXESTfy7WSnqnbCIaNHj2pXblSApweMdM=.3588d9e6-58f0-49e6-ad94-358d179d5f03@github.com>

On Wed, 3 Apr 2024 23:29:44 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 11 additional commits since the last revision:
>> 
>>  - Merge branch 'master' into 8325088
>>  - Remove registration phase
>>    
>>    Makes the code more robust and simple.
>>  - Merge branch 'master' into 8325088
>>  - Update copyright years
>>    
>>    Note: any commit hashes below might be outdated due to subsequent
>>    history rewriting (e.g. git rebase).
>>    
>>     - revert src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java as spurious
>>     - revert test/langtools/jdk/javadoc/doclet/testVisibleMembers/TestVisibleMembers.java as spurious
>>  - Use erased notation only when necessary
>>    
>>    Partially reverts 4f028269, which is the bulk of the previous solution,
>>    then adds a centralised ID registry for executable elements.
>>    
>>    The centralised registry is an alternative solution, which is more
>>    gentle and less disruptive to tests and composability (-link and
>>    -linkoffline).
>>  - Update copyright years
>>    
>>    Note: any commit hashes below might be outdated due to subsequent
>>    history rewriting (e.g. git rebase).
>>    
>>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 4f0282694fd
>>     + update test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java due to 4f0282694fd
>>     + update test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java due to 4f0282694fd
>>     + update test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java due to 4f0282694...
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 571:
> 
>> 569:         var list = Stream.concat(Stream.concat(ctors.stream(), methods.stream()), otherMethods.stream())
>> 570:                 .map(e1 -> (ExecutableElement) e1)
>> 571:                 .toList();
> 
> We can maybe do something like:
> 
> record ErasureCheck(ExecutableElement element, HtmlId erasure) {}
> 
> // ...
>     .map(e1 -> new ErasureCheck(e1, forErasure(e1)))
>     .collect(Collectors.groupingBy(check -> check.erasure == null));
> 
> // 1. Map all elements that can _only_ be addressed by the simple id
> for (var m : groups.get(true)) {...}

I addressed that in c7ea01c0cab. It looks leaner (`forErasure` is now called once), but is that as readable as you might have thought it would be?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1551585397

From liach at openjdk.org  Thu Apr  4 13:57:10 2024
From: liach at openjdk.org (Chen Liang)
Date: Thu, 4 Apr 2024 13:57:10 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <KZUGyNVb8cnMPG3OIKK_6mER4xF0JT6Jnl66lnWJBDw=.13f73119-32f7-4001-ad5c-97fb6fc916f5@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
 <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
 <KZUGyNVb8cnMPG3OIKK_6mER4xF0JT6Jnl66lnWJBDw=.13f73119-32f7-4001-ad5c-97fb6fc916f5@github.com>
Message-ID: <QIIEMAE1R1nzWiLdUjhtQEj8UJh58LG-AbZGiNOAj2M=.be76aa10-02a9-4e31-884d-6fda41e87847@github.com>

On Thu, 4 Apr 2024 11:41:37 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 562:
>> 
>>> 560:                 && e.getKind() != ElementKind.METHOD)
>>> 561:             throw new IllegalArgumentException(String.valueOf(e.getKind()));
>>> 562:         var vmt = configuration.getVisibleMemberTable((TypeElement) e.getEnclosingElement());
>> 
>> Will the vmt differ if we specify `-private`? And say if we have 2 methods like:
>> 
>> private <T extends Runnable> void method(T arg) {}
>> public <T extends Number> void method(T arg) {}
>> 
>> Will the Number public method be consistently erased whether or not `-private` is set?
>
> The answer to your latter question is no. The id that will be assigned to that public method do depend on whether the private overload positioned before it is documented. You cannot do much about it with the current design of `VisibleMemberTable` without unduly complicating this PR. On the bright side, I reckon such a case is extremely rare.

That's actually a sign of relief that the same elements will have the same id with the same input source code

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1551738452

From liach at openjdk.org  Thu Apr  4 14:20:10 2024
From: liach at openjdk.org (Chen Liang)
Date: Thu, 4 Apr 2024 14:20:10 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <op8AxxZs7xcXESTfy7WSnqnbCIaNHj2pXblSApweMdM=.3588d9e6-58f0-49e6-ad94-358d179d5f03@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
 <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
 <op8AxxZs7xcXESTfy7WSnqnbCIaNHj2pXblSApweMdM=.3588d9e6-58f0-49e6-ad94-358d179d5f03@github.com>
Message-ID: <nv4J_3E7CwLyCkk0m-VE3OKXJb5UwTTYq7LkiDrDrsQ=.13d9f81c-6c1c-403a-98c8-7d70495ae311@github.com>

On Thu, 4 Apr 2024 12:28:13 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 571:
>> 
>>> 569:         var list = Stream.concat(Stream.concat(ctors.stream(), methods.stream()), otherMethods.stream())
>>> 570:                 .map(e1 -> (ExecutableElement) e1)
>>> 571:                 .toList();
>> 
>> We can maybe do something like:
>> 
>> record ErasureCheck(ExecutableElement element, HtmlId erasure) {}
>> 
>> // ...
>>     .map(e1 -> new ErasureCheck(e1, forErasure(e1)))
>>     .collect(Collectors.groupingBy(check -> check.erasure == null));
>> 
>> // 1. Map all elements that can _only_ be addressed by the simple id
>> for (var m : groups.get(true)) {...}
>
> I addressed that in c7ea01c0cab. It looks leaner (`forErasure` is now called once), but is that as readable as you might have thought it would be?

Looks great, thanks!

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1551777805

From prappo at openjdk.org  Thu Apr  4 14:57:10 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 4 Apr 2024 14:57:10 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <QIIEMAE1R1nzWiLdUjhtQEj8UJh58LG-AbZGiNOAj2M=.be76aa10-02a9-4e31-884d-6fda41e87847@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
 <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
 <KZUGyNVb8cnMPG3OIKK_6mER4xF0JT6Jnl66lnWJBDw=.13f73119-32f7-4001-ad5c-97fb6fc916f5@github.com>
 <QIIEMAE1R1nzWiLdUjhtQEj8UJh58LG-AbZGiNOAj2M=.be76aa10-02a9-4e31-884d-6fda41e87847@github.com>
Message-ID: <fYwiuKpWLWjhAY_Eu5PbkHyaAHjZtTM-WRv5Rwp-yHA=.e2cf151b-bcc8-4ece-891d-5fbf127b0df1@github.com>

On Thu, 4 Apr 2024 13:53:57 GMT, Chen Liang <liach at openjdk.org> wrote:

>> The answer to your latter question is no. The id that will be assigned to that public method do depend on whether the private overload positioned before it is documented. You cannot do much about it with the current design of `VisibleMemberTable` without unduly complicating this PR. On the bright side, I reckon such a case is extremely rare.
>
> That's actually a sign of relief that the same elements will have the same id with the same input source code

Reading your reply, I think that one of us is likely confused. Your question to which I replied "no" was this:

> Will the Number public method be consistently erased whether or not -private is set?

I replied "no", which means that the id that the public method has DO depend on whether `-private` is specified. Let me expand on that.

If `-private` is specified, the "Method Details" section will have this for the public method:

    <section class="detail" id="method(java.lang.Number)">
    <h3>method</h3>
    
and this for the private method:

    <section class="detail" id="method(T)">
    <h3 id="method(java.lang.Runnable)">method</h3>

Otherwise, the "Method Details" section will only have this for the public method:

    <section class="detail" id="method(T)">
    <h3 id="method(java.lang.Number)">method</h3>

As you can see, depending on whether `-private` is specified, the section id for the public method will be different. 
    
Is that how you understood my reply and felt relief after that?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1551839067

From liach at openjdk.org  Thu Apr  4 15:49:09 2024
From: liach at openjdk.org (Chen Liang)
Date: Thu, 4 Apr 2024 15:49:09 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v3]
In-Reply-To: <fYwiuKpWLWjhAY_Eu5PbkHyaAHjZtTM-WRv5Rwp-yHA=.e2cf151b-bcc8-4ece-891d-5fbf127b0df1@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <ewiV1NZ6L1VBy-tM02RJLBRyVRX4IZod15ITmfhODYY=.530bd0cd-a867-4368-902a-31258331cc56@github.com>
 <IyXilG7dkT-Fl9RlVjqmSh-yQGWDp65ZpIB-SgBckPc=.d51161b0-87ac-43c4-a693-27a8ddf50fed@github.com>
 <KZUGyNVb8cnMPG3OIKK_6mER4xF0JT6Jnl66lnWJBDw=.13f73119-32f7-4001-ad5c-97fb6fc916f5@github.com>
 <QIIEMAE1R1nzWiLdUjhtQEj8UJh58LG-AbZGiNOAj2M=.be76aa10-02a9-4e31-884d-6fda41e87847@github.com>
 <fYwiuKpWLWjhAY_Eu5PbkHyaAHjZtTM-WRv5Rwp-yHA=.e2cf151b-bcc8-4ece-891d-5fbf127b0df1@github.com>
Message-ID: <WrJZBW5EjK6jOmJXdN_-ULnr7ZYJuGLKhgLhS_XeCME=.bee9ac64-86a3-41a9-9db3-367293deea68@github.com>

On Thu, 4 Apr 2024 14:53:09 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> That's actually a sign of relief that the same elements will have the same id with the same input source code
>
> Reading your reply, I think that one of us is likely confused. Your question to which I replied "no" was this:
> 
>> Will the Number public method be consistently erased whether or not -private is set?
> 
> I replied "no", which means that the id that the public method has DO depend on whether `-private` is specified. Let me expand on that.
> 
> If `-private` is specified, the "Method Details" section will have this for the public method:
> 
>     <section class="detail" id="method(java.lang.Number)">
>     <h3>method</h3>
>     
> and this for the private method:
> 
>     <section class="detail" id="method(T)">
>     <h3 id="method(java.lang.Runnable)">method</h3>
> 
> Otherwise, the "Method Details" section will only have this for the public method:
> 
>     <section class="detail" id="method(T)">
>     <h3 id="method(java.lang.Number)">method</h3>
> 
> As you can see, depending on whether `-private` is specified, the section id for the public method will be different. 
>     
> Is that how you understood my reply and felt relief after that?

It's fine, we always have an anchor to the erased version.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1551955976

From jjg at openjdk.org  Thu Apr  4 18:57:11 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 4 Apr 2024 18:57:11 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v4]
In-Reply-To: <-zcgvN_KfqQhTaTptNv7m7HQk8-OZp2A1f1hDb1-x-0=.c532d836-80e2-42c5-b5b3-fe1dd5d7dda7@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <-zcgvN_KfqQhTaTptNv7m7HQk8-OZp2A1f1hDb1-x-0=.c532d836-80e2-42c5-b5b3-fe1dd5d7dda7@github.com>
Message-ID: <5qWaJn4z2zxQpYsYoZlawFhRDmyzlt13takkkA3JnvY=.499bc210-4c0f-4b45-adca-bf82dd14fc89@github.com>

On Thu, 4 Apr 2024 12:28:23 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
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Respond to feedback

Some questions ...

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstructorWriter.java line 200:

> 198:         content.add(heading);
> 199:         return HtmlTree.SECTION(HtmlStyle.detail, content)
> 200:                 .setId(memberAnchor);

It's a bit disappointing that more of this isn't in `HtmlIds`.
It feels like it perpetuates the original ugly code.

Would it make sense for `htmlIds` to return a record/pair containing both the `memberId` and `erasureId` for `ExecutableElement` ?

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

> 565:         var methods = vmt.getVisibleMembers(VisibleMemberTable.Kind.METHODS);
> 566:         // for whatever reason annotation methods are not of Kind.METHODS
> 567:         var otherMethods = vmt.getVisibleMembers(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER);

I'm surprised you need to worry about annotation type members here -- annotation types cannot have type arguments, and so the "simple" id should always be sufficient.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/MethodWriter.java line 211:

> 209:         if (erasureAnchor != null
> 210:                 && !erasureAnchor.name().equals(memberAnchor.name())) {
> 211:             heading.setId(erasureAnchor);

See earlier comment about returning these together.

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

PR Review: https://git.openjdk.org/jdk/pull/18519#pullrequestreview-1980858688
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1552261527
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1552242033
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1552262881

From prappo at openjdk.org  Thu Apr  4 21:25:10 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 4 Apr 2024 21:25:10 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v4]
In-Reply-To: <5qWaJn4z2zxQpYsYoZlawFhRDmyzlt13takkkA3JnvY=.499bc210-4c0f-4b45-adca-bf82dd14fc89@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <-zcgvN_KfqQhTaTptNv7m7HQk8-OZp2A1f1hDb1-x-0=.c532d836-80e2-42c5-b5b3-fe1dd5d7dda7@github.com>
 <5qWaJn4z2zxQpYsYoZlawFhRDmyzlt13takkkA3JnvY=.499bc210-4c0f-4b45-adca-bf82dd14fc89@github.com>
Message-ID: <7G8WbdswwqNSbAX5ERfaEeYasU2c1yc_q48q6RgyBVE=.1b44f707-ea57-4876-b8ba-561f2d82f60c@github.com>

On Thu, 4 Apr 2024 18:52:42 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Respond to feedback
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstructorWriter.java line 200:
> 
>> 198:         content.add(heading);
>> 199:         return HtmlTree.SECTION(HtmlStyle.detail, content)
>> 200:                 .setId(memberAnchor);
> 
> It's a bit disappointing that more of this isn't in `HtmlIds`.
> It feels like it perpetuates the original ugly code.
> 
> Would it make sense for `htmlIds` to return a record/pair containing both the `memberId` and `erasureId` for `ExecutableElement` ?

I'll see how it pans out.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 567:
> 
>> 565:         var methods = vmt.getVisibleMembers(VisibleMemberTable.Kind.METHODS);
>> 566:         // for whatever reason annotation methods are not of Kind.METHODS
>> 567:         var otherMethods = vmt.getVisibleMembers(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER);
> 
> I'm surprised you need to worry about annotation type members here -- annotation types cannot have type arguments, and so the "simple" id should always be sufficient.

True, type parameters are not an issue for annotation interface methods, which [are not allowed to have any parameters][], type or otherwise. However, the code that prints annotations for method signatures does not know that and uses `forMember`, which is applicable to any executable member, of annotation or otherwise.

<img width="356" alt="a screenshot from the generated API Documentation for testNewAndDeprecated" src="https://github.com/openjdk/jdk/assets/32523691/fc808159-7f3f-4a2a-bb25-41474c3b5833">

In principle, I could remove that `vmt.getVisibleMembers(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER)` and the annotation member will be caught by the ["safety net"](https://github.com/openjdk/jdk/pull/18519/files#diff-22d9182196ae739a6de9c29801bb3ca788992b0cbf44564b2aeda2018a7b78e1R611-R621).

Since we are here, there's a `forMember` overload used by `AnnotationTypeMemberWriter`, I probably should remove it for consistency. Thoughts?

[are not allowed to have any parameters]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-9.html#jls-9.6.1

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1552464493
PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1552462722

From jjg at openjdk.org  Thu Apr  4 21:34:11 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 4 Apr 2024 21:34:11 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v4]
In-Reply-To: <7G8WbdswwqNSbAX5ERfaEeYasU2c1yc_q48q6RgyBVE=.1b44f707-ea57-4876-b8ba-561f2d82f60c@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <-zcgvN_KfqQhTaTptNv7m7HQk8-OZp2A1f1hDb1-x-0=.c532d836-80e2-42c5-b5b3-fe1dd5d7dda7@github.com>
 <5qWaJn4z2zxQpYsYoZlawFhRDmyzlt13takkkA3JnvY=.499bc210-4c0f-4b45-adca-bf82dd14fc89@github.com>
 <7G8WbdswwqNSbAX5ERfaEeYasU2c1yc_q48q6RgyBVE=.1b44f707-ea57-4876-b8ba-561f2d82f60c@github.com>
Message-ID: <PNjjjnD87QfQolh6G9GmuV43r-ZaCkeNX8GWEioZDe4=.81ff0204-6415-4442-af36-6e1c126f6f36@github.com>

On Thu, 4 Apr 2024 21:20:19 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java line 567:
>> 
>>> 565:         var methods = vmt.getVisibleMembers(VisibleMemberTable.Kind.METHODS);
>>> 566:         // for whatever reason annotation methods are not of Kind.METHODS
>>> 567:         var otherMethods = vmt.getVisibleMembers(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER);
>> 
>> I'm surprised you need to worry about annotation type members here -- annotation types cannot have type arguments, and so the "simple" id should always be sufficient.
>
> True, type parameters are not an issue for annotation interface methods, which [are not allowed to have any parameters][], type or otherwise. However, the code that prints annotations for method signatures does not know that and uses `forMember`, which is applicable to any executable member, of annotation or otherwise.
> 
> <img width="356" alt="a screenshot from the generated API Documentation for testNewAndDeprecated" src="https://github.com/openjdk/jdk/assets/32523691/fc808159-7f3f-4a2a-bb25-41474c3b5833">
> 
> In principle, I could remove that `vmt.getVisibleMembers(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER)` and the annotation member will be caught by the ["safety net"](https://github.com/openjdk/jdk/pull/18519/files#diff-22d9182196ae739a6de9c29801bb3ca788992b0cbf44564b2aeda2018a7b78e1R611-R621).
> 
> Since we are here, there's a `forMember` overload used by `AnnotationTypeMemberWriter`, I probably should remove it for consistency. Thoughts?
> 
> [are not allowed to have any parameters]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-9.html#jls-9.6.1

If you use `forMember` on an `ExecutableElement` whose enclosing element is an annotation type interface, you know there cannot be any type parameters.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1552474952

From prappo at openjdk.org  Thu Apr  4 21:56:10 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 4 Apr 2024 21:56:10 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v4]
In-Reply-To: <PNjjjnD87QfQolh6G9GmuV43r-ZaCkeNX8GWEioZDe4=.81ff0204-6415-4442-af36-6e1c126f6f36@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <-zcgvN_KfqQhTaTptNv7m7HQk8-OZp2A1f1hDb1-x-0=.c532d836-80e2-42c5-b5b3-fe1dd5d7dda7@github.com>
 <5qWaJn4z2zxQpYsYoZlawFhRDmyzlt13takkkA3JnvY=.499bc210-4c0f-4b45-adca-bf82dd14fc89@github.com>
 <7G8WbdswwqNSbAX5ERfaEeYasU2c1yc_q48q6RgyBVE=.1b44f707-ea57-4876-b8ba-561f2d82f60c@github.com>
 <PNjjjnD87QfQolh6G9GmuV43r-ZaCkeNX8GWEioZDe4=.81ff0204-6415-4442-af36-6e1c126f6f36@github.com>
Message-ID: <nktOazHIDqrtGGTklzlPMYPTklJt9upOpDyh7pdS8ug=.a196438c-9de7-47c2-b1fa-2dc752226ed5@github.com>

On Thu, 4 Apr 2024 21:31:03 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> True, type parameters are not an issue for annotation interface methods, which [are not allowed to have any parameters][], type or otherwise. However, the code that prints annotations for method signatures does not know that and uses `forMember`, which is applicable to any executable member, of annotation or otherwise.
>> 
>> <img width="356" alt="a screenshot from the generated API Documentation for testNewAndDeprecated" src="https://github.com/openjdk/jdk/assets/32523691/fc808159-7f3f-4a2a-bb25-41474c3b5833">
>> 
>> In principle, I could remove that `vmt.getVisibleMembers(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER)` and the annotation member will be caught by the ["safety net"](https://github.com/openjdk/jdk/pull/18519/files#diff-22d9182196ae739a6de9c29801bb3ca788992b0cbf44564b2aeda2018a7b78e1R611-R621).
>> 
>> Since we are here, there's a `forMember` overload used by `AnnotationTypeMemberWriter`, I probably should remove it for consistency. Thoughts?
>> 
>> [are not allowed to have any parameters]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-9.html#jls-9.6.1
>
> If you use `forMember` on an `ExecutableElement` whose enclosing element is an annotation type interface, you know there cannot be any type parameters.

Right, but some accommodation/special-casing for annotations will be there anyway:

  * "safety net",
  * `getVisibleMember(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER)`
  * `e.getEnclosingElement().getKind() == ElementKind.ANNOTATION_TYPE`

I have no preference, let alone strong opinion on either of those options. If you are concerned with "performance", which I know you might be, we could choose the latter option.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1552499948

From jjg at openjdk.org  Thu Apr  4 22:04:00 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 4 Apr 2024 22:04:00 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v4]
In-Reply-To: <nktOazHIDqrtGGTklzlPMYPTklJt9upOpDyh7pdS8ug=.a196438c-9de7-47c2-b1fa-2dc752226ed5@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <-zcgvN_KfqQhTaTptNv7m7HQk8-OZp2A1f1hDb1-x-0=.c532d836-80e2-42c5-b5b3-fe1dd5d7dda7@github.com>
 <5qWaJn4z2zxQpYsYoZlawFhRDmyzlt13takkkA3JnvY=.499bc210-4c0f-4b45-adca-bf82dd14fc89@github.com>
 <7G8WbdswwqNSbAX5ERfaEeYasU2c1yc_q48q6RgyBVE=.1b44f707-ea57-4876-b8ba-561f2d82f60c@github.com>
 <PNjjjnD87QfQolh6G9GmuV43r-ZaCkeNX8GWEioZDe4=.81ff0204-6415-4442-af36-6e1c126f6f36@github.com>
 <nktOazHIDqrtGGTklzlPMYPTklJt9upOpDyh7pdS8ug=.a196438c-9de7-47c2-b1fa-2dc752226ed5@github.com>
Message-ID: <nGMZf1UFLy1rvB5ZNtN4AFHv_3_FYwSPuFTPHs4WAwM=.4233292c-2e74-4479-90a2-f435ef63dba5@github.com>

On Thu, 4 Apr 2024 21:52:20 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> If you use `forMember` on an `ExecutableElement` whose enclosing element is an annotation type interface, you know there cannot be any type parameters.
>
> Right, but some accommodation/special-casing for annotations will be there anyway:
> 
>   * "safety net",
>   * `getVisibleMember(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER)`
>   * `e.getEnclosingElement().getKind() == ElementKind.ANNOTATION_TYPE`
> 
> I have no preference, let alone strong opinion on either of those options. If you are concerned with "performance", which I know you might be, we could choose the latter option.

I was not specifically concerned about performance in this case. It was more a case of code clarity/confusion (possibly my confusion).

So I guess the choice is one of:
* a common code path for all executable elements, whatever their container, regardless of whether there may be any risk of a clash of member ids caused by type parameters or anything else
* fast-track some code paths when you know there are no type parameters involved

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1552506842

From duke at openjdk.org  Fri Apr  5 00:06:16 2024
From: duke at openjdk.org (Nizar Benalla)
Date: Fri, 5 Apr 2024 00:06:16 GMT
Subject: RFR: JDK-8329717 Missing `@since` tags in elements in
 DocumentationTool and Taglet
Message-ID: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>

In this PR I added an `@since` tag to SNIPPET_PATH and isBlockTag() as they were added in later versions

- SNIPPET_PATH was added in JDK 18 [here](https://github.com/openjdk/jdk/commit/0fc47e99d20a1ee886df878f1302769bdd913aab#diff-8f73114f8b0d0d5229231541d5583382c8e8d33147e285f3d90ed8801ce9228bR192)

- isBlockTag() was added in JDK 15 [here](https://github.com/openjdk/jdk/commit/3c0e2b4e16d8fb2f96741bc8d4188aa47f58dd15#diff-3ee1b6e2a11b201a39ce3f2ac14ea9832900d8a3a581bf26577064173d0c9082R101)

This is similar to #18032

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

Commit messages:
 - add `@since` to `SNIPPET_PATH` and `isBlockTag()`

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

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

From prappo at openjdk.org  Fri Apr  5 09:34:11 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 5 Apr 2024 09:34:11 GMT
Subject: RFR: JDK-8329717 Missing `@since` tags in elements in
 DocumentationTool and Taglet
In-Reply-To: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
References: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
Message-ID: <GqgaSUOIJ8LvzAIZhJ3GcsGoh6UqYtdDQWmJqY8fM7c=.424f887e-fc99-446c-bdc0-cb2ae54d97f4@github.com>

On Fri, 5 Apr 2024 00:02:00 GMT, Nizar Benalla <duke at openjdk.org> wrote:

> In this PR I added an `@since` tag to SNIPPET_PATH and isBlockTag() as they were added in later versions
> 
> - SNIPPET_PATH was added in JDK 18 [here](https://github.com/openjdk/jdk/commit/0fc47e99d20a1ee886df878f1302769bdd913aab#diff-8f73114f8b0d0d5229231541d5583382c8e8d33147e285f3d90ed8801ce9228bR192)
> 
> - isBlockTag() was added in JDK 15 [here](https://github.com/openjdk/jdk/commit/3c0e2b4e16d8fb2f96741bc8d4188aa47f58dd15#diff-3ee1b6e2a11b201a39ce3f2ac14ea9832900d8a3a581bf26577064173d0c9082R101)
> 
> This is similar to #18032

Looks good. Thanks.

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java line 99:

> 97:      * @implSpec This implementation returns the inverse
> 98:      * result to {@code isInlineTag}.
> 99:      * @since 15

Might as well insert a blank line above.

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

Marked as reviewed by prappo (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18640#pullrequestreview-1982467362
PR Review Comment: https://git.openjdk.org/jdk/pull/18640#discussion_r1553259747

From duke at openjdk.org  Fri Apr  5 12:05:21 2024
From: duke at openjdk.org (Nizar Benalla)
Date: Fri, 5 Apr 2024 12:05:21 GMT
Subject: RFR: JDK-8329717 Missing `@since` tags in elements in
 DocumentationTool and Taglet [v2]
In-Reply-To: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
References: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
Message-ID: <VEvyo6vxjjEbfMOLGwjFv4YNejAOmccAIx4Dh1cDmqk=.0d7d3240-dc21-4dcd-b40f-e291f1217f5a@github.com>

> In this PR I added an `@since` tag to SNIPPET_PATH and isBlockTag() as they were added in later versions
> 
> - SNIPPET_PATH was added in JDK 18 [here](https://github.com/openjdk/jdk/commit/0fc47e99d20a1ee886df878f1302769bdd913aab#diff-8f73114f8b0d0d5229231541d5583382c8e8d33147e285f3d90ed8801ce9228bR192)
> 
> - isBlockTag() was added in JDK 15 [here](https://github.com/openjdk/jdk/commit/3c0e2b4e16d8fb2f96741bc8d4188aa47f58dd15#diff-3ee1b6e2a11b201a39ce3f2ac14ea9832900d8a3a581bf26577064173d0c9082R101)
> 
> This is similar to #18032

Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:

  add blank line

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18640/files
  - new: https://git.openjdk.org/jdk/pull/18640/files/0ffee115..0c5a300d

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

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

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

From duke at openjdk.org  Fri Apr  5 12:05:22 2024
From: duke at openjdk.org (Nizar Benalla)
Date: Fri, 5 Apr 2024 12:05:22 GMT
Subject: RFR: JDK-8329717 Missing `@since` tags in elements in
 DocumentationTool and Taglet [v2]
In-Reply-To: <GqgaSUOIJ8LvzAIZhJ3GcsGoh6UqYtdDQWmJqY8fM7c=.424f887e-fc99-446c-bdc0-cb2ae54d97f4@github.com>
References: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
 <GqgaSUOIJ8LvzAIZhJ3GcsGoh6UqYtdDQWmJqY8fM7c=.424f887e-fc99-446c-bdc0-cb2ae54d97f4@github.com>
Message-ID: <yuZxtdcUv_w9yN7FTuPViGCFkNy-Qyk27luQtq8dc_g=.331f3f94-353f-42d1-bd43-7ce2befd7340@github.com>

On Fri, 5 Apr 2024 09:30:22 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   add blank line
>
> src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java line 99:
> 
>> 97:      * @implSpec This implementation returns the inverse
>> 98:      * result to {@code isInlineTag}.
>> 99:      * @since 15
> 
> Might as well insert a blank line above.

Done, looking at the existing source code sometimes I find a blank line and sometimes I don't.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18640#discussion_r1553504955

From prappo at openjdk.org  Fri Apr  5 12:05:22 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 5 Apr 2024 12:05:22 GMT
Subject: RFR: JDK-8329717 Missing `@since` tags in elements in
 DocumentationTool and Taglet [v2]
In-Reply-To: <VEvyo6vxjjEbfMOLGwjFv4YNejAOmccAIx4Dh1cDmqk=.0d7d3240-dc21-4dcd-b40f-e291f1217f5a@github.com>
References: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
 <VEvyo6vxjjEbfMOLGwjFv4YNejAOmccAIx4Dh1cDmqk=.0d7d3240-dc21-4dcd-b40f-e291f1217f5a@github.com>
Message-ID: <AIeLnH8fFFBMOnJVxipGUsiQBgFB-1DXwJEOoGe8Fd0=.9b08dd17-1cbd-44e3-b625-756d91b2e3f1@github.com>

On Fri, 5 Apr 2024 12:02:41 GMT, Nizar Benalla <duke at openjdk.org> wrote:

>> In this PR I added an `@since` tag to SNIPPET_PATH and isBlockTag() as they were added in later versions
>> 
>> - SNIPPET_PATH was added in JDK 18 [here](https://github.com/openjdk/jdk/commit/0fc47e99d20a1ee886df878f1302769bdd913aab#diff-8f73114f8b0d0d5229231541d5583382c8e8d33147e285f3d90ed8801ce9228bR192)
>> 
>> - isBlockTag() was added in JDK 15 [here](https://github.com/openjdk/jdk/commit/3c0e2b4e16d8fb2f96741bc8d4188aa47f58dd15#diff-3ee1b6e2a11b201a39ce3f2ac14ea9832900d8a3a581bf26577064173d0c9082R101)
>> 
>> This is similar to #18032
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   add blank line

Marked as reviewed by prappo (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/18640#pullrequestreview-1982978404

From prappo at openjdk.org  Fri Apr  5 12:12:09 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 5 Apr 2024 12:12:09 GMT
Subject: RFR: JDK-8329717 Missing `@since` tags in elements in
 DocumentationTool and Taglet [v2]
In-Reply-To: <yuZxtdcUv_w9yN7FTuPViGCFkNy-Qyk27luQtq8dc_g=.331f3f94-353f-42d1-bd43-7ce2befd7340@github.com>
References: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
 <GqgaSUOIJ8LvzAIZhJ3GcsGoh6UqYtdDQWmJqY8fM7c=.424f887e-fc99-446c-bdc0-cb2ae54d97f4@github.com>
 <yuZxtdcUv_w9yN7FTuPViGCFkNy-Qyk27luQtq8dc_g=.331f3f94-353f-42d1-bd43-7ce2befd7340@github.com>
Message-ID: <wpQMvpQSZ6Ef8gR893WKdq7AJA8lFCreW12aqE3aBQY=.80ee5c90-3953-43c4-a068-3a206e2d632d@github.com>

On Fri, 5 Apr 2024 12:01:52 GMT, Nizar Benalla <duke at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java line 99:
>> 
>>> 97:      * @implSpec This implementation returns the inverse
>>> 98:      * result to {@code isInlineTag}.
>>> 99:      * @since 15
>> 
>> Might as well insert a blank line above.
>
> Done, looking at the existing source code sometimes I find a blank line and sometimes I don't.

Understood; my comment was a mild suggestion, not a requirement. I find it easier to read when `@since` is set off with a blank line.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18640#discussion_r1553514019

From duke at openjdk.org  Fri Apr  5 14:42:29 2024
From: duke at openjdk.org (psoujany)
Date: Fri, 5 Apr 2024 14:42:29 GMT
Subject: RFR: JDK-8325690: The scrollable element <div> with
 non-interactive content is not tabbable [v3]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <kOTd3BWbsGLT5JYDGn9krFscmbQPkGKpYFqPFhDC93U=.350a6fd1-c741-4dcd-a76f-19235615aaeb@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

 - Add tabindex to plain text for div column elements
 - Add tabindex to plain text for div column elements

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/3bd476af..a0f2773e

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

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

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

From prappo at openjdk.org  Fri Apr  5 15:03:36 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 5 Apr 2024 15:03:36 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v5]
In-Reply-To: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
Message-ID: <WdW4zCsNXJAgazmEpps4klHVlvA3edCpk80OdylR-p0=.50f6b5e5-0a83-44ff-8918-855051c76efe@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

Pavel Rappo has updated the pull request incrementally with seven additional commits since the last revision:

 - Update copyright years
   
   Note: any commit hashes below might be outdated due to subsequent
   history rewriting (e.g. git rebase).
   
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 0f33a6477e0
 - Clean up
 - Use a list of alternative ids
 - Cache forMember
 - Clarify some comments
 - Do not handle @interface methods specially
 - Nix forMember used by AnnotationTypeMemberWriter

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18519/files
  - new: https://git.openjdk.org/jdk/pull/18519/files/c7ea01c0..4dee61b7

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

  Stats: 187 lines in 6 files changed: 66 ins; 95 del; 26 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  Fri Apr  5 15:03:36 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 5 Apr 2024 15:03:36 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v4]
In-Reply-To: <7G8WbdswwqNSbAX5ERfaEeYasU2c1yc_q48q6RgyBVE=.1b44f707-ea57-4876-b8ba-561f2d82f60c@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <-zcgvN_KfqQhTaTptNv7m7HQk8-OZp2A1f1hDb1-x-0=.c532d836-80e2-42c5-b5b3-fe1dd5d7dda7@github.com>
 <5qWaJn4z2zxQpYsYoZlawFhRDmyzlt13takkkA3JnvY=.499bc210-4c0f-4b45-adca-bf82dd14fc89@github.com>
 <7G8WbdswwqNSbAX5ERfaEeYasU2c1yc_q48q6RgyBVE=.1b44f707-ea57-4876-b8ba-561f2d82f60c@github.com>
Message-ID: <b02zLLGL2niH9Ou1mDz2VRZQiMgS_POhU1exFSjnMN8=.6831982e-fae0-483f-877a-c40db73ee47b@github.com>

On Thu, 4 Apr 2024 21:21:58 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstructorWriter.java line 200:
>> 
>>> 198:         content.add(heading);
>>> 199:         return HtmlTree.SECTION(HtmlStyle.detail, content)
>>> 200:                 .setId(memberAnchor);
>> 
>> It's a bit disappointing that more of this isn't in `HtmlIds`.
>> It feels like it perpetuates the original ugly code.
>> 
>> Would it make sense for `htmlIds` to return a record/pair containing both the `memberId` and `erasureId` for `ExecutableElement` ?
>
> I'll see how it pans out.

Please have a look at the recent update to see if it's to your liking. Thanks.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18519#discussion_r1553818424

From duke at openjdk.org  Fri Apr  5 15:56:10 2024
From: duke at openjdk.org (Nizar Benalla)
Date: Fri, 5 Apr 2024 15:56:10 GMT
Subject: RFR: JDK-8329717 Missing @since tags in elements in
 DocumentationTool and Taglet [v2]
In-Reply-To: <VEvyo6vxjjEbfMOLGwjFv4YNejAOmccAIx4Dh1cDmqk=.0d7d3240-dc21-4dcd-b40f-e291f1217f5a@github.com>
References: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
 <VEvyo6vxjjEbfMOLGwjFv4YNejAOmccAIx4Dh1cDmqk=.0d7d3240-dc21-4dcd-b40f-e291f1217f5a@github.com>
Message-ID: <-rVscrk4thgCBpH3kQwbZ3lEBE7N9n7_gLgWv8uXenc=.d01bccce-ae9e-4bb9-874a-e271a4ff96eb@github.com>

On Fri, 5 Apr 2024 12:05:21 GMT, Nizar Benalla <duke at openjdk.org> wrote:

>> In this PR I added an `@since` tag to SNIPPET_PATH and isBlockTag() as they were added in later versions
>> 
>> - SNIPPET_PATH was added in JDK 18 [here](https://github.com/openjdk/jdk/commit/0fc47e99d20a1ee886df878f1302769bdd913aab#diff-8f73114f8b0d0d5229231541d5583382c8e8d33147e285f3d90ed8801ce9228bR192)
>> 
>> - isBlockTag() was added in JDK 15 [here](https://github.com/openjdk/jdk/commit/3c0e2b4e16d8fb2f96741bc8d4188aa47f58dd15#diff-3ee1b6e2a11b201a39ce3f2ac14ea9832900d8a3a581bf26577064173d0c9082R101)
>> 
>> This is similar to #18032
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   add blank line

This PR is ready, I plan on integrating it at a later point.

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

PR Comment: https://git.openjdk.org/jdk/pull/18640#issuecomment-2040150871

From jjg at openjdk.org  Fri Apr  5 17:55:10 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 5 Apr 2024 17:55:10 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v5]
In-Reply-To: <WdW4zCsNXJAgazmEpps4klHVlvA3edCpk80OdylR-p0=.50f6b5e5-0a83-44ff-8918-855051c76efe@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <WdW4zCsNXJAgazmEpps4klHVlvA3edCpk80OdylR-p0=.50f6b5e5-0a83-44ff-8918-855051c76efe@github.com>
Message-ID: <xS_mVgAkLc9j3e_BVr2hX-g-LHoXx1IcnTCXrVn_7KE=.0b92954b-07a3-4e07-af0c-a001080e5c7d@github.com>

On Fri, 5 Apr 2024 15:03:36 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
>
> Pavel Rappo has updated the pull request incrementally with seven additional commits since the last revision:
> 
>  - Update copyright years
>    
>    Note: any commit hashes below might be outdated due to subsequent
>    history rewriting (e.g. git rebase).
>    
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 0f33a6477e0
>  - Clean up
>  - Use a list of alternative ids
>  - Cache forMember
>  - Clarify some comments
>  - Do not handle @interface methods specially
>  - Nix forMember used by AnnotationTypeMemberWriter

Approved, with two optional suggestions.  Both could be considered style suggestions.

## 1
(Minor) While I like the new multi-valued return for `forMember(ExecutableElement executable)` I'm slightly surprised at the use of `List` rather than, say, a `record` that gives semantic meaning to the alternatives.  

## 2
Bigger, maybe for later. This could be thought of as more of a suggestion for a space _and_ time performance improvement, should such an improvement become necessary.

Most classes and interfaces do not have type parameters, not just annotation type interfaces. A quick grep survey of JDK indicates 242 classes and interfaces have type parameters out of a total of 3735 classes and interface. I accept that does not take into account classes and interfaces methods that have type parameters.  Anyway, since most classes and interfaces are "simple", the suggestion would be to have a two-level cache.instead of the simple one-level cache in `HtmlIds`.  

The current one-level cache is a simple `Map<ExecutableElement, List<HtmlId>> ids` meaning that there will an entry for every executable element that is encountered. Many of those entries are somewhat unnecessary, since any clash can only occur in classes or methods with type parameters, right?   So, a two-level cache would have an initial level that records whether a type element needs a subsidiary cache of ids for its executable elements. Once it has been determined that a type element has no type parameters or enclosed elements with type parameters, it should be enough to take the simple code path to determine the ids in the simple old-fashioned way. Conversely, if it is determined that the type element has type parameters or enclosed elements with type parameters, then the code can go the xtra mile to compute the second-level cache info.

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

Marked as reviewed by jjg (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18519#pullrequestreview-1983805843

From jjg at openjdk.org  Fri Apr  5 18:23:01 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 5 Apr 2024 18:23:01 GMT
Subject: RFR: JDK-8329717 Missing @since tags in elements in
 DocumentationTool and Taglet [v2]
In-Reply-To: <-rVscrk4thgCBpH3kQwbZ3lEBE7N9n7_gLgWv8uXenc=.d01bccce-ae9e-4bb9-874a-e271a4ff96eb@github.com>
References: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
 <VEvyo6vxjjEbfMOLGwjFv4YNejAOmccAIx4Dh1cDmqk=.0d7d3240-dc21-4dcd-b40f-e291f1217f5a@github.com>
 <-rVscrk4thgCBpH3kQwbZ3lEBE7N9n7_gLgWv8uXenc=.d01bccce-ae9e-4bb9-874a-e271a4ff96eb@github.com>
Message-ID: <xicc_HfqMKOnwFnsG1YuR_GOepnxZAs4W0_PZrwUm3M=.da2aa98e-6c58-45b4-9b71-30cc89e06d58@github.com>

On Fri, 5 Apr 2024 15:53:40 GMT, Nizar Benalla <duke at openjdk.org> wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   add blank line
>
> This PR is ready, I plan on integrating it at a later point.
> I won't make anymore changes, I just want to work on some things.

@nizarbenalla You need to fix the PR summary to agree with the JBS summary.

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

PR Comment: https://git.openjdk.org/jdk/pull/18640#issuecomment-2040377458

From prappo at openjdk.org  Fri Apr  5 19:50:12 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 5 Apr 2024 19:50:12 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v5]
In-Reply-To: <xS_mVgAkLc9j3e_BVr2hX-g-LHoXx1IcnTCXrVn_7KE=.0b92954b-07a3-4e07-af0c-a001080e5c7d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <WdW4zCsNXJAgazmEpps4klHVlvA3edCpk80OdylR-p0=.50f6b5e5-0a83-44ff-8918-855051c76efe@github.com>
 <xS_mVgAkLc9j3e_BVr2hX-g-LHoXx1IcnTCXrVn_7KE=.0b92954b-07a3-4e07-af0c-a001080e5c7d@github.com>
Message-ID: <u22adMNQvMdOly8w61f6ZgyThl-Lh74vx5UCxVIaM6w=.52483eb2-8c4d-4bee-9647-8cada7620365@github.com>

On Fri, 5 Apr 2024 17:52:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Approved, with two optional suggestions. Both could be considered style suggestions.
> 
> ## 1
> (Minor) While I like the new multi-valued return for `forMember(ExecutableElement executable)` I'm slightly surprised at the use of `List` rather than, say, a `record` that gives semantic meaning to the alternatives.
> 

Thanks for approval, Jon. This is my response to your minor suggestions only: although I read the bigger suggestion, it is indeed for when "such an improvement becomes necessary."

In essence, what we have here is a tuple, which in this case is best modelled by a list.

>From a perspective of a single documentation bundle, it does not matter which id we pick from a tuple as they are interchangeable. What matters is that we consistently pick the same id element for the same purpose. If we fail to do that, our intra-links will be broken.

>From a perspective of multiple documentation bundles that could link to each other, our choice of id should be consistent _and conventional_ (the convention is dictated by legacy bundles). Why? Because we not only want a new javadoc bundle to be able to link to, but we also want it to be able _to be linked to_.

Currently, we have 1-tuple and 2-tuple. But I can imagine we have 3-tuple in the future. A list can model n-tuple well. At an anchor creating site, we would iterate over the returned list and add nested `<div>`s (scale better than limited `<section><h3><a>`) with an id. At a link site, we would ask `ids.getFirst()`.

Both ordering and flexible arity is well provided by a list; I don't see why we need a record.

Does this make sense?

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

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

From jjg at openjdk.org  Fri Apr  5 20:01:59 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 5 Apr 2024 20:01:59 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v5]
In-Reply-To: <u22adMNQvMdOly8w61f6ZgyThl-Lh74vx5UCxVIaM6w=.52483eb2-8c4d-4bee-9647-8cada7620365@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <WdW4zCsNXJAgazmEpps4klHVlvA3edCpk80OdylR-p0=.50f6b5e5-0a83-44ff-8918-855051c76efe@github.com>
 <xS_mVgAkLc9j3e_BVr2hX-g-LHoXx1IcnTCXrVn_7KE=.0b92954b-07a3-4e07-af0c-a001080e5c7d@github.com>
 <u22adMNQvMdOly8w61f6ZgyThl-Lh74vx5UCxVIaM6w=.52483eb2-8c4d-4bee-9647-8cada7620365@github.com>
Message-ID: <y0a0agca-8pladS6e4MGcLNbp4KToXXSgW5Tplnzjng=.0d95bf3d-d57b-4145-a244-e739f3196b1b@github.com>

On Fri, 5 Apr 2024 19:47:40 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Does this make sense?
 
 While I am dubious about 3-tuples, your explanation makes enough sense that I accept your reply. Thanks for the explanation.

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

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

From prappo at openjdk.org  Fri Apr  5 20:06:10 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 5 Apr 2024 20:06:10 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v5]
In-Reply-To: <y0a0agca-8pladS6e4MGcLNbp4KToXXSgW5Tplnzjng=.0d95bf3d-d57b-4145-a244-e739f3196b1b@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
 <WdW4zCsNXJAgazmEpps4klHVlvA3edCpk80OdylR-p0=.50f6b5e5-0a83-44ff-8918-855051c76efe@github.com>
 <xS_mVgAkLc9j3e_BVr2hX-g-LHoXx1IcnTCXrVn_7KE=.0b92954b-07a3-4e07-af0c-a001080e5c7d@github.com>
 <u22adMNQvMdOly8w61f6ZgyThl-Lh74vx5UCxVIaM6w=.52483eb2-8c4d-4bee-9647-8cada7620365@github.com>
 <y0a0agca-8pladS6e4MGcLNbp4KToXXSgW5Tplnzjng=.0d95bf3d-d57b-4145-a244-e739f3196b1b@github.com>
Message-ID: <8CcOgQWKzfC_DSgD3NR5uLMGQSRFmVIDvsr0ggSxueA=.c0307336-d494-4953-962c-e9d7486254a4@github.com>

On Fri, 5 Apr 2024 19:58:27 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> > Does this make sense?
> 
> While I am dubious about 3-tuples, your explanation makes enough sense that I accept your reply. Thanks for the explanation.

Yet another alternative notation, should we come up with one in the future. While I do believe that the erased notation is all we need, it has its issues, such as being lengthy and not very intuitive.

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

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

From duke at openjdk.org  Mon Apr  8 07:46:35 2024
From: duke at openjdk.org (psoujany)
Date: Mon, 8 Apr 2024 07:46:35 GMT
Subject: RFR: JDK-8325690: The scrollable element <div> with
 non-interactive content is not tabbable [v4]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <M5x3szInH8kVqX-OWTGvVlj2bj1QgChRbLBiPU9NVY4=.3698732e-1c39-446c-8a56-d775f77da5bf@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex to plain text for div columns

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/a0f2773e..4b9e82bb

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

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

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

From duke at openjdk.org  Mon Apr  8 07:59:25 2024
From: duke at openjdk.org (psoujany)
Date: Mon, 8 Apr 2024 07:59:25 GMT
Subject: RFR: JDK-8325690: The scrollable element <div> with
 non-interactive content is not tabbable [v5]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <IZdOmdRMw7az_Fy_tn7bXx7qJmy_ieyDpfeeezTNG90=.f45da243-dfb4-4c58-81d6-88553fbd1fe8@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex to plain text for div columns

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/4b9e82bb..ac770a01

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

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

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

From prappo at openjdk.org  Mon Apr  8 09:53:32 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 8 Apr 2024 09:53:32 GMT
Subject: RFR: 8325088: Overloads that differ in type parameters may be lost
 [v6]
In-Reply-To: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
References: <hx1pW4NEX78DJF7cHcUMLchBirThIZmaVMNwkZmGbtk=.7b64fd4c-a2ce-4b28-bd38-ac773f1f782d@github.com>
Message-ID: <-Fh0uhjuECMTgqfGDAO2sfnG61tne_qc0jSQXvMJ7Ss=.fb77a8e0-9079-4c62-9bae-20b154fb82b9@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

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

 - Merge branch 'master' into 8325088
 - Update copyright years
   
   Note: any commit hashes below might be outdated due to subsequent
   history rewriting (e.g. git rebase).
   
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 0f33a6477e0
 - Clean up
 - Use a list of alternative ids
 - Cache forMember
 - Clarify some comments
 - Do not handle @interface methods specially
 - Nix forMember used by AnnotationTypeMemberWriter
 - Respond to feedback
 - Merge branch 'master' into 8325088
 - ... and 10 more: https://git.openjdk.org/jdk/compare/60305b37...ffe4078d

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18519/files
  - new: https://git.openjdk.org/jdk/pull/18519/files/4dee61b7..ffe4078d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=18519&range=05
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18519&range=04-05

  Stats: 12589 lines in 348 files changed: 4959 ins; 5873 del; 1757 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  Mon Apr  8 09:53:33 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 8 Apr 2024 09:53:33 GMT
Subject: Integrated: 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: <Q3TE4LMZm5nhplvVZjg0OpicX8BEVoTFOA1zYgIJCdA=.1ba2a265-3802-47dd-b537-7cfa639e8969@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

This pull request has now been integrated.

Changeset: 7c664657
Author:    Pavel Rappo <prappo at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/7c664657630a50ab83d218028cec114ea2d907ac
Stats:     531 lines in 8 files changed: 488 ins; 15 del; 28 mod

8325088: Overloads that differ in type parameters may be lost

Reviewed-by: jjg

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

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

From duke at openjdk.org  Mon Apr  8 10:15:36 2024
From: duke at openjdk.org (psoujany)
Date: Mon, 8 Apr 2024 10:15:36 GMT
Subject: RFR: JDK-8325690: The scrollable element <div> with
 non-interactive content is not tabbable [v6]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <_skMaRjDkobaFF0U0bINkaOrJwonLlXxOJzpNuaKSPw=.0cc44de3-c520-41e1-b675-b08ede856a68@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/ac770a01..53a923c5

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=05
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=04-05

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

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

From prappo at openjdk.org  Mon Apr  8 12:10:09 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 8 Apr 2024 12:10:09 GMT
Subject: RFR: JDK-8324342: doclet should default @since for a nested class
 to that of its enclosing class
In-Reply-To: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
References: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
Message-ID: <ZNLihyUsg0VpdEX3cBbWsb56nC40WOZt1EukzantX_0=.34019910-6b46-4928-bd3c-b1541c180318@github.com>

On Wed, 20 Mar 2024 19:04:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

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

This looks like the right thing to do; thanks for doing this.

A general comment regarding the test cases. It would be better if:

 - the nesting was at least two levels deep (`public class Foo { static class Bar { static class Baz { } } }`), to test search recursion
 - some tags were repeated (IIRC, `@autor` allows for repetition), to test that all such tags from the enclosing context are used

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

> 1: .\" Copyright (c) 1994, 2024, Oracle and/or its affiliates. All rights reserved.

This diff to the man page seems to contain some unrelated changes. If this is intentional, I'd prefer to move those changes to a separate, clean-up PR.

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

PR Review: https://git.openjdk.org/jdk/pull/18407#pullrequestreview-1986191604
PR Review Comment: https://git.openjdk.org/jdk/pull/18407#discussion_r1555693372

From duke at openjdk.org  Mon Apr  8 12:34:35 2024
From: duke at openjdk.org (psoujany)
Date: Mon, 8 Apr 2024 12:34:35 GMT
Subject: RFR: JDK-8325690: The scrollable element <div> with
 non-interactive content is not tabbable [v7]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <VaKiQXCyP-AFI9gDeS3dxgiXs0r3PwEeshVZN2FwP3g=.57c8c961-3cb5-49cd-b521-07661dd3a151@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex to plain text

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/53a923c5..f4e2dffd

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=06
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=05-06

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

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

From duke at openjdk.org  Mon Apr  8 13:39:24 2024
From: duke at openjdk.org (psoujany)
Date: Mon, 8 Apr 2024 13:39:24 GMT
Subject: RFR: JDK-8325690: The scrollable element <div> with
 non-interactive content is not tabbable [v8]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <GKPXd8K1oAI_rvp0pwWEQaI2PZBI4Eha5nynewwngz0=.7c34f7a5-76a4-4873-8f9a-d1e97ccc463a@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Print tabclasses content

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/f4e2dffd..226aeae9

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=07
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=06-07

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

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

From hannesw at openjdk.org  Mon Apr  8 16:50:10 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 8 Apr 2024 16:50:10 GMT
Subject: RFR: JDK-8324342: doclet should default @since for a nested class
 to that of its enclosing class
In-Reply-To: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
References: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
Message-ID: <GNRLAf3eSZLSS0PFzabxcNgTP-NRKc32N6btJxEhyG8=.6fb74c7a-8e4a-441a-9b7d-d88a24749a71@github.com>

On Wed, 20 Mar 2024 19:04:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

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

Looks good. I'll leave it to you and @pavelrappo to decide whether to include the partially unrelated updates to the man page.

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

Marked as reviewed by hannesw (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18407#pullrequestreview-1986947427

From jjg at openjdk.org  Mon Apr  8 21:12:42 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 8 Apr 2024 21:12:42 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v55]
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: <48hbLsx6MHdQQNNWrPRs4C-7sB18MyPOLE0QeTTPSDg=.1c0bd28d-8bd0-4733-a257-2c0f60bef2eb@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 JDK-8329296: Update Elements for '///' documentation comments

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

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

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

  Stats: 331 lines in 10 files changed: 291 ins; 20 del; 20 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 Apr  9 11:11:18 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 9 Apr 2024 11:11:18 GMT
Subject: RFR: JDK-8298405: Implement JEP 467: Markdown Documentation
 Comments [v55]
In-Reply-To: <48hbLsx6MHdQQNNWrPRs4C-7sB18MyPOLE0QeTTPSDg=.1c0bd28d-8bd0-4733-a257-2c0f60bef2eb@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <48hbLsx6MHdQQNNWrPRs4C-7sB18MyPOLE0QeTTPSDg=.1c0bd28d-8bd0-4733-a257-2c0f60bef2eb@github.com>
Message-ID: <1uPEw9BTg1J92Zcw5bKKXcvc7Ula0WFLjFz0moN50U4=.752eb9c2-0a19-422d-adbb-79b71505be7f@github.com>

On Mon, 8 Apr 2024 21:12:42 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:
> 
>   add support for JDK-8329296: Update Elements for '///' documentation comments

Changes for 21f5b00 mostly look good, but I'm not a compiler person.

src/jdk.compiler/share/classes/com/sun/tools/javac/model/JavacElements.java line 443:

> 441:     @DefinedBy(Api.LANGUAGE_MODEL)
> 442:     public CommentKind getDocCommentKind(Element e) {
> 443:         return  getDocCommentItem(e, ((docCommentTable, tree) -> docCommentTable.getCommentKind(tree)));

Nit:
Suggestion:

        return getDocCommentItem(e, ((docCommentTable, tree) -> docCommentTable.getCommentKind(tree)));

src/jdk.compiler/share/classes/com/sun/tools/javac/model/JavacElements.java line 443:

> 441:     @DefinedBy(Api.LANGUAGE_MODEL)
> 442:     public CommentKind getDocCommentKind(Element e) {
> 443:         return  getDocCommentItem(e, ((docCommentTable, tree) -> docCommentTable.getCommentKind(tree)));

Again:
Suggestion:

        return getDocCommentItem(e, ((docCommentTable, tree) -> docCommentTable.getCommentKind(tree)));

src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocCommentTable.java line 55:

> 53: 
> 54:     /**
> 55:      * Get the plain text of the doc comment, if any, for a tree node.

This is likely a copy-pasted comment.

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

PR Review: https://git.openjdk.org/jdk/pull/16388#pullrequestreview-1988489764
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1557248565
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1557249290
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1557444619

From hannesw at openjdk.org  Tue Apr  9 13:14:18 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 9 Apr 2024 13:14:18 GMT
Subject: RFR: JDK-8329617: Update stylesheet for specs and tool documentation
Message-ID: <Lxf0apxsFQJ3WS08ptlY3pBYsjAg0U_geeZQWnAs9F0=.4d0dcbb6-f1a7-4fea-ba4e-1e877da52455@github.com>

Please review an update to the `jdk-default.css` stylesheet used for specifications and tool guides. The original purpose was to make use of the Dejavu web fonts provided by the API docs and to update the navigation bar to match the one in the API docs. However, the updates include some other fixes and improvements also described below.

 - The change to use the DejaVu web fonts consists only of the `@import` statement in line 16 as the stylesheet already used DejaVu web fonts as first choice in its `font-family` rules.
 - The changes to make the navigation bar match the one in the API docs are mostly located at the end of the file (beyond line 160). However, this also includes setting the `margin` property to '0' in the `body` element and adding a `margin` in the `main` and `footer` elements instead. 
 - To set the horizontal margin for page content elements outside the `main` element which occur in some pages, a margin is set explicitly on those elements in lines 48-50. While this is a bit awkward, I think it's still better than working with negative margins in the header to offset the margin in the `body` element.
 - Most of the remaining changes (lines 53-110) are changes are to redefine the styles in simpler terms, such as leaving out declarations that are equal to browser defaults, and removing the units from `0`-length values.

The changes are intended to preserve the layout of the pages, including the body font size which is slightly different from the one used in API docs (`10pt` vs `14px`). I can provide before/after snapshots of the rendered documentation if desired.

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

Commit messages:
 - JDK-8329617: Update stylesheet for specs and tool documentation

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

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

From jjg at openjdk.org  Thu Apr 11 17:42:57 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 11 Apr 2024 17:42:57 GMT
Subject: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments
 [v55]
In-Reply-To: <1uPEw9BTg1J92Zcw5bKKXcvc7Ula0WFLjFz0moN50U4=.752eb9c2-0a19-422d-adbb-79b71505be7f@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <48hbLsx6MHdQQNNWrPRs4C-7sB18MyPOLE0QeTTPSDg=.1c0bd28d-8bd0-4733-a257-2c0f60bef2eb@github.com>
 <1uPEw9BTg1J92Zcw5bKKXcvc7Ula0WFLjFz0moN50U4=.752eb9c2-0a19-422d-adbb-79b71505be7f@github.com>
Message-ID: <oXQpJBD-ik0VdK_m5UXEGiznQQk7PSuN4G1HEm1p_2c=.31a8da35-4adc-4372-b019-37fb257b9755@github.com>

On Tue, 9 Apr 2024 08:53:10 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   add support for JDK-8329296: Update Elements for '///' documentation comments
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/model/JavacElements.java line 443:
> 
>> 441:     @DefinedBy(Api.LANGUAGE_MODEL)
>> 442:     public CommentKind getDocCommentKind(Element e) {
>> 443:         return  getDocCommentItem(e, ((docCommentTable, tree) -> docCommentTable.getCommentKind(tree)));
> 
> Nit:
> Suggestion:
> 
>         return getDocCommentItem(e, ((docCommentTable, tree) -> docCommentTable.getCommentKind(tree)));

Fixed

> src/jdk.compiler/share/classes/com/sun/tools/javac/model/JavacElements.java line 443:
> 
>> 441:     @DefinedBy(Api.LANGUAGE_MODEL)
>> 442:     public CommentKind getDocCommentKind(Element e) {
>> 443:         return  getDocCommentItem(e, ((docCommentTable, tree) -> docCommentTable.getCommentKind(tree)));
> 
> Again:
> Suggestion:
> 
>         return getDocCommentItem(e, ((docCommentTable, tree) -> docCommentTable.getCommentKind(tree)));

Fixed.

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

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

From jjg at openjdk.org  Thu Apr 11 17:52:14 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 11 Apr 2024 17:52:14 GMT
Subject: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments
 [v56]
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: <AO9I9d0P1PDuc5Kjg4Kpy3Tqhg1lMW1oerlPTRFK3Bs=.da684167-eb91-4886-8196-7b866da3ba92@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:

  address review feedback for updates to Elements and friends

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/21f5b004..d4c2c73b

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

  Stats: 9 lines in 2 files changed: 0 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 jjg at openjdk.org  Thu Apr 11 20:55:24 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 11 Apr 2024 20:55:24 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v2]
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: <au6_FZORG1xVh5VnfoMMR60a_2oa1qny0ElKeIGpvFI=.94ed31a5-a875-4bc6-927b-da0f512ad43e@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.

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

  adjust call for `saveDanglingDocComments` for enum members

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18527/files
  - new: https://git.openjdk.org/jdk/pull/18527/files/3d6f1f95..56d6dcac

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

  Stats: 5 lines in 1 file changed: 3 ins; 2 del; 0 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 hannesw at openjdk.org  Fri Apr 12 11:17:05 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 12 Apr 2024 11:17:05 GMT
Subject: RFR: 8330063: Upgrade jQuery to 3.7.1
Message-ID: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>

Please review a change to update jQuery from version 3.6.1 to 3.7.1 in JavaDoc. The jQuery compressed and uncompressed files were obtained from https://jquery.com/download/. Changes were tested against javadoc tests as well as manually using a selection of browsers (Firefox, Chrome, Safari). 

[As of jQuery 3.7.0](https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/#:~:text=jQuery%20no%20longer%20depends%20on%20Sizzle%20as%20a%20separate%20project%2C%20but%20has%20instead%20dropped%20its%20code%20directly%20into%20jQuery%20core.) Sizzle is longer bundled as an independent project. The code is now part of jQuery core, therefore the Sizzle license has been removed from `jquery.md`.

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

Commit messages:
 - JDK-8330063: Upgrade jQuery to 3.7.1

Changes: https://git.openjdk.org/jdk/pull/18756/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18756&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8330063
  Stats: 21689 lines in 9 files changed: 10724 ins; 10957 del; 8 mod
  Patch: https://git.openjdk.org/jdk/pull/18756.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18756/head:pull/18756

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

From jjg at openjdk.org  Fri Apr 12 17:24:43 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 12 Apr 2024 17:24:43 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v2]
In-Reply-To: <CJk_cgw_oK69SgmEsA7fC7wupoZ6Uc_MJ_vAEFUhMlc=.3b61473c-97e6-4a9a-b19b-e387ab9eb5ab@github.com>
References: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
 <CJk_cgw_oK69SgmEsA7fC7wupoZ6Uc_MJ_vAEFUhMlc=.3b61473c-97e6-4a9a-b19b-e387ab9eb5ab@github.com>
Message-ID: <yoXk0XJ1mo_6lFPzenTjynOJmM2R8GNROFOTwN4p00g=.dcedceac-6d2a-4b1f-99ee-57d060b8a69b@github.com>

On Wed, 3 Apr 2024 10:01:37 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   adjust call for `saveDanglingDocComments` for enum members
>
> The build changes look okay. 
> 
> Do you have any plan of going through all the Java modules and fixing the issues, or opening JBS issues to have them fixed? Or will these lint warnings remain disabled for the foreseeable future?

@magicus 
> The build changes look okay.
> 
> Do you have any plan of going through all the Java modules and fixing the issues, or opening JBS issues to have them fixed? Or will these lint warnings remain disabled for the foreseeable future?

The plan is to create an umbrella bug to clean up the individual modules. There is interest to clean up `java.base`, to keep that one free of any warnings, and I can see that the lang tools modules will get cleaner up as well. It will be up to other component teams to decide if and when to clean up other parts of the system.  Once this work has been integrated, it is relatively easy to enable the warnings for a module and to fix the ensuing issues. Since any changes "only" involve comments, it should be reasonably easy to fix them, unlike some pervasive other warnings, like `this-escape`.

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

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

From darcy at openjdk.org  Fri Apr 12 17:41:56 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Fri, 12 Apr 2024 17:41:56 GMT
Subject: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments
 [v56]
In-Reply-To: <AO9I9d0P1PDuc5Kjg4Kpy3Tqhg1lMW1oerlPTRFK3Bs=.da684167-eb91-4886-8196-7b866da3ba92@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <AO9I9d0P1PDuc5Kjg4Kpy3Tqhg1lMW1oerlPTRFK3Bs=.da684167-eb91-4886-8196-7b866da3ba92@github.com>
Message-ID: <5BLnTYx2hjFyOvw3_RQWLDcPwvREkTII1AaLhdQUB7I=.84043d72-429a-4b9a-a119-57f45d239950@github.com>

On Thu, 11 Apr 2024 17:52:14 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:
> 
>   address review feedback for updates to Elements and friends

There should be some quick testing of the new default method on Elements using the VacuousElements implementation; see
`test/langtools/tools/javac/processing/model/util/elements`
for some examples.

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

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

From jjg at openjdk.org  Fri Apr 12 21:04:06 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 12 Apr 2024 21:04:06 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v3]
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: <3Ynu_D2CcFh3usjCkWQVk7VFhTlxVzD4f2nVhvZrP50=.f1c29740-ff73-4a0c-a63b-3e00ece05bbf@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.

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

  call `saveDanglingDocComments` for local variable declarations

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18527/files
  - new: https://git.openjdk.org/jdk/pull/18527/files/56d6dcac..3f745431

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

  Stats: 10 lines in 1 file changed: 5 ins; 2 del; 3 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 duke at openjdk.org  Mon Apr 15 11:46:12 2024
From: duke at openjdk.org (psoujany)
Date: Mon, 15 Apr 2024 11:46:12 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v9]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <b3AteIoZ8DVk7NcOhHc_aKCuh48Pt_EZskiyz1jIk78=.cce33543-3adc-4436-9fe0-2b3fbfd3c9e7@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex to plain text of div coloumns

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/226aeae9..3434b5ae

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=08
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=07-08

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

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

From duke at openjdk.org  Mon Apr 15 14:31:18 2024
From: duke at openjdk.org (psoujany)
Date: Mon, 15 Apr 2024 14:31:18 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v10]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <ySrXffJIN804yXKwjpZ9UYCyhXkdyb-9yvgsroj3HTQ=.019c37ab-e6d7-423e-bf62-80aae2b72231@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex to make scrollable elements tabbable

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/3434b5ae..bf10a578

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=09
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=08-09

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

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

From duke at openjdk.org  Mon Apr 15 16:19:16 2024
From: duke at openjdk.org (psoujany)
Date: Mon, 15 Apr 2024 16:19:16 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v11]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <szi6QHf0p_lsizdgF-BtOYdilicJHdFlVUFU2uwZrhs=.216dea0e-d288-4431-936a-72e6f57905b6@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/bf10a578..aa3bdaef

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=10
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=09-10

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

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

From duke at openjdk.org  Tue Apr 16 05:33:14 2024
From: duke at openjdk.org (psoujany)
Date: Tue, 16 Apr 2024 05:33:14 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v12]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <nMBLlYTP4cx1BjloizuxhmeLEev1siPtTZ8SJ4cK1MM=.5c8a0501-e4c4-4daf-973c-438dc9b03578@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/aa3bdaef..40eb8328

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=11
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=10-11

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

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

From duke at openjdk.org  Tue Apr 16 06:44:17 2024
From: duke at openjdk.org (psoujany)
Date: Tue, 16 Apr 2024 06:44:17 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v13]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <WoNERJZhyCED7GHbAQeAN2_--D90KYl14-RS-19u3Ho=.1652d970-64a5-4cd2-a8c8-e6b3a52c22dc@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex to plain text

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/40eb8328..75ea95d5

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=12
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=11-12

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

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

From duke at openjdk.org  Tue Apr 16 08:24:30 2024
From: duke at openjdk.org (psoujany)
Date: Tue, 16 Apr 2024 08:24:30 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v14]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <8uI0kLtMDDLTHM8uZnbNY3wScV-uSWaYyOIXl1Z-plk=.49f3d9db-ac51-485d-a092-dce8386d9baa@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/75ea95d5..670a97c3

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=13
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=12-13

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

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

From jjg at openjdk.org  Tue Apr 16 18:31:42 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 16 Apr 2024 18:31:42 GMT
Subject: RFR: 8324342: Doclet should default @since for a nested class to
 that of its enclosing class
In-Reply-To: <ZNLihyUsg0VpdEX3cBbWsb56nC40WOZt1EukzantX_0=.34019910-6b46-4928-bd3c-b1541c180318@github.com>
References: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
 <ZNLihyUsg0VpdEX3cBbWsb56nC40WOZt1EukzantX_0=.34019910-6b46-4928-bd3c-b1541c180318@github.com>
Message-ID: <-gRU5o_TyT6Gp4h506voqbUvFj_vj8znY4x_qLviJkE=.63831dbd-28e4-4b0c-9b91-d6e805bc7b28@github.com>

On Mon, 8 Apr 2024 11:53:25 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> 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.
>
> src/jdk.javadoc/share/man/javadoc.1 line 1:
> 
>> 1: .\" Copyright (c) 1994, 2024, Oracle and/or its affiliates. All rights reserved.
> 
> This diff to the man page seems to contain some unrelated changes. If this is intentional, I'd prefer to move those changes to a separate, clean-up PR.

The changes were all described together in the associated CSR, which you reviewed.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18407#discussion_r1567787082

From prappo at openjdk.org  Tue Apr 16 18:40:01 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 16 Apr 2024 18:40:01 GMT
Subject: RFR: 8324342: Doclet should default @since for a nested class to
 that of its enclosing class
In-Reply-To: <-gRU5o_TyT6Gp4h506voqbUvFj_vj8znY4x_qLviJkE=.63831dbd-28e4-4b0c-9b91-d6e805bc7b28@github.com>
References: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
 <ZNLihyUsg0VpdEX3cBbWsb56nC40WOZt1EukzantX_0=.34019910-6b46-4928-bd3c-b1541c180318@github.com>
 <-gRU5o_TyT6Gp4h506voqbUvFj_vj8znY4x_qLviJkE=.63831dbd-28e4-4b0c-9b91-d6e805bc7b28@github.com>
Message-ID: <HA0MxnWgeeGfSd9VLWRW-JqxQmneTyavLSXV-VaG-Vs=.5afd49f3-56bd-400e-9a3d-8ed9514b1607@github.com>

On Tue, 16 Apr 2024 18:29:02 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/man/javadoc.1 line 1:
>> 
>>> 1: .\" Copyright (c) 1994, 2024, Oracle and/or its affiliates. All rights reserved.
>> 
>> This diff to the man page seems to contain some unrelated changes. If this is intentional, I'd prefer to move those changes to a separate, clean-up PR.
>
> The changes were all described together in the associated CSR, which you reviewed.

Hm... I cannot find where, for example, these hunks were described:


 For more details on the conformance requirements for HTML5 documents,
-see \f[B]Conformance requirements\f[R]
-[https://www.w3.org/TR/html5/infrastructure.html#conformance-requirements]
+see \f[B]Conformance requirements for authors\f[R]
+[https://html.spec.whatwg.org/multipage/introduction.html#conformance-requirements-for-authors]
 in the HTML5 Specification.



-This command inserts the following line in the head of every generated
-page:
+This command inserts the following line, containing a
+\f[B]\f[VB]meta\f[B] element\f[R]
+[https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element]
+in the head of every generated page:

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18407#discussion_r1567795365

From prappo at openjdk.org  Wed Apr 17 12:44:44 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 17 Apr 2024 12:44:44 GMT
Subject: RFR: 8330063: Upgrade jQuery to 3.7.1
In-Reply-To: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
References: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
Message-ID: <5xLn-DPFROPhtvCNA6M7AQ5_ezmkMof8kND88P5k1xo=.17dbd971-d16a-4a83-80c2-a98158fd48e6@github.com>

On Fri, 12 Apr 2024 11:11:47 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update jQuery from version 3.6.1 to 3.7.1 in JavaDoc. The jQuery compressed and uncompressed files were obtained from https://jquery.com/download/. Changes were tested against javadoc tests as well as manually using a selection of browsers (Firefox, Chrome, Safari). 
> 
> [As of jQuery 3.7.0](https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/#:~:text=jQuery%20no%20longer%20depends%20on%20Sizzle%20as%20a%20separate%20project%2C%20but%20has%20instead%20dropped%20its%20code%20directly%20into%20jQuery%20core.) Sizzle is longer bundled as an independent project. The code is now part of jQuery core, therefore the Sizzle license has been removed from `jquery.md`.

Generally looks good. Remind me, how did we end up with this `jquery.md` file, initially I mean? From what I see at https://github.com/jquery/jquery/blob/main/LICENSE.txt, jQuery has never had anything about Sizzle in there.

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

PR Comment: https://git.openjdk.org/jdk/pull/18756#issuecomment-2061170981

From hannesw at openjdk.org  Wed Apr 17 13:25:59 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 17 Apr 2024 13:25:59 GMT
Subject: RFR: 8330063: Upgrade jQuery to 3.7.1
In-Reply-To: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
References: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
Message-ID: <lajtAkEn0PJY6gwlUv8w12fT4O8qGlFh8csAWCl3ryo=.887815dd-2f30-4b3d-b78d-040a2464dd44@github.com>

On Fri, 12 Apr 2024 11:11:47 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update jQuery from version 3.6.1 to 3.7.1 in JavaDoc. The jQuery compressed and uncompressed files were obtained from https://jquery.com/download/. Changes were tested against javadoc tests as well as manually using a selection of browsers (Firefox, Chrome, Safari). 
> 
> [As of jQuery 3.7.0](https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/#:~:text=jQuery%20no%20longer%20depends%20on%20Sizzle%20as%20a%20separate%20project%2C%20but%20has%20instead%20dropped%20its%20code%20directly%20into%20jQuery%20core.) Sizzle is longer bundled as an independent project. The code is now part of jQuery core, therefore the Sizzle license has been removed from `jquery.md`.

The Sizzle.js license used to be contained in `external/sizzle/LICENSE.txt`. The file was [removed in the process of inlining Sizzle.js](https://github.com/jquery/jquery/pull/5113/files#diff-df1327f58759ffed4e68f82e113a90e4fb38b8d17ab4e4bf0de7c1824a6c454f).

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

PR Comment: https://git.openjdk.org/jdk/pull/18756#issuecomment-2061252990

From hannesw at openjdk.org  Wed Apr 17 13:33:00 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 17 Apr 2024 13:33:00 GMT
Subject: RFR: 8330063: Upgrade jQuery to 3.7.1
In-Reply-To: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
References: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
Message-ID: <oy8pQYIht1fg-Mgwhl0FgNHNJ19mj9l88NnHfLkg1nQ=.27e4d93c-dc28-4d7b-84b0-78c608d15fa6@github.com>

On Fri, 12 Apr 2024 11:11:47 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update jQuery from version 3.6.1 to 3.7.1 in JavaDoc. The jQuery compressed and uncompressed files were obtained from https://jquery.com/download/. Changes were tested against javadoc tests as well as manually using a selection of browsers (Firefox, Chrome, Safari). 
> 
> [As of jQuery 3.7.0](https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/#:~:text=jQuery%20no%20longer%20depends%20on%20Sizzle%20as%20a%20separate%20project%2C%20but%20has%20instead%20dropped%20its%20code%20directly%20into%20jQuery%20core.) Sizzle is longer bundled as an independent project. The code is now part of jQuery core, therefore the Sizzle license has been removed from `jquery.md`.

In the jQuery.js file the Sizzle.js copyright notice used to be somewhere within the file near the Sizzle code.

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

PR Comment: https://git.openjdk.org/jdk/pull/18756#issuecomment-2061267529

From prappo at openjdk.org  Wed Apr 17 15:54:00 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 17 Apr 2024 15:54:00 GMT
Subject: RFR: 8330063: Upgrade jQuery to 3.7.1
In-Reply-To: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
References: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
Message-ID: <ct4GWNXZrN6ucM_vlCA8hPg2xs8mIRLqvOI8kN0m83w=.008771f9-6f23-4f29-94f4-ee80a2c0f36b@github.com>

On Fri, 12 Apr 2024 11:11:47 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update jQuery from version 3.6.1 to 3.7.1 in JavaDoc. The jQuery compressed and uncompressed files were obtained from https://jquery.com/download/. Changes were tested against javadoc tests as well as manually using a selection of browsers (Firefox, Chrome, Safari). 
> 
> [As of jQuery 3.7.0](https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/#:~:text=jQuery%20no%20longer%20depends%20on%20Sizzle%20as%20a%20separate%20project%2C%20but%20has%20instead%20dropped%20its%20code%20directly%20into%20jQuery%20core.) Sizzle is longer bundled as an independent project. The code is now part of jQuery core, therefore the Sizzle license has been removed from `jquery.md`.

Marked as reviewed by prappo (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/18756#pullrequestreview-2006435858

From duke at openjdk.org  Thu Apr 18 10:01:34 2024
From: duke at openjdk.org (psoujany)
Date: Thu, 18 Apr 2024 10:01:34 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v15]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <jVceFh4PyDdXpcSHgwwage1Qka1kSyybdo5G3n7VhlM=.c0e5170b-5ee9-4d69-bf1f-aebe534b6276@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  add tabindex

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/670a97c3..cde1c600

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=14
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=13-14

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

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

From hannesw at openjdk.org  Thu Apr 18 12:16:52 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 18 Apr 2024 12:16:52 GMT
Subject: RFR: 8294880: Review running time of
 jdk/internal/shellsupport/doc/JavadocHelperTest.java
Message-ID: <f1InD5kPf0hXmiR6kpFCKl4j2iO8QIuhT6KLDcS1YmU=.d5f19994-7281-42d0-81f8-caec7454d851@github.com>

Please review a change to move a long-running shellsupport test from langtools tier1 to tier2, while modifying the tier1 test to only retrieve doc comments for members of `java.lang.StringBuilder`, which is where [the original bug](https://bugs.openjdk.org/browse/JDK-8189778) occurred.  This reduces the running time in the tier1 test from around 90 seconds to 2 seconds on my computer. The tier1 test also adds a non-null check for retrieved doc comments.

I used the existing `langtools_jshell_unstable` test group to add the new test in langtools tier2, which is not a perfect match for the test, but close enough and helps to keep langtools `TEST.groups` file simple.

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

Commit messages:
 - JDK-8294880: Review running time of jdk/internal/shellsupport/doc/JavadocHelperTest.java

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

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

From jjg at openjdk.org  Thu Apr 18 18:35:56 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 18 Apr 2024 18:35:56 GMT
Subject: RFR: 8324342: Doclet should default @since for a nested class to
 that of its enclosing class
In-Reply-To: <ZNLihyUsg0VpdEX3cBbWsb56nC40WOZt1EukzantX_0=.34019910-6b46-4928-bd3c-b1541c180318@github.com>
References: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
 <ZNLihyUsg0VpdEX3cBbWsb56nC40WOZt1EukzantX_0=.34019910-6b46-4928-bd3c-b1541c180318@github.com>
Message-ID: <0IlZq5e-0FxP08QzZiEeSUI0CqU0lVDU6RSO_HiZJAg=.15910e09-4e50-4f15-9f73-5b36e7c75d88@github.com>

On Mon, 8 Apr 2024 12:07:25 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> This looks like the right thing to do; thanks for doing this.
> 
> A general comment regarding the test cases. It would be better if:
> 
> * the nesting was at least two levels deep (`public class Foo { static class Bar { static class Baz { } } }`), to test search recursion
> * some tags were repeated (IIRC, `@autor` allows for repetition), to test that all such tags from the enclosing context are used

Extended tests for double-nested classes and multiple tags

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

PR Comment: https://git.openjdk.org/jdk/pull/18407#issuecomment-2064872970

From jjg at openjdk.org  Thu Apr 18 18:43:13 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 18 Apr 2024 18:43:13 GMT
Subject: RFR: 8324342: Doclet should default @since for a nested class to
 that of its enclosing class [v2]
In-Reply-To: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
References: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
Message-ID: <Vdv2mzAwiEbLBgNVOTAfeKzBPVBqJRceg0lI3fJSRjQ=.97829393-6128-4cbe-8944-b7ee85b3a82c@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.

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

  add more test cases

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18407/files
  - new: https://git.openjdk.org/jdk/pull/18407/files/7a1dc75c..c7318a59

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

  Stats: 101 lines in 2 files changed: 101 ins; 0 del; 0 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 prappo at openjdk.org  Thu Apr 18 18:47:06 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 18 Apr 2024 18:47:06 GMT
Subject: RFR: 8324342: Doclet should default @since for a nested class to
 that of its enclosing class [v2]
In-Reply-To: <Vdv2mzAwiEbLBgNVOTAfeKzBPVBqJRceg0lI3fJSRjQ=.97829393-6128-4cbe-8944-b7ee85b3a82c@github.com>
References: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
 <Vdv2mzAwiEbLBgNVOTAfeKzBPVBqJRceg0lI3fJSRjQ=.97829393-6128-4cbe-8944-b7ee85b3a82c@github.com>
Message-ID: <xXCf4OLxwdaxEthBDfqHFG5cWf8p_K3F1QeGFNcwJ48=.b31dec32-c059-440a-8d19-64f4e4f4eb0f@github.com>

On Thu, 18 Apr 2024 18:43:13 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 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.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   add more test cases

Thanks for adding extra tests. Looks good.

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

Marked as reviewed by prappo (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18407#pullrequestreview-2009628364

From jjg at openjdk.org  Thu Apr 18 18:52:04 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 18 Apr 2024 18:52:04 GMT
Subject: Integrated: 8324342: Doclet should default @since for a nested class
 to that of its enclosing class
In-Reply-To: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
References: <oIRxys620XzbVP6FeFLOu0wMY4uaMJ-Vfnce10Cgitw=.033a8a45-ad1a-4cdd-8125-ea2213074684@github.com>
Message-ID: <Q81E4RsEStRRK-nehsX1_pf3Av26CAnuJrDQ2OQbRpw=.c30f5e44-9406-405d-b991-91010a0fd83e@github.com>

On Wed, 20 Mar 2024 19:04:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

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

This pull request has now been integrated.

Changeset: 6ee84077
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/6ee8407758c92d32e18642b0758d2d5c71ad09f5
Stats:     290 lines in 6 files changed: 256 ins; 4 del; 30 mod

8324342: Doclet should default @since for a nested class to that of its enclosing class

Reviewed-by: prappo, hannesw

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

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

From jjg at openjdk.org  Thu Apr 18 20:52:29 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 18 Apr 2024 20:52:29 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v4]
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: <p1Ldsyr_hNrd7LEhoThBxZzXEtMZk3siO_ZLFZp43vY=.c61e1870-2db1-4ee8-b157-f6f2b0be1715@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.

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

 - improve handling of ignorable doc comments
   suppress warning when building test code
 - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
 - call `saveDanglingDocComments` for local variable declarations
 - adjust call for `saveDanglingDocComments` for enum members
 - JDK-8303689: javac -Xlint could/should report on "dangling" doc comments

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18527/files
  - new: https://git.openjdk.org/jdk/pull/18527/files/3f745431..f3670e7a

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

  Stats: 42074 lines in 1058 files changed: 18282 ins; 15937 del; 7855 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 jjg at openjdk.org  Thu Apr 18 21:34:13 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 18 Apr 2024 21:34:13 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v5]
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: <Pw-vAt9fBf-s7YcdBbtzbYdcM49PkNcmvIfbSmYdjYI=.a94e6477-30de-463b-b509-d4cd38f26cd7@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.

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

  update test

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18527/files
  - new: https://git.openjdk.org/jdk/pull/18527/files/f3670e7a..8ad8b818

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

  Stats: 6 lines in 1 file changed: 6 ins; 0 del; 0 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 jjg at openjdk.org  Thu Apr 18 21:56:16 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 18 Apr 2024 21:56:16 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v6]
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: <_EMQ8vgc0hQdgeWdnqirLLAN8Cj6jcxP0belwJffD8A=.2c536c2b-f0e1-49b4-8fc7-e3a9252e20e2@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.

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

 - Merge with upstream/master
 - update test
 - improve handling of ignorable doc comments
   suppress warning when building test code
 - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
 - call `saveDanglingDocComments` for local variable declarations
 - adjust call for `saveDanglingDocComments` for enum members
 - 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=05
  Stats: 488 lines in 61 files changed: 389 ins; 3 del; 96 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 hannesw at openjdk.org  Fri Apr 19 10:08:10 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 19 Apr 2024 10:08:10 GMT
Subject: Integrated: 8330063: Upgrade jQuery to 3.7.1
In-Reply-To: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
References: <d6nrKDMeu3ux_CHwMzIVW6EbTMGRPvtbsx52YaE3NGg=.54be719c-c2f1-467d-aa5a-5d3abc71de86@github.com>
Message-ID: <0b1Fd5ny9w60kAmClKCQx2t0IdiVxqrPSGjnGoRaNwQ=.218965e5-59b0-464f-8003-12864f2d2c9c@github.com>

On Fri, 12 Apr 2024 11:11:47 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update jQuery from version 3.6.1 to 3.7.1 in JavaDoc. The jQuery compressed and uncompressed files were obtained from https://jquery.com/download/. Changes were tested against javadoc tests as well as manually using a selection of browsers (Firefox, Chrome, Safari). 
> 
> [As of jQuery 3.7.0](https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/#:~:text=jQuery%20no%20longer%20depends%20on%20Sizzle%20as%20a%20separate%20project%2C%20but%20has%20instead%20dropped%20its%20code%20directly%20into%20jQuery%20core.) Sizzle is longer bundled as an independent project. The code is now part of jQuery core, therefore the Sizzle license has been removed from `jquery.md`.

This pull request has now been integrated.

Changeset: 46a2ce4e
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/46a2ce4eb4c961649a70d52a6317a2c022e87d63
Stats:     21689 lines in 9 files changed: 10724 ins; 10957 del; 8 mod

8330063: Upgrade jQuery to 3.7.1

Reviewed-by: prappo

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

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

From duke at openjdk.org  Sat Apr 20 05:49:49 2024
From: duke at openjdk.org (psoujany)
Date: Sat, 20 Apr 2024 05:49:49 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v16]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <QRM2HHXsofn_h7XF6agvf9nQvxBAyW31DfSNooXDhf0=.60828d26-5366-49e5-9eec-18173e953236@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex to grid columns

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/cde1c600..96719f9b

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=15
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=14-15

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

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

From jjg at openjdk.org  Mon Apr 22 18:07:51 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 22 Apr 2024 18:07:51 GMT
Subject: RFR: 8330704: Clean up non-standard use of /** comments in some
 langtools tests
Message-ID: <QVSIksEb5NnF7BXfNZU26MZYFqVf0NdSgTgkKuCLF8g=.980c0320-a902-4c3f-8659-fde95fda90f6@github.com>

Please review a simple change to clean up inappropriate use of `/**` comments in test code -- most notably to enclose the `jtreg` test description.

There is no change to the functionality of any test, and (obviously) all tests continue to pass.

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

Commit messages:
 - JDK-8330704: Clean up non-standard use of /** comments in some langtools tests

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

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

From iris at openjdk.org  Mon Apr 22 18:20:28 2024
From: iris at openjdk.org (Iris Clark)
Date: Mon, 22 Apr 2024 18:20:28 GMT
Subject: RFR: 8330704: Clean up non-standard use of /** comments in some
 langtools tests
In-Reply-To: <QVSIksEb5NnF7BXfNZU26MZYFqVf0NdSgTgkKuCLF8g=.980c0320-a902-4c3f-8659-fde95fda90f6@github.com>
References: <QVSIksEb5NnF7BXfNZU26MZYFqVf0NdSgTgkKuCLF8g=.980c0320-a902-4c3f-8659-fde95fda90f6@github.com>
Message-ID: <ww1vp04Xj8tCX53losUt-iPpbWt3vjzYuzqfd5b-9ig=.78d727a0-4d39-43f2-9c6b-09bcea72af2b@github.com>

On Mon, 22 Apr 2024 18:02:39 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple change to clean up inappropriate use of `/**` comments in test code -- most notably to enclose the `jtreg` test description.
> 
> There is no change to the functionality of any test, and (obviously) all tests continue to pass.

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/18896#pullrequestreview-2015514289

From duke at openjdk.org  Mon Apr 22 20:39:34 2024
From: duke at openjdk.org (Nizar Benalla)
Date: Mon, 22 Apr 2024 20:39:34 GMT
Subject: Integrated: 8329717: Missing `@since` tags in elements in
 DocumentationTool and Taglet
In-Reply-To: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
References: <sae2j5_gFtbHwxGmLOcq-lgULN__rRexQCLENmaWKLc=.728b447f-43d6-4656-a1b4-99f46fa50fb0@github.com>
Message-ID: <55hGiIOZnYdpgk2Jm4Jc-v1Auqh4U7B3WrJgTmoZnkg=.8362875e-9d0a-48a8-9d06-8c25eaf76c96@github.com>

On Fri, 5 Apr 2024 00:02:00 GMT, Nizar Benalla <duke at openjdk.org> wrote:

> In this PR I added an `@since` tag to SNIPPET_PATH and isBlockTag() as they were added in later versions
> 
> - SNIPPET_PATH was added in JDK 18 [here](https://github.com/openjdk/jdk/commit/0fc47e99d20a1ee886df878f1302769bdd913aab#diff-8f73114f8b0d0d5229231541d5583382c8e8d33147e285f3d90ed8801ce9228bR192)
> 
> - isBlockTag() was added in JDK 15 [here](https://github.com/openjdk/jdk/commit/3c0e2b4e16d8fb2f96741bc8d4188aa47f58dd15#diff-3ee1b6e2a11b201a39ce3f2ac14ea9832900d8a3a581bf26577064173d0c9082R101)
> 
> This is similar to #18032

This pull request has now been integrated.

Changeset: 83c74d73
Author:    Nizar Benalla <nizar.benalla at oracle.com>
Committer: Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/83c74d7307e258441abb171552e953f1c6d9b98a
Stats:     6 lines in 2 files changed: 4 ins; 0 del; 2 mod

8329717: Missing `@since` tags in elements in DocumentationTool and Taglet

Reviewed-by: prappo

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

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

From jjg at openjdk.org  Mon Apr 22 21:55:31 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 22 Apr 2024 21:55:31 GMT
Subject: Integrated: 8330704: Clean up non-standard use of /** comments in some
 langtools tests
In-Reply-To: <QVSIksEb5NnF7BXfNZU26MZYFqVf0NdSgTgkKuCLF8g=.980c0320-a902-4c3f-8659-fde95fda90f6@github.com>
References: <QVSIksEb5NnF7BXfNZU26MZYFqVf0NdSgTgkKuCLF8g=.980c0320-a902-4c3f-8659-fde95fda90f6@github.com>
Message-ID: <BTXIgZcCGETmeCoV-jF2o9MN8cLRTDNQhONCNgHOvhk=.7c4e047f-362b-4e7a-9c4b-2ffe970f36bf@github.com>

On Mon, 22 Apr 2024 18:02:39 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple change to clean up inappropriate use of `/**` comments in test code -- most notably to enclose the `jtreg` test description.
> 
> There is no change to the functionality of any test, and (obviously) all tests continue to pass.

This pull request has now been integrated.

Changeset: 1d52234e
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/1d52234e199c7a38c059c0aa88aea2910f749d48
Stats:     44 lines in 22 files changed: 0 ins; 0 del; 44 mod

8330704: Clean up non-standard use of /** comments in some langtools tests

Reviewed-by: iris

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

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

From hannesw at openjdk.org  Tue Apr 23 16:24:58 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 23 Apr 2024 16:24:58 GMT
Subject: RFR: 8294880: Review running time of
 jdk/internal/shellsupport/doc/JavadocHelperTest.java [v2]
In-Reply-To: <f1InD5kPf0hXmiR6kpFCKl4j2iO8QIuhT6KLDcS1YmU=.d5f19994-7281-42d0-81f8-caec7454d851@github.com>
References: <f1InD5kPf0hXmiR6kpFCKl4j2iO8QIuhT6KLDcS1YmU=.d5f19994-7281-42d0-81f8-caec7454d851@github.com>
Message-ID: <coDzpvjtRPquOBXYaA125lAVBOi5uR4oC4j7Cly5apw=.ea33846f-00c7-414d-80b5-c96e532ac3e4@github.com>

> Please review a change to move a long-running shellsupport test from langtools tier1 to tier2, while modifying the tier1 test to only retrieve doc comments for members of `java.lang.StringBuilder`, which is where [the original bug](https://bugs.openjdk.org/browse/JDK-8189778) occurred.  This reduces the running time in the tier1 test from around 90 seconds to 2 seconds on my computer. The tier1 test also adds a non-null check for retrieved doc comments.
> 
> I used the existing `langtools_jshell_unstable` test group to add the new test in langtools tier2, which is not a perfect match for the test, but close enough and helps to keep langtools `TEST.groups` file simple.

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

  Move FullJavaDocHelperTest.java into its own group

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18837/files
  - new: https://git.openjdk.org/jdk/pull/18837/files/340a3b4f..7a45c94d

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

  Stats: 9 lines in 1 file changed: 5 ins; 1 del; 3 mod
  Patch: https://git.openjdk.org/jdk/pull/18837.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18837/head:pull/18837

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

From jjg at openjdk.org  Tue Apr 23 20:26:57 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 23 Apr 2024 20:26:57 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v7]
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: <RHregxT5ye-XTQEWzPqLPVZXgm2Id82FV--QqNLAJMc=.4c5c4e64-3a6c-438f-a877-e6f9689986fd@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.

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

 - Merge with upstream/master
 - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
 - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
 - Merge with upstream/master
 - update test
 - improve handling of ignorable doc comments
   suppress warning when building test code
 - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
 - call `saveDanglingDocComments` for local variable declarations
 - adjust call for `saveDanglingDocComments` for enum members
 - 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=06
  Stats: 485 lines in 59 files changed: 387 ins; 3 del; 95 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 jjg at openjdk.org  Thu Apr 25 22:53:04 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 25 Apr 2024 22:53:04 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v8]
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: <l0Wf7Ng-zjDRAZwhsOY9wf2dytL6ctdsMmLCL3tkgdc=.670a964c-af86-4c75-9d5a-4f6e479ac598@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.

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

 - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
   commit.
 - Merge with upstream/master
 - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
 - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
 - Merge with upstream/master
 - update test
 - improve handling of ignorable doc comments
   suppress warning when building test code
 - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
 - call `saveDanglingDocComments` for local variable declarations
 - adjust call for `saveDanglingDocComments` for enum members
 - ... and 1 more: https://git.openjdk.org/jdk/compare/1c238d43...16a265a2

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

Changes: https://git.openjdk.org/jdk/pull/18527/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=07
  Stats: 485 lines in 59 files changed: 387 ins; 3 del; 95 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 jjg at openjdk.org  Thu Apr 25 23:24:07 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 25 Apr 2024 23:24:07 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v9]
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: <be6kTtJezTLou_YPTgclvACoddoyffmpupwBjO2DIT8=.6cab77e8-c42a-4e22-9bcb-a8fea5cebf67@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.

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

  revert need to disable warning

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18527/files
  - new: https://git.openjdk.org/jdk/pull/18527/files/16a265a2..39689a52

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=08
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=07-08

  Stats: 3 lines in 1 file changed: 0 ins; 2 del; 1 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 vromero at openjdk.org  Fri Apr 26 00:23:33 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Fri, 26 Apr 2024 00:23:33 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v9]
In-Reply-To: <be6kTtJezTLou_YPTgclvACoddoyffmpupwBjO2DIT8=.6cab77e8-c42a-4e22-9bcb-a8fea5cebf67@github.com>
References: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
 <be6kTtJezTLou_YPTgclvACoddoyffmpupwBjO2DIT8=.6cab77e8-c42a-4e22-9bcb-a8fea5cebf67@github.com>
Message-ID: <txquEDIJ7YBKTZ6-EggzWEHSYzFxMXIBbwTuexdYXro=.af5bb232-dbd4-4099-9fc7-3bc22aacdd07@github.com>

On Thu, 25 Apr 2024 23:24:07 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.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   revert need to disable warning

looks good

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java line 583:

> 581:      *     dangling comments are also attached to the tree node
> 582:      *     by registering them using the {@link #deferredLintHandler}.
> 583:      *  5. (Later) Warnings may be genereated for the dangling

typo: generated

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18527#pullrequestreview-2023792395
PR Review Comment: https://git.openjdk.org/jdk/pull/18527#discussion_r1580263826

From hannesw at openjdk.org  Fri Apr 26 15:20:03 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 26 Apr 2024 15:20:03 GMT
Subject: RFR: 8296175: Output warning if generated docs contain diagnostic
 markers
Message-ID: <88a3v9PFd1rqNp4mNkrNuPMk7catg5x228mZO0Yvcsw=.1ddbedb1-925f-40ab-9098-be1a78d51391@github.com>

Please review a change to print a terminal message if the documentation generated by `HtmlDoclet` contains any diagnostic marker elements for invalid input. The message is printed after the documentation has been generated and before the error/warning count with the purpose to let the user know that the documentation is not ready to be deployed and can be consulted for locating invalid input. 

Example `javadoc` output containing the new message:


...
Generating out/index.html...
Generating out/help-doc.html...
The generated documentation contains diagnostic markers for invalid input.
3 errors
1 warning

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

Commit messages:
 - JDK-8296175: Output warning if generated docs contain diagnostic markers

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

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

From jjg at openjdk.org  Fri Apr 26 16:04:09 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 26 Apr 2024 16:04:09 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v10]
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: <WA4RKekV8mLqnrxi1HqfCR2F6DT27mqVdLhigmerCtA=.33dcb72a-f3ff-4d9a-a794-95ff3849e5fa@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.

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

  fix typo

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18527/files
  - new: https://git.openjdk.org/jdk/pull/18527/files/39689a52..48e8b0a2

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=09
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=08-09

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 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  Fri Apr 26 16:42:50 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 26 Apr 2024 16:42:50 GMT
Subject: RFR: 8296175: Output warning if generated docs contain diagnostic
 markers
In-Reply-To: <88a3v9PFd1rqNp4mNkrNuPMk7catg5x228mZO0Yvcsw=.1ddbedb1-925f-40ab-9098-be1a78d51391@github.com>
References: <88a3v9PFd1rqNp4mNkrNuPMk7catg5x228mZO0Yvcsw=.1ddbedb1-925f-40ab-9098-be1a78d51391@github.com>
Message-ID: <sYcAV1GsCy6DNbdTFW95yDbHEuNIbpkOBclY6DYm-xg=.e03a324b-f610-4f6e-823b-728a64ac72af@github.com>

On Fri, 26 Apr 2024 15:14:04 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to print a terminal message if the documentation generated by `HtmlDoclet` contains any diagnostic marker elements for invalid input. The message is printed after the documentation has been generated and before the error/warning count with the purpose to let the user know that the documentation is not ready to be deployed and can be consulted for locating invalid input. 
> 
> Example `javadoc` output containing the new message:
> 
> 
> ...
> Generating out/index.html...
> Generating out/help-doc.html...
> The generated documentation contains diagnostic markers for invalid input.
> 3 errors
> 1 warning

The feature is good, but I'm surprised to see it being tested in DocLintTest.java.

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

PR Review: https://git.openjdk.org/jdk/pull/18980#pullrequestreview-2025454237

From jjg at openjdk.org  Fri Apr 26 18:04:52 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 26 Apr 2024 18:04:52 GMT
Subject: RFR: 8296175: Output warning if generated docs contain diagnostic
 markers
In-Reply-To: <88a3v9PFd1rqNp4mNkrNuPMk7catg5x228mZO0Yvcsw=.1ddbedb1-925f-40ab-9098-be1a78d51391@github.com>
References: <88a3v9PFd1rqNp4mNkrNuPMk7catg5x228mZO0Yvcsw=.1ddbedb1-925f-40ab-9098-be1a78d51391@github.com>
Message-ID: <X_h3YsaBT5XkLoVTDY_P0udsmMYs_jOeZdXzKyvN6Cc=.0e0a3628-f714-475a-b23b-bba9fa7925e0@github.com>

On Fri, 26 Apr 2024 15:14:04 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to print a terminal message if the documentation generated by `HtmlDoclet` contains any diagnostic marker elements for invalid input. The message is printed after the documentation has been generated and before the error/warning count with the purpose to let the user know that the documentation is not ready to be deployed and can be consulted for locating invalid input. 
> 
> Example `javadoc` output containing the new message:
> 
> 
> ...
> Generating out/index.html...
> Generating out/help-doc.html...
> The generated documentation contains diagnostic markers for invalid input.
> 3 errors
> 1 warning

Marked as reviewed by jjg (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/18980#pullrequestreview-2025589147

From jjg at openjdk.org  Fri Apr 26 18:07:51 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 26 Apr 2024 18:07:51 GMT
Subject: RFR: 8296175: Output warning if generated docs contain diagnostic
 markers
In-Reply-To: <sYcAV1GsCy6DNbdTFW95yDbHEuNIbpkOBclY6DYm-xg=.e03a324b-f610-4f6e-823b-728a64ac72af@github.com>
References: <88a3v9PFd1rqNp4mNkrNuPMk7catg5x228mZO0Yvcsw=.1ddbedb1-925f-40ab-9098-be1a78d51391@github.com>
 <sYcAV1GsCy6DNbdTFW95yDbHEuNIbpkOBclY6DYm-xg=.e03a324b-f610-4f6e-823b-728a64ac72af@github.com>
Message-ID: <5lRqQFLMEJ6fnYbhZAoVM9ZXZ4v65WRzxs77umbmjv8=.16f9894f-10da-4896-a4da-fd0bbfc0e34f@github.com>

On Fri, 26 Apr 2024 16:40:33 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> The feature is good, but I'm surprised to see it being tested in DocLintTest.java.

Yeah, good point.  The message should be generated independently of any doclint settings.

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

PR Comment: https://git.openjdk.org/jdk/pull/18980#issuecomment-2079855922

From hannesw at openjdk.org  Fri Apr 26 18:57:51 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 26 Apr 2024 18:57:51 GMT
Subject: RFR: 8296175: Output warning if generated docs contain diagnostic
 markers
In-Reply-To: <5lRqQFLMEJ6fnYbhZAoVM9ZXZ4v65WRzxs77umbmjv8=.16f9894f-10da-4896-a4da-fd0bbfc0e34f@github.com>
References: <88a3v9PFd1rqNp4mNkrNuPMk7catg5x228mZO0Yvcsw=.1ddbedb1-925f-40ab-9098-be1a78d51391@github.com>
 <sYcAV1GsCy6DNbdTFW95yDbHEuNIbpkOBclY6DYm-xg=.e03a324b-f610-4f6e-823b-728a64ac72af@github.com>
 <5lRqQFLMEJ6fnYbhZAoVM9ZXZ4v65WRzxs77umbmjv8=.16f9894f-10da-4896-a4da-fd0bbfc0e34f@github.com>
Message-ID: <Zqjh6KaikJtw9Pc4_htIKlwZKxGDin_l1aq6X2Xbpdo=.915ea33c-5294-4b9c-988d-0d1a52476fbc@github.com>

On Fri, 26 Apr 2024 18:05:14 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> The feature is good, but I'm surprised to see it being tested in DocLintTest.java.

I admit I took a shortcut there, using `DocLintTest` for something it wasn't meant to do. The test had to be updated anyway, and it had both the invalid input and the output checks I needed, so I took advantage.

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

PR Comment: https://git.openjdk.org/jdk/pull/18980#issuecomment-2079958979

From prr at openjdk.org  Fri Apr 26 19:34:00 2024
From: prr at openjdk.org (Phil Race)
Date: Fri, 26 Apr 2024 19:34:00 GMT
Subject: RFR: 8303689: javac -Xlint could/should report on "dangling" doc
 comments [v10]
In-Reply-To: <WA4RKekV8mLqnrxi1HqfCR2F6DT27mqVdLhigmerCtA=.33dcb72a-f3ff-4d9a-a794-95ff3849e5fa@github.com>
References: <T_hVB24wAdfq2M4bC_BxfHPjdB_-uF6w3QyRvcgW7vQ=.309824a7-d67c-4619-9862-017fae5521d4@github.com>
 <WA4RKekV8mLqnrxi1HqfCR2F6DT27mqVdLhigmerCtA=.33dcb72a-f3ff-4d9a-a794-95ff3849e5fa@github.com>
Message-ID: <SD0S716mdRSViTfaViQgFYEkmR7WmBalQQe3_FI7VQc=.b83407a8-0c84-4ed9-8b56-adf6db1a2e0c@github.com>

On Fri, 26 Apr 2024 16:04:09 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.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   fix typo

Marked as reviewed by prr (Reviewer).

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

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

From jjg at openjdk.org  Fri Apr 26 19:49:56 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 26 Apr 2024 19:49:56 GMT
Subject: Integrated: 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: <jz5iSs8rS6B9ZP2l3HbT7UR9gdQiXvxyQFGqikRLN7U=.584799e9-55c0-4a22-b62f-e30406cfe8ea@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.

This pull request has now been integrated.

Changeset: a920af23
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/a920af233a11592af113f456f7608cb59dd1617e
Stats:     482 lines in 58 files changed: 385 ins; 3 del; 94 mod

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

Reviewed-by: vromero, ihse, prr

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

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

From hannesw at openjdk.org  Fri Apr 26 20:02:51 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 26 Apr 2024 20:02:51 GMT
Subject: Integrated: 8296175: Output warning if generated docs contain
 diagnostic markers
In-Reply-To: <88a3v9PFd1rqNp4mNkrNuPMk7catg5x228mZO0Yvcsw=.1ddbedb1-925f-40ab-9098-be1a78d51391@github.com>
References: <88a3v9PFd1rqNp4mNkrNuPMk7catg5x228mZO0Yvcsw=.1ddbedb1-925f-40ab-9098-be1a78d51391@github.com>
Message-ID: <l59Hb7AygS5A13K35av_vGeixhinTDxj8zMYyFMfhBc=.dea9fece-a553-4f44-b32c-2fed35b6cf3f@github.com>

On Fri, 26 Apr 2024 15:14:04 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to print a terminal message if the documentation generated by `HtmlDoclet` contains any diagnostic marker elements for invalid input. The message is printed after the documentation has been generated and before the error/warning count with the purpose to let the user know that the documentation is not ready to be deployed and can be consulted for locating invalid input. 
> 
> Example `javadoc` output containing the new message:
> 
> 
> ...
> Generating out/index.html...
> Generating out/help-doc.html...
> The generated documentation contains diagnostic markers for invalid input.
> 3 errors
> 1 warning

This pull request has now been integrated.

Changeset: aee91fbc
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/aee91fbc70df716b96c202511b4ff1b302df8d60
Stats:     44 lines in 5 files changed: 32 ins; 0 del; 12 mod

8296175: Output warning if generated docs contain diagnostic markers

Reviewed-by: jjg

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

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

From jjg at openjdk.org  Fri Apr 26 20:34:32 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 26 Apr 2024 20:34:32 GMT
Subject: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments
 [v57]
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: <-gBUJIN77XgSqa6gYERcGf2AeCmTWxNzRDnwmzrpS2U=.bac755e7-ba7f-41b5-9d1b-2b6f56c02f3e@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 81 commits:

 - Merge with upstream/master
 - address review feedback for updates to Elements and friends
 - address review feedback for updates to Elements and friends
 - add support for JDK-8329296: Update Elements for '///' documentation comments
 - add support for `--disable-line-doc-comments`
 - 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
 - ... and 71 more: https://git.openjdk.org/jdk/compare/a920af23...c4709cf5

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=56
  Stats: 24098 lines in 228 files changed: 23453 ins; 260 del; 385 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  Fri Apr 26 21:26:19 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 26 Apr 2024 21:26:19 GMT
Subject: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments
 [v58]
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: <MLs8RwacyqdpefVLbIw-eXbnxDrZ2wcyJfZfgag_toU=.7c176ef4-b269-4990-b491-7403ead4efbe@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:

  Suppress warnings building tests

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/c4709cf5..a884ae36

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

  Stats: 2 lines in 1 file changed: 0 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 duke at openjdk.org  Mon Apr 29 04:36:40 2024
From: duke at openjdk.org (psoujany)
Date: Mon, 29 Apr 2024 04:36:40 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v17]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <bcwJlQRrVr00FTZVJumDkvlCFvihFbWA4WHk0ChG-O0=.4e25f882-cc24-4f44-8759-dfbd6599fc1e@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/96719f9b..67e1940e

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=16
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=15-16

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

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

From jjg at openjdk.org  Mon Apr 29 18:15:52 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 29 Apr 2024 18:15:52 GMT
Subject: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments
 [v59]
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: <n2SmbOhfixdaDsnqLOEF3ljuUmSARu3Q0yjxdTxmMjA=.8e2d0baf-1aa1-4bb5-a316-5d442c602cb0@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:

  Remove links to `jdk.javadoc` module from `java.compiler` module`

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/a884ae36..fadc130b

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

  Stats: 9 lines in 1 file changed: 0 ins; 5 del; 4 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 duke at openjdk.org  Tue Apr 30 07:29:42 2024
From: duke at openjdk.org (psoujany)
Date: Tue, 30 Apr 2024 07:29:42 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v18]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <3qXSoFZDNDaswOJKBqkdRC2vpMC1cXzC4JYQS11Ffjk=.3b390bdf-32fa-4ec2-8b2a-a04c2cd9cdf9@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex to grid columns

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/67e1940e..3f32ed59

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=17
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=16-17

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

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

From duke at openjdk.org  Tue Apr 30 09:43:33 2024
From: duke at openjdk.org (psoujany)
Date: Tue, 30 Apr 2024 09:43:33 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v19]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <CJBrb_CW3Sob80k1F4g60qM8yDTDlj0W7NBTcgeWVrA=.437fb82a-0eeb-45d0-ab20-40d41e2771a8@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Add tabindex to grid columns

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/3f32ed59..e31bcbc9

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=18
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=17-18

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

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

From duke at openjdk.org  Tue Apr 30 10:52:23 2024
From: duke at openjdk.org (psoujany)
Date: Tue, 30 Apr 2024 10:52:23 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v20]
In-Reply-To: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
Message-ID: <T9TV681UWAkdge-AEa5E3j_FthkO54zv6wWdM8QbePA=.b6a62093-1424-46e6-b61b-68b4eeaead91@github.com>

> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
> https://bugs.openjdk.org/browse/JDK-8325690

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

  Remove trailing whitespaces

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17819/files
  - new: https://git.openjdk.org/jdk/pull/17819/files/e31bcbc9..885fa89f

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=19
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17819&range=18-19

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

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

From duke at openjdk.org  Tue Apr 30 10:52:24 2024
From: duke at openjdk.org (psoujany)
Date: Tue, 30 Apr 2024 10:52:24 GMT
Subject: RFR: 8325690: The scrollable element <div> with non-interactive
 content is not tabbable [v19]
In-Reply-To: <CJBrb_CW3Sob80k1F4g60qM8yDTDlj0W7NBTcgeWVrA=.437fb82a-0eeb-45d0-ab20-40d41e2771a8@github.com>
References: <sOfcWV4OU4T7B3MdgQV4KPza-Nn9ebkg9lnyE0OWhVE=.1f1acdc1-e379-44ea-8650-8cfdceba61ec@github.com>
 <CJBrb_CW3Sob80k1F4g60qM8yDTDlj0W7NBTcgeWVrA=.437fb82a-0eeb-45d0-ab20-40d41e2771a8@github.com>
Message-ID: <PisLtAI7glBivmhe_bEcw_QkN6Vxt1SLi_hcdse1lAw=.128c7401-e6a6-4531-9fd1-d4e434ea805c@github.com>

On Tue, 30 Apr 2024 09:43:33 GMT, psoujany <duke at openjdk.org> wrote:

>> The scrollable element `<div>` with non-interactive content is not tabbable. Grid columns in the javadoc stylesheet has overflow: auto, which is failing Accessibility checks.
>> https://bugs.openjdk.org/browse/JDK-8325690
>
> psoujany has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add tabindex to grid columns

@hns Could you please review the changes. Thank you.

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

PR Comment: https://git.openjdk.org/jdk/pull/17819#issuecomment-2084976462

From jjg at openjdk.org  Tue Apr 30 20:33:50 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 30 Apr 2024 20:33:50 GMT
Subject: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments
 [v60]
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: <QhopqzGp9Z8FUSZrCkfBj0Ynk2XHrZPGZlpV6-Axim4=.68c55e6c-cc5f-4175-9997-95edfaf8790d@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:

  update commonmark-java from 0.21.0 to 0.22.0

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/fadc130b..74c86f51

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

  Stats: 2382 lines in 53 files changed: 2020 ins; 258 del; 104 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 Apr 30 20:56:21 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 30 Apr 2024 20:56:21 GMT
Subject: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments
 [v61]
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: <WfeEp76yI2ydvziffv05JmzxWUGelLcMVJ13N_c9Zu8=.26b62a07-d07c-4211-b9cb-ba9bc403d9fc@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 85 commits:

 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - update commonmark-java from 0.21.0 to 0.22.0
 - Remove links to `jdk.javadoc` module from `java.compiler` module`
 - Suppress warnings building tests
 - Merge with upstream/master
 - address review feedback for updates to Elements and friends
 - address review feedback for updates to Elements and friends
 - add support for JDK-8329296: Update Elements for '///' documentation comments
 - add support for `--disable-line-doc-comments`
 - Merge branch '8298405.doclet-markdown-v3' of https://github.com/jonathan-gibbons/jdk into 8298405.doclet-markdown-v3
 - ... and 75 more: https://git.openjdk.org/jdk/compare/b96b38c2...20a384b6

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=60
  Stats: 26326 lines in 243 files changed: 25679 ins; 260 del; 387 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 Apr 30 21:32:13 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 30 Apr 2024 21:32:13 GMT
Subject: RFR: 8298405: Implement JEP 467: Markdown Documentation Comments
 [v62]
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: <wpVYrszNWaH_jfBZPg7NILh2k13qmWmIkJcMbq1_Utg=.52a4ce74-df34-4ae6-b307-0d07b2198608@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:

  update copyright years

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/20a384b6..6576d024

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

  Stats: 68 lines in 62 files changed: 0 ins; 7 del; 61 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