From jjg at openjdk.java.net  Mon Jan  3 21:50:18 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 3 Jan 2022 21:50:18 GMT
Subject: [jdk18] RFR: JDK-8273452: DocTrees.getDocCommentTree should be
 specified as idempotent
In-Reply-To: <GhovZDzU7t6WkQLekF1CwPanpuN0newHN5TMPz2FZTs=.984b4252-2fa7-4de7-a33c-bc717e1bd413@github.com>
References: <GhovZDzU7t6WkQLekF1CwPanpuN0newHN5TMPz2FZTs=.984b4252-2fa7-4de7-a33c-bc717e1bd413@github.com>
Message-ID: <tLX_71AwX3UKwCQ7FGZ1J2-11P7gjxCtzJmUpy2uPic=.bde9f730-7d2d-4ef4-a76e-b7fb99943d7b@github.com>

On Thu, 16 Dec 2021 11:05:01 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a doc-only change to add implementation notes to the `DocTrees.getDocCommentTree` methods, some of which return the same `DocCommentTree` instance on repeated invocation and some don't. I decided to use `@implNote` instead of `@implSpec` as usually I wouldn't expect object identity to be part of a Java API specification.
> 
> I verified the described behavior using code analysis and enhancing existing tests. The latter are not included in the commit as this is a `noreg-doc` issue.

I guess it's a gray area whether it should be an `implSpec` or an `implNote`.

It is a relatively important aspect of the API, because the operations are expensive, and even cause some downstream caching. 

For now, it's enough that it is noted in some fashion.

As a general style note, I would suggest a blank line before each `implNote`, and change "The implementation of this method" to either "The default implementation of this method" or just "This implementation".

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

Marked as reviewed by jjg (Reviewer).

PR: https://git.openjdk.java.net/jdk18/pull/36

From jjg at openjdk.java.net  Tue Jan  4 01:26:36 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 4 Jan 2022 01:26:36 GMT
Subject: RFR: JDK-8268831: Improve javadoc tool handling of streams.
Message-ID: <cf7RSoDuPLHqIXKxCoorYoLd5uDWWHlgyuzyjuAS51g=.1c68ece5-0d52-4d67-b3c0-cde6d208b50c@github.com>

Please review a relatively simple cleanup left over from last year's cleanup for `JavadocLog` (was `Messager`).

The cleanup here is to rationalize the inconsistent naming and use of methods named `notice` in `JavadocLog` and `ToolEnvironment`, as well as cleanup use of the primitive `Log.printRawLines`. While it would have been nice to move the definition of `ToolEnvironment.notice` into `JavadocLog`  that dragged with it the need for the `quiet` variable, which led to initialization order problems.  The proposed solution is a compromise.

No tests are affected; `noreg-cleanup`.

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

Commit messages:
 - JDK-8268831: Improve javadoc tool handling of streams.

Changes: https://git.openjdk.java.net/jdk/pull/6950/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=6950&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8268831
  Stats: 69 lines in 5 files changed: 15 ins; 25 del; 29 mod
  Patch: https://git.openjdk.java.net/jdk/pull/6950.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/6950/head:pull/6950

PR: https://git.openjdk.java.net/jdk/pull/6950

From jlahoda at openjdk.java.net  Tue Jan  4 17:27:28 2022
From: jlahoda at openjdk.java.net (Jan Lahoda)
Date: Tue, 4 Jan 2022 17:27:28 GMT
Subject: [jdk18] RFR: 8278373: JavacTypes.searchMethod finds incorrect match
Message-ID: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>

Currently, when javac encounters a javadoc reference, like `@see PrintStream#println(int)`, will first try to find a method `println` in `PrintStream` using subtyping on the argument types, which may find another overload of the method with an argument that is a subtype of `int` - like `println(double)`. Consequently, the link in the javadoc may be to a wrong method.

In this patch, the proposal is to use the subtype search only as a backup option, using the existing check based on `isSameType` first, and only doing an inexact match using subtyping if the more exact match fails to find a method. This fallback should help possible existing broken references to still work as before, while the preferred use of the more exact match should select the correct method in usual correct cases.

This patch fixes some instances of incorrect references in the JDK's javadoc, a diff of the generated javadocs for the JDK mainline is here:
http://cr.openjdk.java.net/~jlahoda/8278373/JDK-8278373.diff

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

Commit messages:
 - 8278373: JavacTypes.searchMethod finds incorrect match

Changes: https://git.openjdk.java.net/jdk18/pull/79/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk18&pr=79&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8278373
  Stats: 70 lines in 2 files changed: 52 ins; 2 del; 16 mod
  Patch: https://git.openjdk.java.net/jdk18/pull/79.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk18 pull/79/head:pull/79

PR: https://git.openjdk.java.net/jdk18/pull/79

From vromero at openjdk.java.net  Tue Jan  4 19:50:15 2022
From: vromero at openjdk.java.net (Vicente Romero)
Date: Tue, 4 Jan 2022 19:50:15 GMT
Subject: [jdk18] RFR: 8278373: JavacTypes.searchMethod finds incorrect
 match
In-Reply-To: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
References: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
Message-ID: <jcnglePx3UVQ48n-o6xwNJWHCoUU3nV8DNvf2d9Tuv0=.66a4148c-46f5-4f49-b93a-0e67d98a6993@github.com>

On Tue, 4 Jan 2022 17:19:44 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Currently, when javac encounters a javadoc reference, like `@see PrintStream#println(int)`, will first try to find a method `println` in `PrintStream` using subtyping on the argument types, which may find another overload of the method with an argument that is a subtype of `int` - like `println(double)`. Consequently, the link in the javadoc may be to a wrong method.
> 
> In this patch, the proposal is to use the subtype search only as a backup option, using the existing check based on `isSameType` first, and only doing an inexact match using subtyping if the more exact match fails to find a method. This fallback should help possible existing broken references to still work as before, while the preferred use of the more exact match should select the correct method in usual correct cases.
> 
> This patch fixes some instances of incorrect references in the JDK's javadoc, a diff of the generated javadocs for the JDK mainline is here:
> http://cr.openjdk.java.net/~jlahoda/8278373/JDK-8278373.diff

looks sensible

will we need a release note for this bug? it could be that some user's APIs could be affected by this change

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

Marked as reviewed by vromero (Reviewer).

PR: https://git.openjdk.java.net/jdk18/pull/79

From jjg at openjdk.java.net  Tue Jan  4 19:54:15 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 4 Jan 2022 19:54:15 GMT
Subject: [jdk18] RFR: 8278373: JavacTypes.searchMethod finds incorrect
 match
In-Reply-To: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
References: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
Message-ID: <3nXgEPemHZli72G96ehNbbHt5-Hc1WMc4UqP1wrP7z8=.84935fb2-c8d3-4906-8da6-72aab0dc9828@github.com>

On Tue, 4 Jan 2022 17:19:44 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Currently, when javac encounters a javadoc reference, like `@see PrintStream#println(int)`, will first try to find a method `println` in `PrintStream` using subtyping on the argument types, which may find another overload of the method with an argument that is a subtype of `int` - like `println(double)`. Consequently, the link in the javadoc may be to a wrong method.
> 
> In this patch, the proposal is to use the subtype search only as a backup option, using the existing check based on `isSameType` first, and only doing an inexact match using subtyping if the more exact match fails to find a method. This fallback should help possible existing broken references to still work as before, while the preferred use of the more exact match should select the correct method in usual correct cases.
> 
> This patch fixes some instances of incorrect references in the JDK's javadoc, a diff of the generated javadocs for the JDK mainline is here:
> http://cr.openjdk.java.net/~jlahoda/8278373/JDK-8278373.diff

Generally good; I think this is the right fix in the current situation and for potential back porting. It provides improved but compatible behavior.

The API diffs were an unexpected "bonus", if that is the right word.  It's better to know about and fix issues than to not know about them.  I've spot checked a few of them and all seem reasonable. The fix is especially obvious when the link and the clear-text are different and meant to be the same.  The one thing I would suggest is that because a lot of the api diffs are related to "subtyping" between primitive types, we might want to add some test cases for that into the test as well.   Here is a random example of the kind of diff I'm talking about:

```   
- as if by calling <a href="../java.base/java/lang/Math.html#max(double,double)"><code>Math.max</code></a>.</div>
+ as if by calling <a href="../java.base/java/lang/Math.html#max(float,float)"><code>Math.max</code></a>.</div>


Further out (JDK 19?) I think we should investigate the need for the `strict == false` case and/or give warnings (in javadoc) when the lookup is not exact.  We should fix any cases in the JDK docs where that is the case, and/or consider removing support for `strict == false` or else make it an opt-in behavior somehow.

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

Marked as reviewed by jjg (Reviewer).

PR: https://git.openjdk.java.net/jdk18/pull/79

From jjg at openjdk.java.net  Tue Jan  4 20:03:18 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 4 Jan 2022 20:03:18 GMT
Subject: [jdk18] RFR: 8278373: JavacTypes.searchMethod finds incorrect
 match
In-Reply-To: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
References: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
Message-ID: <AL3u3SOK8pIJOJ2BvmlWzWOO1mLNPtLICUXxPdmRR4k=.6510c08c-4262-4470-8b26-b7ee13dfa35e@github.com>

On Tue, 4 Jan 2022 17:19:44 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Currently, when javac encounters a javadoc reference, like `@see PrintStream#println(int)`, will first try to find a method `println` in `PrintStream` using subtyping on the argument types, which may find another overload of the method with an argument that is a subtype of `int` - like `println(double)`. Consequently, the link in the javadoc may be to a wrong method.
> 
> In this patch, the proposal is to use the subtype search only as a backup option, using the existing check based on `isSameType` first, and only doing an inexact match using subtyping if the more exact match fails to find a method. This fallback should help possible existing broken references to still work as before, while the preferred use of the more exact match should select the correct method in usual correct cases.
> 
> This patch fixes some instances of incorrect references in the JDK's javadoc, a diff of the generated javadocs for the JDK mainline is here:
> http://cr.openjdk.java.net/~jlahoda/8278373/JDK-8278373.diff

> [snip]
> 
> Further out (JDK 19?) I think we should investigate the need for the `strict == false` case and/or give warnings (in javadoc) when the lookup is not exact. We should fix any cases in the JDK docs where that is the case, and/or consider removing support for `strict == false` or else make it an opt-in behavior somehow.

Filed JDK-8279474

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

PR: https://git.openjdk.java.net/jdk18/pull/79

From jlahoda at openjdk.java.net  Wed Jan  5 14:37:03 2022
From: jlahoda at openjdk.java.net (Jan Lahoda)
Date: Wed, 5 Jan 2022 14:37:03 GMT
Subject: [jdk18] RFR: 8278373: JavacTrees.searchMethod finds incorrect
 match
In-Reply-To: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
References: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
Message-ID: <sgFodMNmbdwDQsVQw3CbM8kM5XQGRuiqCw0zHq1ermE=.c65a6cfd-d369-40b9-a1b6-9710034987a4@github.com>

On Tue, 4 Jan 2022 17:19:44 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Currently, when javac encounters a javadoc reference, like `@see PrintStream#println(int)`, will first try to find a method `println` in `PrintStream` using subtyping on the argument types, which may find another overload of the method with an argument that is a subtype of `int` - like `println(double)`. Consequently, the link in the javadoc may be to a wrong method.
> 
> In this patch, the proposal is to use the subtype search only as a backup option, using the existing check based on `isSameType` first, and only doing an inexact match using subtyping if the more exact match fails to find a method. This fallback should help possible existing broken references to still work as before, while the preferred use of the more exact match should select the correct method in usual correct cases.
> 
> This patch fixes some instances of incorrect references in the JDK's javadoc, a diff of the generated javadocs for the JDK mainline is here:
> http://cr.openjdk.java.net/~jlahoda/8278373/JDK-8278373.diff

I've filled a release note here:
https://bugs.openjdk.java.net/browse/JDK-8279503

And updated the patch to include primitive types and methods with multiple parameters: https://github.com/openjdk/jdk18/pull/79/commits/34e421b96fa7f4e7e20aec16bb758056191b8773

Feedback is welcome!

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

PR: https://git.openjdk.java.net/jdk18/pull/79

From jlahoda at openjdk.java.net  Wed Jan  5 14:37:02 2022
From: jlahoda at openjdk.java.net (Jan Lahoda)
Date: Wed, 5 Jan 2022 14:37:02 GMT
Subject: [jdk18] RFR: 8278373: JavacTrees.searchMethod finds incorrect
 match [v2]
In-Reply-To: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
References: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
Message-ID: <DIfaqsTcwwXliEiAXA4HKmK3kRsOgltc6Q3o6vIGnhc=.98e30e63-4544-44e5-be78-2064dd3eb5eb@github.com>

> Currently, when javac encounters a javadoc reference, like `@see PrintStream#println(int)`, will first try to find a method `println` in `PrintStream` using subtyping on the argument types, which may find another overload of the method with an argument that is a subtype of `int` - like `println(double)`. Consequently, the link in the javadoc may be to a wrong method.
> 
> In this patch, the proposal is to use the subtype search only as a backup option, using the existing check based on `isSameType` first, and only doing an inexact match using subtyping if the more exact match fails to find a method. This fallback should help possible existing broken references to still work as before, while the preferred use of the more exact match should select the correct method in usual correct cases.
> 
> This patch fixes some instances of incorrect references in the JDK's javadoc, a diff of the generated javadocs for the JDK mainline is here:
> http://cr.openjdk.java.net/~jlahoda/8278373/JDK-8278373.diff

Jan Lahoda 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 three additional commits since the last revision:

 - Merge branch 'master' into JDK-8278373
 - Adding new test cases as suggested on the code review.
 - 8278373: JavacTypes.searchMethod finds incorrect match

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

Changes:
  - all: https://git.openjdk.java.net/jdk18/pull/79/files
  - new: https://git.openjdk.java.net/jdk18/pull/79/files/8c0ad7f0..0c88aa60

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk18&pr=79&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk18&pr=79&range=00-01

  Stats: 137 lines in 5 files changed: 116 ins; 8 del; 13 mod
  Patch: https://git.openjdk.java.net/jdk18/pull/79.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk18 pull/79/head:pull/79

PR: https://git.openjdk.java.net/jdk18/pull/79

From vromero at openjdk.java.net  Wed Jan  5 16:48:23 2022
From: vromero at openjdk.java.net (Vicente Romero)
Date: Wed, 5 Jan 2022 16:48:23 GMT
Subject: [jdk18] RFR: 8278373: JavacTrees.searchMethod finds incorrect
 match [v2]
In-Reply-To: <DIfaqsTcwwXliEiAXA4HKmK3kRsOgltc6Q3o6vIGnhc=.98e30e63-4544-44e5-be78-2064dd3eb5eb@github.com>
References: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
 <DIfaqsTcwwXliEiAXA4HKmK3kRsOgltc6Q3o6vIGnhc=.98e30e63-4544-44e5-be78-2064dd3eb5eb@github.com>
Message-ID: <rfaIKB7JBQmTiz3RJQlQwu_ZBxv8kGp_b9-E7_Cy_tI=.b681c97c-fcba-4905-a450-3f0d56d5844f@github.com>

On Wed, 5 Jan 2022 14:37:02 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

>> Currently, when javac encounters a javadoc reference, like `@see PrintStream#println(int)`, will first try to find a method `println` in `PrintStream` using subtyping on the argument types, which may find another overload of the method with an argument that is a subtype of `int` - like `println(double)`. Consequently, the link in the javadoc may be to a wrong method.
>> 
>> In this patch, the proposal is to use the subtype search only as a backup option, using the existing check based on `isSameType` first, and only doing an inexact match using subtyping if the more exact match fails to find a method. This fallback should help possible existing broken references to still work as before, while the preferred use of the more exact match should select the correct method in usual correct cases.
>> 
>> This patch fixes some instances of incorrect references in the JDK's javadoc, a diff of the generated javadocs for the JDK mainline is here:
>> http://cr.openjdk.java.net/~jlahoda/8278373/JDK-8278373.diff
>
> Jan Lahoda 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 three additional commits since the last revision:
> 
>  - Merge branch 'master' into JDK-8278373
>  - Adding new test cases as suggested on the code review.
>  - 8278373: JavacTypes.searchMethod finds incorrect match

latest change looks good to me

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

PR: https://git.openjdk.java.net/jdk18/pull/79

From jjg at openjdk.java.net  Thu Jan  6 20:40:44 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 6 Jan 2022 20:40:44 GMT
Subject: RFR: JDK-8272853: improve `JavadocTester.runTests`
Message-ID: <yKDakYiCFt7M34gQ_YB1eYUrTrgjolfnrJQ6nllG_JA=.104a78a1-255c-4eb7-a8d5-7a22f5e4227e@github.com>

Please review a medium simple test-only fix to improve the `JavadocTester` `runTests` methods.

Currently, there are two overloads: one to invoke no-args test methods, and another to invoke test methods with args, such as a method-specific `Path`.  This latter one is slightly inconvenient to use, since it requires the boilerplate use of a function to create the arguments.

The first overload is updated in a backwards compatible way, to examine the parameters of methods annotated with `@Test`, and to recognize common patterns: namely no-args methods and `(Path)` methods, without the need for any additional function.  The second overload is retained by backwards compatibility, until if and when we decide it is no longer required.

In addition, two new overloads are added, similar to the first two, but with the addition of an extra parameter to decide which methods should be invoked. This is primarily a debugging aid.  Using these overloads, it is easy to specify, on the command line used to run the test, the methods to be executed.

A new test is added to test the new functionality.

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

Commit messages:
 - JDK-8272853: improve `JavadocTester.runTests`

Changes: https://git.openjdk.java.net/jdk/pull/6983/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=6983&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8272853
  Stats: 370 lines in 2 files changed: 359 ins; 6 del; 5 mod
  Patch: https://git.openjdk.java.net/jdk/pull/6983.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/6983/head:pull/6983

PR: https://git.openjdk.java.net/jdk/pull/6983

From jlahoda at openjdk.java.net  Mon Jan 10 08:38:39 2022
From: jlahoda at openjdk.java.net (Jan Lahoda)
Date: Mon, 10 Jan 2022 08:38:39 GMT
Subject: [jdk18] Integrated: 8278373: JavacTrees.searchMethod finds incorrect
 match
In-Reply-To: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
References: <XbMsX_o0DPzcRmiLkhyD0uXxvEfHB8kXLGVoB9DWMFw=.9ccaedb0-4fab-44a1-ab68-8612a85d796e@github.com>
Message-ID: <TMCccJsSpO3nRBTDF56Lh_DwuoUDvuXujXhvqt05Nd4=.f0b7bd98-380d-4040-948a-8f2fcff5b44e@github.com>

On Tue, 4 Jan 2022 17:19:44 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Currently, when javac encounters a javadoc reference, like `@see PrintStream#println(int)`, will first try to find a method `println` in `PrintStream` using subtyping on the argument types, which may find another overload of the method with an argument that is a subtype of `int` - like `println(double)`. Consequently, the link in the javadoc may be to a wrong method.
> 
> In this patch, the proposal is to use the subtype search only as a backup option, using the existing check based on `isSameType` first, and only doing an inexact match using subtyping if the more exact match fails to find a method. This fallback should help possible existing broken references to still work as before, while the preferred use of the more exact match should select the correct method in usual correct cases.
> 
> This patch fixes some instances of incorrect references in the JDK's javadoc, a diff of the generated javadocs for the JDK mainline is here:
> http://cr.openjdk.java.net/~jlahoda/8278373/JDK-8278373.diff

This pull request has now been integrated.

Changeset: 642ab34a
Author:    Jan Lahoda <jlahoda at openjdk.org>
URL:       https://git.openjdk.java.net/jdk18/commit/642ab34a60172f4b629f953e146b54b9c7269033
Stats:     89 lines in 2 files changed: 71 ins; 2 del; 16 mod

8278373: JavacTrees.searchMethod finds incorrect match

Reviewed-by: vromero, jjg

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

PR: https://git.openjdk.java.net/jdk18/pull/79

From hannesw at openjdk.java.net  Mon Jan 10 11:46:06 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 10 Jan 2022 11:46:06 GMT
Subject: [jdk18] RFR: JDK-8273452: DocTrees.getDocCommentTree should be
 specified as idempotent [v2]
In-Reply-To: <GhovZDzU7t6WkQLekF1CwPanpuN0newHN5TMPz2FZTs=.984b4252-2fa7-4de7-a33c-bc717e1bd413@github.com>
References: <GhovZDzU7t6WkQLekF1CwPanpuN0newHN5TMPz2FZTs=.984b4252-2fa7-4de7-a33c-bc717e1bd413@github.com>
Message-ID: <wHzzfXBgln7FpdvfWDceIFUHKt_GnMDW0Pja_p3vJVI=.42a09d9c-652e-42da-858a-d6c3aea84d1a@github.com>

> Please review a doc-only change to add implementation notes to the `DocTrees.getDocCommentTree` methods, some of which return the same `DocCommentTree` instance on repeated invocation and some don't. I decided to use `@implNote` instead of `@implSpec` as usually I wouldn't expect object identity to be part of a Java API specification.
> 
> I verified the described behavior using code analysis and enhancing existing tests. The latter are not included in the commit as this is a `noreg-doc` issue.

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

  JDK-8273452: review feedback

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

Changes:
  - all: https://git.openjdk.java.net/jdk18/pull/36/files
  - new: https://git.openjdk.java.net/jdk18/pull/36/files/f69a1052..66cbd42b

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk18&pr=36&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk18&pr=36&range=00-01

  Stats: 8 lines in 1 file changed: 4 ins; 0 del; 4 mod
  Patch: https://git.openjdk.java.net/jdk18/pull/36.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk18 pull/36/head:pull/36

PR: https://git.openjdk.java.net/jdk18/pull/36

From hannesw at openjdk.java.net  Mon Jan 10 12:07:29 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 10 Jan 2022 12:07:29 GMT
Subject: [jdk18] Integrated: JDK-8273452: DocTrees.getDocCommentTree should be
 specified as idempotent
In-Reply-To: <GhovZDzU7t6WkQLekF1CwPanpuN0newHN5TMPz2FZTs=.984b4252-2fa7-4de7-a33c-bc717e1bd413@github.com>
References: <GhovZDzU7t6WkQLekF1CwPanpuN0newHN5TMPz2FZTs=.984b4252-2fa7-4de7-a33c-bc717e1bd413@github.com>
Message-ID: <lb2tIXx4Zk0lpGhYdBQyVCeJhS5Uki6epHNAlFrJ5uA=.1674789c-446f-4b01-8de5-fd343a68ad3a@github.com>

On Thu, 16 Dec 2021 11:05:01 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a doc-only change to add implementation notes to the `DocTrees.getDocCommentTree` methods, some of which return the same `DocCommentTree` instance on repeated invocation and some don't. I decided to use `@implNote` instead of `@implSpec` as usually I wouldn't expect object identity to be part of a Java API specification.
> 
> I verified the described behavior using code analysis and enhancing existing tests. The latter are not included in the commit as this is a `noreg-doc` issue.

This pull request has now been integrated.

Changeset: 354c9047
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk18/commit/354c9047987c0837d95440780993a0aa84551ea1
Stats:     16 lines in 1 file changed: 16 ins; 0 del; 0 mod

8273452: DocTrees.getDocCommentTree should be specified as idempotent

Reviewed-by: jjg

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

PR: https://git.openjdk.java.net/jdk18/pull/36

From prappo at openjdk.java.net  Mon Jan 10 12:23:12 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 10 Jan 2022 12:23:12 GMT
Subject: RFR: 8273001: Improve the doclet.usage.tagletpath option
 description [v3]
In-Reply-To: <gZaz3XGM9kRN3xyW0ffvf1v3sTYq2jQ6mGmbcUpps1U=.c3c8b06c-8bed-4df6-881a-b828a0b9fef4@github.com>
References: <gZaz3XGM9kRN3xyW0ffvf1v3sTYq2jQ6mGmbcUpps1U=.c3c8b06c-8bed-4df6-881a-b828a0b9fef4@github.com>
Message-ID: <70TGUOPn_qT2w1c7iuB-MTf5AZZw_kls0UTqDaE3ULg=.9a6cebc0-8084-44bc-83d0-1b94562f047d@github.com>

> Please review this PR to clarify javadoc help output. The net effect of this change can be seen when comparing the relevant excerpts from before and after output.
> 
> Before:
> 
>     ...
>     --snippet-path <path>
>                   The path for external snippets
>     -sourcetab <tab length>
>                   Specify the number of spaces each tab takes up in the source
>     -splitindex   Split index into one file per letter
>     -tag <name>:<locations>:<header>
>                   Specify single argument custom tags
>     -taglet       The fully qualified name of Taglet to register
>     -tagletpath   The path to Taglets
>     ...
> 
> 
> After:
> 
>     ...
>     --snippet-path <path>
>                   The path to external snippets
>     -sourcetab <tab length>
>                   Specify the number of spaces each tab takes up in the source
>     -splitindex   Split index into one file per letter
>     -tag <name>:<locations>:<header>
>                   Specify single argument custom tags
>     -taglet       The fully qualified name of taglet to register
>     -tagletpath <path>
>                   The path to custom taglets
>     ...
> 
> 
> I'm not a grammarian, but:
> 
>   * "To" seems more appropriate than "for" in this context.
>   * There's no reason to use title-cased "Taglet(s)". At least there's no more reason for this than there is for "Doclet(s)", which is consistently spelled as "doclet(s)" (except for where it starts a sentence).

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 three additional commits since the last revision:

 - Merge branch 'openjdk:master' into 8273001
 - Rephrase taglet.description as per feedback
   
   Also indents the value for doclet.usage.tagletpath.parameters.
 - Initial commit

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/6745/files
  - new: https://git.openjdk.java.net/jdk/pull/6745/files/8465fd3d..a031dee1

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=6745&range=02
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=6745&range=01-02

  Stats: 40060 lines in 1122 files changed: 28957 ins; 6210 del; 4893 mod
  Patch: https://git.openjdk.java.net/jdk/pull/6745.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/6745/head:pull/6745

PR: https://git.openjdk.java.net/jdk/pull/6745

From jwilhelm at openjdk.java.net  Mon Jan 10 17:10:40 2022
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Mon, 10 Jan 2022 17:10:40 GMT
Subject: Integrated: Merge jdk18
Message-ID: <5hMMnbP2laUfEjb0svduDuzGgdUJckDDcCxaj-7QZg0=.1fd54c99-b81e-41e1-b3d7-bbdbedf161c9@github.com>

Forwardport JDK 18 -> JDK 19

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

Commit messages:
 - Merge
 - 8274679: Remove unnecessary conversion to String in security code in java.base
 - 8142362: Lots of code duplication in Copy class
 - 8218857: Confusing overloads for os::open
 - 8183227: read/write APIs in class os shall return ssize_t
 - 8279300: [arm32] SIGILL when running GetObjectSizeIntrinsicsTest
 - 8278329: some TraceDeoptimization code not included in PRODUCT build
 - 8279523: Parallel: Remove unnecessary PSScavenge::_to_space_top_before_gc
 - 8279522: Serial: Remove unused Generation::clear_remembered_set
 - 8279528: Unused TypeEnter.diag after JDK-8205187
 - ... and 163 more: https://git.openjdk.java.net/jdk/compare/40df5df9...6ff1c607

The merge commit only contains trivial merges, so no merge-specific webrevs have been generated.

Changes: https://git.openjdk.java.net/jdk/pull/7017/files
  Stats: 27994 lines in 750 files changed: 20678 ins; 5315 del; 2001 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7017.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7017/head:pull/7017

PR: https://git.openjdk.java.net/jdk/pull/7017

From jwilhelm at openjdk.java.net  Mon Jan 10 17:10:41 2022
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Mon, 10 Jan 2022 17:10:41 GMT
Subject: Integrated: Merge jdk18
In-Reply-To: <5hMMnbP2laUfEjb0svduDuzGgdUJckDDcCxaj-7QZg0=.1fd54c99-b81e-41e1-b3d7-bbdbedf161c9@github.com>
References: <5hMMnbP2laUfEjb0svduDuzGgdUJckDDcCxaj-7QZg0=.1fd54c99-b81e-41e1-b3d7-bbdbedf161c9@github.com>
Message-ID: <LWy6sTkBpk83budJQIqgEjCdEgq62d3JuxhZCubMyR0=.49c56cd4-a4b8-49f8-9bf0-00ebb2c874cf@github.com>

On Mon, 10 Jan 2022 17:00:05 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Forwardport JDK 18 -> JDK 19

This pull request has now been integrated.

Changeset: d9b1bb58
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/d9b1bb58600c03cee43387864d1530d4dd5f1422
Stats:     615 lines in 24 files changed: 478 ins; 77 del; 60 mod

Merge

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

PR: https://git.openjdk.java.net/jdk/pull/7017

From prappo at openjdk.java.net  Tue Jan 11 12:18:23 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 11 Jan 2022 12:18:23 GMT
Subject: [jdk18] RFR: 8206181: ExceptionInInitializerError: improve
 handling of exceptions in user-provided taglets
In-Reply-To: <H9N4b7ATJ8waJa0T_9p4iYNdOluSFukmzIKvxLZmNsU=.42ce9e1a-4811-4dd5-92f9-f8d2107660e6@github.com>
References: <tG4bYlmEFC4Eoyd3TSNlGQZZzkgl5-ax2Sheegj1nmo=.fb618956-88c1-4907-bf62-6b4ebc268ae2@github.com>
 <H9N4b7ATJ8waJa0T_9p4iYNdOluSFukmzIKvxLZmNsU=.42ce9e1a-4811-4dd5-92f9-f8d2107660e6@github.com>
Message-ID: <xLnBwT_EuM087pJF9D7T4s-g9nIAyhEJ32m-PSGYq2E=.5209bbb1-7e37-4c4e-8810-946c2abd731c@github.com>

On Fri, 17 Dec 2021 18:08:13 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please file a followup bug

Done: https://bugs.openjdk.java.net/browse/JDK-8279843

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

PR: https://git.openjdk.java.net/jdk18/pull/44

From prappo at openjdk.java.net  Tue Jan 11 14:32:40 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 11 Jan 2022 14:32:40 GMT
Subject: [jdk18] Integrated: 8206181: ExceptionInInitializerError: improve
 handling of exceptions in user-provided taglets
In-Reply-To: <tG4bYlmEFC4Eoyd3TSNlGQZZzkgl5-ax2Sheegj1nmo=.fb618956-88c1-4907-bf62-6b4ebc268ae2@github.com>
References: <tG4bYlmEFC4Eoyd3TSNlGQZZzkgl5-ax2Sheegj1nmo=.fb618956-88c1-4907-bf62-6b4ebc268ae2@github.com>
Message-ID: <UXymWjbiQ7mrBSqIzjHkCw6MOQ0Pbsu_ej5QseP9K3A=.23969caa-b681-4049-b26c-dedaff0a0d1f@github.com>

On Fri, 17 Dec 2021 17:51:17 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Using a custom taglet may result in exceptions, not all of which are javadoc bugs. Some of these exceptions are taglet bugs.
> 
> It was noticed that an exception in a static initializer of a custom taglet looks like a javadoc bug, which it is not. The fix was to trivially catch java.lang.ExceptionInInitializerError and translate it into an error like it is already done for some other exceptions.
> 
> While working on this fix, I noticed that there were no tests that cover various exceptions that could arise while registering a taglet:
> 
>   * ClassNotFoundException
>   * NoSuchMethodException
>   * InstantiationException
>   * InvocationTargetException
> 
> I added a test to cover all of those as well as ExceptionInInitializerError and ClassCastException, which I proactively handled similarly to ExceptionInInitializerError.
> 
> I note that a typical taglet-registration error message is quite poor and should be improved in the future. For example, it is unclear that the method that javadoc cannot find is the nullary (i.e. parameterless or no-arg) MyTaglet constructor:
> 
>     Error - Exception java.lang.NoSuchMethodException thrown while trying to register Taglet MyTaglet...

This pull request has now been integrated.

Changeset: 5aecb372
Author:    Pavel Rappo <prappo at openjdk.org>
URL:       https://git.openjdk.java.net/jdk18/commit/5aecb37211c2dec475c56dcc354b6bb4f7e3585e
Stats:     442 lines in 8 files changed: 430 ins; 11 del; 1 mod

8206181: ExceptionInInitializerError: improve handling of exceptions in user-provided taglets

Reviewed-by: jjg

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

PR: https://git.openjdk.java.net/jdk18/pull/44

From nlisker at gmail.com  Sun Jan  2 23:48:53 2022
From: nlisker at gmail.com (Nir Lisker)
Date: Mon, 3 Jan 2022 01:48:53 +0200
Subject: Automatic method declaration for functional interfaces
Message-ID: <CA+0ynh8WyXJP20fpygsDQGoEFFLWZKa=LUPborYWRQekwW4FZw@mail.gmail.com>

Hi,

Many @FunctionalInterface interfaces declare explicitly what their
functional method is, For example, the java.util.function interfaces. I was
wondering if the docs pointing out which is the functional method
automatically would be of any use.

If so, the question becomes what is the best way. Some ideas:
1. An auto-generated comment on the bottom of the interface doc like
Consumer<T> does?
2. Putting it next to the @FunctionalInterface in the declaration on top
(though it might be confusing).
3. Some highlight to the method in the method summary table.

Happy new year,
Nir
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20220103/f77ecf01/attachment.htm>

From jonathan.gibbons at oracle.com  Wed Jan 12 01:13:16 2022
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 11 Jan 2022 17:13:16 -0800
Subject: Automatic method declaration for functional interfaces
In-Reply-To: <CA+0ynh8WyXJP20fpygsDQGoEFFLWZKa=LUPborYWRQekwW4FZw@mail.gmail.com>
References: <CA+0ynh8WyXJP20fpygsDQGoEFFLWZKa=LUPborYWRQekwW4FZw@mail.gmail.com>
Message-ID: <730ec2b5-1619-5aee-44d1-6e7624b5eca5@oracle.com>

Although maybe not overtly obvious, the `Abstract Methods` tab in the 
method summary table gives you what you are looking for, and is close to 
your option #3.

-- Jon

On 1/2/22 3:48 PM, Nir Lisker wrote:
> Hi,
>
> Many @FunctionalInterface interfaces declare explicitly what their 
> functional method is, For example, the java.util.function interfaces. 
> I was wondering if the docs pointing out which is the functional 
> method automatically would be of any use.
>
> If so, the question becomes what is the best way. Some ideas:
> 1. An auto-generated comment on the bottom of the interface doc like 
> Consumer<T> does?
> 2. Putting it next to the?@FunctionalInterface in the declaration on 
> top (though it might be confusing).
> 3. Some highlight to the method in the method summary table.
>
> Happy new year,
> Nir

From hannesw at openjdk.java.net  Wed Jan 12 15:14:44 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Jan 2022 15:14:44 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature
Message-ID: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>

Please review a change in how documentation from `@param` tags is generated. 

The old code generates parameter documentation for each `@param` in the order in which the tags occur in the comment, then adds documentation from inherited `@param` tags for undocumented parameters. 

The new code always generates documentation in the order in which actual parameters are declared in the code, using local or inherited `@param` tags as appropriate. Any `@param` tags that do not have a matching parameter are added afterwards.

Note that `@param` is not just used for parameters of executable members but also type parameters and record components. The second commit of this PR fixes a `ClassCastException` for these uses that was caused by the first commit and adds a few tests for it.

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

Commit messages:
 - JDK-8234682: Fix and add tests for generic type parameters and record components
 - JDK-8234682: The order of @param in the generated docs should match the method signature

Changes: https://git.openjdk.java.net/jdk/pull/7046/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=7046&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8234682
  Stats: 173 lines in 4 files changed: 94 ins; 34 del; 45 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7046.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7046/head:pull/7046

PR: https://git.openjdk.java.net/jdk/pull/7046

From rriggs at openjdk.java.net  Wed Jan 12 15:35:23 2022
From: rriggs at openjdk.java.net (Roger Riggs)
Date: Wed, 12 Jan 2022 15:35:23 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature
In-Reply-To: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
Message-ID: <6BoVNbg1Y7g4It9VM1-XOV3YlFSrAmi7JsSD75HEG8M=.97d34acd-d3f8-43c1-8ff3-d1b7dd88f764@github.com>

On Wed, 12 Jan 2022 08:40:08 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change in how documentation from `@param` tags is generated. 
> 
> The old code generates parameter documentation for each `@param` in the order in which the tags occur in the comment, then adds documentation from inherited `@param` tags for undocumented parameters. 
> 
> The new code always generates documentation in the order in which actual parameters are declared in the code, using local or inherited `@param` tags as appropriate. Any `@param` tags that do not have a matching parameter are added afterwards.
> 
> Note that `@param` is not just used for parameters of executable members but also type parameters and record components. The second commit of this PR fixes a `ClassCastException` for these uses that was caused by the first commit and adds a few tests for it.

It would be helpful if the order of the @param tags in the source was matched the declaration.
Can a warning be generated if the @param tags are out of order?

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

PR: https://git.openjdk.java.net/jdk/pull/7046

From hannesw at openjdk.java.net  Wed Jan 12 17:09:30 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Jan 2022 17:09:30 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature
In-Reply-To: <6BoVNbg1Y7g4It9VM1-XOV3YlFSrAmi7JsSD75HEG8M=.97d34acd-d3f8-43c1-8ff3-d1b7dd88f764@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
 <6BoVNbg1Y7g4It9VM1-XOV3YlFSrAmi7JsSD75HEG8M=.97d34acd-d3f8-43c1-8ff3-d1b7dd88f764@github.com>
Message-ID: <zeulqwfukek__RsyjAgqmySkfCqAdP4yT2Tq_9I_xlY=.b7343c86-1320-4839-b604-dcb6a62011e0@github.com>

On Wed, 12 Jan 2022 15:32:40 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

> It would be helpful if the order of the @param tags in the source was matched the declaration. Can a warning be generated if the @param tags are out of order?

I think it is worth considering. Does it have to be a warning or would an informational notice also do? For something to be reported as warning it should have a certain gravity, I'm not sure `@param` order qualifies for it.

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

PR: https://git.openjdk.java.net/jdk/pull/7046

From jjg at openjdk.java.net  Wed Jan 12 17:09:30 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 12 Jan 2022 17:09:30 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature
In-Reply-To: <zeulqwfukek__RsyjAgqmySkfCqAdP4yT2Tq_9I_xlY=.b7343c86-1320-4839-b604-dcb6a62011e0@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
 <6BoVNbg1Y7g4It9VM1-XOV3YlFSrAmi7JsSD75HEG8M=.97d34acd-d3f8-43c1-8ff3-d1b7dd88f764@github.com>
 <zeulqwfukek__RsyjAgqmySkfCqAdP4yT2Tq_9I_xlY=.b7343c86-1320-4839-b604-dcb6a62011e0@github.com>
Message-ID: <jHYViY_EC5SrB-hIZz9BmFTOKsxvGt8rlcIe3MOVv1I=.3da10a4c-ac5f-4a85-bf0d-00c5f73bd904@github.com>

On Wed, 12 Jan 2022 17:03:32 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> It would be helpful if the order of the @param tags in the source was matched the declaration.
> Can a warning be generated if the @param tags are out of order?

That seems like a good suggestion, for a different PR.  The obvious place to implement such a warning would be in DocLint.

> > It would be helpful if the order of the @param tags in the source was matched the declaration. Can a warning be generated if the @param tags are out of order?
> 
> I think it is worth considering. Does it have to be a warning or would an informational notice also do? For something to be reported as warning it should have a certain gravity, I'm not sure `@param` order qualifies for it.

That's why it should be an opt-in lint-style warning. It's every bit as useful as other lint warnings, like javac's "extra semi-colon" and other minor grumbles.

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

PR: https://git.openjdk.java.net/jdk/pull/7046

From hannesw at openjdk.java.net  Wed Jan 12 17:16:27 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Jan 2022 17:16:27 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature
In-Reply-To: <jHYViY_EC5SrB-hIZz9BmFTOKsxvGt8rlcIe3MOVv1I=.3da10a4c-ac5f-4a85-bf0d-00c5f73bd904@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
 <6BoVNbg1Y7g4It9VM1-XOV3YlFSrAmi7JsSD75HEG8M=.97d34acd-d3f8-43c1-8ff3-d1b7dd88f764@github.com>
 <zeulqwfukek__RsyjAgqmySkfCqAdP4yT2Tq_9I_xlY=.b7343c86-1320-4839-b604-dcb6a62011e0@github.com>
 <jHYViY_EC5SrB-hIZz9BmFTOKsxvGt8rlcIe3MOVv1I=.3da10a4c-ac5f-4a85-bf0d-00c5f73bd904@github.com>
Message-ID: <722giW0FmRwVKDc5cDRp-uOw-ws_PHPAc4U2H5QSmTk=.4fabbbfc-ac88-4820-be59-172128e5b6ad@github.com>

On Wed, 12 Jan 2022 17:04:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> > It would be helpful if the order of the @param tags in the source was matched the declaration.
> > Can a warning be generated if the @param tags are out of order?
> 
> That seems like a good suggestion, for a different PR. The obvious place to implement such a warning would be in DocLint.

I filed an issue: https://bugs.openjdk.java.net/browse/JDK-8279931

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

PR: https://git.openjdk.java.net/jdk/pull/7046

From jwilhelm at openjdk.java.net  Wed Jan 12 23:39:04 2022
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Wed, 12 Jan 2022 23:39:04 GMT
Subject: RFR: Merge jdk18
Message-ID: <rxWfkFNeeY9ejjP258YMgu6JRgFgWkflxz1uVs4IZ7A=.a9bfc8f7-5524-4a53-ae14-fd22a3f5fde8@github.com>

Forwardport JDK 18 -> JDK 19

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

Commit messages:
 - Merge remote-tracking branch 'jdk18/master' into Merge_jdk18
 - 8206181: ExceptionInInitializerError: improve handling of exceptions in user-provided taglets
 - 8279695: [TESTBUG] modify compiler/loopopts/TestSkeletonPredicateNegation.java to run on C1 also
 - 8279356: Method linking fails with guarantee(mh->adapter() != NULL) failed: Adapter blob must already exist!
 - 8278489: Preserve result in native wrapper with +UseHeavyMonitors
 - 8278267: ARM32: several vector test failures for ASHR

The webrevs contain the adjustments done while merging with regards to each parent branch:
 - master: https://webrevs.openjdk.java.net/?repo=jdk&pr=7057&range=00.0
 - jdk18: https://webrevs.openjdk.java.net/?repo=jdk&pr=7057&range=00.1

Changes: https://git.openjdk.java.net/jdk/pull/7057/files
  Stats: 907 lines in 16 files changed: 811 ins; 21 del; 75 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7057.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7057/head:pull/7057

PR: https://git.openjdk.java.net/jdk/pull/7057

From jwilhelm at openjdk.java.net  Thu Jan 13 01:10:29 2022
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 13 Jan 2022 01:10:29 GMT
Subject: Integrated: Merge jdk18
In-Reply-To: <rxWfkFNeeY9ejjP258YMgu6JRgFgWkflxz1uVs4IZ7A=.a9bfc8f7-5524-4a53-ae14-fd22a3f5fde8@github.com>
References: <rxWfkFNeeY9ejjP258YMgu6JRgFgWkflxz1uVs4IZ7A=.a9bfc8f7-5524-4a53-ae14-fd22a3f5fde8@github.com>
Message-ID: <38zJOHU9dDOsz0As8TzSdMeOgHo2owiO-kk59_McW-s=.af44c757-3e59-4b39-bb76-81f82f63eb97@github.com>

On Wed, 12 Jan 2022 23:32:00 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Forwardport JDK 18 -> JDK 19

This pull request has now been integrated.

Changeset: 67e3d51d
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/67e3d51d68e7319bd6d5b01233b664e6ee6b17ec
Stats:     907 lines in 16 files changed: 811 ins; 21 del; 75 mod

Merge

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

PR: https://git.openjdk.java.net/jdk/pull/7057

From prappo at openjdk.java.net  Thu Jan 13 10:35:39 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Thu, 13 Jan 2022 10:35:39 GMT
Subject: RFR: 8279918: Fix various doc typos
Message-ID: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>

- Most of the typos are of a trivial kind: missing whitespace.
- If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
- As I understand it,   in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
- &#39; is an apostrophe, which does not require to be encoded.

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

Commit messages:
 - Initial commit

Changes: https://git.openjdk.java.net/jdk/pull/7063/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=7063&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8279918
  Stats: 85 lines in 34 files changed: 0 ins; 0 del; 85 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7063.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7063/head:pull/7063

PR: https://git.openjdk.java.net/jdk/pull/7063

From kevinw at openjdk.java.net  Thu Jan 13 10:49:28 2022
From: kevinw at openjdk.java.net (Kevin Walls)
Date: Thu, 13 Jan 2022 10:49:28 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
Message-ID: <c7q1emDrYxQ4prMys2ORMJdDTpjyFAeNZLUwAv_mvLo=.b551f39b-e81b-448d-a53a-db93036debff@github.com>

On Thu, 13 Jan 2022 10:30:07 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> - Most of the typos are of a trivial kind: missing whitespace.
> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
> - As I understand it,   in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
> - &#39; is an apostrophe, which does not require to be encoded.

src/java.base/share/classes/sun/text/RuleBasedBreakIterator.java line 73:

> 71:  * will be transparent to the BreakIterator.&nbsp; A sequence of characters will break the
> 72:  * same way it would if any ignore characters it contains are taken out.&nbsp; Break
> 73:  * positions never occur before ignore characters.</p>

"before ignored characters"

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From prappo at openjdk.java.net  Thu Jan 13 11:04:28 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Thu, 13 Jan 2022 11:04:28 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <c7q1emDrYxQ4prMys2ORMJdDTpjyFAeNZLUwAv_mvLo=.b551f39b-e81b-448d-a53a-db93036debff@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <c7q1emDrYxQ4prMys2ORMJdDTpjyFAeNZLUwAv_mvLo=.b551f39b-e81b-448d-a53a-db93036debff@github.com>
Message-ID: <4f89A8T4GDZajnNMg-tT5qWaN5OCrH04Vwh9HZ6uTvg=.f2af94ec-43b4-4521-8158-aef4137b400b@github.com>

On Thu, 13 Jan 2022 10:46:11 GMT, Kevin Walls <kevinw at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it,   in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - &#39; is an apostrophe, which does not require to be encoded.
>
> src/java.base/share/classes/sun/text/RuleBasedBreakIterator.java line 73:
> 
>> 71:  * will be transparent to the BreakIterator.&nbsp; A sequence of characters will break the
>> 72:  * same way it would if any ignore characters it contains are taken out.&nbsp; Break
>> 73:  * positions never occur before ignore characters.</p>
> 
> "before ignored characters"

I believe it's the name of a concept, so I will leave it as is:

> There is one special substitution.  If the description defines a substitution called "<ignore>", the expression must be a [] expression, and the expression defines a set of characters (the "ignore characters") that will be transparent to the BreakIterator.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From kevinw at openjdk.java.net  Thu Jan 13 11:04:28 2022
From: kevinw at openjdk.java.net (Kevin Walls)
Date: Thu, 13 Jan 2022 11:04:28 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
Message-ID: <2bsQg-3igmY6_fAT_OD9jIuJ7ziQBgvB7oF1CiZN_Zo=.51e0dd63-d489-4996-8fb9-b2e8c385cbb8@github.com>

On Thu, 13 Jan 2022 10:30:07 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> - Most of the typos are of a trivial kind: missing whitespace.
> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
> - As I understand it,   in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
> - &#39; is an apostrophe, which does not require to be encoded.

src/java.sql/share/classes/java/sql/BatchUpdateException.java line 58:

> 56:  * A JDBC driver implementation should use
> 57:  * the constructor {@code BatchUpdateException(String reason, String SQLState,
> 58:  * int vendorCode, long []updateCounts, Throwable cause) } instead of

While we are here, is it more normal to say "long[] updateCounts", not separating the [] from the type.
Similarly at line 81, 118, 151, 247, 277, 318, 354.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From prappo at openjdk.java.net  Thu Jan 13 11:07:28 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Thu, 13 Jan 2022 11:07:28 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <2bsQg-3igmY6_fAT_OD9jIuJ7ziQBgvB7oF1CiZN_Zo=.51e0dd63-d489-4996-8fb9-b2e8c385cbb8@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <2bsQg-3igmY6_fAT_OD9jIuJ7ziQBgvB7oF1CiZN_Zo=.51e0dd63-d489-4996-8fb9-b2e8c385cbb8@github.com>
Message-ID: <VCF8_RsgzIZEi2Hls0T3tX08pg3RfYbTtQKrU0WsO6g=.e49acac0-a7d5-4a35-9a27-4bc1e8b39d1a@github.com>

On Thu, 13 Jan 2022 11:00:55 GMT, Kevin Walls <kevinw at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it,   in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - &#39; is an apostrophe, which does not require to be encoded.
>
> src/java.sql/share/classes/java/sql/BatchUpdateException.java line 58:
> 
>> 56:  * A JDBC driver implementation should use
>> 57:  * the constructor {@code BatchUpdateException(String reason, String SQLState,
>> 58:  * int vendorCode, long []updateCounts, Throwable cause) } instead of
> 
> While we are here, is it more normal to say "long[] updateCounts", not separating the [] from the type.
> Similarly at line 81, 118, 151, 247, 277, 318, 354.

I thought about it too, but then noticed how the position of `[]` mimics that of the respective method signatures in code.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From kevinw at openjdk.java.net  Thu Jan 13 11:21:27 2022
From: kevinw at openjdk.java.net (Kevin Walls)
Date: Thu, 13 Jan 2022 11:21:27 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
Message-ID: <zVeD6RgS6UVZkMAhRSuyKSbTi7PESs6zNDZ6lYXRnW4=.fbc4d00e-2dd4-43e5-8115-7e308b725d17@github.com>

On Thu, 13 Jan 2022 10:30:07 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> - Most of the typos are of a trivial kind: missing whitespace.
> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
> - `&#39;` is an apostrophe, which does not require to be encoded.

src/java.sql/share/classes/java/sql/Statement.java line 784:

> 782:      * statement returns a {@code ResultSet} object, the second argument
> 783:      * supplied to this method is not an
> 784:      * {@code int} array whose elements are valid column indexes, the method is called on a

Should it be "or the method is called on...", i.e. add the "or", otherwise it's a list of problems but we don't know if they are all required, or are alternatives.  It probably does not mean that all these have to be true to throw the exception, but it doesn't say that.  We are nitpicking of course.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From kevinw at openjdk.java.net  Thu Jan 13 11:33:27 2022
From: kevinw at openjdk.java.net (Kevin Walls)
Date: Thu, 13 Jan 2022 11:33:27 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
Message-ID: <pjHWjVnBclRVnojpj7BEIAYuSdlwTLMEkAYhI3iPovw=.6e4cd7fe-f085-4572-856d-44d6ecace75c@github.com>

On Thu, 13 Jan 2022 10:30:07 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> - Most of the typos are of a trivial kind: missing whitespace.
> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
> - `&#39;` is an apostrophe, which does not require to be encoded.

Marked as reviewed by kevinw (Committer).

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From kevinw at openjdk.java.net  Thu Jan 13 11:33:27 2022
From: kevinw at openjdk.java.net (Kevin Walls)
Date: Thu, 13 Jan 2022 11:33:27 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <VCF8_RsgzIZEi2Hls0T3tX08pg3RfYbTtQKrU0WsO6g=.e49acac0-a7d5-4a35-9a27-4bc1e8b39d1a@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <2bsQg-3igmY6_fAT_OD9jIuJ7ziQBgvB7oF1CiZN_Zo=.51e0dd63-d489-4996-8fb9-b2e8c385cbb8@github.com>
 <VCF8_RsgzIZEi2Hls0T3tX08pg3RfYbTtQKrU0WsO6g=.e49acac0-a7d5-4a35-9a27-4bc1e8b39d1a@github.com>
Message-ID: <KEQBfIPtqMR39DeUDsPXb3Tqaow0Q487Gne-nJSp5hI=.bf96f113-80dc-48ba-a280-6cd13bb979da@github.com>

On Thu, 13 Jan 2022 11:04:43 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/java.sql/share/classes/java/sql/BatchUpdateException.java line 58:
>> 
>>> 56:  * A JDBC driver implementation should use
>>> 57:  * the constructor {@code BatchUpdateException(String reason, String SQLState,
>>> 58:  * int vendorCode, long []updateCounts, Throwable cause) } instead of
>> 
>> While we are here, is it more normal to say "long[] updateCounts", not separating the [] from the type.
>> Similarly at line 81, 118, 151, 247, 277, 318, 354.
>
> I thought about it too, but then noticed how the position of `[]` mimics that of the respective method signatures in code.

OK, so lines 264,  295, 329, 364, 431 are arguably wrong as well?  Separating the [] completely looks quite rare.
I'll leave it up to you. 8-)

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From prappo at openjdk.java.net  Thu Jan 13 11:33:28 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Thu, 13 Jan 2022 11:33:28 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <zVeD6RgS6UVZkMAhRSuyKSbTi7PESs6zNDZ6lYXRnW4=.fbc4d00e-2dd4-43e5-8115-7e308b725d17@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <zVeD6RgS6UVZkMAhRSuyKSbTi7PESs6zNDZ6lYXRnW4=.fbc4d00e-2dd4-43e5-8115-7e308b725d17@github.com>
Message-ID: <90v_XM2RzHUik7EfePw8m-79pscrcKUAb10T6FMJHYA=.3577ceee-012b-45f7-af57-64f0a8172dfa@github.com>

On Thu, 13 Jan 2022 11:18:42 GMT, Kevin Walls <kevinw at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - `&#39;` is an apostrophe, which does not require to be encoded.
>
> src/java.sql/share/classes/java/sql/Statement.java line 784:
> 
>> 782:      * statement returns a {@code ResultSet} object, the second argument
>> 783:      * supplied to this method is not an
>> 784:      * {@code int} array whose elements are valid column indexes, the method is called on a
> 
> Should it be "or the method is called on...", i.e. add the "or", otherwise it's a list of problems but we don't know if they are all required, or are alternatives.  It probably does not mean that all these have to be true to throw the exception, but it doesn't say that.  We are nitpicking of course.

You are right in that this `@throws` description reads a bit weird in its current form. That said, I wouldn't touch it in this PR for two reasons. Firstly, this wording seems to be consistent with other locations in that file. Secondly, this is a spec territory.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From lancea at openjdk.java.net  Thu Jan 13 11:46:27 2022
From: lancea at openjdk.java.net (Lance Andersen)
Date: Thu, 13 Jan 2022 11:46:27 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
Message-ID: <N93S_4q_0Hb8J6Wqm_8Cur4pRu-cKsGRDYtkT1rj-Qk=.42f89bd3-876e-4017-af48-65fcadfcf62f@github.com>

On Thu, 13 Jan 2022 10:30:07 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> - Most of the typos are of a trivial kind: missing whitespace.
> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
> - `&#39;` is an apostrophe, which does not require to be encoded.

Overall this looks good, thanks for the clean up :-)

A few comments below

src/java.base/share/classes/java/io/DataInput.java line 496:

> 494:      * ceases. If the character {@code '\r'}
> 495:      * is encountered, it is discarded and, if
> 496:      * the following byte converts to the

The above is a bit confusing as it reads(same in ImageInputStream.java).  I think that that can be looked at later.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From lancea at openjdk.java.net  Thu Jan 13 11:46:27 2022
From: lancea at openjdk.java.net (Lance Andersen)
Date: Thu, 13 Jan 2022 11:46:27 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <KEQBfIPtqMR39DeUDsPXb3Tqaow0Q487Gne-nJSp5hI=.bf96f113-80dc-48ba-a280-6cd13bb979da@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <2bsQg-3igmY6_fAT_OD9jIuJ7ziQBgvB7oF1CiZN_Zo=.51e0dd63-d489-4996-8fb9-b2e8c385cbb8@github.com>
 <VCF8_RsgzIZEi2Hls0T3tX08pg3RfYbTtQKrU0WsO6g=.e49acac0-a7d5-4a35-9a27-4bc1e8b39d1a@github.com>
 <KEQBfIPtqMR39DeUDsPXb3Tqaow0Q487Gne-nJSp5hI=.bf96f113-80dc-48ba-a280-6cd13bb979da@github.com>
Message-ID: <zYl0PN2cKub3zwtGJr9wKdC7oq0BrHa6v2TG2esnlZM=.9936d444-caae-47af-916a-d2847c64bcd5@github.com>

On Thu, 13 Jan 2022 11:28:34 GMT, Kevin Walls <kevinw at openjdk.org> wrote:

>> I thought about it too, but then noticed how the position of `[]` mimics that of the respective method signatures in code.
>
> OK, so lines 264,  295, 329, 364, 431 are arguably wrong as well?  Separating the [] completely looks quite rare.
> I'll leave it up to you. 8-)

I think that can be a follow on clean up.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From lancea at openjdk.java.net  Thu Jan 13 11:46:28 2022
From: lancea at openjdk.java.net (Lance Andersen)
Date: Thu, 13 Jan 2022 11:46:28 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <90v_XM2RzHUik7EfePw8m-79pscrcKUAb10T6FMJHYA=.3577ceee-012b-45f7-af57-64f0a8172dfa@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <zVeD6RgS6UVZkMAhRSuyKSbTi7PESs6zNDZ6lYXRnW4=.fbc4d00e-2dd4-43e5-8115-7e308b725d17@github.com>
 <90v_XM2RzHUik7EfePw8m-79pscrcKUAb10T6FMJHYA=.3577ceee-012b-45f7-af57-64f0a8172dfa@github.com>
Message-ID: <siJYLuQdiSxsrufNvzgVR1V3olYqps5ZA0NMBzqBmOY=.1884295a-8707-4e4b-bd7b-a54a1e0b54a2@github.com>

On Thu, 13 Jan 2022 11:29:35 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/java.sql/share/classes/java/sql/Statement.java line 784:
>> 
>>> 782:      * statement returns a {@code ResultSet} object, the second argument
>>> 783:      * supplied to this method is not an
>>> 784:      * {@code int} array whose elements are valid column indexes, the method is called on a
>> 
>> Should it be "or the method is called on...", i.e. add the "or", otherwise it's a list of problems but we don't know if they are all required, or are alternatives.  It probably does not mean that all these have to be true to throw the exception, but it doesn't say that.  We are nitpicking of course.
>
> You are right in that this `@throws` description reads a bit weird in its current form. That said, I wouldn't touch it in this PR for two reasons. Firstly, this wording seems to be consistent with other locations in that file. Secondly, this is a spec territory.

Yes an "or" is probably worthwhile to add.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From prappo at openjdk.java.net  Thu Jan 13 12:40:45 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Thu, 13 Jan 2022 12:40:45 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <N93S_4q_0Hb8J6Wqm_8Cur4pRu-cKsGRDYtkT1rj-Qk=.42f89bd3-876e-4017-af48-65fcadfcf62f@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <N93S_4q_0Hb8J6Wqm_8Cur4pRu-cKsGRDYtkT1rj-Qk=.42f89bd3-876e-4017-af48-65fcadfcf62f@github.com>
Message-ID: <KaZIJRgmte5WexU8y71mFOZ_dLKcoWf8DXvkY5ty59Y=.74f2053d-1dc4-44f0-b499-54caa6d84c7b@github.com>

On Thu, 13 Jan 2022 11:42:48 GMT, Lance Andersen <lancea at openjdk.org> wrote:

> The above is a bit confusing as it reads(same in ImageInputStream.java). I think that that can be looked at later.

Just to clarify: you are okay with removing the ` ` entity, right? As for ImageInputStream, some doc comments should probably use `@inheritDoc`. But this is a much bigger clean-up.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From mullan at openjdk.java.net  Thu Jan 13 13:45:30 2022
From: mullan at openjdk.java.net (Sean Mullan)
Date: Thu, 13 Jan 2022 13:45:30 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
Message-ID: <GoTfQ0njQABWrD7SFvPbmOPuKBIMNKsS3jJHnHMZfDY=.b11b8d73-4c8b-4eb1-8078-33dcd70b013c@github.com>

On Thu, 13 Jan 2022 10:30:07 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> - Most of the typos are of a trivial kind: missing whitespace.
> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
> - `&#39;` is an apostrophe, which does not require to be encoded.

The change in the one security class (KeyStoreLoginModule) looks fine.

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

Marked as reviewed by mullan (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7063

From prappo at openjdk.java.net  Thu Jan 13 13:51:34 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Thu, 13 Jan 2022 13:51:34 GMT
Subject: RFR: 8279918: Fix various doc typos
In-Reply-To: <siJYLuQdiSxsrufNvzgVR1V3olYqps5ZA0NMBzqBmOY=.1884295a-8707-4e4b-bd7b-a54a1e0b54a2@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <zVeD6RgS6UVZkMAhRSuyKSbTi7PESs6zNDZ6lYXRnW4=.fbc4d00e-2dd4-43e5-8115-7e308b725d17@github.com>
 <90v_XM2RzHUik7EfePw8m-79pscrcKUAb10T6FMJHYA=.3577ceee-012b-45f7-af57-64f0a8172dfa@github.com>
 <siJYLuQdiSxsrufNvzgVR1V3olYqps5ZA0NMBzqBmOY=.1884295a-8707-4e4b-bd7b-a54a1e0b54a2@github.com>
Message-ID: <9HH1T6jnf2bbBhD0h9sZZGoBWqEAoYen5Ymr52wVyDA=.7afbde78-363f-4e51-b0ad-a7e0cf2c0d6d@github.com>

On Thu, 13 Jan 2022 11:38:13 GMT, Lance Andersen <lancea at openjdk.org> wrote:

> Yes an "or" is probably worthwhile to add.

I would prefer to leave it for the follow-up cleanup if only because adding "or" here would make it inconsistent with other `@throws SQLException` descriptions in that file and perhaps elsewhere in java.sql:

* java/sql/Statement.java:59
* java/sql/Statement.java:85
* java/sql/Statement.java:346
* java/sql/Statement.java:524
* java/sql/Statement.java:745
* java/sql/Statement.java:814
* java/sql/Statement.java:860
* java/sql/Statement.java:913
* java/sql/Statement.java:962
* java/sql/Statement.java:1225
* java/sql/Statement.java:1269
* java/sql/Statement.java:1314

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From prappo at openjdk.java.net  Thu Jan 13 14:01:04 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Thu, 13 Jan 2022 14:01:04 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
Message-ID: <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>

> - Most of the typos are of a trivial kind: missing whitespace.
> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
> - `&#39;` is an apostrophe, which does not require to be encoded.

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

  Additional typos

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7063/files
  - new: https://git.openjdk.java.net/jdk/pull/7063/files/fe81eeca..b256a13f

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7063&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7063&range=00-01

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From prappo at openjdk.java.net  Thu Jan 13 15:34:22 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Thu, 13 Jan 2022 15:34:22 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature
In-Reply-To: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
Message-ID: <EwU8Qc6uayT-qHd7sxOtDY5T_W_atitjK0xUgWy1kbA=.090f6c2f-621a-4313-acd7-6831c988a712@github.com>

On Wed, 12 Jan 2022 08:40:08 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change in how documentation from `@param` tags is generated. 
> 
> The old code generates parameter documentation for each `@param` in the order in which the tags occur in the comment, then adds documentation from inherited `@param` tags for undocumented parameters. 
> 
> The new code always generates documentation in the order in which actual parameters are declared in the code, using local or inherited `@param` tags as appropriate. Any `@param` tags that do not have a matching parameter are added afterwards.
> 
> Note that `@param` is not just used for parameters of executable members but also type parameters and record components. The second commit of this PR fixes a `ClassCastException` for these uses that was caused by the first commit and adds a few tests for it.

Out of curiosity, how much of a churn does this PR introduce into the generated JDK API documentation? In any case, we should check it, to make sure that nothing surprising comes up.

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

PR: https://git.openjdk.java.net/jdk/pull/7046

From hannesw at openjdk.java.net  Thu Jan 13 15:52:32 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 13 Jan 2022 15:52:32 GMT
Subject: RFR: 8268978: Document the javadoc software stack
In-Reply-To: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
References: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
Message-ID: <uV_6sqQA4hETtulnIpg6azuEJVluOPBHrxUtOgJCdgs=.37b93175-9761-43e2-8a72-545e49cc3449@github.com>

On Wed, 22 Dec 2021 00:48:08 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a `noreg-doc` update to document the javadoc software stack, in the top-level `jdk.javadoc.internal` package.
> 
> The intent is to provide a broad overview.   We can add more specific details, but in general, additional details would probably be better in the `package-info` files for the constituent packages.

A general question about this: Where and how will this documentation mostly be consumed? The `jdk.javadoc.internal` package is not included in standard JDK documentation, so is it likely that this documentation will be mainly consumed within an editor/IDE? 

My feeling is that maybe a less markup-heavy and more text centric form would be easier to consume in that context. For instance, using appropriate HTML headings and paragraphs instead of the deeply nested `<dl>` structure might provide more of a continuous text experience, while still maintaining the hierarchical information. Of course this is a matter of taste, different people have different preferences.

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

PR: https://git.openjdk.java.net/jdk/pull/6914

From hannesw at openjdk.java.net  Thu Jan 13 16:26:27 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 13 Jan 2022 16:26:27 GMT
Subject: RFR: JDK-8272853: improve `JavadocTester.runTests`
In-Reply-To: <yKDakYiCFt7M34gQ_YB1eYUrTrgjolfnrJQ6nllG_JA=.104a78a1-255c-4eb7-a8d5-7a22f5e4227e@github.com>
References: <yKDakYiCFt7M34gQ_YB1eYUrTrgjolfnrJQ6nllG_JA=.104a78a1-255c-4eb7-a8d5-7a22f5e4227e@github.com>
Message-ID: <_-MSJFWLxBd7Y2zf73tGnWPSR42UrizWAK57FMfVD8I=.82449482-63c2-4fa6-a217-4533397bb928@github.com>

On Thu, 6 Jan 2022 20:31:42 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a medium simple test-only fix to improve the `JavadocTester` `runTests` methods.
> 
> Currently, there are two overloads: one to invoke no-args test methods, and another to invoke test methods with args, such as a method-specific `Path`.  This latter one is slightly inconvenient to use, since it requires the boilerplate use of a function to create the arguments.
> 
> The first overload is updated in a backwards compatible way, to examine the parameters of methods annotated with `@Test`, and to recognize common patterns: namely no-args methods and `(Path)` methods, without the need for any additional function.  The second overload is retained by backwards compatibility, until if and when we decide it is no longer required.
> 
> In addition, two new overloads are added, similar to the first two, but with the addition of an extra parameter to decide which methods should be invoked. This is primarily a debugging aid.  Using these overloads, it is easy to specify, on the command line used to run the test, the methods to be executed.
> 
> A new test is added to test the new functionality.

Making the boilerplate to call test methods with a path object obsolete is a very welcome enhancement. Can and should we update existing tests that use the explicit method -> path function to the new form?

You say that the new forms that take a list of method names could be used by passing the method names as command line arguments. That functionality is not included in this PR as far as I can see. Is that planned for a later time?

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

PR: https://git.openjdk.java.net/jdk/pull/6983

From sspitsyn at openjdk.java.net  Thu Jan 13 16:53:27 2022
From: sspitsyn at openjdk.java.net (Serguei Spitsyn)
Date: Thu, 13 Jan 2022 16:53:27 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
Message-ID: <Ibur44h4Co3CBFiirsNKloOUVl2G0KUC1pCEbFz5DII=.80447fd1-effd-4cba-9d5c-572ebcf12e72@github.com>

On Thu, 13 Jan 2022 14:01:04 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - `&#39;` is an apostrophe, which does not require to be encoded.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Additional typos

Hi Pavel,
Looks good.
Thanks,
Serguei

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

Marked as reviewed by sspitsyn (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7063

From lancea at openjdk.java.net  Thu Jan 13 17:18:23 2022
From: lancea at openjdk.java.net (Lance Andersen)
Date: Thu, 13 Jan 2022 17:18:23 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <KaZIJRgmte5WexU8y71mFOZ_dLKcoWf8DXvkY5ty59Y=.74f2053d-1dc4-44f0-b499-54caa6d84c7b@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <N93S_4q_0Hb8J6Wqm_8Cur4pRu-cKsGRDYtkT1rj-Qk=.42f89bd3-876e-4017-af48-65fcadfcf62f@github.com>
 <KaZIJRgmte5WexU8y71mFOZ_dLKcoWf8DXvkY5ty59Y=.74f2053d-1dc4-44f0-b499-54caa6d84c7b@github.com>
Message-ID: <irVQg_VsXH7St95vPZp8vVD3oaWCefUdqLxDETFhN5I=.ebbbb6d8-eba8-4e17-996d-32ffb15716f3@github.com>

On Thu, 13 Jan 2022 12:37:46 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> > The above is a bit confusing as it reads(same in ImageInputStream.java). I think that that can be looked at later.
> 
> Just to clarify: you are okay with removing the ` ` entity, right? As for ImageInputStream, some doc comments should probably use `@inheritDoc`. But this is a much bigger clean-up.

Yes I am.  It just does not flow as well as it could IMHO

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From naoto at openjdk.java.net  Thu Jan 13 17:25:30 2022
From: naoto at openjdk.java.net (Naoto Sato)
Date: Thu, 13 Jan 2022 17:25:30 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
Message-ID: <CmrsmcEGepottkt6pPurYZ3cPdM7oK7v1DInHe5jqbQ=.d9dd81e5-18b2-4e2c-9881-97d586442a35@github.com>

On Thu, 13 Jan 2022 14:01:04 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - `&#39;` is an apostrophe, which does not require to be encoded.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Additional typos

Marked as reviewed by naoto (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From naoto at openjdk.java.net  Thu Jan 13 17:25:31 2022
From: naoto at openjdk.java.net (Naoto Sato)
Date: Thu, 13 Jan 2022 17:25:31 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <4f89A8T4GDZajnNMg-tT5qWaN5OCrH04Vwh9HZ6uTvg=.f2af94ec-43b4-4521-8158-aef4137b400b@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <c7q1emDrYxQ4prMys2ORMJdDTpjyFAeNZLUwAv_mvLo=.b551f39b-e81b-448d-a53a-db93036debff@github.com>
 <4f89A8T4GDZajnNMg-tT5qWaN5OCrH04Vwh9HZ6uTvg=.f2af94ec-43b4-4521-8158-aef4137b400b@github.com>
Message-ID: <4-d5YVHaRmPcyMlFYm2fxtIaRq6Z5PVooC8yd0OIbag=.cbd015b1-b2bd-43ba-b12f-8727087364b5@github.com>

On Thu, 13 Jan 2022 10:59:13 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/java.base/share/classes/sun/text/RuleBasedBreakIterator.java line 73:
>> 
>>> 71:  * will be transparent to the BreakIterator.&nbsp; A sequence of characters will break the
>>> 72:  * same way it would if any ignore characters it contains are taken out.&nbsp; Break
>>> 73:  * positions never occur before ignore characters.</p>
>> 
>> "before ignored characters"
>
> I believe it's the name of a concept, so I will leave it as is:
> 
>> There is one special substitution.  If the description defines a substitution called "<ignore>", the expression must be a [] expression, and the expression defines a set of characters (the "ignore characters") that will be transparent to the BreakIterator.

Yes, that is correct.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From lancea at openjdk.java.net  Thu Jan 13 17:25:31 2022
From: lancea at openjdk.java.net (Lance Andersen)
Date: Thu, 13 Jan 2022 17:25:31 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <9HH1T6jnf2bbBhD0h9sZZGoBWqEAoYen5Ymr52wVyDA=.7afbde78-363f-4e51-b0ad-a7e0cf2c0d6d@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <zVeD6RgS6UVZkMAhRSuyKSbTi7PESs6zNDZ6lYXRnW4=.fbc4d00e-2dd4-43e5-8115-7e308b725d17@github.com>
 <90v_XM2RzHUik7EfePw8m-79pscrcKUAb10T6FMJHYA=.3577ceee-012b-45f7-af57-64f0a8172dfa@github.com>
 <siJYLuQdiSxsrufNvzgVR1V3olYqps5ZA0NMBzqBmOY=.1884295a-8707-4e4b-bd7b-a54a1e0b54a2@github.com>
 <9HH1T6jnf2bbBhD0h9sZZGoBWqEAoYen5Ymr52wVyDA=.7afbde78-363f-4e51-b0ad-a7e0cf2c0d6d@github.com>
Message-ID: <-4rLp_8_PwigKKpD1gGONCS8QMfDkNNNP4uZU1k9u9M=.9119e3bf-b879-42eb-a3a7-af6442a0551e@github.com>

On Thu, 13 Jan 2022 13:48:02 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> > Yes an "or" is probably worthwhile to add.
> 
> I would prefer to leave it for the follow-up cleanup if only because adding "or" here would make it inconsistent with other `@throws SQLException` descriptions in that file and perhaps elsewhere in java.sql:
> 
> * java/sql/Statement.java:59
> * java/sql/Statement.java:85
> * java/sql/Statement.java:346
> * java/sql/Statement.java:524
> * java/sql/Statement.java:745
> * java/sql/Statement.java:814
> * java/sql/Statement.java:860
> * java/sql/Statement.java:913
> * java/sql/Statement.java:962
> * java/sql/Statement.java:1225
> * java/sql/Statement.java:1269
> * java/sql/Statement.java:1314

I am fine with that.  I guess a semi-colon could also be used vs. a comma to divide the Exception scenarios listed

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From lancea at openjdk.java.net  Thu Jan 13 17:35:25 2022
From: lancea at openjdk.java.net (Lance Andersen)
Date: Thu, 13 Jan 2022 17:35:25 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
Message-ID: <wFh5PNvl7A_Oui3iDHyjFGEYyurAzJmGjVKD2bEF1tg=.e962af55-7886-4678-8a7b-39d1a695ae22@github.com>

On Thu, 13 Jan 2022 14:01:04 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - `&#39;` is an apostrophe, which does not require to be encoded.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Additional typos

Marked as reviewed by lancea (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From jjg at openjdk.java.net  Thu Jan 13 23:01:28 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 13 Jan 2022 23:01:28 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <zYl0PN2cKub3zwtGJr9wKdC7oq0BrHa6v2TG2esnlZM=.9936d444-caae-47af-916a-d2847c64bcd5@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <2bsQg-3igmY6_fAT_OD9jIuJ7ziQBgvB7oF1CiZN_Zo=.51e0dd63-d489-4996-8fb9-b2e8c385cbb8@github.com>
 <VCF8_RsgzIZEi2Hls0T3tX08pg3RfYbTtQKrU0WsO6g=.e49acac0-a7d5-4a35-9a27-4bc1e8b39d1a@github.com>
 <KEQBfIPtqMR39DeUDsPXb3Tqaow0Q487Gne-nJSp5hI=.bf96f113-80dc-48ba-a280-6cd13bb979da@github.com>
 <zYl0PN2cKub3zwtGJr9wKdC7oq0BrHa6v2TG2esnlZM=.9936d444-caae-47af-916a-d2847c64bcd5@github.com>
Message-ID: <euQ2BZTUg-jsd4LJYaF9nTXRLsnozIsFNI3en-iH6a0=.1fb0785a-886c-41e7-870f-87b941bb82f6@github.com>

On Thu, 13 Jan 2022 11:40:20 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> OK, so lines 264,  295, 329, 364, 431 are arguably wrong as well?  Separating the [] completely looks quite rare.
>> I'll leave it up to you. 8-)
>
> I think that can be a follow on clean up.

The strange formatting of `long []updateCounts` looks very unusual and well worth a followup cleanup.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From jlahoda at openjdk.java.net  Fri Jan 14 11:22:36 2022
From: jlahoda at openjdk.java.net (Jan Lahoda)
Date: Fri, 14 Jan 2022 11:22:36 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
Message-ID: <mHTQhslPgaefsXLYiV_SvYHyzjK_ugDhBIpWzkdua3o=.d6cc09e9-9eb6-4dbb-9b9a-64b743d7eb37@github.com>

On Thu, 13 Jan 2022 14:01:04 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - `&#39;` is an apostrophe, which does not require to be encoded.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Additional typos

javac changes look good to me.

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

Marked as reviewed by jlahoda (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7063

From azvegint at openjdk.java.net  Fri Jan 14 12:19:28 2022
From: azvegint at openjdk.java.net (Alexander Zvegintsev)
Date: Fri, 14 Jan 2022 12:19:28 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
Message-ID: <2NHrJp-0YZuLsk1to7auM4-WbJ0BxxfUImHMBAYHxs8=.012a0e0c-a9e7-4bb9-b822-21334744d4ed@github.com>

On Thu, 13 Jan 2022 14:01:04 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - `&#39;` is an apostrophe, which does not require to be encoded.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Additional typos

Client changes looks good to me.

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

Marked as reviewed by azvegint (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7063

From egahlin at openjdk.java.net  Fri Jan 14 12:42:32 2022
From: egahlin at openjdk.java.net (Erik Gahlin)
Date: Fri, 14 Jan 2022 12:42:32 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
Message-ID: <V_tZ6iUCrtIDCAbwbWr8Pnj-hACcC7UbdEStP17e3BA=.5c64f1d4-9df7-4d9f-8bbc-f59b2748505f@github.com>

On Thu, 13 Jan 2022 14:01:04 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - `&#39;` is an apostrophe, which does not require to be encoded.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Additional typos

Marked as reviewed by egahlin (Reviewer).

The JFR related changes looks OK.

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From hannesw at openjdk.java.net  Fri Jan 14 13:34:33 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 14 Jan 2022 13:34:33 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature
In-Reply-To: <EwU8Qc6uayT-qHd7sxOtDY5T_W_atitjK0xUgWy1kbA=.090f6c2f-621a-4313-acd7-6831c988a712@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
 <EwU8Qc6uayT-qHd7sxOtDY5T_W_atitjK0xUgWy1kbA=.090f6c2f-621a-4313-acd7-6831c988a712@github.com>
Message-ID: <QZntzwolf1KbiNkH189_SYE54-_NSEqjLo-LDI_nW-A=.eaea13b4-ef91-47bc-86d8-216d33a166bc@github.com>

On Thu, 13 Jan 2022 15:30:59 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Out of curiosity, how much of a churn does this PR introduce into the generated JDK API documentation? In any case, we should check it, to make sure that nothing surprising comes up.

That's a very good question! Turns out there are more than 50 classes in JDK that contain `@param` tags in wrong order. For instance, there is a [Collectors.groupingBy][1] method that gets both type and method parameter order wrong. I'm surprised not more of these get reported as bugs because I think they're quite confusing. 

[1]: https://download.java.net/java/early_access/jdk18/docs/api/java.base/java/util/stream/Collectors.html#groupingBy(java.util.function.Function,java.util.function.Supplier,java.util.stream.Collector)

I checked a few cases against the documentation generated with this PR and the it fixes the problem.

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

PR: https://git.openjdk.java.net/jdk/pull/7046

From prappo at openjdk.java.net  Fri Jan 14 14:53:32 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Fri, 14 Jan 2022 14:53:32 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature
In-Reply-To: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
Message-ID: <PUjumiu9yUXnW7mkf6LQYowbEEZ1nsswqxvSS4lbosQ=.913ac9c0-f39b-475e-8397-73626e941d94@github.com>

On Wed, 12 Jan 2022 08:40:08 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change in how documentation from `@param` tags is generated. 
> 
> The old code generates parameter documentation for each `@param` in the order in which the tags occur in the comment, then adds documentation from inherited `@param` tags for undocumented parameters. 
> 
> The new code always generates documentation in the order in which actual parameters are declared in the code, using local or inherited `@param` tags as appropriate. Any `@param` tags that do not have a matching parameter are added afterwards.
> 
> Note that `@param` is not just used for parameters of executable members but also type parameters and record components. The second commit of this PR fixes a `ClassCastException` for these uses that was caused by the first commit and adds a few tests for it.

test/langtools/jdk/javadoc/doclet/testParamTaglet/TestParamTaglet.java line 63:

> 61:                     </dl>""",
> 62:                 // Param tags that don't match with any real parameters.
> 63:                 // {@inherit} doc misuse does not cause doclet to throw exception.

Should we change this to `{@inheritDoc}`?

test/langtools/jdk/javadoc/doclet/testParamTaglet/pkg/C.java line 50:

> 48:      * @param b another duplicate
> 49:      */
> 50:     public void unorderedParams(int i, double d, boolean b) {}

Consider adding `@Override` to this method and to `nonMatchingParams`.

test/langtools/jdk/javadoc/doclet/testParamTaglet/pkg/C.java line 59:

> 57:      * @param t3 param 3
> 58:      */
> 59:     public static <T1, T2, T3> void genericMethod(T1 t1, T2 t2, T3 t3) {

You use `{}` to denote an empty body everywhere else in this file. Is there a reason you split it into two lines here?

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

PR: https://git.openjdk.java.net/jdk/pull/7046

From jjg at openjdk.java.net  Fri Jan 14 16:08:31 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 14 Jan 2022 16:08:31 GMT
Subject: RFR: 8279918: Fix various doc typos [v2]
In-Reply-To: <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
 <xjtKpoXjmab0GcY8CsWz8yZAReei4r9VUhOisV2zmPY=.cb5ffea8-3ba3-4cfd-bd6c-4d8555c87fcb@github.com>
Message-ID: <96bxwtnI-_Z67Udh4acEGwA2xzIy6dAV6CxOe9HLkRo=.dd8643aa-f3be-42e2-ad72-4a00d90363d9@github.com>

On Thu, 13 Jan 2022 14:01:04 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> - Most of the typos are of a trivial kind: missing whitespace.
>> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
>> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
>> - `&#39;` is an apostrophe, which does not require to be encoded.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Additional typos

jdk.compiler and jdk.javadoc look good

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

Marked as reviewed by jjg (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7063

From prappo at openjdk.java.net  Fri Jan 14 16:13:34 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Fri, 14 Jan 2022 16:13:34 GMT
Subject: Integrated: 8279918: Fix various doc typos
In-Reply-To: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
References: <46YbMVL2FChSPfnSUQA9DT5-GV61UGS5WeBxaGsHGz8=.915d9070-8ee4-4703-bf34-1ae07085e550@github.com>
Message-ID: <iRT0-D_kHCqoTOO_tqTh0WH4UU1j-7Ju2SV6oLUBLhU=.73b73e8f-5608-4fc1-a147-bc569d647428@github.com>

On Thu, 13 Jan 2022 10:30:07 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> - Most of the typos are of a trivial kind: missing whitespace.
> - If any of the typos should be fixed in the upstream projects instead, please say so; I will drop those typos from the patch.
> - As I understand it, ` ` in ImageInputStream and DataInput is an irrelevant formatting artefact and thus can be removed.
> - `&#39;` is an apostrophe, which does not require to be encoded.

This pull request has now been integrated.

Changeset: f1805309
Author:    Pavel Rappo <prappo at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/f1805309352a22119ae2edf8bfbb596f00936224
Stats:     88 lines in 35 files changed: 0 ins; 0 del; 88 mod

8279918: Fix various doc typos

Reviewed-by: kevinw, lancea, mullan, sspitsyn, naoto, jlahoda, azvegint, egahlin, jjg

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

PR: https://git.openjdk.java.net/jdk/pull/7063

From hannesw at openjdk.java.net  Fri Jan 14 16:15:29 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 14 Jan 2022 16:15:29 GMT
Subject: RFR: JDK-8268831: Improve javadoc tool handling of streams.
In-Reply-To: <cf7RSoDuPLHqIXKxCoorYoLd5uDWWHlgyuzyjuAS51g=.1c68ece5-0d52-4d67-b3c0-cde6d208b50c@github.com>
References: <cf7RSoDuPLHqIXKxCoorYoLd5uDWWHlgyuzyjuAS51g=.1c68ece5-0d52-4d67-b3c0-cde6d208b50c@github.com>
Message-ID: <ZsVTmzZDQflUVMFKz9ney66wZUI8H13f6y_jhy8yxeQ=.40749dc2-c8c5-4419-b1cf-df9625703b27@github.com>

On Tue, 4 Jan 2022 01:17:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a relatively simple cleanup left over from last year's cleanup for `JavadocLog` (was `Messager`).
> 
> The cleanup here is to rationalize the inconsistent naming and use of methods named `notice` in `JavadocLog` and `ToolEnvironment`, as well as cleanup use of the primitive `Log.printRawLines`. While it would have been nice to move the definition of `ToolEnvironment.notice` into `JavadocLog`  that dragged with it the need for the `quiet` variable, which led to initialization order problems.  The proposed solution is a compromise.
> 
> No tests are affected; `noreg-cleanup`.

Looks good to me. 

Am I right in the assumption that the writer for `WriterKind.NOTICE` in javadoc is always stdout? I couldn't figure out where the writers are set (I guess it is somewhere in jdk.compiler code).

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/6950

From hannesw at openjdk.java.net  Fri Jan 14 16:35:56 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 14 Jan 2022 16:35:56 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature [v2]
In-Reply-To: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
Message-ID: <QzoW5HzNOnQj24qUp2Fc3H6QjxXLqkeN2Ysh6Bgycok=.27cd5bfc-6e91-4e6c-aa9d-5afb0748dbe1@github.com>

> Please review a change in how documentation from `@param` tags is generated. 
> 
> The old code generates parameter documentation for each `@param` in the order in which the tags occur in the comment, then adds documentation from inherited `@param` tags for undocumented parameters. 
> 
> The new code always generates documentation in the order in which actual parameters are declared in the code, using local or inherited `@param` tags as appropriate. Any `@param` tags that do not have a matching parameter are added afterwards.
> 
> Note that `@param` is not just used for parameters of executable members but also type parameters and record components. The second commit of this PR fixes a `ClassCastException` for these uses that was caused by the first commit and adds a few tests for it.

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

  JDK-8234682: Review feedback

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7046/files
  - new: https://git.openjdk.java.net/jdk/pull/7046/files/231ca4d6..1caa8aed

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7046&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7046&range=00-01

  Stats: 5 lines in 2 files changed: 2 ins; 1 del; 2 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7046.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7046/head:pull/7046

PR: https://git.openjdk.java.net/jdk/pull/7046

From hannesw at openjdk.java.net  Fri Jan 14 16:35:59 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 14 Jan 2022 16:35:59 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature [v2]
In-Reply-To: <PUjumiu9yUXnW7mkf6LQYowbEEZ1nsswqxvSS4lbosQ=.913ac9c0-f39b-475e-8397-73626e941d94@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
 <PUjumiu9yUXnW7mkf6LQYowbEEZ1nsswqxvSS4lbosQ=.913ac9c0-f39b-475e-8397-73626e941d94@github.com>
Message-ID: <3bTwIEWZKTMjl1kzWapIyuXC6PyVw__Bm08X9fSD88c=.4dcadc26-9b9e-4f1e-b2ae-f8ec09e1724d@github.com>

On Fri, 14 Jan 2022 14:29:16 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   JDK-8234682: Review feedback
>
> test/langtools/jdk/javadoc/doclet/testParamTaglet/pkg/C.java line 50:
> 
>> 48:      * @param b another duplicate
>> 49:      */
>> 50:     public void unorderedParams(int i, double d, boolean b) {}
> 
> Consider adding `@Override` to this method and to `nonMatchingParams`.

Thanks for the feedback, Pavel. I added a commit that addresses all your suggestions.

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

PR: https://git.openjdk.java.net/jdk/pull/7046

From anna.kozlova at jetbrains.com  Mon Jan 17 12:36:59 2022
From: anna.kozlova at jetbrains.com (Anna Kozlova)
Date: Mon, 17 Jan 2022 13:36:59 +0100
Subject: parameter types in @link tag
Message-ID: <CAL5kOaX_R8B2a1Q41MhSOL=v+bOWm+71+aUQfiO8tMjPUA34Wg@mail.gmail.com>

Hi all!

I am trying to figure out if the javadoc tool should be ok with a short
class name as parameter type. Is there any specification on @link tag
format?

E.g. javadoc for `java.io.File#isDirectory` contains the following "{@link
java.nio.file.Files#readAttributes(Path,Class,LinkOption[])". LinkOption
isn't resolved but the generated html correctly navigates the
"readAttributes" method. This makes me suspect that the signatures are
checked by short names only.
But this leads to the problem with the ambiguity:
```class Foo {
    /**

     * {@link #bar(Bar)}
     */
    void foo() {}
    void bar(Foo2.Bar f) {}
    void bar(Foo1.Bar f) {}
}
class Foo1 {
    static class Bar {}
}
class Foo2 {
    static class Bar {}
}```

Here the link points to the first method as it is written in the class
"Foo" which looks wrong, or is it ok?

Thank you,
Anna Kozlova
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20220117/3fa62176/attachment.htm>

From jonathan.gibbons at oracle.com  Tue Jan 18 20:07:25 2022
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 18 Jan 2022 12:07:25 -0800
Subject: parameter types in @link tag
In-Reply-To: <CAL5kOaX_R8B2a1Q41MhSOL=v+bOWm+71+aUQfiO8tMjPUA34Wg@mail.gmail.com>
References: <CAL5kOaX_R8B2a1Q41MhSOL=v+bOWm+71+aUQfiO8tMjPUA34Wg@mail.gmail.com>
Message-ID: <949f6922-c962-b884-8ad0-51d23e2642df@oracle.com>

Hi Anna,

The intent is that the names should follow javac usage: either use a 
qualified name or use a simple name that is in scope, such as an 
imported name.

That being said, javadoc does not use pure-javac code for the lookup, 
and there are some allowances made for historical usage. I could believe 
there are residual bugs in this area, and any resolution would be in 
favor of moving closer to javac rules where possible.

-- Jon

On 1/17/22 4:36 AM, Anna Kozlova wrote:
> Hi all!
>
> I am trying to figure out if the javadoc tool should be ok with a 
> short class name as parameter type. Is there any specification on 
> @link tag format?
>
> E.g. javadoc for?`java.io.File#isDirectory`?contains the following 
> "{@link java.nio.file.Files#readAttributes(Path,Class,LinkOption[])". 
> LinkOption
> isn't resolved but the generated html correctly navigates the 
> "readAttributes" method. This makes me suspect that the signatures are 
> checked by short names only.
> But this leads to the problem with the ambiguity:
> ```class Foo {
> /**
> * {@link #bar(Bar)} */ void foo() {}
>      void bar(Foo2.Bar f) {}
>      void bar(Foo1.Bar f) {}
> }
> class Foo1 {
>      static class Bar {}
> }
> class Foo2 {
>      static class Bar {}
> }```
> Here the link points to the first method as it is written in the class 
> "Foo" which looks wrong, or is it ok?
>
> Thank you,
> Anna Kozlova
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20220118/e00cf800/attachment.htm>

From anna.kozlova at jetbrains.com  Tue Jan 18 20:49:34 2022
From: anna.kozlova at jetbrains.com (Anna Kozlova)
Date: Tue, 18 Jan 2022 21:49:34 +0100
Subject: parameter types in @link tag
In-Reply-To: <949f6922-c962-b884-8ad0-51d23e2642df@oracle.com>
References: <CAL5kOaX_R8B2a1Q41MhSOL=v+bOWm+71+aUQfiO8tMjPUA34Wg@mail.gmail.com>
 <949f6922-c962-b884-8ad0-51d23e2642df@oracle.com>
Message-ID: <CAL5kOaUuBNkZTmkFarmZOt_ViFBMoa3SFty81uXE2F-V6eEQ3g@mail.gmail.com>

Thanks, Jon!

Anna

On Tue, Jan 18, 2022 at 9:07 PM Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

> Hi Anna,
>
> The intent is that the names should follow javac usage: either use a
> qualified name or use a simple name that is in scope, such as an imported
> name.
>
> That being said, javadoc does not use pure-javac code for the lookup, and
> there are some allowances made for historical usage.  I could believe there
> are residual bugs in this area, and any resolution would be in favor of
> moving closer to javac rules where possible.
>
> -- Jon
> On 1/17/22 4:36 AM, Anna Kozlova wrote:
>
> Hi all!
>
> I am trying to figure out if the javadoc tool should be ok with a short
> class name as parameter type. Is there any specification on @link tag
> format?
>
> E.g. javadoc for `java.io.File#isDirectory` contains the following "{@link
> java.nio.file.Files#readAttributes(Path,Class,LinkOption[])"
> <%7B at linkjava.nio.file.Files#readAttributes(Path,Class,LinkOption[])>.
> LinkOption
> isn't resolved but the generated html correctly navigates the
> "readAttributes" method. This makes me suspect that the signatures are
> checked by short names only.
> But this leads to the problem with the ambiguity:
> ```class Foo {
>     /**
>
>      * {@link #bar(Bar)}     */    void foo() {}
>     void bar(Foo2.Bar f) {}
>     void bar(Foo1.Bar f) {}
> }class Foo1 {
>     static class Bar {}
> }class Foo2 {
>     static class Bar {}
> }```
>
> Here the link points to the first method as it is written in the class
> "Foo" which looks wrong, or is it ok?
>
> Thank you,
> Anna Kozlova
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20220118/e3a67570/attachment-0001.htm>

From jjg at openjdk.java.net  Wed Jan 19 17:43:29 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 19 Jan 2022 17:43:29 GMT
Subject: RFR: JDK-8268831: Improve javadoc tool handling of streams.
In-Reply-To: <ZsVTmzZDQflUVMFKz9ney66wZUI8H13f6y_jhy8yxeQ=.40749dc2-c8c5-4419-b1cf-df9625703b27@github.com>
References: <cf7RSoDuPLHqIXKxCoorYoLd5uDWWHlgyuzyjuAS51g=.1c68ece5-0d52-4d67-b3c0-cde6d208b50c@github.com>
 <ZsVTmzZDQflUVMFKz9ney66wZUI8H13f6y_jhy8yxeQ=.40749dc2-c8c5-4419-b1cf-df9625703b27@github.com>
Message-ID: <01Wvtw6raWVX6VSt-FE7TdMbylTmEYBkTQzo4TgC3Bs=.50bb84cb-bb79-4ef9-b132-ce914987745f@github.com>

On Fri, 14 Jan 2022 16:12:22 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Looks good to me.
> 
> Am I right in the assumption that the writer for `WriterKind.NOTICE` in javadoc is always stdout? I couldn't figure out where the writers are set (I guess it is somewhere in jdk.compiler code).

This was changed a short while back.   All diagnostics (ERROR, WARNING, NOTICE) go to `stderr` or its equivalent.  `stdout` is only used for output that is "requested" by the user, where the output is the result of the requested action, like command-line help from `--help`.  Although it's not a defining specification, there's a good wikipedia article on [Standard Streams](https://en.wikipedia.org/wiki/Standard_streams).

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

PR: https://git.openjdk.java.net/jdk/pull/6950

From jjg at openjdk.java.net  Wed Jan 19 17:59:29 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 19 Jan 2022 17:59:29 GMT
Subject: Integrated: JDK-8268831: Improve javadoc tool handling of streams.
In-Reply-To: <cf7RSoDuPLHqIXKxCoorYoLd5uDWWHlgyuzyjuAS51g=.1c68ece5-0d52-4d67-b3c0-cde6d208b50c@github.com>
References: <cf7RSoDuPLHqIXKxCoorYoLd5uDWWHlgyuzyjuAS51g=.1c68ece5-0d52-4d67-b3c0-cde6d208b50c@github.com>
Message-ID: <b1_ijZVp1NdYVWwXyq5Qu6Yeiv2Mo4BvUP-LxNw7FBA=.b3d9910b-00c8-4b5b-aebc-00785feafe84@github.com>

On Tue, 4 Jan 2022 01:17:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a relatively simple cleanup left over from last year's cleanup for `JavadocLog` (was `Messager`).
> 
> The cleanup here is to rationalize the inconsistent naming and use of methods named `notice` in `JavadocLog` and `ToolEnvironment`, as well as cleanup use of the primitive `Log.printRawLines`. While it would have been nice to move the definition of `ToolEnvironment.notice` into `JavadocLog`  that dragged with it the need for the `quiet` variable, which led to initialization order problems.  The proposed solution is a compromise.
> 
> No tests are affected; `noreg-cleanup`.

This pull request has now been integrated.

Changeset: 610a1290
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/610a12904d834507754e6d6171a4b8df7e6aa6b0
Stats:     69 lines in 5 files changed: 15 ins; 25 del; 29 mod

8268831: Improve javadoc tool handling of streams.

Reviewed-by: hannesw

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

PR: https://git.openjdk.java.net/jdk/pull/6950

From prappo at openjdk.java.net  Wed Jan 19 18:37:26 2022
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 19 Jan 2022 18:37:26 GMT
Subject: RFR: JDK-8234682: The order of @param in the generated docs should
 match the method signature [v2]
In-Reply-To: <QzoW5HzNOnQj24qUp2Fc3H6QjxXLqkeN2Ysh6Bgycok=.27cd5bfc-6e91-4e6c-aa9d-5afb0748dbe1@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
 <QzoW5HzNOnQj24qUp2Fc3H6QjxXLqkeN2Ysh6Bgycok=.27cd5bfc-6e91-4e6c-aa9d-5afb0748dbe1@github.com>
Message-ID: <XQZQiBeSdlR5nYuQxFn6d9EhYhqDtvdbDslpObZ2io4=.d79432d9-0f05-4ac5-b6e6-1f51720489d4@github.com>

On Fri, 14 Jan 2022 16:35:56 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a change in how documentation from `@param` tags is generated. 
>> 
>> The old code generates parameter documentation for each `@param` in the order in which the tags occur in the comment, then adds documentation from inherited `@param` tags for undocumented parameters. 
>> 
>> The new code always generates documentation in the order in which actual parameters are declared in the code, using local or inherited `@param` tags as appropriate. Any `@param` tags that do not have a matching parameter are added afterwards.
>> 
>> Note that `@param` is not just used for parameters of executable members but also type parameters and record components. The second commit of this PR fixes a `ClassCastException` for these uses that was caused by the first commit and adds a few tests for it.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   JDK-8234682: Review feedback

1. As you pointed elsewhere, `rank` is actually a position of a particular parameter. Later, we could rename `rank` into `position` or something similarly appropriate.
2. Although "ranks" precede this patch, my gut feeling is that rank being String rather than Integer, is a bad idea. But as long as "ranks" are not compared for order (only for equality), we are okay; alphanumeric order differs from that of numeric: "1", "11", "2" vs 1, 2, 11. We should revisit "ranks" later.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java line 211:

> 209:         CommentHelper ch = writer.configuration().utils.getCommentHelper(e);
> 210:         if (!paramTags.isEmpty()) {
> 211:             Map<String,String> rankMap = getRankMap(writer.configuration().utils, formalParameters);

Suggestion:

            Map<String, String> rankMap = getRankMap(writer.configuration().utils, formalParameters);

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java line 229:

> 227:                             case PARAMETER -> "doclet.Parameters_dup_warn";
> 228:                             case TYPE_PARAMETER -> "doclet.TypeParameters_dup_warn";
> 229:                             case RECORD_COMPONENT -> "doclet.RecordComponents_dup_warn";

Suggestion:

                            case PARAMETER        -> "doclet.Parameters_dup_warn";
                            case TYPE_PARAMETER   -> "doclet.TypeParameters_dup_warn";
                            case RECORD_COMPONENT -> "doclet.RecordComponents_dup_warn";

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java line 230:

> 228:      * @param alreadyDocumented the set of exceptions that have already
> 229:      *        been documented.
> 230:      * @param rankMap a {@link java.util.Map} which holds ordering

It's ironic that a method whose job, at least in part, is to warn about duplicated `@param` tags had one of its `@param` tags duplicated. Was it an Easter egg of sorts?

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

Marked as reviewed by prappo (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7046

From jjg at openjdk.java.net  Wed Jan 19 19:22:57 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 19 Jan 2022 19:22:57 GMT
Subject: RFR: 8268978: Document the javadoc software stack
In-Reply-To: <uV_6sqQA4hETtulnIpg6azuEJVluOPBHrxUtOgJCdgs=.37b93175-9761-43e2-8a72-545e49cc3449@github.com>
References: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
 <uV_6sqQA4hETtulnIpg6azuEJVluOPBHrxUtOgJCdgs=.37b93175-9761-43e2-8a72-545e49cc3449@github.com>
Message-ID: <ZgqBt77RaSt2veJq0omoz2THi81JmK2OU9wIzntf-8U=.a7836b54-2ce4-42ab-912b-7f23240e16da@github.com>

On Thu, 13 Jan 2022 15:48:59 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> A general question about this: Where and how will this documentation mostly be consumed? The `jdk.javadoc.internal` package is not included in standard JDK documentation, so is it likely that this documentation will be mainly consumed within an editor/IDE?
> 
> My feeling is that maybe a less markup-heavy and more text centric form would be easier to consume in that context. For instance, using appropriate HTML headings and paragraphs instead of the deeply nested `<dl>` structure might provide more of a continuous text experience, while still maintaining the hierarchical information. Of course this is a matter of taste, different people have different preferences.

This is to document the design for the benefit of potential future developers.  I have no illusions that we will ever run javadoc over the internal documentation as a matter of course, but it is getting better/easier to view documentation comments in an editor./IDE, and with that in mind, I note that IntelliJ IDEA does an excellent job in its Reader Mode of displaying the comment and handling the HTML markup.  I also think it is worth keeping relatively high standards for internal documentation, at least for internal public and protected API. (I accept that it is hard to persuade people to better comment private API :-( )

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

PR: https://git.openjdk.java.net/jdk/pull/6914

From jjg at openjdk.java.net  Wed Jan 19 19:24:55 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 19 Jan 2022 19:24:55 GMT
Subject: RFR: JDK-8272984: javadoc support for SOURCE_DATE_EPOCH [v2]
In-Reply-To: <yWyTwMQzSKKAyVWv4erZWD4ZpSq_v3PDPVEEaqh69ok=.1a855f0f-cf0d-4adb-926c-f39ecdaa68ef@github.com>
References: <Gdqjj3DMB6Kuq37oAy6bekv2izi0BpPI1p80w66w_HA=.cfeabb57-432a-4eee-9a4f-fc37a660a4fe@github.com>
 <Wcglf7yInRU3xQsrvnFcYA302aw_jJApPQpvJa8ZAnk=.1939d72a-c320-4e1e-9b10-02d101190c73@github.com>
 <yWyTwMQzSKKAyVWv4erZWD4ZpSq_v3PDPVEEaqh69ok=.1a855f0f-cf0d-4adb-926c-f39ecdaa68ef@github.com>
Message-ID: <CNxGyRJ5tne7rOka3OzqOJ43nSDk6drtMjm3aaJC7Qo=.fe5eac24-8f01-4b4b-a6d9-26ba407db233@github.com>

On Tue, 21 Dec 2021 07:22:30 GMT, Alan Bateman <alanb at openjdk.org> wrote:

> I think this issue will require wider discussion because all previous investigation into this topic have concluded with the JDK not reading the env variable directly, instead providing a way to configure the timestamp. For the jar and jmod tools the option --date is used to specify a fixed timestamp for entries when reproducible builds are required. The Properties.store API specifies to read the system property java.properties.date so that date/timestamp in the comment uses a fixed date.

Noted.

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

PR: https://git.openjdk.java.net/jdk/pull/6905

From hannesw at openjdk.java.net  Thu Jan 20 15:43:15 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 20 Jan 2022 15:43:15 GMT
Subject: RFR: JDK-8268335: Find better way to exclude empty HTML elements
Message-ID: <cS5H2TCmALRLjI1aqK64ARy1Xxz8nyP1KaZ0VVgLQPQ=.d8addc59-0ec5-4374-a270-7b9e05bd2e5d@github.com>

Please review a change to straighten out the mechanism to avoid generating empty HTML elements in javadoc. 

Currently this is implemented using the `Content.isValid()` method in `HtmlTree.add(Content)` to check whether the the content argument should be added or dropped. This seems wrong since we don't really want to check for validity but non-emptiness (we want to drop empty elements, not print a warning or error).

So the first decision was to get rid of the `Content.isValid()` method and use `Content.isEmpty()` instead. I considered keeping `isValid()` and using it to actually do some validation checks, but in the end decided it didn't make much sense and scrapped the method.

My initial approach was to take care of emptiness at the content creation site, but it soon turned out there are too many sites potentially creating empty content. After fixing 40+ sites using a new `Content.addNonEmpty(Content)` method I still got empty elements that shouldn't be there in the JDK documentation.

Therefore `HtmlTree.add(Content)` still checks for and drops empty content arguments. Instead, I added a new `HtmlTree.addUnchecked(Content)` method that adds the argument without the checks. The new method is only used 5 times in the whole codebase. It replaces the use of the special `HtmlTree.EMPTY` content token which is no longer needed.

A few remarks about the rewritten `HtmlTree.isEmpty()` method: its purpose is to determine whether content is missing in an element that should have content. It therefore always returns `false` for elements that are expected or allowed to be without content. This is maybe a bit counter-intuitive, but it is what is needed. We could do a combined check such as `isVoid() || !isEmpty()` but that would still leave out elements that *can* be empty, such as `<script>`.

The implementation of `HtmlTree.isEmpty()` is deliberately simple and conservative. For instance, it doesn't look at attributes to decide whether an element is allowed to be empty. The rationale for this is to make the behavior as predictable as possible and avoid surprises.

Since we no longer have a validity check in `HtmlTree.add(Content)` I had to remove a few lines of code in `TestHtmlDocument.java` that expected invalid tags to be dropped. Otherwise there are no test changes, as this is a noreg-cleanup task. I did compare the javadoc JDK documention before and after this change, the output is unchanged.

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

Commit messages:
 - JDK-8268335: Remove unnecessary if statement
 - JDK-8268335: Find better way to exclude empty HTML elements

Changes: https://git.openjdk.java.net/jdk/pull/7159/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=7159&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8268335
  Stats: 185 lines in 16 files changed: 44 ins; 75 del; 66 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7159.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7159/head:pull/7159

PR: https://git.openjdk.java.net/jdk/pull/7159

From hannesw at openjdk.java.net  Thu Jan 20 16:15:14 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 20 Jan 2022 16:15:14 GMT
Subject: RFR: JDK-8280393: Promote use of HtmlTree factory methods
Message-ID: <IkUurGpN05L8QJDBZywZ4pO6DO5fu8i2XJtRoMBQoQU=.9baf1c80-84bd-4e7c-ae73-f38536ded0fd@github.com>

This is a simple cleanup to add and/or make use of `HtmlTree` factory methods for `UL` and `DIV` with a single `HtmlStyle` parameter.

There are no test changes (noreg-cleanup) and no changes in the generated JDK documentation.

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

Commit messages:
 - JDK-8280393: Promote use of HtmlTree factory methods

Changes: https://git.openjdk.java.net/jdk/pull/7162/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=7162&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8280393
  Stats: 108 lines in 19 files changed: 11 ins; 40 del; 57 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7162.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7162/head:pull/7162

PR: https://git.openjdk.java.net/jdk/pull/7162

From hannesw at openjdk.java.net  Thu Jan 20 16:20:56 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 20 Jan 2022 16:20:56 GMT
Subject: Integrated: JDK-8234682: The order of @param in the generated docs
 should match the method signature
In-Reply-To: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
References: <nKpw_Eb877YaUP24ek8ZrJaZ3Gi8GK6HX6B7S3APHX4=.86d15188-5789-4579-8ae4-9af6e879b460@github.com>
Message-ID: <OBT1HPOCTURoSczddrGL7Zq1FB2QZ8QXiNjcLxXqNiE=.197de100-66e8-45f9-bd05-08607ac950b8@github.com>

On Wed, 12 Jan 2022 08:40:08 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change in how documentation from `@param` tags is generated. 
> 
> The old code generates parameter documentation for each `@param` in the order in which the tags occur in the comment, then adds documentation from inherited `@param` tags for undocumented parameters. 
> 
> The new code always generates documentation in the order in which actual parameters are declared in the code, using local or inherited `@param` tags as appropriate. Any `@param` tags that do not have a matching parameter are added afterwards.
> 
> Note that `@param` is not just used for parameters of executable members but also type parameters and record components. The second commit of this PR fixes a `ClassCastException` for these uses that was caused by the first commit and adds a few tests for it.

This pull request has now been integrated.

Changeset: ec8b6acf
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/ec8b6acff39953ca60309c6f1db7ae4c93404da9
Stats:     173 lines in 4 files changed: 95 ins; 34 del; 44 mod

8234682: The order of @param in the generated docs should match the method signature

Reviewed-by: prappo

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

PR: https://git.openjdk.java.net/jdk/pull/7046

From jjg at openjdk.java.net  Thu Jan 20 18:22:56 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 20 Jan 2022 18:22:56 GMT
Subject: RFR: JDK-8280393: Promote use of HtmlTree factory methods
In-Reply-To: <IkUurGpN05L8QJDBZywZ4pO6DO5fu8i2XJtRoMBQoQU=.9baf1c80-84bd-4e7c-ae73-f38536ded0fd@github.com>
References: <IkUurGpN05L8QJDBZywZ4pO6DO5fu8i2XJtRoMBQoQU=.9baf1c80-84bd-4e7c-ae73-f38536ded0fd@github.com>
Message-ID: <9km6BZ0G7qTDJg_0cDfrs9ippZNmCZmKl1O1PteG4FI=.f9803a8c-91f1-4d19-be54-8a8fdbd2e1ea@github.com>

On Thu, 20 Jan 2022 16:08:03 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This is a simple cleanup to add and/or make use of `HtmlTree` factory methods for `UL` and `DIV` with a single `HtmlStyle` parameter.
> 
> There are no test changes (noreg-cleanup) and no changes in the generated JDK documentation.

Looks good to me!

The final comment on (HtmlTree.UL) says it all ... a small addition has a big impact. Nice.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlSerialMethodWriter.java line 74:

> 72:     @Override
> 73:     public Content getMethodsContentHeader(boolean isLastContent) {
> 74:         return new HtmlTree(TagName.LI).setStyle(HtmlStyle.blockList);

While I agree that this is a direct simplification of the existing code, I thought our CSS style was to put/declare the style just on the `ul` element, and then use `ul.STYLE > li` in the stylesheet.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageTreeWriter.java line 152:

> 150:         HtmlTree ul = HtmlTree.UL(HtmlStyle.horizontal);
> 151:         ul.add(getNavLinkMainTree(resources.getText("doclet.All_Packages")));
> 152:         div.add(ul);

This is a general comment that is not specific to this instance.

You could also simplify the code further by using method chaining, even to the point of (in this case) eliminating the need for the local variable.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java line 858:

> 856:                 .setStyle(style);
> 857:     }
> 858: 

Minor addition, with a big impact: very nice!

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

Marked as reviewed by jjg (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7162

From jjg at openjdk.java.net  Fri Jan 21 00:20:19 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 21 Jan 2022 00:20:19 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds
Message-ID: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>

Please review a javadoc update to support a new `--date` option to support reproducible builds.

This pull request supersedes https://github.com/openjdk/jdk/pull/6905. In that PR, the `SOURCE_DATE_EPOCH` environment variable was used to provide the time stamp, but review feedback suggested the use of a new command-line option, `--date`.  The format of the argument of the `--date` option is that same as that of similar options for the _jar_ and _jmod_ tools, and the code to handle the value is based on code in the _jar_ tool.

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

Commit messages:
 - JDK-8272984: javadoc support for reproducible builds

Changes: https://git.openjdk.java.net/jdk/pull/7171/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=7171&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8272984
  Stats: 243 lines in 9 files changed: 229 ins; 1 del; 13 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7171.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7171/head:pull/7171

PR: https://git.openjdk.java.net/jdk/pull/7171

From alanb at openjdk.java.net  Fri Jan 21 08:06:46 2022
From: alanb at openjdk.java.net (Alan Bateman)
Date: Fri, 21 Jan 2022 08:06:46 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds
In-Reply-To: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
Message-ID: <iuRdVX5XG-j-K5eOjVQHAinMXp3md_SKkP8FqhsWTVk=.bcc9e4e1-2219-4e3a-bb3b-5d194df1efa2@github.com>

On Fri, 21 Jan 2022 00:11:21 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a javadoc update to support a new `--date` option to support reproducible builds.
> 
> This pull request supersedes https://github.com/openjdk/jdk/pull/6905. In that PR, the `SOURCE_DATE_EPOCH` environment variable was used to provide the time stamp, but review feedback suggested the use of a new command-line option, `--date`.  The format of the argument of the `--date` option is that same as that of similar options for the _jar_ and _jmod_ tools, and the code to handle the value is based on code in the _jar_ tool.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 356:

> 354: 
> 355:                 new XOption(resources, "--date", 1) {
> 356:                     // Valid --date range: within a year of now

Adding "--date" looks reasonable and makes it consistent with jar/jmod. I'm just not sure about restricting the date to "within a year of now". I assume projects will use the SOURCE_DATE_EPOCH to create a value for --date so they will run into issues if someone tries to build the project again, in a year.

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From hannesw at openjdk.java.net  Fri Jan 21 08:28:17 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Jan 2022 08:28:17 GMT
Subject: RFR: JDK-8280393: Promote use of HtmlTree factory methods [v2]
In-Reply-To: <IkUurGpN05L8QJDBZywZ4pO6DO5fu8i2XJtRoMBQoQU=.9baf1c80-84bd-4e7c-ae73-f38536ded0fd@github.com>
References: <IkUurGpN05L8QJDBZywZ4pO6DO5fu8i2XJtRoMBQoQU=.9baf1c80-84bd-4e7c-ae73-f38536ded0fd@github.com>
Message-ID: <agW7wHEPC65unpYV4QdL8F0Uqqp6M3QKcHf6tC1-eq8=.8311aee3-03ab-4127-9078-a980644c8195@github.com>

> This is a simple cleanup to add and/or make use of `HtmlTree` factory methods for `UL` and `DIV` with a single `HtmlStyle` parameter.
> 
> There are no test changes (noreg-cleanup) and no changes in the generated JDK documentation.

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

  JDK-8280393: Remove unnecessary class attribute

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7162/files
  - new: https://git.openjdk.java.net/jdk/pull/7162/files/6a658676..40373b11

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7162&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7162&range=00-01

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

PR: https://git.openjdk.java.net/jdk/pull/7162

From hannesw at openjdk.java.net  Fri Jan 21 08:28:20 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Jan 2022 08:28:20 GMT
Subject: RFR: JDK-8280393: Promote use of HtmlTree factory methods [v2]
In-Reply-To: <9km6BZ0G7qTDJg_0cDfrs9ippZNmCZmKl1O1PteG4FI=.f9803a8c-91f1-4d19-be54-8a8fdbd2e1ea@github.com>
References: <IkUurGpN05L8QJDBZywZ4pO6DO5fu8i2XJtRoMBQoQU=.9baf1c80-84bd-4e7c-ae73-f38536ded0fd@github.com>
 <9km6BZ0G7qTDJg_0cDfrs9ippZNmCZmKl1O1PteG4FI=.f9803a8c-91f1-4d19-be54-8a8fdbd2e1ea@github.com>
Message-ID: <Ro92LKzmwron0VDfEDMDqAkTLs-3bGZln7Vn3zvIh5c=.703c1bb6-ea87-4a8e-8af0-cb2623aacdf7@github.com>

On Thu, 20 Jan 2022 18:13:45 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   JDK-8280393: Remove unnecessary class attribute
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlSerialMethodWriter.java line 74:
> 
>> 72:     @Override
>> 73:     public Content getMethodsContentHeader(boolean isLastContent) {
>> 74:         return new HtmlTree(TagName.LI).setStyle(HtmlStyle.blockList);
> 
> While I agree that this is a direct simplification of the existing code, I thought our CSS style was to put/declare the style just on the `ul` element, and then use `ul.STYLE > li` in the stylesheet.

You are right, the class attribute is not needed. I left it there because my goal was not to cause any output changes. However, after removing the attribute, tests still pass and the change in the "Serialized Form" page does not affect the appearance of the page (I checked both in the browser and in the stylesheet). I'll therefore add a commit to remove the style from this `<li>` element.

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

PR: https://git.openjdk.java.net/jdk/pull/7162

From hannesw at openjdk.java.net  Fri Jan 21 09:13:49 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Jan 2022 09:13:49 GMT
Subject: Integrated: JDK-8280393: Promote use of HtmlTree factory methods
In-Reply-To: <IkUurGpN05L8QJDBZywZ4pO6DO5fu8i2XJtRoMBQoQU=.9baf1c80-84bd-4e7c-ae73-f38536ded0fd@github.com>
References: <IkUurGpN05L8QJDBZywZ4pO6DO5fu8i2XJtRoMBQoQU=.9baf1c80-84bd-4e7c-ae73-f38536ded0fd@github.com>
Message-ID: <iavpa-XSiUFwSazDFeFrQHsWSwkyCVRIZNH_QUcGMgs=.fa11db47-e645-4433-bae8-81eca54139a5@github.com>

On Thu, 20 Jan 2022 16:08:03 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This is a simple cleanup to add and/or make use of `HtmlTree` factory methods for `UL` and `DIV` with a single `HtmlStyle` parameter.
> 
> There are no test changes (noreg-cleanup) and no changes in the generated JDK documentation.

This pull request has now been integrated.

Changeset: ab2c8d3c
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/ab2c8d3c9baf1080f436287785e4e02fd79953a7
Stats:     108 lines in 19 files changed: 11 ins; 40 del; 57 mod

8280393: Promote use of HtmlTree factory methods

Reviewed-by: jjg

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

PR: https://git.openjdk.java.net/jdk/pull/7162

From hannesw at openjdk.java.net  Fri Jan 21 09:18:59 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Jan 2022 09:18:59 GMT
Subject: RFR: JDK-8268335: Find better way to exclude empty HTML elements
 [v2]
In-Reply-To: <cS5H2TCmALRLjI1aqK64ARy1Xxz8nyP1KaZ0VVgLQPQ=.d8addc59-0ec5-4374-a270-7b9e05bd2e5d@github.com>
References: <cS5H2TCmALRLjI1aqK64ARy1Xxz8nyP1KaZ0VVgLQPQ=.d8addc59-0ec5-4374-a270-7b9e05bd2e5d@github.com>
Message-ID: <bCyF1QiI93ELUVh9zfphadx93SZPqn5onCvgLIATxBk=.01be18cd-b512-48c7-8cc4-fccbcd92c047@github.com>

> Please review a change to straighten out the mechanism to avoid generating empty HTML elements in javadoc. 
> 
> Currently this is implemented using the `Content.isValid()` method in `HtmlTree.add(Content)` to check whether the the content argument should be added or dropped. This seems wrong since we don't really want to check for validity but non-emptiness (we want to drop empty elements, not print a warning or error).
> 
> So the first decision was to get rid of the `Content.isValid()` method and use `Content.isEmpty()` instead. I considered keeping `isValid()` and using it to actually do some validation checks, but in the end decided it didn't make much sense and scrapped the method.
> 
> My initial approach was to take care of emptiness at the content creation site, but it soon turned out there are too many sites potentially creating empty content. After fixing 40+ sites using a new `Content.addNonEmpty(Content)` method I still got empty elements that shouldn't be there in the JDK documentation.
> 
> Therefore `HtmlTree.add(Content)` still checks for and drops empty content arguments. Instead, I added a new `HtmlTree.addUnchecked(Content)` method that adds the argument without the checks. The new method is only used 5 times in the whole codebase. It replaces the use of the special `HtmlTree.EMPTY` content token which is no longer needed.
> 
> A few remarks about the rewritten `HtmlTree.isEmpty()` method: its purpose is to determine whether content is missing in an element that should have content. It therefore always returns `false` for elements that are expected or allowed to be without content. This is maybe a bit counter-intuitive, but it is what is needed. We could do a combined check such as `isVoid() || !isEmpty()` but that would still leave out elements that *can* be empty, such as `<script>`.
> 
> The implementation of `HtmlTree.isEmpty()` is deliberately simple and conservative. For instance, it doesn't look at attributes to decide whether an element is allowed to be empty. The rationale for this is to make the behavior as predictable as possible and avoid surprises.
> 
> Since we no longer have a validity check in `HtmlTree.add(Content)` I had to remove a few lines of code in `TestHtmlDocument.java` that expected invalid tags to be dropped. Otherwise there are no test changes, as this is a noreg-cleanup task. I did compare the javadoc JDK documention before and after this change, the output is unchanged.

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

 - Merge branch 'master' into JDK-8268335
 - JDK-8268335: Remove unnecessary if statement
 - JDK-8268335: Find better way to exclude empty HTML elements

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

Changes: https://git.openjdk.java.net/jdk/pull/7159/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=7159&range=01
  Stats: 181 lines in 16 files changed: 44 ins; 75 del; 62 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7159.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7159/head:pull/7159

PR: https://git.openjdk.java.net/jdk/pull/7159

From jjg at openjdk.java.net  Fri Jan 21 16:16:43 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 21 Jan 2022 16:16:43 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds
In-Reply-To: <iuRdVX5XG-j-K5eOjVQHAinMXp3md_SKkP8FqhsWTVk=.bcc9e4e1-2219-4e3a-bb3b-5d194df1efa2@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <iuRdVX5XG-j-K5eOjVQHAinMXp3md_SKkP8FqhsWTVk=.bcc9e4e1-2219-4e3a-bb3b-5d194df1efa2@github.com>
Message-ID: <Q6E5OfM_npJ3zmQXRruEVn76NwBdhYRjUttZVxjU7iw=.8691b0df-e52b-4e5e-b525-626d49137d23@github.com>

On Fri, 21 Jan 2022 08:04:03 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Please review a javadoc update to support a new `--date` option to support reproducible builds.
>> 
>> This pull request supersedes https://github.com/openjdk/jdk/pull/6905. In that PR, the `SOURCE_DATE_EPOCH` environment variable was used to provide the time stamp, but review feedback suggested the use of a new command-line option, `--date`.  The format of the argument of the `--date` option is that same as that of similar options for the _jar_ and _jmod_ tools, and the code to handle the value is based on code in the _jar_ tool.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 356:
> 
>> 354: 
>> 355:                 new XOption(resources, "--date", 1) {
>> 356:                     // Valid --date range: within a year of now
> 
> Adding "--date" looks reasonable and makes it consistent with jar/jmod. I'm just not sure about restricting the date to "within a year of now". I assume projects will use the SOURCE_DATE_EPOCH to create a value for --date so they will run into issues if someone tries to build the project again, in a year.

I'll change the range to 10 years. 

I was expecting that the common use of reproducible builds was to compare builds created within a reasonably short period of time. I was wanting to set a range that was less than the seemingly arbitrary range of 1980-2099 allowed by the jar tool.

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Fri Jan 21 16:23:25 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 21 Jan 2022 16:23:25 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
Message-ID: <EC7EpzmFX_SUIUuBhL-LGx1xCG9ue6qmpacDqHL9rQs=.f093857a-7eda-47b0-bda1-c1c96640591a@github.com>

> Please review a javadoc update to support a new `--date` option to support reproducible builds.
> 
> This pull request supersedes https://github.com/openjdk/jdk/pull/6905. In that PR, the `SOURCE_DATE_EPOCH` environment variable was used to provide the time stamp, but review feedback suggested the use of a new command-line option, `--date`.  The format of the argument of the `--date` option is that same as that of similar options for the _jar_ and _jmod_ tools, and the code to handle the value is based on code in the _jar_ tool.

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

  change allowable date range to within 10 years of the time of use

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7171/files
  - new: https://git.openjdk.java.net/jdk/pull/7171/files/0fcc9223..65ab48ed

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7171&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7171&range=00-01

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From hannesw at openjdk.java.net  Fri Jan 21 16:31:44 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Jan 2022 16:31:44 GMT
Subject: RFR: 8268978: Document the javadoc software stack
In-Reply-To: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
References: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
Message-ID: <Sh3R6l8-ZamiOddaQ7XokZrkGeuSb1tHT18npYoW0KU=.48f6713c-0379-4a9e-a3b5-484deecc126d@github.com>

On Wed, 22 Dec 2021 00:48:08 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a `noreg-doc` update to document the javadoc software stack, in the top-level `jdk.javadoc.internal` package.
> 
> The intent is to provide a broad overview.   We can add more specific details, but in general, additional details would probably be better in the `package-info` files for the constituent packages.

This is a very useful overview and introduction!

It looks very good to me, except I think the information in "Other Doclets" should be merged with or added to the "Doclet Interface" section as described below.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/package-info.java line 121:

> 119:  *          Which is best for any application will depend of the circumstances, but
> 120:  *          if a tool does not need access to the documentation comments in a program,
> 121:  *          it is possible that one of the other invocation mechanisms will be more convenient.

Should the "Other Doclets" part above be added to the "Doclet Interface" section below? I think they deal with very related topics. The text above goes into some detail about when and how to implement doclets, which is the topic of the text below. Also, the list above mostly describes the actual components of the javadoc module, but "Other Doclets" is not really part of that.

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/6914

From alanb at openjdk.java.net  Sun Jan 23 09:02:04 2022
From: alanb at openjdk.java.net (Alan Bateman)
Date: Sun, 23 Jan 2022 09:02:04 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <Q6E5OfM_npJ3zmQXRruEVn76NwBdhYRjUttZVxjU7iw=.8691b0df-e52b-4e5e-b525-626d49137d23@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <iuRdVX5XG-j-K5eOjVQHAinMXp3md_SKkP8FqhsWTVk=.bcc9e4e1-2219-4e3a-bb3b-5d194df1efa2@github.com>
 <Q6E5OfM_npJ3zmQXRruEVn76NwBdhYRjUttZVxjU7iw=.8691b0df-e52b-4e5e-b525-626d49137d23@github.com>
Message-ID: <Fhf-MJ5oUv6ZpbivsnIAyRyumVSgdwgXHpOYxqOyIWM=.dac92ad7-6f7f-4c99-87a1-1233320d7149@github.com>

On Fri, 21 Jan 2022 16:13:49 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> I was expecting that the common use of reproducible builds was to compare builds created within a reasonably short period of time. I was wanting to set a range that was less than the seemingly arbitrary range of 1980-2099 allowed by the jar tool.

The restriction that the year be in the range 1980-2099 is because of the legacy ZIP format and the use of extended DOS time stamps. It would require introducing new APIs to support a wider date range. I don't think javadoc needs to put any restriction on the range. I don't have any objection to 10 years, I was mostly curious why it is needed.

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From hannesw at openjdk.java.net  Mon Jan 24 13:44:20 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 24 Jan 2022 13:44:20 GMT
Subject: RFR: JDK-8272984: javadoc support for SOURCE_DATE_EPOCH [v2]
In-Reply-To: <Wcglf7yInRU3xQsrvnFcYA302aw_jJApPQpvJa8ZAnk=.1939d72a-c320-4e1e-9b10-02d101190c73@github.com>
References: <Gdqjj3DMB6Kuq37oAy6bekv2izi0BpPI1p80w66w_HA=.cfeabb57-432a-4eee-9a4f-fc37a660a4fe@github.com>
 <Wcglf7yInRU3xQsrvnFcYA302aw_jJApPQpvJa8ZAnk=.1939d72a-c320-4e1e-9b10-02d101190c73@github.com>
Message-ID: <_v68QiaKqm-NG8JPe-ngwnjosEDcNMvIzSBTObGUfZs=.68b789ad-3535-44a5-80e1-3fe22bc5cb10@github.com>

On Tue, 21 Dec 2021 06:26:52 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a relatively simple patch to support the standard SOURCE_DATE_EPOCH environment variable, used by those who are interested in reproducible builds. (See https://reproducible-builds.org)
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   ignore invalid settings

I think this PR should be closed as it has been superseded by #7171.

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

PR: https://git.openjdk.java.net/jdk/pull/6905

From hannesw at openjdk.java.net  Mon Jan 24 16:03:14 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 24 Jan 2022 16:03:14 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <EC7EpzmFX_SUIUuBhL-LGx1xCG9ue6qmpacDqHL9rQs=.f093857a-7eda-47b0-bda1-c1c96640591a@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <EC7EpzmFX_SUIUuBhL-LGx1xCG9ue6qmpacDqHL9rQs=.f093857a-7eda-47b0-bda1-c1c96640591a@github.com>
Message-ID: <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>

On Fri, 21 Jan 2022 16:23:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a javadoc update to support a new `--date` option to support reproducible builds.
>> 
>> This pull request supersedes https://github.com/openjdk/jdk/pull/6905. In that PR, the `SOURCE_DATE_EPOCH` environment variable was used to provide the time stamp, but review feedback suggested the use of a new command-line option, `--date`.  The format of the argument of the `--date` option is that same as that of similar options for the _jar_ and _jmod_ tools, and the code to handle the value is based on code in the _jar_ tool.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   change allowable date range to within 10 years of the time of use

Generally looks good, but I have a few questions and found a lone typo.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java line 171:

> 169: 
> 170:     /**
> 171:      * TRhe build date, to be recorded in generated files.

Typo: TRhe

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 433:

> 431: doclet.usage.date.description=\
> 432:     Specifies the value to be used to timestamp the generated\n\
> 433:     pages, in ISO_ZONED_DATE_TIME format

I guess it is technically correct to use  a `DateTimeFormatter` constant name here, but wouldn't it be better form to use a generic term like "ISO-8601 format"?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 359:

> 357:                     private static final ZonedDateTime now = ZonedDateTime.now();
> 358:                     static final ZonedDateTime DATE_MIN = now.minusYears(10);
> 359:                     static final ZonedDateTime DATE_MAX = now.plusYears(10);

What's the purpose of limiting valid dates this way?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 370:

> 368:                         try {
> 369:                             date = ZonedDateTime.parse(arg, DateTimeFormatter.ISO_ZONED_DATE_TIME)
> 370:                                     .withZoneSameInstant(ZoneOffset.UTC);

I notice that the new option takes a date-time with timezone, but the timezone is discarded here (and the date-time is later converted to a java.util.Date). Since the purpose of this change is to enable reproducible builds, I guess it should be possible to define the timezone used in the "Generated by" comment (which as far as I can tell is the timezone of the local host).

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Mon Jan 24 18:54:10 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 18:54:10 GMT
Subject: RFR: 8268978: Document the javadoc software stack
In-Reply-To: <Sh3R6l8-ZamiOddaQ7XokZrkGeuSb1tHT18npYoW0KU=.48f6713c-0379-4a9e-a3b5-484deecc126d@github.com>
References: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
 <Sh3R6l8-ZamiOddaQ7XokZrkGeuSb1tHT18npYoW0KU=.48f6713c-0379-4a9e-a3b5-484deecc126d@github.com>
Message-ID: <EwsdxKCc8SbDHVuyogkAVl-m-szxs8KXsn5N7sNwhRc=.bca17935-2c43-4c54-bace-f16384ebc73f@github.com>

On Fri, 21 Jan 2022 16:25:42 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a `noreg-doc` update to document the javadoc software stack, in the top-level `jdk.javadoc.internal` package.
>> 
>> The intent is to provide a broad overview.   We can add more specific details, but in general, additional details would probably be better in the `package-info` files for the constituent packages.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/package-info.java line 121:
> 
>> 119:  *          Which is best for any application will depend of the circumstances, but
>> 120:  *          if a tool does not need access to the documentation comments in a program,
>> 121:  *          it is possible that one of the other invocation mechanisms will be more convenient.
> 
> Should the "Other Doclets" part above be added to the "Doclet Interface" section below? I think they deal with very related topics. The text above goes into some detail about when and how to implement doclets, which is the topic of the text below. Also, the list above mostly describes the actual components of the javadoc module, but "Other Doclets" is not really part of that.

I'll take a look.

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

PR: https://git.openjdk.java.net/jdk/pull/6914

From jjg at openjdk.java.net  Mon Jan 24 19:01:17 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 19:01:17 GMT
Subject: RFR: 8268978: Document the javadoc software stack
In-Reply-To: <EwsdxKCc8SbDHVuyogkAVl-m-szxs8KXsn5N7sNwhRc=.bca17935-2c43-4c54-bace-f16384ebc73f@github.com>
References: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
 <Sh3R6l8-ZamiOddaQ7XokZrkGeuSb1tHT18npYoW0KU=.48f6713c-0379-4a9e-a3b5-484deecc126d@github.com>
 <EwsdxKCc8SbDHVuyogkAVl-m-szxs8KXsn5N7sNwhRc=.bca17935-2c43-4c54-bace-f16384ebc73f@github.com>
Message-ID: <8d-hTg9TbPu4vzPKCeqkzqTA05x8UFei7fiWjnXZXCk=.525357c5-7aa8-498a-9ab7-202b69b2a565@github.com>

On Mon, 24 Jan 2022 18:51:02 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/package-info.java line 121:
>> 
>>> 119:  *          Which is best for any application will depend of the circumstances, but
>>> 120:  *          if a tool does not need access to the documentation comments in a program,
>>> 121:  *          it is possible that one of the other invocation mechanisms will be more convenient.
>> 
>> Should the "Other Doclets" part above be added to the "Doclet Interface" section below? I think they deal with very related topics. The text above goes into some detail about when and how to implement doclets, which is the topic of the text below. Also, the list above mostly describes the actual components of the javadoc module, but "Other Doclets" is not really part of that.
>
> I'll take a look.

I think it helps to keep them separate ... and the text is adjacent.

"Other Doclets" is somewhat more about why you might not want to write a doclet these days ... it's addressing the historical past where there were lots of doclets, a lot of which did not even look at doc comments ... i.e they were using the Doclet API as an early Language Model API.

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

PR: https://git.openjdk.java.net/jdk/pull/6914

From jjg at openjdk.java.net  Mon Jan 24 19:07:13 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 19:07:13 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <EC7EpzmFX_SUIUuBhL-LGx1xCG9ue6qmpacDqHL9rQs=.f093857a-7eda-47b0-bda1-c1c96640591a@github.com>
 <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>
Message-ID: <uXNcfyMo7XjYiep6wTwsV01tPqHJ0n-erA_oH_8HtiY=.45353a29-5f07-4500-9c87-80689587cd59@github.com>

On Mon, 24 Jan 2022 15:41:31 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   change allowable date range to within 10 years of the time of use
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 433:
> 
>> 431: doclet.usage.date.description=\
>> 432:     Specifies the value to be used to timestamp the generated\n\
>> 433:     pages, in ISO_ZONED_DATE_TIME format
> 
> I guess it is technically correct to use  a `DateTimeFormatter` constant name here, but wouldn't it be better form to use a generic term like "ISO-8601 format"?

Yeah, you're right, that would be better, and sufficient.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 370:
> 
>> 368:                         try {
>> 369:                             date = ZonedDateTime.parse(arg, DateTimeFormatter.ISO_ZONED_DATE_TIME)
>> 370:                                     .withZoneSameInstant(ZoneOffset.UTC);
> 
> I notice that the new option takes a date-time with timezone, but the timezone is discarded here (and the date-time is later converted to a java.util.Date). Since the purpose of this change is to enable reproducible builds, I guess it should be possible to define the timezone used in the "Generated by" comment (which as far as I can tell is the timezone of the local host).

I went out of my way to ensure that the _output_ form was not affected, in case there is anyone relying on the existing format ... and yes, we have tests for that as well.

I'd be open to formally changing the format of the output timestamp, but I think that should be a separate RFE.

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Mon Jan 24 19:07:13 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 19:07:13 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <Fhf-MJ5oUv6ZpbivsnIAyRyumVSgdwgXHpOYxqOyIWM=.dac92ad7-6f7f-4c99-87a1-1233320d7149@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <iuRdVX5XG-j-K5eOjVQHAinMXp3md_SKkP8FqhsWTVk=.bcc9e4e1-2219-4e3a-bb3b-5d194df1efa2@github.com>
 <Q6E5OfM_npJ3zmQXRruEVn76NwBdhYRjUttZVxjU7iw=.8691b0df-e52b-4e5e-b525-626d49137d23@github.com>
 <Fhf-MJ5oUv6ZpbivsnIAyRyumVSgdwgXHpOYxqOyIWM=.dac92ad7-6f7f-4c99-87a1-1233320d7149@github.com>
Message-ID: <xMrqspQ-ybyh7XAHlKcEsnRM3rm8EgmtEXX5YoPOAB8=.8154eb75-b985-4a19-80ba-e31c12c1dd06@github.com>

On Sun, 23 Jan 2022 08:58:18 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> I'll change the range to 10 years. 
>> 
>> I was expecting that the common use of reproducible builds was to compare builds created within a reasonably short period of time. I was wanting to set a range that was less than the seemingly arbitrary range of 1980-2099 allowed by the jar tool.
>
>> I was expecting that the common use of reproducible builds was to compare builds created within a reasonably short period of time. I was wanting to set a range that was less than the seemingly arbitrary range of 1980-2099 allowed by the jar tool.
> 
> The restriction that the year be in the range 1980-2099 is because of the legacy ZIP format and the use of extended DOS time stamps. It would require introducing new APIs to support a wider date range. I don't think javadoc needs to put any restriction on the range. I don't have any objection to 10 years, I was mostly curious why it is needed.

I was following the jmod code, which uses a range, and I guessed (apparently correctly) that the chosen range was ip-specific.

I think it is worthwhile having a sanity-check on the provided range.

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Mon Jan 24 19:11:15 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 19:11:15 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <EC7EpzmFX_SUIUuBhL-LGx1xCG9ue6qmpacDqHL9rQs=.f093857a-7eda-47b0-bda1-c1c96640591a@github.com>
 <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>
Message-ID: <_2Ui0wq4MSoCA08FXxQ6U-MC27y56fmcXFhsAscNhl8=.71fc291b-1686-4493-a2b7-6ce7b58677dc@github.com>

On Mon, 24 Jan 2022 15:32:46 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   change allowable date range to within 10 years of the time of use
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 359:
> 
>> 357:                     private static final ZonedDateTime now = ZonedDateTime.now();
>> 358:                     static final ZonedDateTime DATE_MIN = now.minusYears(10);
>> 359:                     static final ZonedDateTime DATE_MAX = now.plusYears(10);
> 
> What's the purpose of limiting valid dates this way?

Partly because the code on which I based this on (in the jar tool) had a range check, and partly because I think it makes sense to do a sanity check on the provided value.  The range in the jar tool was 1980-2099 which (see elsewhere) is an artifact of the zip spec, so I changed the range to a "reasonably broad" range of reasonable values.

Given that (for now) we convert internally to a `Date`, we can't accept years before Unix epoch, 1970, anyway, so that's another reason for the check.

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Mon Jan 24 19:55:34 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 19:55:34 GMT
Subject: RFR: JDK-8280402: Add new convenience forms to HtmlTree
Message-ID: <g2KIDj0C72bGmmLU37plIACtuDvYK5Yyrf30HJAsWts=.77af4827-430d-4f7b-b89d-8723706a4dc6@github.com>

Please review a simple `noreg-clean` update to `HtmlTree` and a couple of friends.  The updates are to continue the trend towards the use of Facebook tory methods for `HtmlTree` objects, and to leverage generic methods and lambdas to generate composite content. The cleanup is mostly extracted from some parallel work for a separate PR.  Some of the more general cleanup was suggested by an IDE.

All javadoc tests pass locally; I have a job in  progress to validate the fix on all platforms, although there is no reason to believe there might be any issues.

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

Commit messages:
 - fix whitespace
 - JDK-8280402: Add new convenience forms to HtmlTree

Changes: https://git.openjdk.java.net/jdk/pull/7166/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=7166&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8280402
  Stats: 174 lines in 3 files changed: 100 ins; 22 del; 52 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7166.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7166/head:pull/7166

PR: https://git.openjdk.java.net/jdk/pull/7166

From hannesw at openjdk.java.net  Mon Jan 24 19:55:35 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 24 Jan 2022 19:55:35 GMT
Subject: RFR: JDK-8280402: Add new convenience forms to HtmlTree
In-Reply-To: <g2KIDj0C72bGmmLU37plIACtuDvYK5Yyrf30HJAsWts=.77af4827-430d-4f7b-b89d-8723706a4dc6@github.com>
References: <g2KIDj0C72bGmmLU37plIACtuDvYK5Yyrf30HJAsWts=.77af4827-430d-4f7b-b89d-8723706a4dc6@github.com>
Message-ID: <1EI4OvDsEuMDgFTbbtYoZbf35Zqq22Wn0fwaeDXJVnE=.c82e0f81-d899-46b4-a273-8ad944281efa@github.com>

On Thu, 20 Jan 2022 19:31:41 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple `noreg-clean` update to `HtmlTree` and a couple of friends.  The updates are to continue the trend towards the use of Facebook tory methods for `HtmlTree` objects, and to leverage generic methods and lambdas to generate composite content. The cleanup is mostly extracted from some parallel work for a separate PR.  Some of the more general cleanup was suggested by an IDE.
> 
> All javadoc tests pass locally; I have a job in  progress to validate the fix on all platforms, although there is no reason to believe there might be any issues.

Looks good! 

I would propose to move the implementation of `addAll` from `HtmlTree` to `Content` as explained in the in-code comment. 

One additional place where `addAll` could be used is in TagletWriterImpl.java around line 356 where the stream/filter/forEach construct may be replaced with `seeList.addAll(links, HtmlTree::LI);` (the filtering of invalid/empty elements is actually redundant since this is already done in `HtmlTree.add(Content)`).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java line 240:

> 238:         list.forEach(item -> add(mapper.apply(item)));
> 239:         return this;
> 240:     }

We could move this implementation of `addAll` to the `Content` base class as it is except for changing the return type to `Content`. This would make the method available in other subclasses that override/support `add(Content)`, such as `ContentBuilder`. The only observable change would be that it wouldn't throw `UnsupportedOperationException` when called with an empty collection in non-addable classes.  I think that's an acceptable behaviour for an internal API.

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7166

From jjg at openjdk.java.net  Mon Jan 24 20:03:05 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 20:03:05 GMT
Subject: RFR: JDK-8280402: Add new convenience forms to HtmlTree
In-Reply-To: <1EI4OvDsEuMDgFTbbtYoZbf35Zqq22Wn0fwaeDXJVnE=.c82e0f81-d899-46b4-a273-8ad944281efa@github.com>
References: <g2KIDj0C72bGmmLU37plIACtuDvYK5Yyrf30HJAsWts=.77af4827-430d-4f7b-b89d-8723706a4dc6@github.com>
 <1EI4OvDsEuMDgFTbbtYoZbf35Zqq22Wn0fwaeDXJVnE=.c82e0f81-d899-46b4-a273-8ad944281efa@github.com>
Message-ID: <2REVhhXT1qK6joxztP8WG50zl_xG1dpbSzx9jQP7KAA=.25ef14f2-73a9-4883-b95a-e5b3bad59cf4@github.com>

On Fri, 21 Jan 2022 09:58:14 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a simple `noreg-clean` update to `HtmlTree` and a couple of friends.  The updates are to continue the trend towards the use of Facebook tory methods for `HtmlTree` objects, and to leverage generic methods and lambdas to generate composite content. The cleanup is mostly extracted from some parallel work for a separate PR.  Some of the more general cleanup was suggested by an IDE.
>> 
>> All javadoc tests pass locally; I have a job in  progress to validate the fix on all platforms, although there is no reason to believe there might be any issues.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java line 240:
> 
>> 238:         list.forEach(item -> add(mapper.apply(item)));
>> 239:         return this;
>> 240:     }
> 
> We could move this implementation of `addAll` to the `Content` base class as it is except for changing the return type to `Content`. This would make the method available in other subclasses that override/support `add(Content)`, such as `ContentBuilder`. The only observable change would be that it wouldn't throw `UnsupportedOperationException` when called with an empty collection in non-addable classes.  I think that's an acceptable behaviour for an internal API.

Another observable change would be that the method could not be used in method chaining, because of the different return type.  But having the method applicable at least in a limited form in ContentBuilder would be nice, but that suggests leaving a covariant override here.

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

PR: https://git.openjdk.java.net/jdk/pull/7166

From hannesw at openjdk.java.net  Mon Jan 24 20:25:11 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 24 Jan 2022 20:25:11 GMT
Subject: RFR: 8268978: Document the javadoc software stack
In-Reply-To: <8d-hTg9TbPu4vzPKCeqkzqTA05x8UFei7fiWjnXZXCk=.525357c5-7aa8-498a-9ab7-202b69b2a565@github.com>
References: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
 <Sh3R6l8-ZamiOddaQ7XokZrkGeuSb1tHT18npYoW0KU=.48f6713c-0379-4a9e-a3b5-484deecc126d@github.com>
 <EwsdxKCc8SbDHVuyogkAVl-m-szxs8KXsn5N7sNwhRc=.bca17935-2c43-4c54-bace-f16384ebc73f@github.com>
 <8d-hTg9TbPu4vzPKCeqkzqTA05x8UFei7fiWjnXZXCk=.525357c5-7aa8-498a-9ab7-202b69b2a565@github.com>
Message-ID: <Pm_Xia8hMH0kXC-yhBBDPJly-mRCMLxEckncEIsEe60=.27387fc3-7b48-4fec-8734-ffd755a72525@github.com>

On Mon, 24 Jan 2022 18:58:07 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> I'll take a look.
>
> I think it helps to keep them separate ... and the text is adjacent.
> 
> "Other Doclets" is somewhat more about why you might not want to write a doclet these days ... it's addressing the historical past where there were lots of doclets, a lot of which did not even look at doc comments ... i.e they were using the Doclet API as an early Language Model API.

Fine with me. Your explanation makes sense, another bit of history learned.

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

PR: https://git.openjdk.java.net/jdk/pull/6914

From jjg at openjdk.java.net  Mon Jan 24 20:45:06 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 20:45:06 GMT
Subject: RFR: JDK-8280402: Add new convenience forms to HtmlTree
In-Reply-To: <2REVhhXT1qK6joxztP8WG50zl_xG1dpbSzx9jQP7KAA=.25ef14f2-73a9-4883-b95a-e5b3bad59cf4@github.com>
References: <g2KIDj0C72bGmmLU37plIACtuDvYK5Yyrf30HJAsWts=.77af4827-430d-4f7b-b89d-8723706a4dc6@github.com>
 <1EI4OvDsEuMDgFTbbtYoZbf35Zqq22Wn0fwaeDXJVnE=.c82e0f81-d899-46b4-a273-8ad944281efa@github.com>
 <2REVhhXT1qK6joxztP8WG50zl_xG1dpbSzx9jQP7KAA=.25ef14f2-73a9-4883-b95a-e5b3bad59cf4@github.com>
Message-ID: <KGXO7ikpe-RJb4DFtFttr7U7PYwIaDM9hBqyJB2M-Yw=.f9dd6d6a-2fdd-4371-9617-50c7d472133e@github.com>

On Mon, 24 Jan 2022 19:59:59 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java line 240:
>> 
>>> 238:         list.forEach(item -> add(mapper.apply(item)));
>>> 239:         return this;
>>> 240:     }
>> 
>> We could move this implementation of `addAll` to the `Content` base class as it is except for changing the return type to `Content`. This would make the method available in other subclasses that override/support `add(Content)`, such as `ContentBuilder`. The only observable change would be that it wouldn't throw `UnsupportedOperationException` when called with an empty collection in non-addable classes.  I think that's an acceptable behaviour for an internal API.
>
> Another observable change would be that the method could not be used in method chaining, because of the different return type.  But having the method applicable at least in a limited form in ContentBuilder would be nice, but that suggests leaving a covariant override here.

Another reason to make a minor update ... the doc comment on the method in Content is incorrect ... the `@implSpec` is wrong.

I'll copy (not move) the implementation from `HtmlTree` to `Content`.

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

PR: https://git.openjdk.java.net/jdk/pull/7166

From jjg at openjdk.java.net  Mon Jan 24 20:48:11 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 20:48:11 GMT
Subject: RFR: 8268978: Document the javadoc software stack
In-Reply-To: <Pm_Xia8hMH0kXC-yhBBDPJly-mRCMLxEckncEIsEe60=.27387fc3-7b48-4fec-8734-ffd755a72525@github.com>
References: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
 <Sh3R6l8-ZamiOddaQ7XokZrkGeuSb1tHT18npYoW0KU=.48f6713c-0379-4a9e-a3b5-484deecc126d@github.com>
 <EwsdxKCc8SbDHVuyogkAVl-m-szxs8KXsn5N7sNwhRc=.bca17935-2c43-4c54-bace-f16384ebc73f@github.com>
 <8d-hTg9TbPu4vzPKCeqkzqTA05x8UFei7fiWjnXZXCk=.525357c5-7aa8-498a-9ab7-202b69b2a565@github.com>
 <Pm_Xia8hMH0kXC-yhBBDPJly-mRCMLxEckncEIsEe60=.27387fc3-7b48-4fec-8734-ffd755a72525@github.com>
Message-ID: <R8elsyltuCAqO6P0krVwpZHAh5BZNS6AtgZOclkhgiw=.958e5a62-19b1-4f11-9b64-7f822eec5f8c@github.com>

On Mon, 24 Jan 2022 20:22:12 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> I think it helps to keep them separate ... and the text is adjacent.
>> 
>> "Other Doclets" is somewhat more about why you might not want to write a doclet these days ... it's addressing the historical past where there were lots of doclets, a lot of which did not even look at doc comments ... i.e they were using the Doclet API as an early Language Model API.
>
> Fine with me. Your explanation makes sense, another bit of history learned.

I'd forgotten, until now, there is a more detailed version of this text on the OpenJDK website.  I'll leave all the text here, but add an `@see`

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

PR: https://git.openjdk.java.net/jdk/pull/6914

From jjg at openjdk.java.net  Mon Jan 24 20:51:44 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 20:51:44 GMT
Subject: RFR: JDK-8280402: Add new convenience forms to HtmlTree [v2]
In-Reply-To: <g2KIDj0C72bGmmLU37plIACtuDvYK5Yyrf30HJAsWts=.77af4827-430d-4f7b-b89d-8723706a4dc6@github.com>
References: <g2KIDj0C72bGmmLU37plIACtuDvYK5Yyrf30HJAsWts=.77af4827-430d-4f7b-b89d-8723706a4dc6@github.com>
Message-ID: <g3kBbLsV6oU6ZPAr-6QWMPRSWetOUGbngl4e0pBi-Ms=.9f3b7455-2b03-409b-9e30-5acc779c0806@github.com>

> Please review a simple `noreg-clean` update to `HtmlTree` and a couple of friends.  The updates are to continue the trend towards the use of Facebook tory methods for `HtmlTree` objects, and to leverage generic methods and lambdas to generate composite content. The cleanup is mostly extracted from some parallel work for a separate PR.  Some of the more general cleanup was suggested by an IDE.
> 
> All javadoc tests pass locally; I have a job in  progress to validate the fix on all platforms, although there is no reason to believe there might be any issues.

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

  fix whitespace

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7166/files
  - new: https://git.openjdk.java.net/jdk/pull/7166/files/58a63f32..75a69eae

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7166&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7166&range=00-01

  Stats: 9 lines in 2 files changed: 3 ins; 1 del; 5 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7166.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7166/head:pull/7166

PR: https://git.openjdk.java.net/jdk/pull/7166

From jjg at openjdk.java.net  Mon Jan 24 20:57:48 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 20:57:48 GMT
Subject: RFR: 8268978: Document the javadoc software stack [v2]
In-Reply-To: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
References: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
Message-ID: <B1TApuAnT1N2pGMAtlw_j8El3F-EMQ5eTBn9O9rm7R0=.0247f40c-d35d-4a8b-a5bb-2fb4ea7ebf4c@github.com>

> Please review a `noreg-doc` update to document the javadoc software stack, in the top-level `jdk.javadoc.internal` package.
> 
> The intent is to provide a broad overview.   We can add more specific details, but in general, additional details would probably be better in the `package-info` files for the constituent packages.

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

  Added some @see links

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/6914/files
  - new: https://git.openjdk.java.net/jdk/pull/6914/files/f3323251..95d4729f

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=6914&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=6914&range=00-01

  Stats: 4 lines in 1 file changed: 4 ins; 0 del; 0 mod
  Patch: https://git.openjdk.java.net/jdk/pull/6914.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/6914/head:pull/6914

PR: https://git.openjdk.java.net/jdk/pull/6914

From jjg at openjdk.java.net  Mon Jan 24 20:59:13 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 20:59:13 GMT
Subject: Withdrawn: JDK-8272984: javadoc support for SOURCE_DATE_EPOCH
In-Reply-To: <Gdqjj3DMB6Kuq37oAy6bekv2izi0BpPI1p80w66w_HA=.cfeabb57-432a-4eee-9a4f-fc37a660a4fe@github.com>
References: <Gdqjj3DMB6Kuq37oAy6bekv2izi0BpPI1p80w66w_HA=.cfeabb57-432a-4eee-9a4f-fc37a660a4fe@github.com>
Message-ID: <JcqYxIVu91AqUXbB4t4pPDwlz06KWB1j-UV-as2r84U=.873dbd16-ed85-432e-bac3-d012ece587d9@github.com>

On Tue, 21 Dec 2021 03:37:27 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a relatively simple patch to support the standard SOURCE_DATE_EPOCH environment variable, used by those who are interested in reproducible builds. (See https://reproducible-builds.org)

This pull request has been closed without being integrated.

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

PR: https://git.openjdk.java.net/jdk/pull/6905

From jjg at openjdk.java.net  Mon Jan 24 21:03:10 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 21:03:10 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <EC7EpzmFX_SUIUuBhL-LGx1xCG9ue6qmpacDqHL9rQs=.f093857a-7eda-47b0-bda1-c1c96640591a@github.com>
 <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>
Message-ID: <wilwxXpymTp8mOxsumVI5p0_qHgKaCqajyyVOYIkaOY=.4e8588ec-27e1-494c-90a4-17a25a53a460@github.com>

On Mon, 24 Jan 2022 15:06:31 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   change allowable date range to within 10 years of the time of use
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java line 171:
> 
>> 169: 
>> 170:     /**
>> 171:      * TRhe build date, to be recorded in generated files.
> 
> Typo: TRhe

Fixed

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Mon Jan 24 21:03:11 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 21:03:11 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <uXNcfyMo7XjYiep6wTwsV01tPqHJ0n-erA_oH_8HtiY=.45353a29-5f07-4500-9c87-80689587cd59@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <EC7EpzmFX_SUIUuBhL-LGx1xCG9ue6qmpacDqHL9rQs=.f093857a-7eda-47b0-bda1-c1c96640591a@github.com>
 <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>
 <uXNcfyMo7XjYiep6wTwsV01tPqHJ0n-erA_oH_8HtiY=.45353a29-5f07-4500-9c87-80689587cd59@github.com>
Message-ID: <QIvRK8k3Xz9YXgfX1-6iV5vh90E2gHM1QRnjEluBAxA=.8ac5c011-a707-4d7c-bd48-e3e380d77776@github.com>

On Mon, 24 Jan 2022 19:02:05 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 433:
>> 
>>> 431: doclet.usage.date.description=\
>>> 432:     Specifies the value to be used to timestamp the generated\n\
>>> 433:     pages, in ISO_ZONED_DATE_TIME format
>> 
>> I guess it is technically correct to use  a `DateTimeFormatter` constant name here, but wouldn't it be better form to use a generic term like "ISO-8601 format"?
>
> Yeah, you're right, that would be better, and sufficient.

Fixed

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Mon Jan 24 21:20:38 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 24 Jan 2022 21:20:38 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v3]
In-Reply-To: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
Message-ID: <7L1BRAzfk0HmAz3prjiU5nUVBsy4k27Y_hzJ0fHjCIQ=.1a4d93b7-0a68-49c7-a131-df84ff510b8c@github.com>

> Please review a javadoc update to support a new `--date` option to support reproducible builds.
> 
> This pull request supersedes https://github.com/openjdk/jdk/pull/6905. In that PR, the `SOURCE_DATE_EPOCH` environment variable was used to provide the time stamp, but review feedback suggested the use of a new command-line option, `--date`.  The format of the argument of the `--date` option is that same as that of similar options for the _jar_ and _jmod_ tools, and the code to handle the value is based on code in the _jar_ tool.

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

  Fix typo
  Improve command-line help message
  Clean up imports in new test

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7171/files
  - new: https://git.openjdk.java.net/jdk/pull/7171/files/65ab48ed..037cabbf

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7171&range=02
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7171&range=01-02

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From hannesw at openjdk.java.net  Tue Jan 25 11:08:34 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 25 Jan 2022 11:08:34 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <uXNcfyMo7XjYiep6wTwsV01tPqHJ0n-erA_oH_8HtiY=.45353a29-5f07-4500-9c87-80689587cd59@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <EC7EpzmFX_SUIUuBhL-LGx1xCG9ue6qmpacDqHL9rQs=.f093857a-7eda-47b0-bda1-c1c96640591a@github.com>
 <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>
 <uXNcfyMo7XjYiep6wTwsV01tPqHJ0n-erA_oH_8HtiY=.45353a29-5f07-4500-9c87-80689587cd59@github.com>
Message-ID: <QvJeWLdNdLGa45v07YOfou53srylM4MvhxCDZNFPfvU=.5c827ea6-fe65-4e2b-9624-f9b78235a32d@github.com>

On Mon, 24 Jan 2022 19:04:18 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 370:
>> 
>>> 368:                         try {
>>> 369:                             date = ZonedDateTime.parse(arg, DateTimeFormatter.ISO_ZONED_DATE_TIME)
>>> 370:                                     .withZoneSameInstant(ZoneOffset.UTC);
>> 
>> I notice that the new option takes a date-time with timezone, but the timezone is discarded here (and the date-time is later converted to a java.util.Date). Since the purpose of this change is to enable reproducible builds, I guess it should be possible to define the timezone used in the "Generated by" comment (which as far as I can tell is the timezone of the local host).
>
> I went out of my way to ensure that the _output_ form was not affected, in case there is anyone relying on the existing format ... and yes, we have tests for that as well.
> 
> I'd be open to formally changing the format of the output timestamp, but I think that should be a separate RFE.

What I meant was not to change the format used in javadoc output but rather to preserve the time zone of the timestamp passed as `--date` option argument. Since `java.util.Date.toString()` always uses the default time zone, to reproduce a documentation bundle generated in a different time zone one would have to set the default time zone in addition to using the `--date` option. This could be avoided by retaining the `ZonedDateTime` with the original time zone instead of converting it to a `java.util.Date`. The following `DateTimeFormatter` instance could then be used to generate a timestamp string identical to the one produced by `Date.toString()` but with the correct time zone:

     DateTimeFormatter.ofPattern("EEE MMM dd HH:mm:ss zzz yyyy").withLocale(Locale.US);

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Tue Jan 25 18:06:35 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 25 Jan 2022 18:06:35 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v2]
In-Reply-To: <QvJeWLdNdLGa45v07YOfou53srylM4MvhxCDZNFPfvU=.5c827ea6-fe65-4e2b-9624-f9b78235a32d@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <EC7EpzmFX_SUIUuBhL-LGx1xCG9ue6qmpacDqHL9rQs=.f093857a-7eda-47b0-bda1-c1c96640591a@github.com>
 <b26qyj9fp6cl9URsLFE1JNsZF_xbRC9U73eFALhCUyo=.ac068b45-f206-4401-8136-06024a364087@github.com>
 <uXNcfyMo7XjYiep6wTwsV01tPqHJ0n-erA_oH_8HtiY=.45353a29-5f07-4500-9c87-80689587cd59@github.com>
 <QvJeWLdNdLGa45v07YOfou53srylM4MvhxCDZNFPfvU=.5c827ea6-fe65-4e2b-9624-f9b78235a32d@github.com>
Message-ID: <NvpWUQ7SDHLJbI0o2_qHxUJnDmzkx4EIZBUy2_enea4=.904d2d67-5e4c-48d0-9822-d94f1140d46d@github.com>

On Tue, 25 Jan 2022 11:04:42 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> I went out of my way to ensure that the _output_ form was not affected, in case there is anyone relying on the existing format ... and yes, we have tests for that as well.
>> 
>> I'd be open to formally changing the format of the output timestamp, but I think that should be a separate RFE.
>
> What I meant was not to change the format used in javadoc output but rather to preserve the time zone of the timestamp passed as `--date` option argument. Since `java.util.Date.toString()` always uses the default time zone, to reproduce a documentation bundle generated in a different time zone one would have to set the default time zone in addition to using the `--date` option. This could be avoided by retaining the `ZonedDateTime` with the original time zone instead of converting it to a `java.util.Date`. The following `DateTimeFormatter` instance could then be used to generate a timestamp string identical to the one produced by `Date.toString()` but with the correct time zone:
> 
>      DateTimeFormatter.ofPattern("EEE MMM dd HH:mm:ss zzz yyyy").withLocale(Locale.US);

Thanks for the suggestio; that helps.

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Tue Jan 25 19:43:08 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 25 Jan 2022 19:43:08 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v4]
In-Reply-To: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
Message-ID: <QGGBaEgMPTpyAJ069FaNOe56GTZ0cmcKZXZGPRD8C48=.da72a11c-a4e9-4dd5-828a-b32027695b0c@github.com>

> Please review a javadoc update to support a new `--date` option to support reproducible builds.
> 
> This pull request supersedes https://github.com/openjdk/jdk/pull/6905. In that PR, the `SOURCE_DATE_EPOCH` environment variable was used to provide the time stamp, but review feedback suggested the use of a new command-line option, `--date`.  The format of the argument of the `--date` option is that same as that of similar options for the _jar_ and _jmod_ tools, and the code to handle the value is based on code in the _jar_ tool.

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

  Address review feedback: propagate time zone

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7171/files
  - new: https://git.openjdk.java.net/jdk/pull/7171/files/037cabbf..8e45739b

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7171&range=03
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7171&range=02-03

  Stats: 36 lines in 4 files changed: 10 ins; 1 del; 25 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7171.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7171/head:pull/7171

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Wed Jan 26 02:28:04 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 26 Jan 2022 02:28:04 GMT
Subject: RFR: JDK-8280488: doclint reference checks withstand warning
 suppression
Message-ID: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>

Please review a small modification to the way that bad references are reported by DocLint.

A new "mode" is introduced, `strictReferenceChecks`.   

If the mode is _not_ set, references that explicitly include a module name when that module name is not resolved in the module graph will be reported with a (suppressible) warning instead of an error.  All other issues with references will be reported as errors. This is the mode used by javac.

If the mode is set, all issues with references will be reported as errors. This is the mode used by javadoc.

This will need to be documented in the tool guide (man page).

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

Commit messages:
 - JDK-8280488: doclint reference checks withstand warning suppression

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

PR: https://git.openjdk.java.net/jdk/pull/7222

From darcy at openjdk.java.net  Wed Jan 26 02:49:35 2022
From: darcy at openjdk.java.net (Joe Darcy)
Date: Wed, 26 Jan 2022 02:49:35 GMT
Subject: RFR: JDK-8280488: doclint reference checks withstand warning
 suppression
In-Reply-To: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>
References: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>
Message-ID: <3U1ZhzST2-RL1c7FYYtsMg64mWf6FCDd9gSO297jGm8=.3ff79cbe-fdd0-418b-819e-dd1e8662d091@github.com>

On Wed, 26 Jan 2022 02:20:24 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small modification to the way that bad references are reported by DocLint.
> 
> A new "mode" is introduced, `strictReferenceChecks`.   
> 
> If the mode is _not_ set, references that explicitly include a module name when that module name is not resolved in the module graph will be reported with a (suppressible) warning instead of an error.  All other issues with references will be reported as errors. This is the mode used by javac.
> 
> If the mode is set, all issues with references will be reported as errors. This is the mode used by javadoc.
> 
> This will need to be documented in the tool guide (man page).

Question: for the JDK use case in particular, to turn all the doclint warning on during compilation, the cross-module references need to be SuppressWarning'ed?

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

PR: https://git.openjdk.java.net/jdk/pull/7222

From hannesw at openjdk.java.net  Wed Jan 26 11:34:31 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Jan 2022 11:34:31 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v4]
In-Reply-To: <QGGBaEgMPTpyAJ069FaNOe56GTZ0cmcKZXZGPRD8C48=.da72a11c-a4e9-4dd5-828a-b32027695b0c@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <QGGBaEgMPTpyAJ069FaNOe56GTZ0cmcKZXZGPRD8C48=.da72a11c-a4e9-4dd5-828a-b32027695b0c@github.com>
Message-ID: <qX5Zgo7PWfnl1_YzSm_ve9Et6uJ_RgOKjP0HwTXE8No=.4b867529-410d-4bf6-b304-328f20e39cd6@github.com>

On Tue, 25 Jan 2022 19:43:08 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a javadoc update to support a new `--date` option to support reproducible builds.
>> 
>> This pull request supersedes https://github.com/openjdk/jdk/pull/6905. In that PR, the `SOURCE_DATE_EPOCH` environment variable was used to provide the time stamp, but review feedback suggested the use of a new command-line option, `--date`.  The format of the argument of the `--date` option is that same as that of similar options for the _jar_ and _jmod_ tools, and the code to handle the value is based on code in the _jar_ tool.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Address review feedback: propagate time zone

Looks good to me.

The CSR should be updated to reflect the changed option help message. Talking about that change: I'm a bit unsure about it, as ISO 8601 does not include the optional zone ID, which is an extension in `DateTimeFormatter.ISO_ZONED_DATE_TIME`. So maybe the previous message was more correct and useful after all?

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Wed Jan 26 15:46:35 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 26 Jan 2022 15:46:35 GMT
Subject: RFR: JDK-8272984: javadoc support for reproducible builds [v4]
In-Reply-To: <qX5Zgo7PWfnl1_YzSm_ve9Et6uJ_RgOKjP0HwTXE8No=.4b867529-410d-4bf6-b304-328f20e39cd6@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
 <QGGBaEgMPTpyAJ069FaNOe56GTZ0cmcKZXZGPRD8C48=.da72a11c-a4e9-4dd5-828a-b32027695b0c@github.com>
 <qX5Zgo7PWfnl1_YzSm_ve9Et6uJ_RgOKjP0HwTXE8No=.4b867529-410d-4bf6-b304-328f20e39cd6@github.com>
Message-ID: <Guyk6bsSCDLwEfUMSh3715kB3qSi-k31SRHbVFCqK0o=.f1589f63-96d7-4b23-a6e0-98acefdc66df@github.com>

On Wed, 26 Jan 2022 11:31:06 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Looks good to me.
> 
> The CSR should be updated to reflect the changed option help message. Talking about that change: I'm a bit unsure about it, as ISO 8601 does not include the optional zone ID, which is an extension in `DateTimeFormatter.ISO_ZONED_DATE_TIME`. So maybe the previous message was more correct and useful after all?

The tool guide (man page) is a good place to discuss the exact format, give examples, and maybe even tie it back to SOURCE_DATE_EPOCH.

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From jjg at openjdk.java.net  Wed Jan 26 16:46:23 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 26 Jan 2022 16:46:23 GMT
Subject: RFR: JDK-8280488: doclint reference checks withstand warning
 suppression [v2]
In-Reply-To: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>
References: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>
Message-ID: <3SMZQb4sjR_F1xktjg2EEXwx0fH6E6NK9qC-Zx3Lsdg=.b511cc8b-bdb7-4395-bf46-ebd5f916d8c5@github.com>

> Please review a small modification to the way that bad references are reported by DocLint.
> 
> A new "mode" is introduced, `strictReferenceChecks`.   
> 
> If the mode is _not_ set, references that explicitly include a module name when that module name is not resolved in the module graph will be reported with a (suppressible) warning instead of an error.  All other issues with references will be reported as errors. This is the mode used by javac.
> 
> If the mode is set, all issues with references will be reported as errors. This is the mode used by javadoc.
> 
> This will need to be documented in the tool guide (man page).

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

  fix typos

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7222/files
  - new: https://git.openjdk.java.net/jdk/pull/7222/files/a529be49..d27de5de

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7222&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7222&range=00-01

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

PR: https://git.openjdk.java.net/jdk/pull/7222

From jjg at openjdk.java.net  Wed Jan 26 17:00:34 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 26 Jan 2022 17:00:34 GMT
Subject: RFR: JDK-8280488: doclint reference checks withstand warning
 suppression
In-Reply-To: <3U1ZhzST2-RL1c7FYYtsMg64mWf6FCDd9gSO297jGm8=.3ff79cbe-fdd0-418b-819e-dd1e8662d091@github.com>
References: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>
 <3U1ZhzST2-RL1c7FYYtsMg64mWf6FCDd9gSO297jGm8=.3ff79cbe-fdd0-418b-819e-dd1e8662d091@github.com>
Message-ID: <oiHg2qnvmER4O6Q6ehgFGSqqCQQr3jccDrux2wyyXmY=.159d6d22-5076-4156-bcc2-676ab7d385fc@github.com>

On Wed, 26 Jan 2022 02:46:45 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Question: for the JDK use case in particular, to turn all the doclint warning on during compilation, the cross-module references need to be SuppressWarning'ed?

Only forward references, where the target module is not on the module path, will need a `@SuppressWarnings` annotation.  (For example, a reference to `java.desktop` from `java.base`.   If the cross-module reference is to a module that is on the module path, you will get an error if the reference as whole cannot be resolved. (For a reference to `java.base/java.lang.OObject`  in `java.desktop` (or any module) will always cause an error.

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

PR: https://git.openjdk.java.net/jdk/pull/7222

From jjg at openjdk.java.net  Wed Jan 26 17:13:43 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 26 Jan 2022 17:13:43 GMT
Subject: Integrated: 8268978: Document the javadoc software stack
In-Reply-To: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
References: <fyHc3agWVpg0bPd3xT4BLdtDD8hratoMxEPmCsAcIqk=.6b4d34df-fdc4-48d5-a4be-d1f9da055fdc@github.com>
Message-ID: <mbw-6EIvOyWoter92GdFy6uGXZTMBeNUyGtBNYXYNYo=.ec6b56d5-5ff2-4edb-8fab-e169d2b0414c@github.com>

On Wed, 22 Dec 2021 00:48:08 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a `noreg-doc` update to document the javadoc software stack, in the top-level `jdk.javadoc.internal` package.
> 
> The intent is to provide a broad overview.   We can add more specific details, but in general, additional details would probably be better in the `package-info` files for the constituent packages.

This pull request has now been integrated.

Changeset: b8365aa4
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/b8365aa48599a318c426c2ec4ffb3f296ffdbd73
Stats:     132 lines in 1 file changed: 125 ins; 0 del; 7 mod

8268978: Document the javadoc software stack

Reviewed-by: hannesw

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

PR: https://git.openjdk.java.net/jdk/pull/6914

From jjg at openjdk.java.net  Wed Jan 26 17:13:42 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 26 Jan 2022 17:13:42 GMT
Subject: Integrated: JDK-8280402: Add new convenience forms to HtmlTree
In-Reply-To: <g2KIDj0C72bGmmLU37plIACtuDvYK5Yyrf30HJAsWts=.77af4827-430d-4f7b-b89d-8723706a4dc6@github.com>
References: <g2KIDj0C72bGmmLU37plIACtuDvYK5Yyrf30HJAsWts=.77af4827-430d-4f7b-b89d-8723706a4dc6@github.com>
Message-ID: <NwCo9Wi4ljtkCkSos8AH0R5mp5MRDSsIi7jtCfgl1To=.76d98793-3977-4532-b5d1-c0c918e15053@github.com>

On Thu, 20 Jan 2022 19:31:41 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple `noreg-clean` update to `HtmlTree` and a couple of friends.  The updates are to continue the trend towards the use of Facebook tory methods for `HtmlTree` objects, and to leverage generic methods and lambdas to generate composite content. The cleanup is mostly extracted from some parallel work for a separate PR.  Some of the more general cleanup was suggested by an IDE.
> 
> All javadoc tests pass locally; I have a job in  progress to validate the fix on all platforms, although there is no reason to believe there might be any issues.

This pull request has now been integrated.

Changeset: e1d8f555
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/e1d8f555644e7766811bda1468af3f7f3d3f4239
Stats:     176 lines in 3 files changed: 102 ins; 22 del; 52 mod

8280402: Add new convenience forms to HtmlTree

Reviewed-by: hannesw

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

PR: https://git.openjdk.java.net/jdk/pull/7166

From jjg at openjdk.java.net  Wed Jan 26 18:51:52 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 26 Jan 2022 18:51:52 GMT
Subject: RFR: JDK-8280738: Minor cleanup for HtmlStyle
Message-ID: <6qF9241SxFw14__RCaj-3s1vlWb5oTa2HFZ48jrhXW8=.b6bbc169-57a1-4002-9879-095e5622628b@github.com>

Please review a simple update to reorder some members of the enum `HtmlStyle`, and to make some minor updates to the comments.

This is to facilitate automated extraction of information into an upcoming new spec for the output from the standard doclet.

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

Commit messages:
 - JDK-8280738: Minor cleanup for HtmlStyle

Changes: https://git.openjdk.java.net/jdk/pull/7235/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=7235&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8280738
  Stats: 82 lines in 1 file changed: 54 ins; 26 del; 2 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7235.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7235/head:pull/7235

PR: https://git.openjdk.java.net/jdk/pull/7235

From darcy at openjdk.java.net  Wed Jan 26 20:11:57 2022
From: darcy at openjdk.java.net (Joe Darcy)
Date: Wed, 26 Jan 2022 20:11:57 GMT
Subject: RFR: JDK-8280534: Enable compile-time doclint reference checking
Message-ID: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>

The changes in this PR on top of the out-for-review changes in https://git.openjdk.java.net/jdk/pull/7222 allow compile-time doclint checking to be enabled in all JDK modules.

Typically, a @SuppressWarnings("doclint:refernce") annotation is added to declaration with javadoc blocks that have already had distinguished cross-module links added (JDK-8280492).

One exception is in src/java.base/share/classes/java/net/package-info.java where the cross-module link was (for now) removed. Currently the SuppressWarnings annotation type is not declared to allow its annotations to be applied to package declarations. I'll look into amending that, but in the mean time, I think it is beneficial for the JDK build, and the base module in particular, to have compile-time doclint protections turned on.

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

Commit messages:
 - Cover java.base.
 - JDK-8280534: Enable compile-time doclint reference checking

Changes: https://git.openjdk.java.net/jdk/pull/7237/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=7237&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8280534
  Stats: 28 lines in 21 files changed: 20 ins; 0 del; 8 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7237.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7237/head:pull/7237

PR: https://git.openjdk.java.net/jdk/pull/7237

From serb at openjdk.java.net  Wed Jan 26 20:30:31 2022
From: serb at openjdk.java.net (Sergey Bylokhov)
Date: Wed, 26 Jan 2022 20:30:31 GMT
Subject: RFR: JDK-8280534: Enable compile-time doclint reference checking
In-Reply-To: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
References: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
Message-ID: <f-_Q8ppKeB2sDaXGiX5h76KOgHpDW90wzl48xQYnddU=.a12d3439-900e-4616-a950-468e801814e1@github.com>

On Wed, 26 Jan 2022 20:05:07 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> The changes in this PR on top of the out-for-review changes in https://git.openjdk.java.net/jdk/pull/7222 allow compile-time doclint checking to be enabled in all JDK modules.
> 
> Typically, a @SuppressWarnings("doclint:refernce") annotation is added to declaration with javadoc blocks that have already had distinguished cross-module links added (JDK-8280492).
> 
> One exception is in src/java.base/share/classes/java/net/package-info.java where the cross-module link was (for now) removed. Currently the SuppressWarnings annotation type is not declared to allow its annotations to be applied to package declarations. I'll look into amending that, but in the mean time, I think it is beneficial for the JDK build, and the base module in particular, to have compile-time doclint protections turned on.

Marked as reviewed by serb (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/7237

From jjg at openjdk.java.net  Thu Jan 27 01:39:44 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 27 Jan 2022 01:39:44 GMT
Subject: RFR: JDK-8279486: jdk/javadoc/tool/CheckManPageOptions.java depends on
 source hierarchy
Message-ID: <CPfX1w29YuJl0Ax1jryOLedbzvvlb5-aCATCYSoFP9Y=.4f0e6ece-7ff0-40e9-8c29-7f6013600ef7@github.com>

Please review a small test update to have this test pass if the main`src/` directory cannot be found. (Yes, apparently that happens in some testing scenarios.)

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

Commit messages:
 - JDK-8279486: jdk/javadoc/tool/CheckManPageOptions.java depends on source hierarchy

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

PR: https://git.openjdk.java.net/jdk/pull/7240

From hannesw at openjdk.java.net  Thu Jan 27 10:05:28 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 27 Jan 2022 10:05:28 GMT
Subject: RFR: JDK-8279486: jdk/javadoc/tool/CheckManPageOptions.java
 depends on source hierarchy
In-Reply-To: <CPfX1w29YuJl0Ax1jryOLedbzvvlb5-aCATCYSoFP9Y=.4f0e6ece-7ff0-40e9-8c29-7f6013600ef7@github.com>
References: <CPfX1w29YuJl0Ax1jryOLedbzvvlb5-aCATCYSoFP9Y=.4f0e6ece-7ff0-40e9-8c29-7f6013600ef7@github.com>
Message-ID: <0igURYr_c0LGHSDOc75dTJhs9TenllyQYeJxZT-XBBA=.eadad929-8d2a-47a1-b985-d8594f10c8d8@github.com>

On Thu, 27 Jan 2022 01:31:52 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small test update to have this test pass if the main`src/` directory cannot be found. (Yes, apparently that happens in some testing scenarios.)

Looks good to me.

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7240

From hannesw at openjdk.java.net  Thu Jan 27 10:46:35 2022
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 27 Jan 2022 10:46:35 GMT
Subject: RFR: JDK-8280738: Minor cleanup for HtmlStyle
In-Reply-To: <6qF9241SxFw14__RCaj-3s1vlWb5oTa2HFZ48jrhXW8=.b6bbc169-57a1-4002-9879-095e5622628b@github.com>
References: <6qF9241SxFw14__RCaj-3s1vlWb5oTa2HFZ48jrhXW8=.b6bbc169-57a1-4002-9879-095e5622628b@github.com>
Message-ID: <4P2oNMYBuO0_Mm_QbBqmiRe0molLcUu1dIrUhu0M_yw=.ac18e23f-4b72-44ad-9325-639a948a80b3@github.com>

On Wed, 26 Jan 2022 18:45:15 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple update to reorder some members of the enum `HtmlStyle`, and to make some minor updates to the comments.
> 
> This is to facilitate automated extraction of information into an upcoming new spec for the output from the standard doclet.

Looks good. The `@apiNote` regarding editor-folds could be improved (missing parenthesis).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java line 53:

> 51:  * @apiNote
> 52:  * The stylized use of {@code editor-fold} comments and line comments (beginning {@code //}
> 53:  * is to support extracting details of declarations with external tools.  Edit with care!

Missing closing parenthesis

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7235

From jjg at openjdk.java.net  Thu Jan 27 22:03:18 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 27 Jan 2022 22:03:18 GMT
Subject: Integrated: JDK-8280835: jdk/javadoc/tool/CheckManPageOptions.java
 depends on source hierarchy
In-Reply-To: <CPfX1w29YuJl0Ax1jryOLedbzvvlb5-aCATCYSoFP9Y=.4f0e6ece-7ff0-40e9-8c29-7f6013600ef7@github.com>
References: <CPfX1w29YuJl0Ax1jryOLedbzvvlb5-aCATCYSoFP9Y=.4f0e6ece-7ff0-40e9-8c29-7f6013600ef7@github.com>
Message-ID: <BVk4tiXQ68p64-MJvxbscYZKmNSrSSegMKrqrtRF14Q=.e17e4b4f-e770-437c-b3f9-c8e7d5bd433b@github.com>

On Thu, 27 Jan 2022 01:31:52 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small test update to have this test pass if the main`src/` directory cannot be found. (Yes, apparently that happens in some testing scenarios.)

This pull request has now been integrated.

Changeset: 6d242e40
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/6d242e406539e97bdd4da82c478db901942b770f
Stats:     8 lines in 1 file changed: 6 ins; 0 del; 2 mod

8280835: jdk/javadoc/tool/CheckManPageOptions.java depends on source hierarchy

Reviewed-by: hannesw

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

PR: https://git.openjdk.java.net/jdk/pull/7240

From naoto at openjdk.java.net  Fri Jan 28 00:08:21 2022
From: naoto at openjdk.java.net (Naoto Sato)
Date: Fri, 28 Jan 2022 00:08:21 GMT
Subject: RFR: JDK-8280534: Enable compile-time doclint reference checking
In-Reply-To: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
References: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
Message-ID: <1cfRNjI3cmzGOT_gioY8Gx0tFcPsFBEsxz5PClEVY7s=.e5c3c6fb-2602-4652-ada1-33577e60c139@github.com>

On Wed, 26 Jan 2022 20:05:07 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> The changes in this PR on top of the out-for-review changes in https://git.openjdk.java.net/jdk/pull/7222 allow compile-time doclint checking to be enabled in all JDK modules.
> 
> Typically, a @SuppressWarnings("doclint:refernce") annotation is added to declaration with javadoc blocks that have already had distinguished cross-module links added (JDK-8280492).
> 
> One exception is in src/java.base/share/classes/java/net/package-info.java where the cross-module link was (for now) removed. Currently the SuppressWarnings annotation type is not declared to allow its annotations to be applied to package declarations. I'll look into amending that, but in the mean time, I think it is beneficial for the JDK build, and the base module in particular, to have compile-time doclint protections turned on.

Looks fine. Nit: some files need copyright year updates.

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

Marked as reviewed by naoto (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/7237

From darcy at openjdk.java.net  Fri Jan 28 00:30:32 2022
From: darcy at openjdk.java.net (Joe Darcy)
Date: Fri, 28 Jan 2022 00:30:32 GMT
Subject: RFR: JDK-8280534: Enable compile-time doclint reference checking
In-Reply-To: <1cfRNjI3cmzGOT_gioY8Gx0tFcPsFBEsxz5PClEVY7s=.e5c3c6fb-2602-4652-ada1-33577e60c139@github.com>
References: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
 <1cfRNjI3cmzGOT_gioY8Gx0tFcPsFBEsxz5PClEVY7s=.e5c3c6fb-2602-4652-ada1-33577e60c139@github.com>
Message-ID: <YfDf_70NLxYgY1rjFvv3OZuoxP1J4NPlL24aursrflE=.123c2343-ffac-46da-bc58-7c2bbb0c1d9c@github.com>

On Fri, 28 Jan 2022 00:04:34 GMT, Naoto Sato <naoto at openjdk.org> wrote:

> Looks fine. Nit: some files need copyright year updates.

Acknowledged; I'll run a copyright update script before pushing (I tend to run that close to pushing to avoid spurious, if minor, merge conflicts). Thanks.

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

PR: https://git.openjdk.java.net/jdk/pull/7237

From mchung at openjdk.java.net  Fri Jan 28 01:54:16 2022
From: mchung at openjdk.java.net (Mandy Chung)
Date: Fri, 28 Jan 2022 01:54:16 GMT
Subject: RFR: JDK-8280534: Enable compile-time doclint reference checking
In-Reply-To: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
References: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
Message-ID: <AL4yOB03XoaFCW2gjDr2-rXao6QSM39kKroqkDq4WGs=.0395990c-1a77-4092-b6ff-91e8fc301ab7@github.com>

On Wed, 26 Jan 2022 20:05:07 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> The changes in this PR on top of the out-for-review changes in https://git.openjdk.java.net/jdk/pull/7222 allow compile-time doclint checking to be enabled in all JDK modules.
> 
> Typically, a @SuppressWarnings("doclint:refernce") annotation is added to declaration with javadoc blocks that have already had distinguished cross-module links added (JDK-8280492).
> 
> One exception is in src/java.base/share/classes/java/net/package-info.java where the cross-module link was (for now) removed. Currently the SuppressWarnings annotation type is not declared to allow its annotations to be applied to package declarations. I'll look into amending that, but in the mean time, I think it is beneficial for the JDK build, and the base module in particular, to have compile-time doclint protections turned on.

Marked as reviewed by mchung (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/7237

From darcy at openjdk.java.net  Fri Jan 28 02:12:11 2022
From: darcy at openjdk.java.net (Joe Darcy)
Date: Fri, 28 Jan 2022 02:12:11 GMT
Subject: RFR: JDK-8280488: doclint reference checks withstand warning
 suppression [v2]
In-Reply-To: <3SMZQb4sjR_F1xktjg2EEXwx0fH6E6NK9qC-Zx3Lsdg=.b511cc8b-bdb7-4395-bf46-ebd5f916d8c5@github.com>
References: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>
 <3SMZQb4sjR_F1xktjg2EEXwx0fH6E6NK9qC-Zx3Lsdg=.b511cc8b-bdb7-4395-bf46-ebd5f916d8c5@github.com>
Message-ID: <vscRM3GDbiawh7x162N_XkQncAZisNS74vCRPTQmZuY=.e0f04c01-6722-48d6-a8e8-5e8d640ad1ce@github.com>

On Wed, 26 Jan 2022 16:46:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a small modification to the way that bad references are reported by DocLint.
>> 
>> A new "mode" is introduced, `strictReferenceChecks`.   
>> 
>> If the mode is _not_ set, references that explicitly include a module name when that module name is not resolved in the module graph will be reported with a (suppressible) warning instead of an error.  All other issues with references will be reported as errors. This is the mode used by javac.
>> 
>> If the mode is set, all issues with references will be reported as errors. This is the mode used by javadoc.
>> 
>> This will need to be documented in the tool guide (man page).
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   fix typos

FYI, the build completes with the changes in this PR, expanding the target set of of SuppressWarnings (JDK-8280744), and https://github.com/openjdk/jdk/pull/7237.

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

PR: https://git.openjdk.java.net/jdk/pull/7222

From darcy at openjdk.java.net  Fri Jan 28 02:15:59 2022
From: darcy at openjdk.java.net (Joe Darcy)
Date: Fri, 28 Jan 2022 02:15:59 GMT
Subject: RFR: JDK-8280534: Enable compile-time doclint reference checking
 [v2]
In-Reply-To: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
References: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
Message-ID: <Fxy7myywOjnfKigO0p4stkgBamKAVF2EWGZBxTjkXFk=.7c12d6c1-eed4-4ce5-8f91-d00ca4248a31@github.com>

> The changes in this PR on top of the out-for-review changes in https://git.openjdk.java.net/jdk/pull/7222 allow compile-time doclint checking to be enabled in all JDK modules.
> 
> Typically, a @SuppressWarnings("doclint:refernce") annotation is added to declaration with javadoc blocks that have already had distinguished cross-module links added (JDK-8280492).
> 
> One exception is in src/java.base/share/classes/java/net/package-info.java where the cross-module link was (for now) removed. Currently the SuppressWarnings annotation type is not declared to allow its annotations to be applied to package declarations. I'll look into amending that, but in the mean time, I think it is beneficial for the JDK build, and the base module in particular, to have compile-time doclint protections turned on.

Joe Darcy 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 four additional commits since the last revision:

 - Use capabilities of JDK-8280744.
 - Merge branch 'master' into JDK-8280534
 - Cover java.base.
 - JDK-8280534: Enable compile-time doclint reference checking

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7237/files
  - new: https://git.openjdk.java.net/jdk/pull/7237/files/70e9fb4a..d03401c6

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7237&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7237&range=00-01

  Stats: 2743 lines in 129 files changed: 1556 ins; 659 del; 528 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7237.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7237/head:pull/7237

PR: https://git.openjdk.java.net/jdk/pull/7237

From lancea at openjdk.java.net  Fri Jan 28 11:48:13 2022
From: lancea at openjdk.java.net (Lance Andersen)
Date: Fri, 28 Jan 2022 11:48:13 GMT
Subject: RFR: JDK-8280534: Enable compile-time doclint reference checking
 [v2]
In-Reply-To: <Fxy7myywOjnfKigO0p4stkgBamKAVF2EWGZBxTjkXFk=.7c12d6c1-eed4-4ce5-8f91-d00ca4248a31@github.com>
References: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
 <Fxy7myywOjnfKigO0p4stkgBamKAVF2EWGZBxTjkXFk=.7c12d6c1-eed4-4ce5-8f91-d00ca4248a31@github.com>
Message-ID: <wqdys6-s4SEU1-g9Sps2cniJ0ZeFFEQUJF-YVF13gWo=.f8523bbf-101b-4f3b-af4f-743dbe7f206d@github.com>

On Fri, 28 Jan 2022 02:15:59 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> The changes in this PR on top of the out-for-review changes in https://git.openjdk.java.net/jdk/pull/7222 allow compile-time doclint checking to be enabled in all JDK modules.
>> 
>> Typically, a @SuppressWarnings("doclint:refernce") annotation is added to declaration with javadoc blocks that have already had distinguished cross-module links added (JDK-8280492).
>> 
>> One exception is in src/java.base/share/classes/java/net/package-info.java where the cross-module link was (for now) removed. Currently the SuppressWarnings annotation type is not declared to allow its annotations to be applied to package declarations. I'll look into amending that, but in the mean time, I think it is beneficial for the JDK build, and the base module in particular, to have compile-time doclint protections turned on.
>
> Joe Darcy 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 four additional commits since the last revision:
> 
>  - Use capabilities of JDK-8280744.
>  - Merge branch 'master' into JDK-8280534
>  - Cover java.base.
>  - JDK-8280534: Enable compile-time doclint reference checking

Marked as reviewed by lancea (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/7237

From darcy at openjdk.java.net  Fri Jan 28 18:03:11 2022
From: darcy at openjdk.java.net (Joe Darcy)
Date: Fri, 28 Jan 2022 18:03:11 GMT
Subject: RFR: JDK-8280488: doclint reference checks withstand warning
 suppression [v2]
In-Reply-To: <3SMZQb4sjR_F1xktjg2EEXwx0fH6E6NK9qC-Zx3Lsdg=.b511cc8b-bdb7-4395-bf46-ebd5f916d8c5@github.com>
References: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>
 <3SMZQb4sjR_F1xktjg2EEXwx0fH6E6NK9qC-Zx3Lsdg=.b511cc8b-bdb7-4395-bf46-ebd5f916d8c5@github.com>
Message-ID: <BQCOVTvCtSZdPFfdPDaldqmWXXWO32qFl-bDN5-cHyQ=.76af4b97-fdfa-4feb-9141-012f53c7cd92@github.com>

On Wed, 26 Jan 2022 16:46:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a small modification to the way that bad references are reported by DocLint.
>> 
>> A new "mode" is introduced, `strictReferenceChecks`.   
>> 
>> If the mode is _not_ set, references that explicitly include a module name when that module name is not resolved in the module graph will be reported with a (suppressible) warning instead of an error.  All other issues with references will be reported as errors. This is the mode used by javac.
>> 
>> If the mode is set, all issues with references will be reported as errors. This is the mode used by javadoc.
>> 
>> This will need to be documented in the tool guide (man page).
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   fix typos

Marked as reviewed by darcy (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/7222

From iris at openjdk.java.net  Fri Jan 28 18:12:11 2022
From: iris at openjdk.java.net (Iris Clark)
Date: Fri, 28 Jan 2022 18:12:11 GMT
Subject: RFR: JDK-8280534: Enable compile-time doclint reference checking
 [v2]
In-Reply-To: <Fxy7myywOjnfKigO0p4stkgBamKAVF2EWGZBxTjkXFk=.7c12d6c1-eed4-4ce5-8f91-d00ca4248a31@github.com>
References: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
 <Fxy7myywOjnfKigO0p4stkgBamKAVF2EWGZBxTjkXFk=.7c12d6c1-eed4-4ce5-8f91-d00ca4248a31@github.com>
Message-ID: <d1YTezrNDqic36vdPpueAkddkE5lghv2CAUSj17NdBQ=.10063564-830b-4001-89f4-034072d1fa28@github.com>

On Fri, 28 Jan 2022 02:15:59 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> The changes in this PR on top of the out-for-review changes in https://git.openjdk.java.net/jdk/pull/7222 allow compile-time doclint checking to be enabled in all JDK modules.
>> 
>> Typically, a @SuppressWarnings("doclint:refernce") annotation is added to declaration with javadoc blocks that have already had distinguished cross-module links added (JDK-8280492).
>> 
>> One exception is in src/java.base/share/classes/java/net/package-info.java where the cross-module link was (for now) removed. Currently the SuppressWarnings annotation type is not declared to allow its annotations to be applied to package declarations. I'll look into amending that, but in the mean time, I think it is beneficial for the JDK build, and the base module in particular, to have compile-time doclint protections turned on.
>
> Joe Darcy 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 four additional commits since the last revision:
> 
>  - Use capabilities of JDK-8280744.
>  - Merge branch 'master' into JDK-8280534
>  - Cover java.base.
>  - JDK-8280534: Enable compile-time doclint reference checking

Marked as reviewed by iris (Reviewer).

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

PR: https://git.openjdk.java.net/jdk/pull/7237

From jjg at openjdk.java.net  Mon Jan 31 22:41:10 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 31 Jan 2022 22:41:10 GMT
Subject: RFR: JDK-8280738: Minor cleanup for HtmlStyle
In-Reply-To: <4P2oNMYBuO0_Mm_QbBqmiRe0molLcUu1dIrUhu0M_yw=.ac18e23f-4b72-44ad-9325-639a948a80b3@github.com>
References: <6qF9241SxFw14__RCaj-3s1vlWb5oTa2HFZ48jrhXW8=.b6bbc169-57a1-4002-9879-095e5622628b@github.com>
 <4P2oNMYBuO0_Mm_QbBqmiRe0molLcUu1dIrUhu0M_yw=.ac18e23f-4b72-44ad-9325-639a948a80b3@github.com>
Message-ID: <EzcXZjdWUSS324gImjgBbkSZiIB6IV39HS7JghlJbqI=.c6352bc2-b68e-46be-91a9-fbeac3fc1800@github.com>

On Thu, 27 Jan 2022 10:22:20 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a simple update to reorder some members of the enum `HtmlStyle`, and to make some minor updates to the comments.
>> 
>> This is to facilitate automated extraction of information into an upcoming new spec for the output from the standard doclet.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java line 53:
> 
>> 51:  * @apiNote
>> 52:  * The stylized use of {@code editor-fold} comments and line comments (beginning {@code //}
>> 53:  * is to support extracting details of declarations with external tools.  Edit with care!
> 
> Missing closing parenthesis

Noted

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

PR: https://git.openjdk.java.net/jdk/pull/7235

From jjg at openjdk.java.net  Mon Jan 31 22:48:49 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 31 Jan 2022 22:48:49 GMT
Subject: RFR: JDK-8280738: Minor cleanup for HtmlStyle [v2]
In-Reply-To: <6qF9241SxFw14__RCaj-3s1vlWb5oTa2HFZ48jrhXW8=.b6bbc169-57a1-4002-9879-095e5622628b@github.com>
References: <6qF9241SxFw14__RCaj-3s1vlWb5oTa2HFZ48jrhXW8=.b6bbc169-57a1-4002-9879-095e5622628b@github.com>
Message-ID: <zBu1-aBFCcbLe6r9WUxiBafKZShXQTLWD0lxq1UZk00=.0d8f40a9-3e8a-4193-9ae7-ae45f3a83f0b@github.com>

> Please review a simple update to reorder some members of the enum `HtmlStyle`, and to make some minor updates to the comments.
> 
> This is to facilitate automated extraction of information into an upcoming new spec for the output from the standard doclet.

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

  fix missing paren

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7235/files
  - new: https://git.openjdk.java.net/jdk/pull/7235/files/df8c810e..0f8d94c5

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7235&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7235&range=00-01

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

PR: https://git.openjdk.java.net/jdk/pull/7235

From jjg at openjdk.java.net  Mon Jan 31 22:48:51 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 31 Jan 2022 22:48:51 GMT
Subject: Integrated: JDK-8280738: Minor cleanup for HtmlStyle
In-Reply-To: <6qF9241SxFw14__RCaj-3s1vlWb5oTa2HFZ48jrhXW8=.b6bbc169-57a1-4002-9879-095e5622628b@github.com>
References: <6qF9241SxFw14__RCaj-3s1vlWb5oTa2HFZ48jrhXW8=.b6bbc169-57a1-4002-9879-095e5622628b@github.com>
Message-ID: <D46iqwmMf4ZcUpPo_dOvAzfIEzytZF6L3qOtJnLGpHs=.0a0394ea-a5fe-4aa2-8f58-f6687c88582a@github.com>

On Wed, 26 Jan 2022 18:45:15 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple update to reorder some members of the enum `HtmlStyle`, and to make some minor updates to the comments.
> 
> This is to facilitate automated extraction of information into an upcoming new spec for the output from the standard doclet.

This pull request has now been integrated.

Changeset: 74921e84
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/74921e8422ce31a22516b279a00935b1917c089d
Stats:     82 lines in 1 file changed: 54 ins; 26 del; 2 mod

8280738: Minor cleanup for HtmlStyle

Reviewed-by: hannesw

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

PR: https://git.openjdk.java.net/jdk/pull/7235

From jjg at openjdk.java.net  Mon Jan 31 22:51:17 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 31 Jan 2022 22:51:17 GMT
Subject: Integrated: JDK-8280488: doclint reference checks withstand warning
 suppression
In-Reply-To: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>
References: <atHPmbzgHgIXMzM-flrHZOXU3YLd_qfUDay8iByBRgU=.6c832350-59c0-4ef7-b62e-68cdcbcf30f1@github.com>
Message-ID: <ug7NZFJh3VxCjYT5T27xb6GWqduhr0cJX7CgoJloOpc=.61db4557-1367-4d63-b0f7-25184d749dd4@github.com>

On Wed, 26 Jan 2022 02:20:24 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small modification to the way that bad references are reported by DocLint.
> 
> A new "mode" is introduced, `strictReferenceChecks`.   
> 
> If the mode is _not_ set, references that explicitly include a module name when that module name is not resolved in the module graph will be reported with a (suppressible) warning instead of an error.  All other issues with references will be reported as errors. This is the mode used by javac.
> 
> If the mode is set, all issues with references will be reported as errors. This is the mode used by javadoc.
> 
> This will need to be documented in the tool guide (man page).

This pull request has now been integrated.

Changeset: ee3be0bb
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/ee3be0bb567f0e28fd3e920ef3685607d0a8d656
Stats:     311 lines in 5 files changed: 309 ins; 0 del; 2 mod

8280488: doclint reference checks withstand warning suppression

Reviewed-by: darcy

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

PR: https://git.openjdk.java.net/jdk/pull/7222

From jjg at openjdk.java.net  Mon Jan 31 22:57:16 2022
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 31 Jan 2022 22:57:16 GMT
Subject: Integrated: JDK-8272984: javadoc support for reproducible builds
In-Reply-To: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
References: <BynJlhc60h7BVPxugo7WnclGetniJqvaR-bjY3HhQ9E=.de4b9afb-652f-4fbf-821f-0dd07eab7989@github.com>
Message-ID: <J-DhNQLo4Y4jGo5PObebf-jFd3f-PGbBHYbdiBz7sMk=.238c0f70-6d47-442e-83f1-ab80750d1bad@github.com>

On Fri, 21 Jan 2022 00:11:21 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a javadoc update to support a new `--date` option to support reproducible builds.
> 
> This pull request supersedes https://github.com/openjdk/jdk/pull/6905. In that PR, the `SOURCE_DATE_EPOCH` environment variable was used to provide the time stamp, but review feedback suggested the use of a new command-line option, `--date`.  The format of the argument of the `--date` option is that same as that of similar options for the _jar_ and _jmod_ tools, and the code to handle the value is based on code in the _jar_ tool.

This pull request has now been integrated.

Changeset: 96d0df72
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/96d0df72db277f127bd4c6b8c51bfc64d1c593e0
Stats:     256 lines in 10 files changed: 235 ins; 1 del; 20 mod

8272984: javadoc support for reproducible builds

Reviewed-by: hannesw

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

PR: https://git.openjdk.java.net/jdk/pull/7171

From darcy at openjdk.java.net  Mon Jan 31 23:12:57 2022
From: darcy at openjdk.java.net (Joe Darcy)
Date: Mon, 31 Jan 2022 23:12:57 GMT
Subject: RFR: JDK-8280534: Enable compile-time doclint reference checking
 [v3]
In-Reply-To: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
References: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
Message-ID: <PJrhOD11TCvrBateDpHZrocf-P6SCI8avABFQwJLYc0=.4595acca-adad-4731-94a6-028dc53ad10f@github.com>

> The changes in this PR on top of the out-for-review changes in https://git.openjdk.java.net/jdk/pull/7222 allow compile-time doclint checking to be enabled in all JDK modules.
> 
> Typically, a @SuppressWarnings("doclint:refernce") annotation is added to declaration with javadoc blocks that have already had distinguished cross-module links added (JDK-8280492).
> 
> One exception is in src/java.base/share/classes/java/net/package-info.java where the cross-module link was (for now) removed. Currently the SuppressWarnings annotation type is not declared to allow its annotations to be applied to package declarations. I'll look into amending that, but in the mean time, I think it is beneficial for the JDK build, and the base module in particular, to have compile-time doclint protections turned on.

Joe Darcy 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:

 - Merge branch 'master' into JDK-8280534
 - Use capabilities of JDK-8280744.
 - Merge branch 'master' into JDK-8280534
 - Cover java.base.
 - JDK-8280534: Enable compile-time doclint reference checking

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7237/files
  - new: https://git.openjdk.java.net/jdk/pull/7237/files/d03401c6..a0b37495

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7237&range=02
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7237&range=01-02

  Stats: 1473 lines in 53 files changed: 585 ins; 557 del; 331 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7237.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7237/head:pull/7237

PR: https://git.openjdk.java.net/jdk/pull/7237

From darcy at openjdk.java.net  Mon Jan 31 23:26:10 2022
From: darcy at openjdk.java.net (Joe Darcy)
Date: Mon, 31 Jan 2022 23:26:10 GMT
Subject: Integrated: JDK-8280534: Enable compile-time doclint reference
 checking
In-Reply-To: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
References: <gyWYzRVkXs2_p-X1NQRQv4nBDgtRcJ5JVSOdHp4ulWI=.3fa32ff8-3dbc-4277-b406-7f4eea1d0ffb@github.com>
Message-ID: <yvGiiPkELoa3bb17boUjPjypNJFKnJ5aCSkEQF1_Gm8=.35286cb5-1434-4332-8499-dbb4fd318045@github.com>

On Wed, 26 Jan 2022 20:05:07 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> The changes in this PR on top of the out-for-review changes in https://git.openjdk.java.net/jdk/pull/7222 allow compile-time doclint checking to be enabled in all JDK modules.
> 
> Typically, a @SuppressWarnings("doclint:refernce") annotation is added to declaration with javadoc blocks that have already had distinguished cross-module links added (JDK-8280492).
> 
> One exception is in src/java.base/share/classes/java/net/package-info.java where the cross-module link was (for now) removed. Currently the SuppressWarnings annotation type is not declared to allow its annotations to be applied to package declarations. I'll look into amending that, but in the mean time, I think it is beneficial for the JDK build, and the base module in particular, to have compile-time doclint protections turned on.

This pull request has now been integrated.

Changeset: 4dbebb62
Author:    Joe Darcy <darcy at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/4dbebb62aa264adda8d96a06f608ef9d13155a26
Stats:     28 lines in 21 files changed: 21 ins; 0 del; 7 mod

8280534: Enable compile-time doclint reference checking

Reviewed-by: serb, naoto, mchung, lancea, iris

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

PR: https://git.openjdk.java.net/jdk/pull/7237

From vab2048 at gmail.com  Sat Jan 29 17:57:40 2022
From: vab2048 at gmail.com (Vikram Bakshi)
Date: Sat, 29 Jan 2022 17:57:40 -0000
Subject: Feature request: link to source from javadoc
Message-ID: <CANExk-7qOTtqOBAgCbnyKWzF_ore4n_HFgGPs-QaUrj-0LcPDg@mail.gmail.com>

Hello javadoc developers,

Apologies if this is the wrong place for this type of message - I did not
know where else to reach out.

I have a feature request which I would like to propose for a future javadoc
version: a link to the actual source code of the definition within the
produced javadoc.

Something similar to what Haskell produces is what I am thinking. See here:
https://hackage.haskell.org/package/base-4.16.0.0/docs/Prelude.html#g:27

You see the type signatures of the functions and their description just
like how it would be for the javadoc produced for a class, but on the right
there is also a button for '#' and 'Source'. The source button feature is
what I am requesting. It takes you straight to the code where the actual
definition is.

This has been really useful to me when learning Haskell and would also be
useful for beginners who are learning Java. Obviously there would need to
be some kind of link to the source code and making that linking mechanism
is not trivial. Sometimes projects which do not intend to be open source
may not even want that link generated, etc. There are lots of non-trivial
points on what an implementation would look like.

The linking in the javadoc would not just be useful for people who are
learning java. For those of us, like me, who have been programming with
Java for many years there are lots of times where we want to go from the
javadoc to the actual implementation and we are forced to find the repo on
github and navigate the package structure to get to the actual class and
search for the definition and implementation there. This would make things
simpler.

Please let me know what you think of the idea (total garbage idea, useful
but not priority, etc). I am interested in hearing your thoughts and
responses.

Regards,
Vikram
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20220129/cc11c9be/attachment.htm>