From darcy at openjdk.java.net  Tue Aug  3 04:49:43 2021
From: darcy at openjdk.java.net (Joe Darcy)
Date: Tue, 3 Aug 2021 04:49:43 GMT
Subject: RFR: 8271711: Remove WorkArounds.isSynthetic
Message-ID: <InmvzZCjOsoEjZ5T8rK37bUkw9_wf9Kb1o5m6bUe9rY=.b5cccdcf-df7b-467e-80ae-3eae95983244@github.com>

Switch out logic in WorkArounds for a different expression implemented using javax.lang.model.Elements logic.

Langtools regression test suite passes with the changes.

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

Commit messages:
 - 8271711: Remove WorkArounds.isSynthetic

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

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

From jjg at openjdk.java.net  Tue Aug  3 18:01:29 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 3 Aug 2021 18:01:29 GMT
Subject: RFR: 8271711: Remove WorkArounds.isSynthetic
In-Reply-To: <InmvzZCjOsoEjZ5T8rK37bUkw9_wf9Kb1o5m6bUe9rY=.b5cccdcf-df7b-467e-80ae-3eae95983244@github.com>
References: <InmvzZCjOsoEjZ5T8rK37bUkw9_wf9Kb1o5m6bUe9rY=.b5cccdcf-df7b-467e-80ae-3eae95983244@github.com>
Message-ID: <4yYULYSyXcaafVLJU0rXjSZQxWv5OtvV4sbYmwKksHM=.53ffaca5-a8fe-403a-90ed-fb5262845958@github.com>

On Tue, 3 Aug 2021 04:40:33 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Switch out logic in WorkArounds for a different expression implemented using javax.lang.model.Elements logic.
> 
> Langtools regression test suite passes with the changes.

Nice. Always good to reduce the workarounds.

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

Marked as reviewed by jjg (Reviewer).

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

From darcy at openjdk.java.net  Tue Aug  3 18:16:35 2021
From: darcy at openjdk.java.net (Joe Darcy)
Date: Tue, 3 Aug 2021 18:16:35 GMT
Subject: Integrated: 8271711: Remove WorkArounds.isSynthetic
In-Reply-To: <InmvzZCjOsoEjZ5T8rK37bUkw9_wf9Kb1o5m6bUe9rY=.b5cccdcf-df7b-467e-80ae-3eae95983244@github.com>
References: <InmvzZCjOsoEjZ5T8rK37bUkw9_wf9Kb1o5m6bUe9rY=.b5cccdcf-df7b-467e-80ae-3eae95983244@github.com>
Message-ID: <4k8PfrzXvvJL4D6GSXjm3g8c_ONDWZZYMygArWnHzoc=.f5a19c81-a21a-4b2b-9633-c9e18df2810f@github.com>

On Tue, 3 Aug 2021 04:40:33 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Switch out logic in WorkArounds for a different expression implemented using javax.lang.model.Elements logic.
> 
> Langtools regression test suite passes with the changes.

This pull request has now been integrated.

Changeset: 6594d3a3
Author:    Joe Darcy <darcy at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/6594d3a3ef175a71ea34c7698ab96537c761f022
Stats:     5 lines in 2 files changed: 0 ins; 1 del; 4 mod

8271711: Remove WorkArounds.isSynthetic

Reviewed-by: jjg

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

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

From jjg at openjdk.java.net  Thu Aug  5 19:26:50 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 5 Aug 2021 19:26:50 GMT
Subject: [jdk17] RFR: JDK-8270872: Final nroff manpage update for JDK 17
Message-ID: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>

Please review a semi-automatic update of the nroff man pages from the upstream files.

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

Commit messages:
 - JDK-8270872: Final nroff manpage update for JDK 17

Changes: https://git.openjdk.java.net/jdk17/pull/303/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk17&pr=303&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8270872
  Stats: 289 lines in 27 files changed: 117 ins; 31 del; 141 mod
  Patch: https://git.openjdk.java.net/jdk17/pull/303.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk17 pull/303/head:pull/303

PR: https://git.openjdk.java.net/jdk17/pull/303

From darcy at openjdk.java.net  Thu Aug  5 19:44:37 2021
From: darcy at openjdk.java.net (Joe Darcy)
Date: Thu, 5 Aug 2021 19:44:37 GMT
Subject: [jdk17] RFR: JDK-8270872: Final nroff manpage update for JDK 17
In-Reply-To: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
References: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
Message-ID: <aWsXaUX5hmJ55kEcFzOXW7NqpE9NgjKXkZrDuNOHFJo=.2e213a1d-9d49-41ac-92d7-166ef9c08c67@github.com>

On Thu, 5 Aug 2021 19:20:50 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a semi-automatic update of the nroff man pages from the upstream files.

Marked as reviewed by darcy (Reviewer).

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

PR: https://git.openjdk.java.net/jdk17/pull/303

From naoto at openjdk.java.net  Thu Aug  5 20:01:37 2021
From: naoto at openjdk.java.net (Naoto Sato)
Date: Thu, 5 Aug 2021 20:01:37 GMT
Subject: [jdk17] RFR: JDK-8270872: Final nroff manpage update for JDK 17
In-Reply-To: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
References: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
Message-ID: <5VznFurUrli9tpiJDmqooJwAZUZy_oLp1iKDIoRP4X8=.e27f9831-478f-48d2-afc6-ecf29f0cb6ae@github.com>

On Thu, 5 Aug 2021 19:20:50 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a semi-automatic update of the nroff man pages from the upstream files.

src/jdk.hotspot.agent/share/man/jhsdb.1 line 1:

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

This seems not correct?

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

PR: https://git.openjdk.java.net/jdk17/pull/303

From mr at openjdk.java.net  Thu Aug  5 20:13:39 2021
From: mr at openjdk.java.net (Mark Reinhold)
Date: Thu, 5 Aug 2021 20:13:39 GMT
Subject: [jdk17] RFR: JDK-8270872: Final nroff manpage update for JDK 17
In-Reply-To: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
References: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
Message-ID: <jv6rEFb4aLBK1e6FBH186cyOqbPFVYLvomqdfzafljA=.95892c77-ab88-422f-91fc-343dfe6f99c6@github.com>

On Thu, 5 Aug 2021 19:20:50 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a semi-automatic update of the nroff man pages from the upstream files.

Marked as reviewed by mr (Lead).

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

PR: https://git.openjdk.java.net/jdk17/pull/303

From iris at openjdk.java.net  Thu Aug  5 20:40:40 2021
From: iris at openjdk.java.net (Iris Clark)
Date: Thu, 5 Aug 2021 20:40:40 GMT
Subject: [jdk17] RFR: JDK-8270872: Final nroff manpage update for JDK 17
In-Reply-To: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
References: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
Message-ID: <liAhrSHq9y4NbW5DufoiKCG95FcISducefm4wUe8ocE=.57c889b5-b016-4678-9980-e62769b62f8d@github.com>

On Thu, 5 Aug 2021 19:20:50 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a semi-automatic update of the nroff man pages from the upstream files.

Marked as reviewed by iris (Reviewer).

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

PR: https://git.openjdk.java.net/jdk17/pull/303

From jjg at openjdk.java.net  Thu Aug  5 21:39:38 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 5 Aug 2021 21:39:38 GMT
Subject: [jdk17] RFR: JDK-8270872: Final nroff manpage update for JDK 17
In-Reply-To: <5VznFurUrli9tpiJDmqooJwAZUZy_oLp1iKDIoRP4X8=.e27f9831-478f-48d2-afc6-ecf29f0cb6ae@github.com>
References: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
 <5VznFurUrli9tpiJDmqooJwAZUZy_oLp1iKDIoRP4X8=.e27f9831-478f-48d2-afc6-ecf29f0cb6ae@github.com>
Message-ID: <7b4mD0HqCA8-xI1PdJIHax5Zcae4sdFjereDxxPMhgg=.d97f1543-346d-45f3-aad0-2a9beb62bfd3@github.com>

On Thu, 5 Aug 2021 19:57:59 GMT, Naoto Sato <naoto at openjdk.org> wrote:

>> Please review a semi-automatic update of the nroff man pages from the upstream files.
>
> src/jdk.hotspot.agent/share/man/jhsdb.1 line 1:
> 
>> 1: .\" Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
> 
> This seems not correct?

According to the comments in the makefile (`closed/make/UpdateOpenManPages.gmk`) the copyright line is taken from the original Markdown file, so if the year is wrong there, it will be wrong in the generated nroff file.

I think it would be incorrect to edit the dates locally in these files, because they'll just be overwritten when we generate the files again. Ideally, the dates should be fixed (if necessary) in the Markdown files, but that seems out of scope for this P1.

This is "just" an issue with copyright dates in source files ... and yes, while I know copyright dates are important, this problem is arguably part of an ongoing more general problem.

I note that the generated files *do* correctly identify themselves with `2021` in the visible output generated to the console by the `man` command.

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

PR: https://git.openjdk.java.net/jdk17/pull/303

From naoto at openjdk.java.net  Thu Aug  5 21:44:35 2021
From: naoto at openjdk.java.net (Naoto Sato)
Date: Thu, 5 Aug 2021 21:44:35 GMT
Subject: [jdk17] RFR: JDK-8270872: Final nroff manpage update for JDK 17
In-Reply-To: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
References: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
Message-ID: <aq2UDjtBswQl63RvqgMXPgYZu5Eo9b34GJqGM0YzOpE=.185c7174-d0dd-4b52-9815-f7909a45187a@github.com>

On Thu, 5 Aug 2021 19:20:50 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a semi-automatic update of the nroff man pages from the upstream files.

Marked as reviewed by naoto (Reviewer).

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

PR: https://git.openjdk.java.net/jdk17/pull/303

From naoto at openjdk.java.net  Thu Aug  5 21:44:36 2021
From: naoto at openjdk.java.net (Naoto Sato)
Date: Thu, 5 Aug 2021 21:44:36 GMT
Subject: [jdk17] RFR: JDK-8270872: Final nroff manpage update for JDK 17
In-Reply-To: <7b4mD0HqCA8-xI1PdJIHax5Zcae4sdFjereDxxPMhgg=.d97f1543-346d-45f3-aad0-2a9beb62bfd3@github.com>
References: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
 <5VznFurUrli9tpiJDmqooJwAZUZy_oLp1iKDIoRP4X8=.e27f9831-478f-48d2-afc6-ecf29f0cb6ae@github.com>
 <7b4mD0HqCA8-xI1PdJIHax5Zcae4sdFjereDxxPMhgg=.d97f1543-346d-45f3-aad0-2a9beb62bfd3@github.com>
Message-ID: <zxzpN1zq_GPnLlqPZjkb7VWpnT9XlftAF6CiUVNUuQI=.7d6b28b8-1e27-4783-86f7-d3a6f71bb39d@github.com>

On Thu, 5 Aug 2021 21:36:58 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.hotspot.agent/share/man/jhsdb.1 line 1:
>> 
>>> 1: .\" Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
>> 
>> This seems not correct?
>
> According to the comments in the makefile (`closed/make/UpdateOpenManPages.gmk`) the copyright line is taken from the original Markdown file, so if the year is wrong there, it will be wrong in the generated nroff file.
> 
> I think it would be incorrect to edit the dates locally in these files, because they'll just be overwritten when we generate the files again. Ideally, the dates should be fixed (if necessary) in the Markdown files, but that seems out of scope for this P1.
> 
> This is "just" an issue with copyright dates in source files ... and yes, while I know copyright dates are important, this problem is arguably part of an ongoing more general problem.
> 
> I note that the generated files *do* correctly identify themselves with `2021` in the visible output generated to the console by the `man` command.

Thanks for the explanation, Jon. Fine by me.

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

PR: https://git.openjdk.java.net/jdk17/pull/303

From mr at openjdk.java.net  Thu Aug  5 21:44:36 2021
From: mr at openjdk.java.net (Mark Reinhold)
Date: Thu, 5 Aug 2021 21:44:36 GMT
Subject: [jdk17] RFR: JDK-8270872: Final nroff manpage update for JDK 17
In-Reply-To: <zxzpN1zq_GPnLlqPZjkb7VWpnT9XlftAF6CiUVNUuQI=.7d6b28b8-1e27-4783-86f7-d3a6f71bb39d@github.com>
References: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
 <5VznFurUrli9tpiJDmqooJwAZUZy_oLp1iKDIoRP4X8=.e27f9831-478f-48d2-afc6-ecf29f0cb6ae@github.com>
 <7b4mD0HqCA8-xI1PdJIHax5Zcae4sdFjereDxxPMhgg=.d97f1543-346d-45f3-aad0-2a9beb62bfd3@github.com>
 <zxzpN1zq_GPnLlqPZjkb7VWpnT9XlftAF6CiUVNUuQI=.7d6b28b8-1e27-4783-86f7-d3a6f71bb39d@github.com>
Message-ID: <k4aobJsxKwpdOZQqr1GFaBhAGbMh16e4EUxpDAql-Us=.5d7d0799-8d1c-42a0-91a2-44b0912ed475@github.com>

On Thu, 5 Aug 2021 21:40:40 GMT, Naoto Sato <naoto at openjdk.org> wrote:

>> According to the comments in the makefile (`closed/make/UpdateOpenManPages.gmk`) the copyright line is taken from the original Markdown file, so if the year is wrong there, it will be wrong in the generated nroff file.
>> 
>> I think it would be incorrect to edit the dates locally in these files, because they'll just be overwritten when we generate the files again. Ideally, the dates should be fixed (if necessary) in the Markdown files, but that seems out of scope for this P1.
>> 
>> This is "just" an issue with copyright dates in source files ... and yes, while I know copyright dates are important, this problem is arguably part of an ongoing more general problem.
>> 
>> I note that the generated files *do* correctly identify themselves with `2021` in the visible output generated to the console by the `man` command.
>
> Thanks for the explanation, Jon. Fine by me.

I agree that fixing this date is not necessary at this time.

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

PR: https://git.openjdk.java.net/jdk17/pull/303

From jjg at openjdk.java.net  Thu Aug  5 22:15:29 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 5 Aug 2021 22:15:29 GMT
Subject: [jdk17] Integrated: JDK-8270872: Final nroff manpage update for JDK 17
In-Reply-To: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
References: <o52TRFEciQIkCH68afOXPv-DPva8a-LLokU6K0aPPVI=.ca6ced5d-9a0c-4700-bf86-0f29750adca6@github.com>
Message-ID: <k3Bqh5GeG3FgEBh_9rbFrDjJrTd6VSoO2S-KYSPIY_s=.50ab8e33-39b0-4ca9-9931-61cb55ec5c0d@github.com>

On Thu, 5 Aug 2021 19:20:50 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a semi-automatic update of the nroff man pages from the upstream files.

This pull request has now been integrated.

Changeset: dfacda48
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk17/commit/dfacda488bfbe2e11e8d607a6d08527710286982
Stats:     289 lines in 27 files changed: 117 ins; 31 del; 141 mod

8270872: Final nroff manpage update for JDK 17

Reviewed-by: darcy, mr, iris, naoto

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

PR: https://git.openjdk.java.net/jdk17/pull/303

From jwilhelm at openjdk.java.net  Thu Aug  5 23:57:59 2021
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 5 Aug 2021 23:57:59 GMT
Subject: RFR: Merge jdk17
Message-ID: <ZWfLNTnRXylfPAqm6WcKdGasNkjf5rRSe56fGDYxYsw=.b7033ab6-6b03-4303-afcc-71fd6b9ec8b2@github.com>

Forwardport JDK 17 -> JDK 18

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

Commit messages:
 - Merge
 - 8270872: Final nroff manpage update for JDK 17
 - 8271588: JFR Recorder Thread crashed with SIGSEGV in write_klass
 - 8271863: ProblemList serviceability/sa/TestJmapCore.java on linux-x64 with ZGC

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

Changes: https://git.openjdk.java.net/jdk/pull/5026/files
  Stats: 307 lines in 32 files changed: 129 ins; 33 del; 145 mod
  Patch: https://git.openjdk.java.net/jdk/pull/5026.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/5026/head:pull/5026

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

From jwilhelm at openjdk.java.net  Fri Aug  6 01:27:32 2021
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Fri, 6 Aug 2021 01:27:32 GMT
Subject: RFR: Merge jdk17 [v2]
In-Reply-To: <ZWfLNTnRXylfPAqm6WcKdGasNkjf5rRSe56fGDYxYsw=.b7033ab6-6b03-4303-afcc-71fd6b9ec8b2@github.com>
References: <ZWfLNTnRXylfPAqm6WcKdGasNkjf5rRSe56fGDYxYsw=.b7033ab6-6b03-4303-afcc-71fd6b9ec8b2@github.com>
Message-ID: <1oUovSIU_RoljyN5VHPljZLMI5NpHqK3ys9BDhsuLI8=.15d53c62-802e-4982-9415-527c302b8ab4@github.com>

> Forwardport JDK 17 -> JDK 18

Jesper Wilhelmsson has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 440 commits:

 - Merge
 - 8271293: Monitor class should use ThreadBlockInVMPreprocess
   
   Reviewed-by: dholmes, dcubed
 - 8270116: Expand ButtonGroupLayoutTraversalTest.java to run in all LaFs, including Aqua on macOS
   
   Reviewed-by: psadhukhan, aivanov
 - 8271905: mark hotspot runtime/Metaspace tests which ignore external VM flags
   
   Reviewed-by: stuefe
 - 8271308: (fc) FileChannel.transferTo() transfers no more than Integer.MAX_VALUE bytes in one call
   
   Reviewed-by: alanb, vtewari
 - 8271953: fix mis-merge in JDK-8271878
   
   Reviewed-by: jwilhelm, ctornqvi
 - 8267840: Improve URLStreamHandler.parseURL()
   
   Reviewed-by: dfuchs, redestad
 - 8271840: Add simple Integer.toString microbenchmarks
   
   Reviewed-by: shade
 - 8271121: ZGC: stack overflow (segv) when -Xlog:gc+start=debug
   
   Reviewed-by: ayang, eosterlund
 - 8270903: sun.net.httpserver.HttpConnection: Improve toString
   
   Reviewed-by: chegar, vtewari
 - ... and 430 more: https://git.openjdk.java.net/jdk/compare/dfacda48...7e069880

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

Changes: https://git.openjdk.java.net/jdk/pull/5026/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=5026&range=01
  Stats: 97370 lines in 1522 files changed: 61891 ins; 27834 del; 7645 mod
  Patch: https://git.openjdk.java.net/jdk/pull/5026.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/5026/head:pull/5026

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

From jwilhelm at openjdk.java.net  Fri Aug  6 01:27:33 2021
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Fri, 6 Aug 2021 01:27:33 GMT
Subject: Integrated: Merge jdk17
In-Reply-To: <ZWfLNTnRXylfPAqm6WcKdGasNkjf5rRSe56fGDYxYsw=.b7033ab6-6b03-4303-afcc-71fd6b9ec8b2@github.com>
References: <ZWfLNTnRXylfPAqm6WcKdGasNkjf5rRSe56fGDYxYsw=.b7033ab6-6b03-4303-afcc-71fd6b9ec8b2@github.com>
Message-ID: <lfK3BfjviJuRKG0C--gFo3MRja2_KrGtQjN4gEp4OsU=.9c421dfd-08de-40d5-8fb5-f88dcad215bb@github.com>

On Thu, 5 Aug 2021 23:49:48 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Forwardport JDK 17 -> JDK 18

This pull request has now been integrated.

Changeset: 14692d5e
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/14692d5ed0652b867fcf28baafa498a9441683ac
Stats:     307 lines in 32 files changed: 129 ins; 33 del; 145 mod

Merge

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

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

From prappo at openjdk.java.net  Fri Aug  6 12:24:06 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Fri, 6 Aug 2021 12:24:06 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

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

  Pass through FIXMEs and TODOs
  
  Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/0a47e9c2..22d1e07d

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=06
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=05-06

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

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

From hannesw at openjdk.java.net  Wed Aug 11 10:42:48 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 11 Aug 2021 10:42:48 GMT
Subject: RFR: JDK-8272158: SoftReference related bugs under memory pressure
Message-ID: <lWnGB7Srse14hF_TX1FJY_vfFEXvKiRmGqVzi9cKfEk=.51704a6a-bcb3-4be5-8420-c434571061fb@github.com>

This change fixes two problems related to usage of soft references in javadoc. 

The one in `VisibleMemberTable` is rather trivial, it just avoids getting the softly referenced value twice, which allowed GC to clear the reference between the two calls. 

For the one in `CommentHelper`, I considered a few different solutions: Store CommentHelper instances with hard references, compute the overridden element information on demand instead of storing it in the object, or ignore missing overridden object info based on the rationale that any issues should already have been reported on the overridden element itself. I decided to go with the on-demand lookup of overridden elements as the additional overhead was minimal (a total of 3 milliseconds for the JDK docs) and the reduction in state/complexity seemed like an additional benefit.

I labeled the issue as "noreg-hard". To test the fix I ran the JDK `docs` target with reduced heap space (appending `-Xmx664m` to `$1_JAVA_ARGS` in make/Docs.gmk). With max heap values in that range, the task either succeeds or fails with `OutOfMemoryError`. Previously, it sometimes failed with `NullPointerException` due to one of the two issues.

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

Commit messages:
 - JDK-8272158: SoftReference related bugs under memory pressure

Changes: https://git.openjdk.java.net/jdk/pull/5080/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=5080&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8272158
  Stats: 42 lines in 3 files changed: 8 ins; 19 del; 15 mod
  Patch: https://git.openjdk.java.net/jdk/pull/5080.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/5080/head:pull/5080

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

From jjg at openjdk.java.net  Wed Aug 11 17:45:48 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 11 Aug 2021 17:45:48 GMT
Subject: RFR: JDK-8271159: [REDO] JDK-8249634 doclint should report implicit
 constructor as missing javadoc comments
Message-ID: <BrDVfsxpUN7yzPoRZHrCh3hjpwM3U95dQBI2LZdr0sc=.f2f64440-180c-4bb8-a788-b64b7cc55f43@github.com>

Please review a do-over of JDK-8249634, to report a missing doc comment when an implicit/default constructor is used.

The `src` code is the same as before.   The previous version had missing test files (now added), and had a test fail because an interaction with another changeset that was pushed while the previous version was in review. The solution for that is the use of `-Xdoclint:all,-missing` in `TestDocTreeDiags.java`.

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

Commit messages:
 - JDK-8271159: [REDO] JDK-8249634 doclint should report implicit constructor as missing javadoc comments

Changes: https://git.openjdk.java.net/jdk/pull/5088/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=5088&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8271159
  Stats: 240 lines in 77 files changed: 125 ins; 4 del; 111 mod
  Patch: https://git.openjdk.java.net/jdk/pull/5088.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/5088/head:pull/5088

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

From darcy at openjdk.java.net  Wed Aug 11 18:03:25 2021
From: darcy at openjdk.java.net (Joe Darcy)
Date: Wed, 11 Aug 2021 18:03:25 GMT
Subject: RFR: JDK-8271159: [REDO] JDK-8249634 doclint should report
 implicit constructor as missing javadoc comments
In-Reply-To: <BrDVfsxpUN7yzPoRZHrCh3hjpwM3U95dQBI2LZdr0sc=.f2f64440-180c-4bb8-a788-b64b7cc55f43@github.com>
References: <BrDVfsxpUN7yzPoRZHrCh3hjpwM3U95dQBI2LZdr0sc=.f2f64440-180c-4bb8-a788-b64b7cc55f43@github.com>
Message-ID: <8-v6822Vfm_SfsnPuuWA6hb5cRcDykIrPuT1XQRZUUc=.7aa297aa-8deb-49de-bb7c-e53cc2a02bf6@github.com>

On Wed, 11 Aug 2021 17:38:49 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a do-over of JDK-8249634, to report a missing doc comment when an implicit/default constructor is used.
> 
> The `src` code is the same as before.   The previous version had missing test files (now added), and had a test fail because an interaction with another changeset that was pushed while the previous version was in review. The solution for that is the use of `-Xdoclint:all,-missing` in `TestDocTreeDiags.java`.

Marked as reviewed by darcy (Reviewer).

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

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

From jjg at openjdk.java.net  Wed Aug 11 18:06:30 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 11 Aug 2021 18:06:30 GMT
Subject: Integrated: JDK-8271159: [REDO] JDK-8249634 doclint should report
 implicit constructor as missing javadoc comments
In-Reply-To: <BrDVfsxpUN7yzPoRZHrCh3hjpwM3U95dQBI2LZdr0sc=.f2f64440-180c-4bb8-a788-b64b7cc55f43@github.com>
References: <BrDVfsxpUN7yzPoRZHrCh3hjpwM3U95dQBI2LZdr0sc=.f2f64440-180c-4bb8-a788-b64b7cc55f43@github.com>
Message-ID: <nDjTr52bvwtew7cJ7XEsAmopnktZg2Q3FRZdthOhxLA=.1987c7e9-c71e-4226-a30c-5389806edf5e@github.com>

On Wed, 11 Aug 2021 17:38:49 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a do-over of JDK-8249634, to report a missing doc comment when an implicit/default constructor is used.
> 
> The `src` code is the same as before.   The previous version had missing test files (now added), and had a test fail because an interaction with another changeset that was pushed while the previous version was in review. The solution for that is the use of `-Xdoclint:all,-missing` in `TestDocTreeDiags.java`.

This pull request has now been integrated.

Changeset: ec8d3bad
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/ec8d3badc869be7898b5a49fa5f9ba447bbbcf8d
Stats:     240 lines in 77 files changed: 125 ins; 4 del; 111 mod

8271159: [REDO] JDK-8249634 doclint should report implicit constructor as missing javadoc comments

Reviewed-by: darcy

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

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

From jjg at openjdk.java.net  Wed Aug 11 18:07:34 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 11 Aug 2021 18:07:34 GMT
Subject: Integrated: JDK-8269774: doclint reports missing javadoc comments for
 JavaFX properties if the docs are on the property method
In-Reply-To: <tkF_afQ1LjnJnIoi-uo7H4Jjg9rI81fxgfhO36htBIk=.0b0278d5-c5b0-46a4-96c7-a464e263371f@github.com>
References: <tkF_afQ1LjnJnIoi-uo7H4Jjg9rI81fxgfhO36htBIk=.0b0278d5-c5b0-46a4-96c7-a464e263371f@github.com>
Message-ID: <9ho2UaCxhsIfp--vEgxJIxmVBCQED7U6ni1XmrdokmU=.81c524ef-61a1-491b-a12f-4654b0595b20@github.com>

On Fri, 9 Jul 2021 19:17:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple change to the code for generating docs for JavaFX properties, in order to suppress an inappropriate
> "missing comment" warning.
> 
> The change is to use `hasDocCommentTree` instead of `getDocCommentTree`.
> 
> A new test is added, that runs javadoc on similar classes, with and without a comment on the field for a property. In both cases, no warnings about missing comments should be generated, and when the comment is available, it is used as expected.

This pull request has now been integrated.

Changeset: 9ba8a12c
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/9ba8a12cfbb3d7d17be454e29ee6ff476c8690c2
Stats:     160 lines in 2 files changed: 159 ins; 0 del; 1 mod

8269774: doclint reports missing javadoc comments for JavaFX properties if the docs are on the property method

Reviewed-by: kcr, hannesw

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

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

From hannesw at openjdk.java.net  Thu Aug 12 12:45:34 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 12 Aug 2021 12:45:34 GMT
Subject: RFR: JDK-8264274: Block tags in overview.html are ignored
Message-ID: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>

This is a simple fix to generate block tags in overview files specified by the `-overview` option. 

I added a protected `addOverviewTags` method in `AbstractOverviewIndexWriter` which is probably overkill but keeps things flexible and separated.

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

Commit messages:
 - JDK-8264274: Block tags in overview.html are ignored

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

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

From jjg at openjdk.java.net  Thu Aug 12 17:44:49 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 12 Aug 2021 17:44:49 GMT
Subject: RFR: JDK-8270195: Add missing links between methods of JavaFX
 properties
Message-ID: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>

Please review a medium-size update to the support for JavaFX properties in the Standard Doclet.

A JavaFX property is typically defined by a group of up to 4 elements:
* an optional field, which is typically private
* a no-args property method, whose name ends in `Property` and which returns an appropriate property object
* an optional getter method which can get the value of the property
* an optional setter method which can set the value of the property

Either the field (if present) or the property method (but not both) should have a comment describing the property. The rest should generally _not_have comments: comments will be automatically generated.

This change is primarily to improve the generation of the comments. `@see` links are generated between the methods for a property. In addition, improvements are made to the handling of `@return` ... adding it as needed, and removing it when not (the latter occurs when generating the docs for the property itself, using the info in the property method.)

There is some amount of cleanup to the implementation, most notably moving (and rewriting) the code to generate comments for property methods from `MemberSummaryBuilder` to `CommentUtils`,which is where most other synthesized comments are generated. However, the goal has also been to not unduly change the spirit and spec of the original code.

A new combo test for JavaFX properties is provided, that creates different instances of a class, containing different property-related methods with and without comments. Basic properties of the output are then verified for each property method: the description, any parameter info, any return info, and any links to other related methods.

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

Commit messages:
 - JDK-8270195: Add missing links between methods of JavaFX properties

Changes: https://git.openjdk.java.net/jdk/pull/5102/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=5102&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8270195
  Stats: 1024 lines in 12 files changed: 740 ins; 157 del; 127 mod
  Patch: https://git.openjdk.java.net/jdk/pull/5102.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/5102/head:pull/5102

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

From jjg at openjdk.java.net  Thu Aug 12 18:01:27 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 12 Aug 2021 18:01:27 GMT
Subject: RFR: JDK-8264274: Block tags in overview.html are ignored
In-Reply-To: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>
References: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>
Message-ID: <hEsOBuxPqxyx13tqkOVmoRwa6qJy22XuIK16fewJXfc=.d15e086a-3794-41e2-b8fc-e8c9dc89294d@github.com>

On Thu, 12 Aug 2021 12:39:37 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This is a simple fix to generate block tags in overview files specified by the `-overview` option. 
> 
> I added a protected `addOverviewTags` method in `AbstractOverviewIndexWriter` which is probably overkill but keeps things flexible and separated.

`src/` code looks good; `test/` code has a question...

test/langtools/jdk/javadoc/doclet/testOverview/TestOverview.java line 80:

> 78:                     <dd>
> 79:                     <ul class="see-list">
> 80:                     <li><a href="%1$sp1/C.html" title="class in p1"><code>C</code></a></li>

What's with the funky URL?

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

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

From jjg at openjdk.java.net  Fri Aug 13 03:59:49 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 13 Aug 2021 03:59:49 GMT
Subject: RFR: JDK-8272374: doclint should report missing "body" comments
Message-ID: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>

Please review a relatively simple update to have doclnt check for empty "descriptions" -- the body of a doc comment, before the block tags.

It is already the case that doclint checks for missing/empty descriptions in block tags, like @param, @return, etc.

There are three cases to consider:

* The comment itself is missing: this was already checked and reported as "missing comment".
* The comment is present, but is empty ... this seems relatively unlikely, but is nevertheless checked and reported as "empty comment".
* The comment is present but only has block tags. This is not always a problem, since the description may be inherited, for example, in an overriding method, but when it is an issue, it is reported as "no initial description". 

No diagnostic is reported if the description is missing but the first tag is `@deprecated`, because in this case, javadoc will use the body of the `@deprecated` tag for the summary. See [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA) and the corresponding entry in the summary table to see an example of this situation.

Diagnostics are reported if the declaration is not an overriding method and does not begin with `@deprecated`.  This occurs in a number of places in the `java.desktop` module, often where the doc comment is of the form `/** @return _description_ */`.  To suppress those warnings for now, the `-missing` option is added to `DOCLINT_OPTIONS` for the `java.desktop` module.  To see the effects of this anti-pattern, look at the empty descriptions for [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)

Many of the doclint tests needed to be updated, because of their over-simplistic minimal comments. It was not possible, in general, to avoid updating the source code while preserving line numbers, so in many cases, the golden `*.out` files had to be updated as well.

A new test is added, focussing on the different forms of empty/missing descriptions, as described above.

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

Commit messages:
 - JDK-8272374: doclint should report missing "body" comments

Changes: https://git.openjdk.java.net/jdk/pull/5106/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=5106&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8272374
  Stats: 281 lines in 37 files changed: 152 ins; 10 del; 119 mod
  Patch: https://git.openjdk.java.net/jdk/pull/5106.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/5106/head:pull/5106

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

From hannesw at openjdk.java.net  Fri Aug 13 08:07:25 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 13 Aug 2021 08:07:25 GMT
Subject: RFR: JDK-8264274: Block tags in overview.html are ignored
In-Reply-To: <hEsOBuxPqxyx13tqkOVmoRwa6qJy22XuIK16fewJXfc=.d15e086a-3794-41e2-b8fc-e8c9dc89294d@github.com>
References: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>
 <hEsOBuxPqxyx13tqkOVmoRwa6qJy22XuIK16fewJXfc=.d15e086a-3794-41e2-b8fc-e8c9dc89294d@github.com>
Message-ID: <JVee9bI2TZ3bKuvbLWXmvgJOhpUmy-Ol-1eQrBcG1_E=.3fe32a5c-e8d4-4044-b3fb-fe3a26d41dbc@github.com>

On Thu, 12 Aug 2021 17:56:01 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This is a simple fix to generate block tags in overview files specified by the `-overview` option. 
>> 
>> I added a protected `addOverviewTags` method in `AbstractOverviewIndexWriter` which is probably overkill but keeps things flexible and separated.
>
> test/langtools/jdk/javadoc/doclet/testOverview/TestOverview.java line 80:
> 
>> 78:                     <dd>
>> 79:                     <ul class="see-list">
>> 80:                     <li><a href="%1$sp1/C.html" title="class in p1"><code>C</code></a></li>
> 
> What's with the funky URL?

That's just a format string specifier "%1$s", meaning the first format argument (see invocation of `formatted` method below to adapt the string to a module or non-module context). 

I realize now that I could have omitted the argument index part of the format specifier, will update the PR if that is true.

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

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

From hannesw at openjdk.java.net  Fri Aug 13 08:20:47 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 13 Aug 2021 08:20:47 GMT
Subject: RFR: JDK-8264274: Block tags in overview.html are ignored [v2]
In-Reply-To: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>
References: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>
Message-ID: <6NgmO6qjBtUBDeOZQoh0eknZo8S9MtMX26gTs8gdo6Y=.614f90bf-c0f0-403a-aa93-77fdc923351e@github.com>

> This is a simple fix to generate block tags in overview files specified by the `-overview` option. 
> 
> I added a protected `addOverviewTags` method in `AbstractOverviewIndexWriter` which is probably overkill but keeps things flexible and separated.

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

  JDK-8264274: Simplify format specifier

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/5099/files
  - new: https://git.openjdk.java.net/jdk/pull/5099/files/bcec66cb..8b781ea2

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

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

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

From jjg at openjdk.java.net  Fri Aug 13 14:24:26 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 13 Aug 2021 14:24:26 GMT
Subject: RFR: JDK-8272158: SoftReference related bugs under memory pressure
In-Reply-To: <lWnGB7Srse14hF_TX1FJY_vfFEXvKiRmGqVzi9cKfEk=.51704a6a-bcb3-4be5-8420-c434571061fb@github.com>
References: <lWnGB7Srse14hF_TX1FJY_vfFEXvKiRmGqVzi9cKfEk=.51704a6a-bcb3-4be5-8420-c434571061fb@github.com>
Message-ID: <MT5fPKo8Y1Jb3BrHryESX9ZHpvxl0Ri3miZzJMA5PxI=.5b3d29dd-c1c2-4608-a9e4-98430db34578@github.com>

On Wed, 11 Aug 2021 10:36:48 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This change fixes two problems related to usage of soft references in javadoc. 
> 
> The one in `VisibleMemberTable` is rather trivial, it just avoids getting the softly referenced value twice, which allowed GC to clear the reference between the two calls. 
> 
> For the one in `CommentHelper`, I considered a few different solutions: Store CommentHelper instances with hard references, compute the overridden element information on demand instead of storing it in the object, or ignore missing overridden object info based on the rationale that any issues should already have been reported on the overridden element itself. I decided to go with the on-demand lookup of overridden elements as the additional overhead was minimal (a total of 3 milliseconds for the JDK docs) and the reduction in state/complexity seemed like an additional benefit.
> 
> I labeled the issue as "noreg-hard". To test the fix I ran the JDK `docs` target with reduced heap space (appending `-Xmx664m` to `$1_JAVA_ARGS` in make/Docs.gmk). With max heap values in that range, the task either succeeds or fails with `OutOfMemoryError`. Previously, it sometimes failed with `NullPointerException` due to one of the two issues.

Maybe we should have a general review of the use of `SoftReference` and `WeakReference` in javadoc and the standard doclet.

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

Marked as reviewed by jjg (Reviewer).

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

From kcr at openjdk.java.net  Fri Aug 13 15:37:26 2021
From: kcr at openjdk.java.net (Kevin Rushforth)
Date: Fri, 13 Aug 2021 15:37:26 GMT
Subject: RFR: JDK-8270195: Add missing links between methods of JavaFX
 properties
In-Reply-To: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
References: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
Message-ID: <4kmKKzmGU9NjJtRAftt-_M1JWx7ZVASg0TMgjyW0krA=.29596d5b-06fe-4883-8d1e-abb68eef7592@github.com>

On Thu, 12 Aug 2021 17:38:14 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a medium-size update to the support for JavaFX properties in the Standard Doclet.
> 
> A JavaFX property is typically defined by a group of up to 4 elements:
> * an optional field, which is typically private
> * a no-args property method, whose name ends in `Property` and which returns an appropriate property object
> * an optional getter method which can get the value of the property
> * an optional setter method which can set the value of the property
> 
> Either the field (if present) or the property method (but not both) should have a comment describing the property. The rest should generally _not_have comments: comments will be automatically generated.
> 
> This change is primarily to improve the generation of the comments. `@see` links are generated between the methods for a property. In addition, improvements are made to the handling of `@return` ... adding it as needed, and removing it when not (the latter occurs when generating the docs for the property itself, using the info in the property method.)
> 
> There is some amount of cleanup to the implementation, most notably moving (and rewriting) the code to generate comments for property methods from `MemberSummaryBuilder` to `CommentUtils`,which is where most other synthesized comments are generated. However, the goal has also been to not unduly change the spirit and spec of the original code.
> 
> A new combo test for JavaFX properties is provided, that creates different instances of a class, containing different property-related methods with and without comments. Basic properties of the output are then verified for each property method: the description, any parameter info, any return info, and any links to other related methods.

I ran javadoc with this patch to generate the JavaFX docs, and it all looks good. I verified that the synthesized `@see`, `@param`, and `@return`  are now all consistently added. The name of the property is now consistently in `<code></code>` style, too.

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

Marked as reviewed by kcr (Author).

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

From kcr at openjdk.java.net  Fri Aug 13 15:46:27 2021
From: kcr at openjdk.java.net (Kevin Rushforth)
Date: Fri, 13 Aug 2021 15:46:27 GMT
Subject: RFR: JDK-8272374: doclint should report missing "body" comments
In-Reply-To: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
References: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
Message-ID: <WwN_qGlfgMwTevBmVoMK-DMKpS3tSjre37lUOjfYAEI=.b206ebfc-5eda-4a48-93d4-877d3165a01f@github.com>

On Fri, 13 Aug 2021 03:51:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a relatively simple update to have doclnt check for empty "descriptions" -- the body of a doc comment, before the block tags.
> 
> It is already the case that doclint checks for missing/empty descriptions in block tags, like @param, @return, etc.
> 
> There are three cases to consider:
> 
> * The comment itself is missing: this was already checked and reported as "missing comment".
> * The comment is present, but is empty ... this seems relatively unlikely, but is nevertheless checked and reported as "empty comment".
> * The comment is present but only has block tags. This is not always a problem, since the description may be inherited, for example, in an overriding method, but when it is an issue, it is reported as "no initial description". 
> 
> No diagnostic is reported if the description is missing but the first tag is `@deprecated`, because in this case, javadoc will use the body of the `@deprecated` tag for the summary. See [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA) and the corresponding entry in the summary table to see an example of this situation.
> 
> Diagnostics are reported if the declaration is not an overriding method and does not begin with `@deprecated`.  This occurs in a number of places in the `java.desktop` module, often where the doc comment is of the form `/** @return _description_ */`.  To suppress those warnings for now, the `-missing` option is added to `DOCLINT_OPTIONS` for the `java.desktop` module.  To see the effects of this anti-pattern, look at the empty descriptions for [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)
> 
> Many of the doclint tests needed to be updated, because of their over-simplistic minimal comments. It was not possible, in general, to avoid updating the source code while preserving line numbers, so in many cases, the golden `*.out` files had to be updated as well.
> 
> A new test is added, focussing on the different forms of empty/missing descriptions, as described above.

I tested this by using it to generate the JavaFX docs. We have 62 new warnings for methods with empty descriptions that we otherwise would not have easily found.

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

Marked as reviewed by kcr (Author).

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

From hannesw at openjdk.java.net  Mon Aug 16 07:49:32 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 16 Aug 2021 07:49:32 GMT
Subject: Integrated: JDK-8272158: SoftReference related bugs under memory
 pressure
In-Reply-To: <lWnGB7Srse14hF_TX1FJY_vfFEXvKiRmGqVzi9cKfEk=.51704a6a-bcb3-4be5-8420-c434571061fb@github.com>
References: <lWnGB7Srse14hF_TX1FJY_vfFEXvKiRmGqVzi9cKfEk=.51704a6a-bcb3-4be5-8420-c434571061fb@github.com>
Message-ID: <FOK63ljh8_7kBWb_BL_j1zIQhHLToJosnugk8RpPbvg=.b7ceaa9f-4db8-4b8f-937c-9cb7f2fdf7fc@github.com>

On Wed, 11 Aug 2021 10:36:48 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This change fixes two problems related to usage of soft references in javadoc. 
> 
> The one in `VisibleMemberTable` is rather trivial, it just avoids getting the softly referenced value twice, which allowed GC to clear the reference between the two calls. 
> 
> For the one in `CommentHelper`, I considered a few different solutions: Store CommentHelper instances with hard references, compute the overridden element information on demand instead of storing it in the object, or ignore missing overridden object info based on the rationale that any issues should already have been reported on the overridden element itself. I decided to go with the on-demand lookup of overridden elements as the additional overhead was minimal (a total of 3 milliseconds for the JDK docs) and the reduction in state/complexity seemed like an additional benefit.
> 
> I labeled the issue as "noreg-hard". To test the fix I ran the JDK `docs` target with reduced heap space (appending `-Xmx664m` to `$1_JAVA_ARGS` in make/Docs.gmk). With max heap values in that range, the task either succeeds or fails with `OutOfMemoryError`. Previously, it sometimes failed with `NullPointerException` due to one of the two issues.

This pull request has now been integrated.

Changeset: 5db36ced
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/5db36cedc91d0954ececd309a5f8f59ea828f6c1
Stats:     42 lines in 3 files changed: 8 ins; 19 del; 15 mod

8272158: SoftReference related bugs under memory pressure

Reviewed-by: jjg

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

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

From hannesw at openjdk.java.net  Mon Aug 16 11:45:25 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 16 Aug 2021 11:45:25 GMT
Subject: RFR: JDK-8272374: doclint should report missing "body" comments
In-Reply-To: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
References: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
Message-ID: <-8oey_QHb7omZMiWEFbMUkK37CdVDjxTBxEqCuZyumo=.130eca61-0ac3-4176-99ee-7426eb13048a@github.com>

On Fri, 13 Aug 2021 03:51:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a relatively simple update to have doclnt check for empty "descriptions" -- the body of a doc comment, before the block tags.
> 
> It is already the case that doclint checks for missing/empty descriptions in block tags, like @param, @return, etc.
> 
> There are three cases to consider:
> 
> * The comment itself is missing: this was already checked and reported as "missing comment".
> * The comment is present, but is empty ... this seems relatively unlikely, but is nevertheless checked and reported as "empty comment".
> * The comment is present but only has block tags. This is not always a problem, since the description may be inherited, for example, in an overriding method, but when it is an issue, it is reported as "no initial description". 
> 
> No diagnostic is reported if the description is missing but the first tag is `@deprecated`, because in this case, javadoc will use the body of the `@deprecated` tag for the summary. See [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA) and the corresponding entry in the summary table to see an example of this situation.
> 
> Diagnostics are reported if the declaration is not an overriding method and does not begin with `@deprecated`.  This occurs in a number of places in the `java.desktop` module, often where the doc comment is of the form `/** @return _description_ */`.  To suppress those warnings for now, the `-missing` option is added to `DOCLINT_OPTIONS` for the `java.desktop` module.  To see the effects of this anti-pattern, look at the empty descriptions for [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)
> 
> Many of the doclint tests needed to be updated, because of their over-simplistic minimal comments. It was not possible, in general, to avoid updating the source code while preserving line numbers, so in many cases, the golden `*.out` files had to be updated as well.
> 
> A new test is added, focussing on the different forms of empty/missing descriptions, as described above.

Looks good. One thing I wonder about is why you only look for `@deprecated` in the first block tag. I guess it is just a convention to add this tag at the first position?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 203:

> 201:                     // Don't report an empty description if the comment begins with @deprecated,
> 202:                     // because javadoc will use the content of that tag in summary tables.
> 203:                     if (firstTag.getKind() != DocTree.Kind.DEPRECATED) {

Why do we only check the first block tag here?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 204:

> 202:                     // because javadoc will use the content of that tag in summary tables.
> 203:                     if (firstTag.getKind() != DocTree.Kind.DEPRECATED) {
> 204:                         env.messages.report(MISSING, Kind.WARNING, tree, "dc.empty.description");

Is there a reason to not use `reportMissing` here?

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

Marked as reviewed by hannesw (Reviewer).

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

From jjg at openjdk.java.net  Mon Aug 16 17:11:29 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 16 Aug 2021 17:11:29 GMT
Subject: RFR: JDK-8272374: doclint should report missing "body" comments
In-Reply-To: <-8oey_QHb7omZMiWEFbMUkK37CdVDjxTBxEqCuZyumo=.130eca61-0ac3-4176-99ee-7426eb13048a@github.com>
References: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
 <-8oey_QHb7omZMiWEFbMUkK37CdVDjxTBxEqCuZyumo=.130eca61-0ac3-4176-99ee-7426eb13048a@github.com>
Message-ID: <8_n_Wcn6QF4nXLkgtIgrlTSKESOi5HmTpC_a4pcUKMM=.c9499fce-31b5-40ee-a806-2e92d5894bd6@github.com>

On Fri, 13 Aug 2021 09:20:19 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a relatively simple update to have doclnt check for empty "descriptions" -- the body of a doc comment, before the block tags.
>> 
>> It is already the case that doclint checks for missing/empty descriptions in block tags, like @param, @return, etc.
>> 
>> There are three cases to consider:
>> 
>> * The comment itself is missing: this was already checked and reported as "missing comment".
>> * The comment is present, but is empty ... this seems relatively unlikely, but is nevertheless checked and reported as "empty comment".
>> * The comment is present but only has block tags. This is not always a problem, since the description may be inherited, for example, in an overriding method, but when it is an issue, it is reported as "no initial description". 
>> 
>> No diagnostic is reported if the description is missing but the first tag is `@deprecated`, because in this case, javadoc will use the body of the `@deprecated` tag for the summary. See [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA) and the corresponding entry in the summary table to see an example of this situation.
>> 
>> Diagnostics are reported if the declaration is not an overriding method and does not begin with `@deprecated`.  This occurs in a number of places in the `java.desktop` module, often where the doc comment is of the form `/** @return _description_ */`.  To suppress those warnings for now, the `-missing` option is added to `DOCLINT_OPTIONS` for the `java.desktop` module.  To see the effects of this anti-pattern, look at the empty descriptions for [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)
>> 
>> Many of the doclint tests needed to be updated, because of their over-simplistic minimal comments. It was not possible, in general, to avoid updating the source code while preserving line numbers, so in many cases, the golden `*.out` files had to be updated as well.
>> 
>> A new test is added, focussing on the different forms of empty/missing descriptions, as described above.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 203:
> 
>> 201:                     // Don't report an empty description if the comment begins with @deprecated,
>> 202:                     // because javadoc will use the content of that tag in summary tables.
>> 203:                     if (firstTag.getKind() != DocTree.Kind.DEPRECATED) {
> 
> Why do we only check the first block tag here?

Various reasons, 
1. It seems the convention is to simply prefix an existing comment with `@deprecated` or to replace the existing body description with `@deprecated reason-why-deprecated`
2. This is only for the case when there is no body description; it seems hard to imagine that someone would start a comment with `@see` `@param` `@return` etc and then have the `@deprecated` tag.

That being said, it would be easy enough to change the code to check for any instance of `@deprecated`.

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

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

From jjg at openjdk.java.net  Mon Aug 16 17:18:29 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 16 Aug 2021 17:18:29 GMT
Subject: RFR: JDK-8272374: doclint should report missing "body" comments
In-Reply-To: <-8oey_QHb7omZMiWEFbMUkK37CdVDjxTBxEqCuZyumo=.130eca61-0ac3-4176-99ee-7426eb13048a@github.com>
References: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
 <-8oey_QHb7omZMiWEFbMUkK37CdVDjxTBxEqCuZyumo=.130eca61-0ac3-4176-99ee-7426eb13048a@github.com>
Message-ID: <zSgCk1XSolAY6wI1fBxC3WAynvajj___3TTetRl33R0=.e183b36b-11db-403c-a2a1-c0f3085bfb40@github.com>

On Fri, 13 Aug 2021 09:21:40 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a relatively simple update to have doclnt check for empty "descriptions" -- the body of a doc comment, before the block tags.
>> 
>> It is already the case that doclint checks for missing/empty descriptions in block tags, like @param, @return, etc.
>> 
>> There are three cases to consider:
>> 
>> * The comment itself is missing: this was already checked and reported as "missing comment".
>> * The comment is present, but is empty ... this seems relatively unlikely, but is nevertheless checked and reported as "empty comment".
>> * The comment is present but only has block tags. This is not always a problem, since the description may be inherited, for example, in an overriding method, but when it is an issue, it is reported as "no initial description". 
>> 
>> No diagnostic is reported if the description is missing but the first tag is `@deprecated`, because in this case, javadoc will use the body of the `@deprecated` tag for the summary. See [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA) and the corresponding entry in the summary table to see an example of this situation.
>> 
>> Diagnostics are reported if the declaration is not an overriding method and does not begin with `@deprecated`.  This occurs in a number of places in the `java.desktop` module, often where the doc comment is of the form `/** @return _description_ */`.  To suppress those warnings for now, the `-missing` option is added to `DOCLINT_OPTIONS` for the `java.desktop` module.  To see the effects of this anti-pattern, look at the empty descriptions for [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)
>> 
>> Many of the doclint tests needed to be updated, because of their over-simplistic minimal comments. It was not possible, in general, to avoid updating the source code while preserving line numbers, so in many cases, the golden `*.out` files had to be updated as well.
>> 
>> A new test is added, focussing on the different forms of empty/missing descriptions, as described above.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 204:
> 
>> 202:                     // because javadoc will use the content of that tag in summary tables.
>> 203:                     if (firstTag.getKind() != DocTree.Kind.DEPRECATED) {
>> 204:                         env.messages.report(MISSING, Kind.WARNING, tree, "dc.empty.description");
> 
> Is there a reason to not use `reportMissing` here?

It doesn't have the right signature. `reportMissing` reports a missing comment on an element; here, we're reporting a missing description within a `DocTree`.  There's a similar occurrence at line 1214.

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

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

From jjg at openjdk.java.net  Mon Aug 16 17:22:31 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 16 Aug 2021 17:22:31 GMT
Subject: RFR: JDK-8272374: doclint should report missing "body" comments
In-Reply-To: <8_n_Wcn6QF4nXLkgtIgrlTSKESOi5HmTpC_a4pcUKMM=.c9499fce-31b5-40ee-a806-2e92d5894bd6@github.com>
References: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
 <-8oey_QHb7omZMiWEFbMUkK37CdVDjxTBxEqCuZyumo=.130eca61-0ac3-4176-99ee-7426eb13048a@github.com>
 <8_n_Wcn6QF4nXLkgtIgrlTSKESOi5HmTpC_a4pcUKMM=.c9499fce-31b5-40ee-a806-2e92d5894bd6@github.com>
Message-ID: <2nzruNweIsajakC9eWy6UFJVrR6m5T4TDQuSvxP5PaY=.ec56f7db-f398-4d74-aa9f-f8c0b47a690b@github.com>

On Mon, 16 Aug 2021 17:08:13 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 203:
>> 
>>> 201:                     // Don't report an empty description if the comment begins with @deprecated,
>>> 202:                     // because javadoc will use the content of that tag in summary tables.
>>> 203:                     if (firstTag.getKind() != DocTree.Kind.DEPRECATED) {
>> 
>> Why do we only check the first block tag here?
>
> Various reasons, 
> 1. It seems the convention is to simply prefix an existing comment with `@deprecated` or to replace the existing body description with `@deprecated reason-why-deprecated`
> 2. This is only for the case when there is no body description; it seems hard to imagine that someone would start a comment with `@see` `@param` `@return` etc and then have the `@deprecated` tag.
> 
> That being said, it would be easy enough to change the code to check for any instance of `@deprecated`.

Given that the downstream code does not impose any ordering restrictions on the tags, it is probably with doing the same here.

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

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

From jjg at openjdk.java.net  Mon Aug 16 17:38:05 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 16 Aug 2021 17:38:05 GMT
Subject: RFR: JDK-8272374: doclint should report missing "body" comments
 [v2]
In-Reply-To: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
References: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
Message-ID: <yCUKX3UFlHzs7WalGdtNHtXaU6NPIt8h9227KKUBPsQ=.f2afbe37-98eb-4708-a97c-fa37f8fac786@github.com>

> Please review a relatively simple update to have doclnt check for empty "descriptions" -- the body of a doc comment, before the block tags.
> 
> It is already the case that doclint checks for missing/empty descriptions in block tags, like @param, @return, etc.
> 
> There are three cases to consider:
> 
> * The comment itself is missing: this was already checked and reported as "missing comment".
> * The comment is present, but is empty ... this seems relatively unlikely, but is nevertheless checked and reported as "empty comment".
> * The comment is present but only has block tags. This is not always a problem, since the description may be inherited, for example, in an overriding method, but when it is an issue, it is reported as "no initial description". 
> 
> No diagnostic is reported if the description is missing but the first tag is `@deprecated`, because in this case, javadoc will use the body of the `@deprecated` tag for the summary. See [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA) and the corresponding entry in the summary table to see an example of this situation.
> 
> Diagnostics are reported if the declaration is not an overriding method and does not begin with `@deprecated`.  This occurs in a number of places in the `java.desktop` module, often where the doc comment is of the form `/** @return _description_ */`.  To suppress those warnings for now, the `-missing` option is added to `DOCLINT_OPTIONS` for the `java.desktop` module.  To see the effects of this anti-pattern, look at the empty descriptions for [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)
> 
> Many of the doclint tests needed to be updated, because of their over-simplistic minimal comments. It was not possible, in general, to avoid updating the source code while preserving line numbers, so in many cases, the golden `*.out` files had to be updated as well.
> 
> A new test is added, focussing on the different forms of empty/missing descriptions, as described above.

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

  address review comment

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/5106/files
  - new: https://git.openjdk.java.net/jdk/pull/5106/files/60c6f569..6c875688

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

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

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

From jjg at openjdk.java.net  Mon Aug 16 18:18:29 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 16 Aug 2021 18:18:29 GMT
Subject: RFR: JDK-8264274: Block tags in overview.html are ignored [v2]
In-Reply-To: <6NgmO6qjBtUBDeOZQoh0eknZo8S9MtMX26gTs8gdo6Y=.614f90bf-c0f0-403a-aa93-77fdc923351e@github.com>
References: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>
 <6NgmO6qjBtUBDeOZQoh0eknZo8S9MtMX26gTs8gdo6Y=.614f90bf-c0f0-403a-aa93-77fdc923351e@github.com>
Message-ID: <zU4VsVNSjL1NYKnVYtfoP8ycZPJKqvOHK_OOuBmNDyA=.4124986a-d1c2-4334-87ee-10f7bb6ae51e@github.com>

On Fri, 13 Aug 2021 08:20:47 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This is a simple fix to generate block tags in overview files specified by the `-overview` option. 
>> 
>> I added a protected `addOverviewTags` method in `AbstractOverviewIndexWriter` which is probably overkill but keeps things flexible and separated.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   JDK-8264274: Simplify format specifier

Marked as reviewed by jjg (Reviewer).

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

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

From jjg at openjdk.java.net  Mon Aug 16 18:18:30 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 16 Aug 2021 18:18:30 GMT
Subject: RFR: JDK-8264274: Block tags in overview.html are ignored [v2]
In-Reply-To: <JVee9bI2TZ3bKuvbLWXmvgJOhpUmy-Ol-1eQrBcG1_E=.3fe32a5c-e8d4-4044-b3fb-fe3a26d41dbc@github.com>
References: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>
 <hEsOBuxPqxyx13tqkOVmoRwa6qJy22XuIK16fewJXfc=.d15e086a-3794-41e2-b8fc-e8c9dc89294d@github.com>
 <JVee9bI2TZ3bKuvbLWXmvgJOhpUmy-Ol-1eQrBcG1_E=.3fe32a5c-e8d4-4044-b3fb-fe3a26d41dbc@github.com>
Message-ID: <JNePvV7kfsr01PA8BtGn4XFuzoEeRhV7ISy5CuXfDFA=.9ac7388c-ed38-4780-aaca-9607c976a719@github.com>

On Fri, 13 Aug 2021 08:04:24 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> test/langtools/jdk/javadoc/doclet/testOverview/TestOverview.java line 80:
>> 
>>> 78:                     <dd>
>>> 79:                     <ul class="see-list">
>>> 80:                     <li><a href="%1$sp1/C.html" title="class in p1"><code>C</code></a></li>
>> 
>> What's with the funky URL?
>
> That's just a format string specifier "%1$s", meaning the first format argument (see invocation of `formatted` method below to adapt the string to a module or non-module context). 
> 
> I realize now that I could have omitted the argument index part of the format specifier, will update the PR if that is true.

Doh, silly me; of course.

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

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

From jjg at openjdk.java.net  Mon Aug 16 20:51:32 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 16 Aug 2021 20:51:32 GMT
Subject: Integrated: JDK-8272374: doclint should report missing "body" comments
In-Reply-To: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
References: <VR0LawdnoOHmZl_244sRHbULLBONAzfe8OYchIP6ErA=.aa8d7634-2a1b-4f8c-89f0-09b996d6c2f2@github.com>
Message-ID: <o5oW72ZtT8p2p9Yp8TDFbMvu-xZB9eLW2Nyp6xda0zQ=.c3be5680-d99e-41f2-91f0-4196820f4092@github.com>

On Fri, 13 Aug 2021 03:51:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a relatively simple update to have doclnt check for empty "descriptions" -- the body of a doc comment, before the block tags.
> 
> It is already the case that doclint checks for missing/empty descriptions in block tags, like @param, @return, etc.
> 
> There are three cases to consider:
> 
> * The comment itself is missing: this was already checked and reported as "missing comment".
> * The comment is present, but is empty ... this seems relatively unlikely, but is nevertheless checked and reported as "empty comment".
> * The comment is present but only has block tags. This is not always a problem, since the description may be inherited, for example, in an overriding method, but when it is an issue, it is reported as "no initial description". 
> 
> No diagnostic is reported if the description is missing but the first tag is `@deprecated`, because in this case, javadoc will use the body of the `@deprecated` tag for the summary. See [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA) and the corresponding entry in the summary table to see an example of this situation.
> 
> Diagnostics are reported if the declaration is not an overriding method and does not begin with `@deprecated`.  This occurs in a number of places in the `java.desktop` module, often where the doc comment is of the form `/** @return _description_ */`.  To suppress those warnings for now, the `-missing` option is added to `DOCLINT_OPTIONS` for the `java.desktop` module.  To see the effects of this anti-pattern, look at the empty descriptions for [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)
> 
> Many of the doclint tests needed to be updated, because of their over-simplistic minimal comments. It was not possible, in general, to avoid updating the source code while preserving line numbers, so in many cases, the golden `*.out` files had to be updated as well.
> 
> A new test is added, focussing on the different forms of empty/missing descriptions, as described above.

This pull request has now been integrated.

Changeset: ae45592d
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/ae45592d3304f50aa9e8e114416a41e7899fe37b
Stats:     280 lines in 37 files changed: 151 ins; 10 del; 119 mod

8272374: doclint should report missing "body" comments

Reviewed-by: kcr, hannesw

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

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

From jjg at openjdk.java.net  Mon Aug 16 22:45:41 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 16 Aug 2021 22:45:41 GMT
Subject: RFR: JDK-8271227: Missing `{@code }` in com.sun.source.*
Message-ID: <QrLj2xNu_uWyrD_IF0oFEUMS9PX8dtimLEwLhY1xm40=.15691434-2c42-4d20-aa8a-862ac2795e48@github.com>

Please review a simple `noreg-doc` update to files in the `com.sun.source.*` API, to enclose type names in the descriptions in doc comments with `{@code }`. 

Apart from fixing one typo, the changes are all formatting changes, with no changes to the content of the spec, so no CSR.

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

Commit messages:
 - JDK-8271227: Missing `{@code }` in com.sun.source.*

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

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

From iris at openjdk.java.net  Mon Aug 16 22:55:30 2021
From: iris at openjdk.java.net (Iris Clark)
Date: Mon, 16 Aug 2021 22:55:30 GMT
Subject: RFR: JDK-8271227: Missing `{@code }` in com.sun.source.*
In-Reply-To: <QrLj2xNu_uWyrD_IF0oFEUMS9PX8dtimLEwLhY1xm40=.15691434-2c42-4d20-aa8a-862ac2795e48@github.com>
References: <QrLj2xNu_uWyrD_IF0oFEUMS9PX8dtimLEwLhY1xm40=.15691434-2c42-4d20-aa8a-862ac2795e48@github.com>
Message-ID: <Jb_bKnRSw3kiZjs2ZI_GRTUX6KGqNu5lEHfwSOv9_ZY=.9926d3a4-8b9c-4500-9010-8d1c4def0349@github.com>

On Mon, 16 Aug 2021 22:37:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple `noreg-doc` update to files in the `com.sun.source.*` API, to enclose type names in the descriptions in doc comments with `{@code }`. 
> 
> Apart from fixing one typo, the changes are all formatting changes, with no changes to the content of the spec, so no CSR.

Marked as reviewed by iris (Reviewer).

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

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

From jjg at openjdk.java.net  Mon Aug 16 22:58:31 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 16 Aug 2021 22:58:31 GMT
Subject: Integrated: JDK-8271227: Missing `{@code }` in com.sun.source.*
In-Reply-To: <QrLj2xNu_uWyrD_IF0oFEUMS9PX8dtimLEwLhY1xm40=.15691434-2c42-4d20-aa8a-862ac2795e48@github.com>
References: <QrLj2xNu_uWyrD_IF0oFEUMS9PX8dtimLEwLhY1xm40=.15691434-2c42-4d20-aa8a-862ac2795e48@github.com>
Message-ID: <DwbCnCQQOOBzmC5mn3CTJR6DneH5exiVFEH_fXchd_E=.ca18aa3e-51c6-4f05-a9e1-f7020149e0ec@github.com>

On Mon, 16 Aug 2021 22:37:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple `noreg-doc` update to files in the `com.sun.source.*` API, to enclose type names in the descriptions in doc comments with `{@code }`. 
> 
> Apart from fixing one typo, the changes are all formatting changes, with no changes to the content of the spec, so no CSR.

This pull request has now been integrated.

Changeset: 3fb19279
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/3fb19279da240ecabee04148ba8907f036450575
Stats:     133 lines in 3 files changed: 0 ins; 0 del; 133 mod

8271227: Missing `{@code }` in com.sun.source.*

Reviewed-by: iris

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

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

From hannesw at openjdk.java.net  Tue Aug 17 08:32:28 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 17 Aug 2021 08:32:28 GMT
Subject: Integrated: JDK-8264274: Block tags in overview.html are ignored
In-Reply-To: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>
References: <JXCW7v-Z8gFryfxVqoW26n70VgskN1XvaawpoLYiSCo=.d35e4ce0-df10-4c6e-bb6e-28e842bdd2a1@github.com>
Message-ID: <zr_6ppI3EOw0LFH33Go4ZwHFz80aynZBNbAEDG5Oj2o=.fdd117b9-19af-4056-a24d-691eab6f4574@github.com>

On Thu, 12 Aug 2021 12:39:37 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This is a simple fix to generate block tags in overview files specified by the `-overview` option. 
> 
> I added a protected `addOverviewTags` method in `AbstractOverviewIndexWriter` which is probably overkill but keeps things flexible and separated.

This pull request has now been integrated.

Changeset: 0e3fde6c
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/0e3fde6c3c2f5c05777b79ff5eb1188014269b0f
Stats:     30 lines in 3 files changed: 20 ins; 1 del; 9 mod

8264274: Block tags in overview.html are ignored

Reviewed-by: jjg

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

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

From hannesw at openjdk.java.net  Wed Aug 18 12:03:28 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 18 Aug 2021 12:03:28 GMT
Subject: RFR: JDK-8270195: Add missing links between methods of JavaFX
 properties
In-Reply-To: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
References: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
Message-ID: <BEd0PwHjK7G-H1TIQ17uUayoeyit1aokYDBI8A8mUso=.ef313db5-d274-49e4-914b-56b322f3cc98@github.com>

On Thu, 12 Aug 2021 17:38:14 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a medium-size update to the support for JavaFX properties in the Standard Doclet.
> 
> A JavaFX property is typically defined by a group of up to 4 elements:
> * an optional field, which is typically private
> * a no-args property method, whose name ends in `Property` and which returns an appropriate property object
> * an optional getter method which can get the value of the property
> * an optional setter method which can set the value of the property
> 
> Either the field (if present) or the property method (but not both) should have a comment describing the property. The rest should generally _not_have comments: comments will be automatically generated.
> 
> This change is primarily to improve the generation of the comments. `@see` links are generated between the methods for a property. In addition, improvements are made to the handling of `@return` ... adding it as needed, and removing it when not (the latter occurs when generating the docs for the property itself, using the info in the property method.)
> 
> There is some amount of cleanup to the implementation, most notably moving (and rewriting) the code to generate comments for property methods from `MemberSummaryBuilder` to `CommentUtils`,which is where most other synthesized comments are generated. However, the goal has also been to not unduly change the spirit and spec of the original code.
> 
> A new combo test for JavaFX properties is provided, that creates different instances of a class, containing different property-related methods with and without comments. Basic properties of the output are then verified for each property method: the description, any parameter info, any return info, and any links to other related methods.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java line 528:

> 526:      * @return a content tree for the text
> 527:      */
> 528:     public List<? extends DocTree> getComment(String key, Object o0, Object o1, Object o2) {

What is the purpose of this rather complex method to format a text resource? It seems like it is arguments `o1` and `o2` are never used. Couldn't this be implemented simply using `MessageFormat` as it used to be?

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

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

From jjg at openjdk.java.net  Wed Aug 18 20:17:39 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 18 Aug 2021 20:17:39 GMT
Subject: RFR: JDK-8271258: @param with non-ascii variable names produces
 incorrect results
Message-ID: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>

Please review a simple change to fix the use of non-ASCII characters in @param names.

The underlying problem was accidentally relying on `DocTree.toString()` for an `IdentifierTree` in `CommentHelper`.  The fix is simply to get the underlying `Name` and call `toString` on that.

There is some loosely related cleanup in `ParamTaglet`. I did see if it was possible to avoid excessive use of `String` in this part of the code, but that quickly became a rat-hole.

The existing related test is updated to include this new case, of a Chinese identifier occurring in various places, similar to the test case in the original bug.

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

Commit messages:
 - JDK-8271258: @param with non-ascii variable names produces incorrect results

Changes: https://git.openjdk.java.net/jdk/pull/5168/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=5168&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8271258
  Stats: 94 lines in 3 files changed: 63 ins; 6 del; 25 mod
  Patch: https://git.openjdk.java.net/jdk/pull/5168.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/5168/head:pull/5168

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

From hannesw at openjdk.java.net  Thu Aug 19 09:44:24 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 19 Aug 2021 09:44:24 GMT
Subject: RFR: JDK-8271258: @param with non-ascii variable names produces
 incorrect results
In-Reply-To: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>
References: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>
Message-ID: <--kwl4aUVyJf9OHkkMe69qqX1-d79qV2qyB7A9rAi1Y=.5927cd0b-2a92-4189-85fd-dff3d0e41c4c@github.com>

On Wed, 18 Aug 2021 20:10:48 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple change to fix the use of non-ASCII characters in @param names.
> 
> The underlying problem was accidentally relying on `DocTree.toString()` for an `IdentifierTree` in `CommentHelper`.  The fix is simply to get the underlying `Name` and call `toString` on that.
> 
> There is some loosely related cleanup in `ParamTaglet`. I did see if it was possible to avoid excessive use of `String` in this part of the code, but that quickly became a rat-hole.
> 
> The existing related test is updated to include this new case, of a Chinese identifier occurring in various places, similar to the test case in the original bug.

The fix and the added test look good, but I think you accidentally dropped a test string in the existing test.

test/langtools/jdk/javadoc/doclet/testUnicode/TestUnicode.java line 64:

> 62:         checkOutput("Code.html", true,
> 63:                 """
> 64:                         """);

Is don't think this is supposed to be an empty string, is it?

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

Changes requested by hannesw (Reviewer).

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

From myano at openjdk.java.net  Fri Aug 20 10:31:47 2021
From: myano at openjdk.java.net (Masanori Yano)
Date: Fri, 20 Aug 2021 10:31:47 GMT
Subject: RFR: 8248001: javadoc generates invalid HTML pages whose ftp:// links
 are broken
Message-ID: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>

Could you please review the 8248001 bug fixes?

The problem is that javadoc generates invalid HTML pages whose ftp:// links are broken. The fix changes not to use protocol names directly, but to use regular expression.

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

Commit messages:
 - 8248001: javadoc generates invalid HTML pages whose ftp:// links are broken
 - 8248001: javadoc generates invalid HTML pages whose ftp:// links are broken
 - 8248001: javadoc generates invalid HTML pages whose ftp:// links are broken

Changes: https://git.openjdk.java.net/jdk/pull/5198/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=5198&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8248001
  Stats: 324 lines in 5 files changed: 319 ins; 4 del; 1 mod
  Patch: https://git.openjdk.java.net/jdk/pull/5198.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/5198/head:pull/5198

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

From prappo at openjdk.java.net  Fri Aug 20 10:51:23 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Fri, 20 Aug 2021 10:51:23 GMT
Subject: RFR: 8248001: javadoc generates invalid HTML pages whose ftp://
 links are broken
In-Reply-To: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>
References: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>
Message-ID: <ahB3g8-B9SSJ4J-q0uW3itCswu7PGfYUhxR53btCAKk=.0255f3b4-a5c2-4c28-8bc7-724e42519e7e@github.com>

On Fri, 20 Aug 2021 10:12:11 GMT, Masanori Yano <myano at openjdk.org> wrote:

> Could you please review the 8248001 bug fixes?
> 
> The problem is that javadoc generates invalid HTML pages whose ftp:// links are broken. The fix changes not to use protocol names directly, but to use regular expression.

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

> 1701:             return text;
> 1702:         }
> 1703:         if (text.matches("^[^:/?#]+:.+$")) {

Why not use `java.net.URI` API to determine if the link contains a scheme?

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

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

From dfuchs at openjdk.java.net  Fri Aug 20 11:26:26 2021
From: dfuchs at openjdk.java.net (Daniel Fuchs)
Date: Fri, 20 Aug 2021 11:26:26 GMT
Subject: RFR: 8248001: javadoc generates invalid HTML pages whose ftp://
 links are broken
In-Reply-To: <ahB3g8-B9SSJ4J-q0uW3itCswu7PGfYUhxR53btCAKk=.0255f3b4-a5c2-4c28-8bc7-724e42519e7e@github.com>
References: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>
 <ahB3g8-B9SSJ4J-q0uW3itCswu7PGfYUhxR53btCAKk=.0255f3b4-a5c2-4c28-8bc7-724e42519e7e@github.com>
Message-ID: <luwvXZ5xVJj1b5bjh4U_TTtbZGOS4N9TAIYDPLp46S4=.0a470613-04e9-4ad6-9a72-4707c12b0596@github.com>

On Fri, 20 Aug 2021 10:48:10 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Could you please review the 8248001 bug fixes?
>> 
>> The problem is that javadoc generates invalid HTML pages whose ftp:// links are broken. The fix changes not to use protocol names directly, but to use regular expression.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1703:
> 
>> 1701:             return text;
>> 1702:         }
>> 1703:         if (text.matches("^[^:/?#]+:.+$")) {
> 
> Why not use `java.net.URI` API to determine if the link contains a scheme?

I assume the link is in an HTML document and goes in an HTML document. If you wanted to use java.net.URI, depending on where from `text` comes from and whereto it goes, you might need first to decode it using URLDecoder, and then you might need to re-encode it before spitting it out... That's a lot of operations where things could go wrong, especially if the link contains a query string.

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

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

From dfuchs at openjdk.java.net  Fri Aug 20 11:44:25 2021
From: dfuchs at openjdk.java.net (Daniel Fuchs)
Date: Fri, 20 Aug 2021 11:44:25 GMT
Subject: RFR: 8248001: javadoc generates invalid HTML pages whose ftp://
 links are broken
In-Reply-To: <luwvXZ5xVJj1b5bjh4U_TTtbZGOS4N9TAIYDPLp46S4=.0a470613-04e9-4ad6-9a72-4707c12b0596@github.com>
References: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>
 <ahB3g8-B9SSJ4J-q0uW3itCswu7PGfYUhxR53btCAKk=.0255f3b4-a5c2-4c28-8bc7-724e42519e7e@github.com>
 <luwvXZ5xVJj1b5bjh4U_TTtbZGOS4N9TAIYDPLp46S4=.0a470613-04e9-4ad6-9a72-4707c12b0596@github.com>
Message-ID: <uTXidQfq4LGpFMsxGiw_EzFuIRDMnIDR6hvAN3TjGiM=.7f0509f1-67a3-4926-afd0-a8ce9fdc8e18@github.com>

On Fri, 20 Aug 2021 11:22:07 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1703:
>> 
>>> 1701:             return text;
>>> 1702:         }
>>> 1703:         if (text.matches("^[^:/?#]+:.+$")) {
>> 
>> Why not use `java.net.URI` API to determine if the link contains a scheme?
>
> I assume the link is in an HTML document and goes in an HTML document. If you wanted to use java.net.URI, depending on where from `text` comes from and whereto it goes, you might need first to decode it using URLDecoder, and then you might need to re-encode it before spitting it out... That's a lot of operations where things could go wrong, especially if the link contains a query string.

That said a stricter regexp (unless I'm mistaken) could be: `^[a-zA-Z][a-zA-Z0-9+-.]*:.*$`
[ from RFC 2396:     scheme        = alpha *( alpha | digit | "+" | "-" | "." ) ]

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

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

From prappo at openjdk.java.net  Fri Aug 20 11:59:25 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Fri, 20 Aug 2021 11:59:25 GMT
Subject: RFR: 8248001: javadoc generates invalid HTML pages whose ftp://
 links are broken
In-Reply-To: <uTXidQfq4LGpFMsxGiw_EzFuIRDMnIDR6hvAN3TjGiM=.7f0509f1-67a3-4926-afd0-a8ce9fdc8e18@github.com>
References: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>
 <ahB3g8-B9SSJ4J-q0uW3itCswu7PGfYUhxR53btCAKk=.0255f3b4-a5c2-4c28-8bc7-724e42519e7e@github.com>
 <luwvXZ5xVJj1b5bjh4U_TTtbZGOS4N9TAIYDPLp46S4=.0a470613-04e9-4ad6-9a72-4707c12b0596@github.com>
 <uTXidQfq4LGpFMsxGiw_EzFuIRDMnIDR6hvAN3TjGiM=.7f0509f1-67a3-4926-afd0-a8ce9fdc8e18@github.com>
Message-ID: <rFeoyv8bovsFmH9qJyCsd2Knf2gRfRvaRO0EGD9AWig=.941ea1ac-6c58-4140-bd16-5a9879b98a70@github.com>

On Fri, 20 Aug 2021 11:41:02 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> I assume the link is in an HTML document and goes in an HTML document. If you wanted to use java.net.URI, depending on where from `text` comes from and whereto it goes, you might need first to decode it using URLDecoder, and then you might need to re-encode it before spitting it out... That's a lot of operations where things could go wrong, especially if the link contains a query string.
>
> That said a stricter regexp (unless I'm mistaken) could be: `^[a-zA-Z][a-zA-Z0-9+-.]*:.*$`
> [ from RFC 2396:     scheme        = alpha *( alpha | digit | "+" | "-" | "." ) ]

My only concerns were correctness and code reuse. Using an API doesn't require one to read through RFC.

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

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

From jjg at openjdk.java.net  Fri Aug 20 18:53:33 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 20 Aug 2021 18:53:33 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
Message-ID: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>

On Fri, 6 Aug 2021 12:24:06 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Pass through FIXMEs and TODOs
>   
>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.

Generally impressive piece of work.

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java line 291:

> 289: 
> 290:     /**
> 291:      * Visits a SnippetTree node.

There's been a recent update, and these class names should now be wrapped in `{@code }`

src/jdk.compiler/share/classes/com/sun/source/doctree/SnippetTree.java line 32:

> 30: /**
> 31:  * A tree node for an {@code @snippet} inline tag, as specified by
> 32:  * <a href="http://openjdk.java.net/jeps/413">JEP 413</a>.

The reference to a JEP is unusual.  The public spec for a snippet should be in the tag spec.

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 513:

> 511: 
> 512:     /**
> 513:      * {@inheritDoc} This implementation scans the children in left to right order.

(minor)
I would suggest/recommend a line-break after the `{@inheritDoc}`
Likewise for similar occurrences elsewhere.

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 516:

> 514:      *
> 515:      * @param node  {@inheritDoc}
> 516:      * @param p  {@inheritDoc}

Do you need the `{@inheritDoc}` ... isn't that the default behavior if no tag is specified?

Likewise for similar occurrences elsewhere.

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

> 921:          * probably be considered on a case-by-case basis, for an attribute
> 922:          * value of the {@snippet} tag we do not recurse.
> 923:          */

This discussion does not belong here.

We should specify simple defensible rules (in the spec) and implement them accordingly.
If there is nothing more obvious, I suggest the rules for (Unicode) identifiers.

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

> 1247: //                    messages.warning(
> 1248: //                            ch.getDocTreePath(see), "doclet.see.class_or_package_not_found",
> 1249: //                            tagName, seeText);

FIXME

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java line 399:

> 397:                         classes.add(n.name());
> 398:                     } else if (s instanceof Style.Link l) {
> 399:                         assert !linkEncountered; // FIXME: do not assert; pick the first link

FIXME

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java line 406:

> 404:                             // diagnostic output
> 405:                         }
> 406:                     } else if (s instanceof Style.Markup) {

Is the empty `if` expected?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java line 87:

> 85:     snippet,
> 86:     //</editor-fold>
> 87: 

Suggest removing the editor-fold comments.  It'll be listed as not-yet-categorized by virtue of being in the initial list.

If the code generates standard styles, they should be listed here, so that they get documented in the sometime-forthcoming stylesheet spec.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties line 360:

> 358: 
> 359: doclet.tag.attribute.repeated=\
> 360:  repeated attribute: "{0}"

check the resource file for other quoted values; I think you'll find single quotes are the prevailing standard.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 39:

> 37: import jdk.javadoc.internal.doclets.toolkit.taglets.snippet.Parser;
> 38: import jdk.javadoc.internal.doclets.toolkit.taglets.snippet.StyledText;
> 39: import jdk.javadoc.internal.doclets.toolkit.util.Utils;

The langtools/javac/javadoc convention is to put standard JavaSE imports (`java.*`, `javax.*` ) first.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 96:

> 94:             // recently encountered of two, the iteration order might differ
> 95:             // from the source order
> 96:             error(writer, holder, a, "doclet.tag.attribute.repeated", a.getName().toString());

Can we use a `LinkedHashMap` or similar to preserve encounter order?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 178:

> 176:         }
> 177: 
> 178:         // FIXME cache parsed external snippet (WeakHashMap)

FIXME

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 260:

> 258:      * There's a separate issue of mapping discrepancies back to their
> 259:      * originating source in the doc comment and the external file. Maybe there
> 260:      * is a value in it, or may be there isn't. In any case, accurate mapping

"maybe"

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 274:

> 272:     private StyledText parse(String content) throws ParseException {
> 273:         // FIXME: need to be able to process more fine-grained, i.e. around a particular region...
> 274:         // or, which is even better, cache the styled text

FIXME

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 287:

> 285: 
> 286:     // FIXME: figure out how to do that correctly
> 287:     // FIXME: consider returning null from this method so it can be used as oneliner

FIXME

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 69:

> 67: // FIXME: How to treat Form Feed? (i.e. is it vertical or horizontal whitespace?)
> 68: // FIXME: what to do with lines not covered by any markup? (i.e. in between markup)
> 69: // FIXME: all parsing errors must be localized.

FIXME

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 134:

> 132:             this.eolMarker = eolMarker;
> 133:             // capture the rightmost eolMarker (e.g. "//")
> 134:             // The bellow Pattern.compile should never throw PatternSyntaxException

"below" ?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 177:

> 175:                 }
> 176:                 thisLineTags.addAll(parsedTags);
> 177:                 for (var tagIterator = thisLineTags.iterator(); tagIterator.hasNext(); ) {

oooh, not wrong; just unexpected mix of styles ;-)

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 186:

> 184:                 }
> 185:                 if (parsedTags.isEmpty()) { // (2)
> 186:                     // TODO: log this with NOTICE;

does this need to be addressed?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 207:

> 205: 
> 206:             append(text, Set.of(), line);
> 207:             // FIXME: mark up trailing whitespace!

FIXME

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/CommentHelper.java line 376:

> 374: 
> 375:     public TypeElement getReferencedClass(Element e) {
> 376:         Utils utils = configuration.utils;

Whinge. This new method does not really belong here, also implying that the body of the old method does not belong here (in the class) either.  Generally, queries on elements belong in `Utils`, not `CommentHelper`.

But, OK for now, I guess.

--

As a one-off, it was OK to let this slide. Given there are repeated similar occurrences later on, can you file an RFE to move the `Element` / non-`DocTree` methods to `Utils`.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/CommentHelper.java line 406:

> 404: 
> 405:     public Element getReferencedMember(Element e) {
> 406:         Utils utils = configuration.utils;

Same whinge as above.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/CommentHelper.java line 431:

> 429:     }
> 430: 
> 431:     public PackageElement getReferencedPackage(Element e) {

ditto

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/CommentHelper.java line 444:

> 442:     }
> 443: 
> 444:     public ModuleElement getReferencedModule(Element e) {

ditto

test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetTag.java line 27:

> 25:  * @test
> 26:  * @bug 8201533
> 27:  * @library /tools/lib ../../lib

need @summary

test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetTag.java line 81:

> 79: 
> 80:     public static void main(String... args) throws Exception {
> 81:         new TestSnippetTag().runTests(m -> new Object[]{Paths.get(m.getName())});

This is just a suggestion for future convenience.
For big tests like this, for ease of debugging, it can be useful to be able to specify the method(s) to be executed.   Maybe there should be a variants of `runTests` that takes a `String[]` or `List<String>`

test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetTag.java line 1508:

> 1506:                 )
> 1507: // Uncomment when parser has improved (this would allow to write meta snippets,
> 1508: // i.e. snippets showing how to write snippets.

Just a question: what are the limitations in the parser that are getting in the way here?

test/langtools/tools/javac/doctree/SnippetTest.java line 26:

> 24: /*
> 25:  * @test
> 26:  * @bug 8201533

Need `@summary`

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

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

From jjg at openjdk.java.net  Sat Aug 21 03:16:39 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Sat, 21 Aug 2021 03:16:39 GMT
Subject: RFR: JDK-8265253: javac -Xdoclint:all gives "no comment" warning for
 code that can't be commented
Message-ID: <fXGm9RZMy77DUrw3b0q122JA50quka_YXJksYdyKm-U=.00b33b40-070f-4377-9262-040d08a658cb@github.com>

Please review a simple update for doclint, to suppress "missing comment" warnings on the internally-synthesized class resulting from use of an anonymous class body in a member declaration in an enum class..

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

Commit messages:
 - JDK-8265253: javac -Xdoclint:all gives "no comment" warning for code that can't be commented

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

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

From github.com+15714253+anthonyvdotbe at openjdk.java.net  Sat Aug 21 08:04:22 2021
From: github.com+15714253+anthonyvdotbe at openjdk.java.net (Anthony Vanelverdinghe)
Date: Sat, 21 Aug 2021 08:04:22 GMT
Subject: RFR: 8248001: javadoc generates invalid HTML pages whose ftp://
 links are broken
In-Reply-To: <rFeoyv8bovsFmH9qJyCsd2Knf2gRfRvaRO0EGD9AWig=.941ea1ac-6c58-4140-bd16-5a9879b98a70@github.com>
References: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>
 <ahB3g8-B9SSJ4J-q0uW3itCswu7PGfYUhxR53btCAKk=.0255f3b4-a5c2-4c28-8bc7-724e42519e7e@github.com>
 <luwvXZ5xVJj1b5bjh4U_TTtbZGOS4N9TAIYDPLp46S4=.0a470613-04e9-4ad6-9a72-4707c12b0596@github.com>
 <uTXidQfq4LGpFMsxGiw_EzFuIRDMnIDR6hvAN3TjGiM=.7f0509f1-67a3-4926-afd0-a8ce9fdc8e18@github.com>
 <rFeoyv8bovsFmH9qJyCsd2Knf2gRfRvaRO0EGD9AWig=.941ea1ac-6c58-4140-bd16-5a9879b98a70@github.com>
Message-ID: <1y-BgdU69vHP84B7P-QAfhLxnflsxuRZEqkjqPHaBZk=.eaf75027-faa7-4474-9af0-a5f6300e11f9@github.com>

On Fri, 20 Aug 2021 11:56:08 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> That said a stricter regexp (unless I'm mistaken) could be: `^[a-zA-Z][a-zA-Z0-9+-.]*:.+$`
>> [ from RFC 2396:     scheme        = alpha *( alpha | digit | "+" | "-" | "." ) ]
>
> My only concerns were correctness and code reuse. Using an API doesn't require one to read through RFC.

I'd argue for simply adding `ftp:` as an additional condition (unless there's other interesting URI schemes I'm not thinking of?). If a regex is to be used, I agree it should be much stricter (and defined in a constant, so that the `Pattern` doesn't need to be compiled on each invocation?).

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

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

From hannesw at openjdk.java.net  Mon Aug 23 12:59:31 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 23 Aug 2021 12:59:31 GMT
Subject: RFR: JDK-8265253: javac -Xdoclint:all gives "no comment" warning
 for code that can't be commented
In-Reply-To: <fXGm9RZMy77DUrw3b0q122JA50quka_YXJksYdyKm-U=.00b33b40-070f-4377-9262-040d08a658cb@github.com>
References: <fXGm9RZMy77DUrw3b0q122JA50quka_YXJksYdyKm-U=.00b33b40-070f-4377-9262-040d08a658cb@github.com>
Message-ID: <1ekvRzAVGtgHy_BxyZJ3sgckF327v-71dtrLJhlxwp4=.d5d5af05-212d-4c30-aede-7e657e719736@github.com>

On Sat, 21 Aug 2021 03:08:41 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple update for doclint, to suppress "missing comment" warnings on the internally-synthesized class resulting from use of an anonymous class body in a member declaration in an enum class..

Looks good.

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

Marked as reviewed by hannesw (Reviewer).

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

From prappo at openjdk.java.net  Mon Aug 23 14:08:52 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 14:08:52 GMT
Subject: RFR: 8266666: Implementation for snippets [v8]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <3xHiNyTqxKK4xHo1s5mucwvbIc9x8T0O7pbKCFGZ_4o=.5d7f6a13-e185-4df6-b92f-91c6520a5ad0@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 12 commits:

 - Merge branch 'master' into 8266666
 - Pass through FIXMEs and TODOs
   
   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
 - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
   
   Co-authored-by: Hannes Wallnoefer <hannesw at gmail.com>
 - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
   
   Co-authored-by: Hannes Wallnoefer <hannesw at gmail.com>
 - Change AnnotatedText<T> to StyledText
   
   Renames the class, removes its generic parameter, and changes the related terminology from "annotate" to "style".
 - Restructure ...toolkit.taglets.snippet.** packages
   
   This commit moves the contents of the jdk.javadoc.internal.doclets.toolkit.taglets.snippet.{action,parser,text} packages into the jdk.javadoc.internal.doclets.toolkit.taglets.snippet package.
 - Make CSS rules more specific
 - Improve comments
   
   This commit adds trivial commentary to some of the Java declarations. This commit also adds the "This is NOT part of any supported API..." disclaimer.
 - Update @since tags
 - Update copyright years
 - ... and 2 more: https://git.openjdk.java.net/jdk/compare/b7f75c0a...e1dbd98d

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

Changes: https://git.openjdk.java.net/jdk/pull/4795/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=07
  Stats: 4716 lines in 44 files changed: 4689 ins; 4 del; 23 mod
  Patch: https://git.openjdk.java.net/jdk/pull/4795.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/4795/head:pull/4795

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

From prappo at openjdk.java.net  Mon Aug 23 14:08:53 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 14:08:53 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <0Wi4TkCH6CinNMMZnY56KyT1YWBz34P2kwiXOo0ZrUg=.80c9f0ab-1af9-446e-9d36-697104019f64@github.com>

On Fri, 20 Aug 2021 17:45:21 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java line 291:
> 
>> 289: 
>> 290:     /**
>> 291:      * Visits a SnippetTree node.
> 
> There's been a recent update, and these class names should now be wrapped in `{@code }`

I was aware of that update and hoped to incorporate it properly with the next merge, which I've just done: e1dbd98dfa51f7568e787b1b72a6e30bfc6f4987

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

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

From prappo at openjdk.java.net  Mon Aug 23 15:22:35 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 15:22:35 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <Ol3_bDxdVr96D7TjGIWuFWTXiUO11-oftgl4FVZM9SQ=.0b082b6e-3f68-45cb-9443-49d50fd404b2@github.com>

On Fri, 20 Aug 2021 17:49:03 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 513:
> 
>> 511: 
>> 512:     /**
>> 513:      * {@inheritDoc} This implementation scans the children in left to right order.
> 
> (minor)
> I would suggest/recommend a line-break after the `{@inheritDoc}`
> Likewise for similar occurrences elsewhere.

See https://github.com/openjdk/jdk/pull/4795#discussion_r694070081. Let's NOT do it in this PR.

> src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 516:
> 
>> 514:      *
>> 515:      * @param node  {@inheritDoc}
>> 516:      * @param p  {@inheritDoc}
> 
> Do you need the `{@inheritDoc}` ... isn't that the default behavior if no tag is specified?
> 
> Likewise for similar occurrences elsewhere.

I don't think that I need `{@inheritDoc}` to inherit the comments in that and the similar cases in that file. I used that style because other parts of the file use it and I didn't want to update the file inconsistently. If we don't like that style, we are free to change it. That said, let's NOT do it in this PR.

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

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

From prappo at openjdk.java.net  Mon Aug 23 15:31:08 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 15:31:08 GMT
Subject: RFR: 8266666: Implementation for snippets [v9]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <8npES8SI6DiPj2CIU2FPqcFUw6G10V-cfCQVNus6ZfU=.f7f7e83f-a68a-4a89-9300-4c14397851d7@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

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

  Remove JEP link from SnippetTree

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/e1dbd98d..942b1e98

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=08
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=07-08

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

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

From prappo at openjdk.java.net  Mon Aug 23 15:31:13 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 15:31:13 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <l8k9QTCdnfWkJ4-GeRTFs4o7SZJgZ_hHqAcoa0XGzsc=.aabc119b-6ab7-4eaa-bdd2-5352e288fc83@github.com>

On Fri, 20 Aug 2021 17:46:38 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> src/jdk.compiler/share/classes/com/sun/source/doctree/SnippetTree.java line 32:
> 
>> 30: /**
>> 31:  * A tree node for an {@code @snippet} inline tag, as specified by
>> 32:  * <a href="http://openjdk.java.net/jeps/413">JEP 413</a>.
> 
> The reference to a JEP is unusual.  The public spec for a snippet should be in the tag spec.

Fixed in 942b1e9874f1f103b75c9d1b737b289296254dc7.

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

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

From prappo at openjdk.java.net  Mon Aug 23 16:04:34 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 16:04:34 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <sbBmVd7mJ8LGMVSFhGQtpBCuJ6hK6DJhzodAbKb9oUs=.ec5f206e-2c19-499a-b8c5-0ad521a933d1@github.com>

On Fri, 20 Aug 2021 17:54:37 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This discussion does not belong here.

I've hoped to specify tag syntax before we push this PR. Until the syntax has been specified, the comment has to be stored somewhere. What would be an appropriate place to store that comment in?

> I suggest the rules for (Unicode) identifiers

What do those rules look like? Do you have a link handy?

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

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

From prappo at openjdk.java.net  Mon Aug 23 16:12:00 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 16:12:00 GMT
Subject: RFR: 8266666: Implementation for snippets [v10]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <yzFbLQJhxcO1DASdGpCrWVS7blQ6j3oio1sXf5iFPro=.1e95333d-8863-409a-8bd0-9c1666914335@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

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

  Remove superfluous editor-fold

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/942b1e98..731a1a6b

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=09
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=08-09

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

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

From prappo at openjdk.java.net  Mon Aug 23 16:12:05 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 16:12:05 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <JPFYNmlQGj9YOmSggK-GHc6zUcuX-JmNr4CgNKD8RrM=.1751b115-4984-4fbb-8cd0-cf6cb92074b0@github.com>

On Fri, 20 Aug 2021 18:03:12 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java line 87:
> 
>> 85:     snippet,
>> 86:     //</editor-fold>
>> 87: 
> 
> Suggest removing the editor-fold comments.  It'll be listed as not-yet-categorized by virtue of being in the initial list.
> 
> If the code generates standard styles, they should be listed here, so that they get documented in the sometime-forthcoming stylesheet spec.

Fixed in 731a1a6be1a.

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

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

From prappo at openjdk.java.net  Mon Aug 23 17:18:33 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 17:18:33 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <2iWH0I7EWTfC6BjytMqzwNiGfz4ThWzW06SpDyM6urY=.10eb237b-b287-4a4c-a243-bf42f330a17b@github.com>

On Fri, 20 Aug 2021 18:25:02 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 177:
> 
>> 175:                 }
>> 176:                 thisLineTags.addAll(parsedTags);
>> 177:                 for (var tagIterator = thisLineTags.iterator(); tagIterator.hasNext(); ) {
> 
> oooh, not wrong; just unexpected mix of styles ;-)

Can you be more specific? In what sense is this unexpected?

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 186:
> 
>> 184:                 }
>> 185:                 if (parsedTags.isEmpty()) { // (2)
>> 186:                     // TODO: log this with NOTICE;
> 
> does this need to be addressed?

I think that it does. It's the case of spurious markup. Such a case likely requires author's attention.

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

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

From jjg at openjdk.java.net  Mon Aug 23 17:34:34 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 23 Aug 2021 17:34:34 GMT
Subject: Integrated: JDK-8265253: javac -Xdoclint:all gives "no comment"
 warning for code that can't be commented
In-Reply-To: <fXGm9RZMy77DUrw3b0q122JA50quka_YXJksYdyKm-U=.00b33b40-070f-4377-9262-040d08a658cb@github.com>
References: <fXGm9RZMy77DUrw3b0q122JA50quka_YXJksYdyKm-U=.00b33b40-070f-4377-9262-040d08a658cb@github.com>
Message-ID: <v0jFH4d5rCDVs5y8Fq-qAcSR3jl3oGMuTpmZAZK6jvQ=.2881fcd3-8629-4ec3-b4aa-6b45a328e63c@github.com>

On Sat, 21 Aug 2021 03:08:41 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple update for doclint, to suppress "missing comment" warnings on the internally-synthesized class resulting from use of an anonymous class body in a member declaration in an enum class..

This pull request has now been integrated.

Changeset: 18840724
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/18840724749c839259688bfa052652a1f34a378a
Stats:     60 lines in 3 files changed: 59 ins; 0 del; 1 mod

8265253: javac -Xdoclint:all gives "no comment" warning for code that can't be commented

Reviewed-by: hannesw

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

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

From jjg at openjdk.java.net  Mon Aug 23 17:39:36 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 23 Aug 2021 17:39:36 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <sbBmVd7mJ8LGMVSFhGQtpBCuJ6hK6DJhzodAbKb9oUs=.ec5f206e-2c19-499a-b8c5-0ad521a933d1@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
 <sbBmVd7mJ8LGMVSFhGQtpBCuJ6hK6DJhzodAbKb9oUs=.ec5f206e-2c19-499a-b8c5-0ad521a933d1@github.com>
Message-ID: <McZcJN1VUIkDrqnx5BrygJaVI_f-o2isDNLfIwAHAww=.26db7491-38cb-436a-a941-876bcfb81f54@github.com>

On Mon, 23 Aug 2021 16:01:51 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 923:
>> 
>>> 921:          * probably be considered on a case-by-case basis, for an attribute
>>> 922:          * value of the {@snippet} tag we do not recurse.
>>> 923:          */
>> 
>> This discussion does not belong here.
>> 
>> We should specify simple defensible rules (in the spec) and implement them accordingly.
>> If there is nothing more obvious, I suggest the rules for (Unicode) identifiers.
>
>> This discussion does not belong here.
> 
> I've hoped to specify tag syntax before we push this PR. Until the syntax has been specified, the comment has to be stored somewhere. What would be an appropriate place to store that comment in?
> 
>> I suggest the rules for (Unicode) identifiers
> 
> What do those rules look like? Do you have a link handy?

Check `Character.isUnicodeIdentifierStart` / `Character.isUnicodeIdentifierPart`
Variant suggestion (if different) ... use the identifier rules for the name of the attribute

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

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

From jjg at openjdk.java.net  Mon Aug 23 17:44:28 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 23 Aug 2021 17:44:28 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <McZcJN1VUIkDrqnx5BrygJaVI_f-o2isDNLfIwAHAww=.26db7491-38cb-436a-a941-876bcfb81f54@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
 <sbBmVd7mJ8LGMVSFhGQtpBCuJ6hK6DJhzodAbKb9oUs=.ec5f206e-2c19-499a-b8c5-0ad521a933d1@github.com>
 <McZcJN1VUIkDrqnx5BrygJaVI_f-o2isDNLfIwAHAww=.26db7491-38cb-436a-a941-876bcfb81f54@github.com>
Message-ID: <J3qTvJOwplW8OHy3KuGnljZA8mAdyZvUp06T0wAOJ7U=.283df618-78ee-456c-8a3b-64b17fdd75bf@github.com>

On Mon, 23 Aug 2021 17:36:02 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>>> This discussion does not belong here.
>> 
>> I've hoped to specify tag syntax before we push this PR. Until the syntax has been specified, the comment has to be stored somewhere. What would be an appropriate place to store that comment in?
>> 
>>> I suggest the rules for (Unicode) identifiers
>> 
>> What do those rules look like? Do you have a link handy?
>
> Check `Character.isUnicodeIdentifierStart` / `Character.isUnicodeIdentifierPart`
> Variant suggestion (if different) ... use the identifier rules for the name of the attribute

A discussion like that belongs in JBS.  The result of the discussion belongs in spec and/or code.

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

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

From jjg at openjdk.java.net  Mon Aug 23 17:44:29 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 23 Aug 2021 17:44:29 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <u6ZtH6lViaHM5K3c92XGVZFIwCwyDQqpxl8ZfeqYBlk=.488f910e-e15e-4add-8bff-205aa3eeda6a@github.com>

On Fri, 20 Aug 2021 18:46:43 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetTag.java line 81:
> 
>> 79: 
>> 80:     public static void main(String... args) throws Exception {
>> 81:         new TestSnippetTag().runTests(m -> new Object[]{Paths.get(m.getName())});
> 
> This is just a suggestion for future convenience.
> For big tests like this, for ease of debugging, it can be useful to be able to specify the method(s) to be executed.   Maybe there should be a variants of `runTests` that takes a `String[]` or `List<String>`

I filed JDK-8272853 for us.

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

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

From jjg at openjdk.java.net  Mon Aug 23 17:51:28 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 23 Aug 2021 17:51:28 GMT
Subject: RFR: JDK-8271258: @param with non-ascii variable names produces
 incorrect results
In-Reply-To: <--kwl4aUVyJf9OHkkMe69qqX1-d79qV2qyB7A9rAi1Y=.5927cd0b-2a92-4189-85fd-dff3d0e41c4c@github.com>
References: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>
 <--kwl4aUVyJf9OHkkMe69qqX1-d79qV2qyB7A9rAi1Y=.5927cd0b-2a92-4189-85fd-dff3d0e41c4c@github.com>
Message-ID: <-iUob5XaHtunbiOfathYjgpzfciDQsPqpoo1nPc1v24=.4de4b4fb-15f3-4211-98a8-2ae31c7b3ef6@github.com>

On Thu, 19 Aug 2021 09:35:11 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a simple change to fix the use of non-ASCII characters in @param names.
>> 
>> The underlying problem was accidentally relying on `DocTree.toString()` for an `IdentifierTree` in `CommentHelper`.  The fix is simply to get the underlying `Name` and call `toString` on that.
>> 
>> There is some loosely related cleanup in `ParamTaglet`. I did see if it was possible to avoid excessive use of `String` in this part of the code, but that quickly became a rat-hole.
>> 
>> The existing related test is updated to include this new case, of a Chinese identifier occurring in various places, similar to the test case in the original bug.
>
> test/langtools/jdk/javadoc/doclet/testUnicode/TestUnicode.java line 64:
> 
>> 62:         checkOutput("Code.html", true,
>> 63:                 """
>> 64:                         """);
> 
> Is don't think this is supposed to be an empty string, is it?

Oops, will investigate what happened in my repo.

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

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

From prappo at openjdk.java.net  Mon Aug 23 18:06:33 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 18:06:33 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <0qVuBDPSH0SVQCGtJC0jj03eNdjdFrPYXhYlhoAktC8=.8be3b169-bbc6-440d-9846-59f21848e5e8@github.com>

On Fri, 20 Aug 2021 18:09:47 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 39:
> 
>> 37: import jdk.javadoc.internal.doclets.toolkit.taglets.snippet.Parser;
>> 38: import jdk.javadoc.internal.doclets.toolkit.taglets.snippet.StyledText;
>> 39: import jdk.javadoc.internal.doclets.toolkit.util.Utils;
> 
> The langtools/javac/javadoc convention is to put standard JavaSE imports (`java.*`, `javax.*` ) first.

Since we are here, is there any langtools convention for when to collapse a span of single-import declarations into an import-on-demand (.*) declaration?

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

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

From jjg at openjdk.java.net  Mon Aug 23 18:07:00 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 23 Aug 2021 18:07:00 GMT
Subject: RFR: JDK-8271258: @param with non-ascii variable names produces
 incorrect results [v2]
In-Reply-To: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>
References: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>
Message-ID: <R0n1JXyvGwxXaOSszQQV4pi6w26Scxh-PNOAySq2fhc=.bf4578f3-e043-4b0d-b916-24a629c931fc@github.com>

> Please review a simple change to fix the use of non-ASCII characters in @param names.
> 
> The underlying problem was accidentally relying on `DocTree.toString()` for an `IdentifierTree` in `CommentHelper`.  The fix is simply to get the underlying `Name` and call `toString` on that.
> 
> There is some loosely related cleanup in `ParamTaglet`. I did see if it was possible to avoid excessive use of `String` in this part of the code, but that quickly became a rat-hole.
> 
> The existing related test is updated to include this new case, of a Chinese identifier occurring in various places, similar to the test case in the original bug.

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

  repair broken test.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/5168/files
  - new: https://git.openjdk.java.net/jdk/pull/5168/files/de5e26ef..fc264885

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

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

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

From prappo at openjdk.java.net  Mon Aug 23 18:13:56 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 23 Aug 2021 18:13:56 GMT
Subject: RFR: 8266666: Implementation for snippets [v11]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <OB7_1i1GGwB6_ij6yktDDKQZBwLi4kkN0QIvH5drSKU=.f9915031-f1b8-4023-b8b5-e1d14a886cae@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

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

  Add @summary to tests
  
  From https://openjdk.java.net/jtreg/faq.html:
  
  The @summary tag describes the condition that is checked by the test. It is especially useful for non-regression tests, which by definition don't have bug numbers, but even if there's a bug number it's helpful to include a summary. Note that a test summary is generally not the same thing as a Bugtraq synopsis, since the latter describes the bug rather than the condition that the bug violates.
  
  That said, the JBS synopsis for 8266666 suits those tests just fine.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/731a1a6b..0510287e

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=10
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=09-10

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

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

From jjg at openjdk.java.net  Mon Aug 23 20:23:29 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 23 Aug 2021 20:23:29 GMT
Subject: RFR: JDK-8270195: Add missing links between methods of JavaFX
 properties
In-Reply-To: <BEd0PwHjK7G-H1TIQ17uUayoeyit1aokYDBI8A8mUso=.ef313db5-d274-49e4-914b-56b322f3cc98@github.com>
References: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
 <BEd0PwHjK7G-H1TIQ17uUayoeyit1aokYDBI8A8mUso=.ef313db5-d274-49e4-914b-56b322f3cc98@github.com>
Message-ID: <tePSfC2dnzDuFKu8sJNB0vaf9obVywTvRkalNUqffaA=.6657b8b2-3990-4625-9137-ff6a2ae60cbd@github.com>

On Wed, 18 Aug 2021 12:00:15 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> What is the purpose of this rather complex method to format a text resource? It seems like it is arguments `o1` and `o2` are never used. Couldn't this be implemented simply using `MessageFormat` as it used to be?

This is the `DocTree` equivalent of similar code in `Content`, to format structured objects into a format string. Previously, using `MessageFormat`, the code used "regular" text to inject the name of the property. Now, using this new code, we can inject the equivalent of `{@code _name_ }`.

Yes, it is currently a bit more general than strictly required, in that currently we only require a single value to be injected. I guess I was just following the pattern of supporting future use.

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

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

From hannesw at openjdk.java.net  Tue Aug 24 08:15:24 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 24 Aug 2021 08:15:24 GMT
Subject: RFR: JDK-8271258: @param with non-ascii variable names produces
 incorrect results [v2]
In-Reply-To: <R0n1JXyvGwxXaOSszQQV4pi6w26Scxh-PNOAySq2fhc=.bf4578f3-e043-4b0d-b916-24a629c931fc@github.com>
References: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>
 <R0n1JXyvGwxXaOSszQQV4pi6w26Scxh-PNOAySq2fhc=.bf4578f3-e043-4b0d-b916-24a629c931fc@github.com>
Message-ID: <GrUuVQ290YBVZRYBSV_17hi4n2JiDFfFc_CNnC0TQ4U=.e193f310-c9c1-4f12-bfd9-c7a6a2121b25@github.com>

On Mon, 23 Aug 2021 18:07:00 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a simple change to fix the use of non-ASCII characters in @param names.
>> 
>> The underlying problem was accidentally relying on `DocTree.toString()` for an `IdentifierTree` in `CommentHelper`.  The fix is simply to get the underlying `Name` and call `toString` on that.
>> 
>> There is some loosely related cleanup in `ParamTaglet`. I did see if it was possible to avoid excessive use of `String` in this part of the code, but that quickly became a rat-hole.
>> 
>> The existing related test is updated to include this new case, of a Chinese identifier occurring in various places, similar to the test case in the original bug.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   repair broken test.

Looks good now!

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

Marked as reviewed by hannesw (Reviewer).

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

From hannesw at openjdk.java.net  Tue Aug 24 09:12:26 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 24 Aug 2021 09:12:26 GMT
Subject: RFR: JDK-8270195: Add missing links between methods of JavaFX
 properties
In-Reply-To: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
References: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
Message-ID: <Sdg76r6qWK0NkOYhZ1HzuYkbFvlevYFDsBOuFKO1-U4=.e0f4cb07-8857-4da2-bff9-15ee3add9f43@github.com>

On Thu, 12 Aug 2021 17:38:14 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a medium-size update to the support for JavaFX properties in the Standard Doclet.
> 
> A JavaFX property is typically defined by a group of up to 4 elements:
> * an optional field, which is typically private
> * a no-args property method, whose name ends in `Property` and which returns an appropriate property object
> * an optional getter method which can get the value of the property
> * an optional setter method which can set the value of the property
> 
> Either the field (if present) or the property method (but not both) should have a comment describing the property. The rest should generally _not_have comments: comments will be automatically generated.
> 
> This change is primarily to improve the generation of the comments. `@see` links are generated between the methods for a property. In addition, improvements are made to the handling of `@return` ... adding it as needed, and removing it when not (the latter occurs when generating the docs for the property itself, using the info in the property method.)
> 
> There is some amount of cleanup to the implementation, most notably moving (and rewriting) the code to generate comments for property methods from `MemberSummaryBuilder` to `CommentUtils`,which is where most other synthesized comments are generated. However, the goal has also been to not unduly change the spirit and spec of the original code.
> 
> A new combo test for JavaFX properties is provided, that creates different instances of a class, containing different property-related methods with and without comments. Basic properties of the output are then verified for each property method: the description, any parameter info, any return info, and any links to other related methods.

Looks good. Apologies for the slow review, It took some time to get acquainted with the workings and handling of javafx properties.

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

Marked as reviewed by hannesw (Reviewer).

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

From hannesw at openjdk.java.net  Tue Aug 24 09:12:26 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 24 Aug 2021 09:12:26 GMT
Subject: RFR: JDK-8270195: Add missing links between methods of JavaFX
 properties
In-Reply-To: <tePSfC2dnzDuFKu8sJNB0vaf9obVywTvRkalNUqffaA=.6657b8b2-3990-4625-9137-ff6a2ae60cbd@github.com>
References: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
 <BEd0PwHjK7G-H1TIQ17uUayoeyit1aokYDBI8A8mUso=.ef313db5-d274-49e4-914b-56b322f3cc98@github.com>
 <tePSfC2dnzDuFKu8sJNB0vaf9obVywTvRkalNUqffaA=.6657b8b2-3990-4625-9137-ff6a2ae60cbd@github.com>
Message-ID: <2xvkI1qi-hKwHvLhM9VAAdb2SW7dIyImLdyxbw9yuYM=.2cc30332-b095-4a7e-af6b-f7cff9ee7a0a@github.com>

On Mon, 23 Aug 2021 20:20:19 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java line 528:
>> 
>>> 526:      * @return a content tree for the text
>>> 527:      */
>>> 528:     public List<? extends DocTree> getComment(String key, Object o0, Object o1, Object o2) {
>> 
>> What is the purpose of this rather complex method to format a text resource? It seems like it is arguments `o1` and `o2` are never used. Couldn't this be implemented simply using `MessageFormat` as it used to be?
>
>> What is the purpose of this rather complex method to format a text resource? It seems like it is arguments `o1` and `o2` are never used. Couldn't this be implemented simply using `MessageFormat` as it used to be?
> 
> This is the `DocTree` equivalent of similar code in `Content`, to format structured objects into a format string. Previously, using `MessageFormat`, the code used "regular" text to inject the name of the property. Now, using this new code, we can inject the equivalent of `{@code _name_ }`.
> 
> Yes, it is currently a bit more general than strictly required, in that currently we only require a single value to be injected. I guess I was just following the pattern of supporting future use.

Thanks for the explanation. Sounds reasonable.

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

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

From hannesw at openjdk.java.net  Tue Aug 24 10:03:23 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 24 Aug 2021 10:03:23 GMT
Subject: RFR: 8248001: javadoc generates invalid HTML pages whose ftp://
 links are broken
In-Reply-To: <uTXidQfq4LGpFMsxGiw_EzFuIRDMnIDR6hvAN3TjGiM=.7f0509f1-67a3-4926-afd0-a8ce9fdc8e18@github.com>
References: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>
 <ahB3g8-B9SSJ4J-q0uW3itCswu7PGfYUhxR53btCAKk=.0255f3b4-a5c2-4c28-8bc7-724e42519e7e@github.com>
 <luwvXZ5xVJj1b5bjh4U_TTtbZGOS4N9TAIYDPLp46S4=.0a470613-04e9-4ad6-9a72-4707c12b0596@github.com>
 <uTXidQfq4LGpFMsxGiw_EzFuIRDMnIDR6hvAN3TjGiM=.7f0509f1-67a3-4926-afd0-a8ce9fdc8e18@github.com>
Message-ID: <8J8k9Tdirl2MjXOwdkXFQFv21zyayLOErvq4NMAV7Ug=.4fc6ce62-bb92-4504-8af4-5daa6e66cbb7@github.com>

On Fri, 20 Aug 2021 11:41:02 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> I assume the link is in an HTML document and goes in an HTML document. If you wanted to use java.net.URI, depending on where from `text` comes from and whereto it goes, you might need first to decode it using URLDecoder, and then you might need to re-encode it before spitting it out... That's a lot of operations where things could go wrong, especially if the link contains a query string.
>
> That said a stricter regexp (unless I'm mistaken) could be: `^[a-zA-Z][a-zA-Z0-9+-.]*:.+$`
> [ from RFC 2396:     scheme        = alpha *( alpha | digit | "+" | "-" | "." ) ]

I would normally opt for a generic regexp-based solution such as proposed by @dfuch, but there is a security aspect to this as well (e.g. script invocation), so I'd go with the more conservative approach here to just add `ftp:` protocol to the list.

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

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

From prappo at openjdk.java.net  Tue Aug 24 10:27:56 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 10:27:56 GMT
Subject: RFR: 8266666: Implementation for snippets [v12]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <5pYpCnvgOSaVG_1lJtlHEXNrwrmaDtyw0SyRa1jQBgM=.130e1005-309e-4357-8eff-e2468d0502f1@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

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

  Fix import layout and typos

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/0510287e..a7cd1551

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=11
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=10-11

  Stats: 31 lines in 2 files changed: 15 ins; 14 del; 2 mod
  Patch: https://git.openjdk.java.net/jdk/pull/4795.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/4795/head:pull/4795

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

From prappo at openjdk.java.net  Tue Aug 24 10:27:59 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 10:27:59 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <0qVuBDPSH0SVQCGtJC0jj03eNdjdFrPYXhYlhoAktC8=.8be3b169-bbc6-440d-9846-59f21848e5e8@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
 <0qVuBDPSH0SVQCGtJC0jj03eNdjdFrPYXhYlhoAktC8=.8be3b169-bbc6-440d-9846-59f21848e5e8@github.com>
Message-ID: <BnpKBWc2s3CzI4dM9ele3uQUmJLGVTIxf1v5DCKJrZo=.6cb8a6b2-30e7-4826-a557-e20cf1418fa0@github.com>

On Mon, 23 Aug 2021 18:03:51 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 39:
>> 
>>> 37: import jdk.javadoc.internal.doclets.toolkit.taglets.snippet.Parser;
>>> 38: import jdk.javadoc.internal.doclets.toolkit.taglets.snippet.StyledText;
>>> 39: import jdk.javadoc.internal.doclets.toolkit.util.Utils;
>> 
>> The langtools/javac/javadoc convention is to put standard JavaSE imports (`java.*`, `javax.*` ) first.
>
> Since we are here, is there any langtools convention for when to collapse a span of single-import declarations into an import-on-demand (.*) declaration?

Fixed in a7cd155.

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

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

From prappo at openjdk.java.net  Tue Aug 24 10:28:05 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 10:28:05 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <tJa6tteqbFnAaqqU4AGEvlVRuBCVKH4bukfbZ0zy0zc=.ab203352-967e-4b87-9b2a-e269d0598729@github.com>

On Fri, 20 Aug 2021 18:13:32 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 260:
> 
>> 258:      * There's a separate issue of mapping discrepancies back to their
>> 259:      * originating source in the doc comment and the external file. Maybe there
>> 260:      * is a value in it, or may be there isn't. In any case, accurate mapping
> 
> "maybe"

Fixed in a7cd155.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 134:
> 
>> 132:             this.eolMarker = eolMarker;
>> 133:             // capture the rightmost eolMarker (e.g. "//")
>> 134:             // The bellow Pattern.compile should never throw PatternSyntaxException
> 
> "below" ?

Fixed in a7cd155.

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

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

From prappo at openjdk.java.net  Tue Aug 24 11:33:33 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 11:33:33 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <lJunviL7QcvJ7zS_wCCvX8kQn_OfYBXi0jOG1CanUHU=.043e1c41-654e-4ae1-b85c-3d30bd174cd0@github.com>

On Fri, 20 Aug 2021 18:07:30 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties line 360:
> 
>> 358: 
>> 359: doclet.tag.attribute.repeated=\
>> 360:  repeated attribute: "{0}"
> 
> check the resource file for other quoted values; I think you'll find single quotes are the prevailing standard.

I didn't find single quotes to be the prevailing standard neither in `doclet.properties` nor in `compiler.properties`. In fact, it seems to be the opposite: whenever a parameter (not constant) is output, it's either unquoted or double-quoted. Did I look in the right place?

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

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

From prappo at openjdk.java.net  Tue Aug 24 11:56:25 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 11:56:25 GMT
Subject: RFR: JDK-8271258: @param with non-ascii variable names produces
 incorrect results [v2]
In-Reply-To: <-iUob5XaHtunbiOfathYjgpzfciDQsPqpoo1nPc1v24=.4de4b4fb-15f3-4211-98a8-2ae31c7b3ef6@github.com>
References: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>
 <--kwl4aUVyJf9OHkkMe69qqX1-d79qV2qyB7A9rAi1Y=.5927cd0b-2a92-4189-85fd-dff3d0e41c4c@github.com>
 <-iUob5XaHtunbiOfathYjgpzfciDQsPqpoo1nPc1v24=.4de4b4fb-15f3-4211-98a8-2ae31c7b3ef6@github.com>
Message-ID: <QXv6dI2g_R_E-M3H5230kPE5pCJip3DXuFn34Oti2uI=.6cdec261-fcf2-413e-aaa9-6351253610eb@github.com>

On Mon, 23 Aug 2021 17:48:02 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> test/langtools/jdk/javadoc/doclet/testUnicode/TestUnicode.java line 64:
>> 
>>> 62:         checkOutput("Code.html", true,
>>> 63:                 """
>>> 64:                         """);
>> 
>> Is don't think this is supposed to be an empty string, is it?
>
> Oops, will investigate what happened in my repo.

This could've been detected during testing, if we had https://github.com/openjdk/jdk/pull/4811.

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

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

From prappo at openjdk.java.net  Tue Aug 24 13:14:57 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 13:14:57 GMT
Subject: RFR: 8266666: Implementation for snippets [v13]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <j3L8GO7XVcDrt_IW3gcn99u1NkxCsAUHRFd4pJI6l7g=.2758bc09-0bfc-4eaf-ba7b-4493e06843f8@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

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

  Clarify the attributes order comment

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/a7cd1551..26de3408

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=12
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=11-12

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

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

From prappo at openjdk.java.net  Tue Aug 24 13:15:00 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 13:15:00 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <z0iCX2MhKUG1JtrsvHWPCLYA-aHOaIc1VKW3dqWx9V4=.21682432-7f23-434d-8bc9-0bf747a08f6d@github.com>

On Fri, 20 Aug 2021 18:11:05 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 96:
> 
>> 94:             // recently encountered of two, the iteration order might differ
>> 95:             // from the source order
>> 96:             error(writer, holder, a, "doclet.tag.attribute.repeated", a.getName().toString());
> 
> Can we use a `LinkedHashMap` or similar to preserve encounter order?

If you look closely, you will see that the ordering characteristics of the `Map` implementation used to collect attributes is immaterial. My comment was about the implied (but unspecified) order of attributes in the list returned from the `SnippetTree.getAttributes()` method; see the third paragraph in the description of https://bugs.openjdk.java.net/browse/JDK-8266826

I clarified the comment in 26de34083a3.

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

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

From jjg at openjdk.java.net  Tue Aug 24 14:27:31 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 24 Aug 2021 14:27:31 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <BnpKBWc2s3CzI4dM9ele3uQUmJLGVTIxf1v5DCKJrZo=.6cb8a6b2-30e7-4826-a557-e20cf1418fa0@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
 <0qVuBDPSH0SVQCGtJC0jj03eNdjdFrPYXhYlhoAktC8=.8be3b169-bbc6-440d-9846-59f21848e5e8@github.com>
 <BnpKBWc2s3CzI4dM9ele3uQUmJLGVTIxf1v5DCKJrZo=.6cb8a6b2-30e7-4826-a557-e20cf1418fa0@github.com>
Message-ID: <wad2WKaPUjaaIMXNkR2bjTfykS-3jDoj2Mnn9ZslUnU=.5ae0f94c-7c8c-4327-85c5-ada43a4e62ee@github.com>

On Tue, 24 Aug 2021 10:24:35 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Since we are here, is there any langtools convention for when to collapse a span of single-import declarations into an import-on-demand (.*) declaration?
>
> Fixed in a7cd155.

> Since we are here, is there any langtools convention for when to collapse a span of single-import declarations into an import-on-demand (.*) declaration?

langtools does not use import-on-demand, and it is practice e to expand them to single imports if any creep into the code.   Also, imports are ordered with Java SE (`java.*` `javax.*`) imports first, before others.

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

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

From jjg at openjdk.java.net  Tue Aug 24 14:36:34 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 24 Aug 2021 14:36:34 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <lJunviL7QcvJ7zS_wCCvX8kQn_OfYBXi0jOG1CanUHU=.043e1c41-654e-4ae1-b85c-3d30bd174cd0@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
 <lJunviL7QcvJ7zS_wCCvX8kQn_OfYBXi0jOG1CanUHU=.043e1c41-654e-4ae1-b85c-3d30bd174cd0@github.com>
Message-ID: <VzU1oJzPitByr9JY24gWgdTrrtRyC6w6ErOwY2c9NdA=.b8933d8b-738f-4f74-8ad2-236d28656942@github.com>

On Tue, 24 Aug 2021 11:30:54 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties line 360:
>> 
>>> 358: 
>>> 359: doclet.tag.attribute.repeated=\
>>> 360:  repeated attribute: "{0}"
>> 
>> check the resource file for other quoted values; I think you'll find single quotes are the prevailing standard.
>
> I didn't find single quotes to be the prevailing standard neither in `doclet.properties` nor in `compiler.properties`. In fact, it seems to be the opposite: whenever a parameter (not constant) is output, it's either unquoted or double-quoted. Did I look in the right place?

OK, it's not as dominant as I thought ... 2 to 1.
Grepping through English properties files `jdk.compiler` and `jdk.javadoc`, there are 142 lines containing `'` and 75 lines containing `"`
Maybe we should have a separate cleanup, after figuring out which form we should use.

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 177:
>> 
>>> 175:                 }
>>> 176:                 thisLineTags.addAll(parsedTags);
>>> 177:                 for (var tagIterator = thisLineTags.iterator(); tagIterator.hasNext(); ) {
>> 
>> oooh, not wrong; just unexpected mix of styles ;-)
>
> Can you be more specific? In what sense is this unexpected?

Just the combination of `var`, iterators, and a `for `(;;)` loop, that's all. Not wrong, just uncommon; it took me a double-take to parse it, that's all.   The code is OK, no need to change it.

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

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

From jjg at openjdk.java.net  Tue Aug 24 14:44:29 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 24 Aug 2021 14:44:29 GMT
Subject: Integrated: JDK-8271258: @param with non-ascii variable names
 produces incorrect results
In-Reply-To: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>
References: <wbTEXyLjh2FqAabZ5iN9LQF_FHvINzgXHj6Cm_PS3Is=.d34908ec-f0af-4fd8-a926-fe1370a15492@github.com>
Message-ID: <KhZ5_Tx2gD-oIPqValNQo_WLPPxSIROzP-9aYT7a39I=.227a394f-9430-4eae-a41f-e9977ddaca6c@github.com>

On Wed, 18 Aug 2021 20:10:48 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple change to fix the use of non-ASCII characters in @param names.
> 
> The underlying problem was accidentally relying on `DocTree.toString()` for an `IdentifierTree` in `CommentHelper`.  The fix is simply to get the underlying `Name` and call `toString` on that.
> 
> There is some loosely related cleanup in `ParamTaglet`. I did see if it was possible to avoid excessive use of `String` in this part of the code, but that quickly became a rat-hole.
> 
> The existing related test is updated to include this new case, of a Chinese identifier occurring in various places, similar to the test case in the original bug.

This pull request has now been integrated.

Changeset: 94f5e441
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/94f5e441f637b7a75227ba11a2b25d70f96cd274
Stats:     92 lines in 3 files changed: 62 ins; 6 del; 24 mod

8271258: @param with non-ascii variable names produces incorrect results

Reviewed-by: hannesw

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

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

From jjg at openjdk.java.net  Tue Aug 24 16:14:32 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 24 Aug 2021 16:14:32 GMT
Subject: Integrated: JDK-8270195: Add missing links between methods of JavaFX
 properties
In-Reply-To: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
References: <FCU2eMoMPYh061xkz_uQI16_f-3-JUrO8EjrjnphAFs=.61825669-2b05-425b-9d74-f350b6f50eca@github.com>
Message-ID: <jB7pUttOuJKO1aKGBowEld1DdIgmWr6ND9rLjrvXdpw=.be8e8a53-8aff-4ec1-b2f4-150dcb514122@github.com>

On Thu, 12 Aug 2021 17:38:14 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a medium-size update to the support for JavaFX properties in the Standard Doclet.
> 
> A JavaFX property is typically defined by a group of up to 4 elements:
> * an optional field, which is typically private
> * a no-args property method, whose name ends in `Property` and which returns an appropriate property object
> * an optional getter method which can get the value of the property
> * an optional setter method which can set the value of the property
> 
> Either the field (if present) or the property method (but not both) should have a comment describing the property. The rest should generally _not_have comments: comments will be automatically generated.
> 
> This change is primarily to improve the generation of the comments. `@see` links are generated between the methods for a property. In addition, improvements are made to the handling of `@return` ... adding it as needed, and removing it when not (the latter occurs when generating the docs for the property itself, using the info in the property method.)
> 
> There is some amount of cleanup to the implementation, most notably moving (and rewriting) the code to generate comments for property methods from `MemberSummaryBuilder` to `CommentUtils`,which is where most other synthesized comments are generated. However, the goal has also been to not unduly change the spirit and spec of the original code.
> 
> A new combo test for JavaFX properties is provided, that creates different instances of a class, containing different property-related methods with and without comments. Basic properties of the output are then verified for each property method: the description, any parameter info, any return info, and any links to other related methods.

This pull request has now been integrated.

Changeset: d34f17c6
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/d34f17c6973748693de1bdd040bc3e8a0f15f197
Stats:     1024 lines in 12 files changed: 740 ins; 157 del; 127 mod

8270195: Add missing links between methods of JavaFX properties

Reviewed-by: kcr, hannesw

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

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

From prappo at openjdk.java.net  Tue Aug 24 16:55:39 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 16:55:39 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <-hDrj20tKNB2jnaL3i6ygSGR10XC1XX8Lx9NUV6ZMAs=.e9042f9f-40a2-4cf0-a515-4238d0e1effc@github.com>

On Fri, 20 Aug 2021 18:50:44 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> Generally impressive piece of work.

@jonathan-gibbons, do we need to mention the semantic change to `com.sun.source.doctree.AttributeTree` in the release notes? Before this PR, `AttributeTree` used to only represent HTML attributes. After this PR has been integrated, that interface will also represent attributes of the standard doclet tags. (Currently, the only such tag is `{@snippet}`.)

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

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

From jjg at openjdk.java.net  Tue Aug 24 17:25:30 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 24 Aug 2021 17:25:30 GMT
Subject: RFR: 8266666: Implementation for snippets [v13]
In-Reply-To: <j3L8GO7XVcDrt_IW3gcn99u1NkxCsAUHRFd4pJI6l7g=.2758bc09-0bfc-4eaf-ba7b-4493e06843f8@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <j3L8GO7XVcDrt_IW3gcn99u1NkxCsAUHRFd4pJI6l7g=.2758bc09-0bfc-4eaf-ba7b-4493e06843f8@github.com>
Message-ID: <SeJFi3Ecbk9ayU0nwz8VX0nK_uVofX_Sz_Q9n6cB2vQ=.370cbaef-3c29-41d1-bac7-8e170d4fa8b8@github.com>

On Tue, 24 Aug 2021 13:14:57 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Clarify the attributes order comment

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java line 82:

> 80:      */
> 81:     snippet,
> 82: 

This is OK for now, given that we do not have a "public" way to process these comments at this time. However, we should probably do a cleanup later on (soon), and maybe create a new section in `HtmlStyle` for all snippet related styles ... i.e. including `bold`, `italic` etc, so that all styles end up in the upcoming documentation.

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

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

From jjg at openjdk.java.net  Tue Aug 24 17:32:32 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 24 Aug 2021 17:32:32 GMT
Subject: RFR: 8266666: Implementation for snippets [v13]
In-Reply-To: <oF0h93PSTZszdDPcg7CEshJIULfAeD-Brr-aYCXhmQQ=.9eeb4f21-d782-4dbb-8d09-034b9c594a16@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <oF0h93PSTZszdDPcg7CEshJIULfAeD-Brr-aYCXhmQQ=.9eeb4f21-d782-4dbb-8d09-034b9c594a16@github.com>
Message-ID: <Z97mzfLWKhGCjvQePaxZbzQ-JyIyUg7PD0WyVj2dpUI=.4cbf01b3-9434-48ee-b106-c97973d99680@github.com>

On Mon, 26 Jul 2021 14:31:27 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> I would prefer if variables such as this that are used farther than a few lines from their definition had more meaningful names.

It's also confusing that `r` is a `String` but `r1`, `r2` (lines 209-211) are `StyledText`

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

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

From prappo at openjdk.java.net  Tue Aug 24 17:46:51 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 17:46:51 GMT
Subject: RFR: 8266666: Implementation for snippets [v14]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <QrB0qoVRM9vvaYb7QAVBZGj-EkkksCod3fUDhhAWwKI=.65645bc1-606c-45cc-95ae-1992f2eb4209@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 18 commits:

 - Merge branch 'master' into 8266666
   
   This merge is to promptly resolve a conflict in src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java.
 - Clarify the attributes order comment
 - Fix import layout and typos
 - Add @summary to tests
   
   From https://openjdk.java.net/jtreg/faq.html:
   
   The @summary tag describes the condition that is checked by the test. It is especially useful for non-regression tests, which by definition don't have bug numbers, but even if there's a bug number it's helpful to include a summary. Note that a test summary is generally not the same thing as a Bugtraq synopsis, since the latter describes the bug rather than the condition that the bug violates.
   
   That said, the JBS synopsis for 8266666 suits those tests just fine.
 - Remove superfluous editor-fold
 - Remove JEP link from SnippetTree
 - Merge branch 'master' into 8266666
 - Pass through FIXMEs and TODOs
   
   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
 - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
   
   Co-authored-by: Hannes Wallnoefer <hannesw at gmail.com>
 - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
   
   Co-authored-by: Hannes Wallnoefer <hannesw at gmail.com>
 - ... and 8 more: https://git.openjdk.java.net/jdk/compare/d34f17c6...4c5e92b7

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

Changes: https://git.openjdk.java.net/jdk/pull/4795/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=13
  Stats: 4812 lines in 59 files changed: 4708 ins; 12 del; 92 mod
  Patch: https://git.openjdk.java.net/jdk/pull/4795.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/4795/head:pull/4795

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

From jjg at openjdk.java.net  Tue Aug 24 21:01:43 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 24 Aug 2021 21:01:43 GMT
Subject: RFR: JDK-8272375: Improve phrasing of synthesized descriptions in
 JavaFX docs
Message-ID: <0J4gBHFP9GEbSUHYySTyJ3GnN8ADUtmSszCqbfQc4YE=.6559e11c-d74d-433f-8cb8-03d3ac226b4a@github.com>

Please review a very simple change to the support for the synthesized method descriptions in JavaFX. 

The change is just to change the order of words in generated descriptions from  
  _the property `NAME`_ 
to 
  _the `NAME` property_

As such, there are no changes to the mainstream code; just a change to the resource files and corresponding changes to some tests.

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

Commit messages:
 - JDK-8272375: Improve phrasing of synthesized descriptions in JavaFX docs

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

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

From jjg at openjdk.java.net  Tue Aug 24 21:59:29 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 24 Aug 2021 21:59:29 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <Th-1B_-MGbPpHryb-9t1qioxaoUnEjCCCxcTVEK-yb4=.dffe6e3a-0a32-43c8-862e-f38320730395@github.com>

On Fri, 20 Aug 2021 18:50:44 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> Generally impressive piece of work.

> @jonathan-gibbons, do we need to mention the semantic change to `com.sun.source.doctree.AttributeTree` in the release notes? Before this PR, `AttributeTree` used to only represent HTML attributes. After this PR has been integrated, that interface will also represent attributes of the standard doclet tags. (Currently, the only such tag is `{@snippet}`.)

It doesn't seem worth a release note ... we're just using the tree in more places ...

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

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

From prappo at openjdk.java.net  Tue Aug 24 21:59:30 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 21:59:30 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
Message-ID: <NKPikVf4msYmfEWaNQuh-qcSZ5bQ8RrS509ddpMXeNw=.5d7cd974-f406-48ad-8cc3-b649f0c33491@github.com>

On Fri, 20 Aug 2021 18:42:53 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Pass through FIXMEs and TODOs
>>   
>>   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>
> test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetTag.java line 1508:
> 
>> 1506:                 )
>> 1507: // Uncomment when parser has improved (this would allow to write meta snippets,
>> 1508: // i.e. snippets showing how to write snippets.
> 
> Just a question: what are the limitations in the parser that are getting in the way here?

Both the commented-out code and its description are from a previous version of markup; you can see that the syntax is slightly different from what we have in JEP today. It's good that you asked this question, because this piece is outdated.

Although the markup syntax has changed, the idea for the test remained: there has to be a way to produce a snippet that showcases markup. I will have to implement that idea.

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

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

From prappo at openjdk.java.net  Tue Aug 24 22:12:34 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 22:12:34 GMT
Subject: RFR: 8266666: Implementation for snippets [v14]
In-Reply-To: <QrB0qoVRM9vvaYb7QAVBZGj-EkkksCod3fUDhhAWwKI=.65645bc1-606c-45cc-95ae-1992f2eb4209@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <QrB0qoVRM9vvaYb7QAVBZGj-EkkksCod3fUDhhAWwKI=.65645bc1-606c-45cc-95ae-1992f2eb4209@github.com>
Message-ID: <4Q-TLoinrffkDvPKnmpo9478OEe8ZqDNErClMKXml6Q=.34c649f6-28fb-480a-8b5b-b10f3fdc66c0@github.com>

On Tue, 24 Aug 2021 17:46:51 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.
>
> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 18 commits:
> 
>  - Merge branch 'master' into 8266666
>    
>    This merge is to promptly resolve a conflict in src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java.
>  - Clarify the attributes order comment
>  - Fix import layout and typos
>  - Add @summary to tests
>    
>    From https://openjdk.java.net/jtreg/faq.html:
>    
>    The @summary tag describes the condition that is checked by the test. It is especially useful for non-regression tests, which by definition don't have bug numbers, but even if there's a bug number it's helpful to include a summary. Note that a test summary is generally not the same thing as a Bugtraq synopsis, since the latter describes the bug rather than the condition that the bug violates.
>    
>    That said, the JBS synopsis for 8266666 suits those tests just fine.
>  - Remove superfluous editor-fold
>  - Remove JEP link from SnippetTree
>  - Merge branch 'master' into 8266666
>  - Pass through FIXMEs and TODOs
>    
>    Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
>  - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
>    
>    Co-authored-by: Hannes Wallnoefer <hannesw at gmail.com>
>  - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
>    
>    Co-authored-by: Hannes Wallnoefer <hannesw at gmail.com>
>  - ... and 8 more: https://git.openjdk.java.net/jdk/compare/d34f17c6...4c5e92b7

Heads-up: the recent merge 4c5e92b from openjdk:master seems faulty. It fails a test and reports unexpected entries in this PR's "Files changed" tab. Because that merge is the most recent commit in the PR branch, instead of carefully repairing the history with a revert and remerge, I will force push a correct merge. Apologies for any noise or inconvenience.

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

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

From prappo at openjdk.java.net  Tue Aug 24 22:22:34 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 22:22:34 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <Th-1B_-MGbPpHryb-9t1qioxaoUnEjCCCxcTVEK-yb4=.dffe6e3a-0a32-43c8-862e-f38320730395@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
 <Th-1B_-MGbPpHryb-9t1qioxaoUnEjCCCxcTVEK-yb4=.dffe6e3a-0a32-43c8-862e-f38320730395@github.com>
Message-ID: <eoWwTPqiuAsunj2xoUdaUqgTq4bVFG6XtUFgfEdiVjU=.3df6f10d-cb38-43a7-8d77-c9c3ab263fbc@github.com>

On Tue, 24 Aug 2021 21:56:05 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> > @jonathan-gibbons, do we need to mention the semantic change to `com.sun.source.doctree.AttributeTree` in the release notes? Before this PR, `AttributeTree` used to only represent HTML attributes. After this PR has been integrated, that interface will also represent attributes of the standard doclet tags. (Currently, the only such tag is `{@snippet}`.)
> 
> It doesn't seem worth a release note ... we're just using the tree in more places ... but it wouldn't be wrong to create one ... after all, I guess we did have to change doclint to accommodate the new usage.

Look at it this way. Previously, if you had an instance of `AttributeTree`, you could be sure that it belonged to an instance of `StartElementTree`. After this PR has been merged, this will no longer be the case. I think that this fact should be recorded somewhere besides the API itself.

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

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

From prappo at openjdk.java.net  Tue Aug 24 22:26:48 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 24 Aug 2021 22:26:48 GMT
Subject: RFR: 8266666: Implementation for snippets [v15]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <lQeF9uraLzftdPH6a_tLVcPi-jKUBayHUkRhCiOSNR8=.369760f4-6e33-48c0-9e8b-cba725510731@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 18 commits:

 - Merge branch 'master' into 8266666
   
   Redoing a faulty merge and pushing the result forcefully.
 - Clarify the attributes order comment
 - Fix import layout and typos
 - Add @summary to tests
   
   From https://openjdk.java.net/jtreg/faq.html:
   
   The @summary tag describes the condition that is checked by the test. It is especially useful for non-regression tests, which by definition don't have bug numbers, but even if there's a bug number it's helpful to include a summary. Note that a test summary is generally not the same thing as a Bugtraq synopsis, since the latter describes the bug rather than the condition that the bug violates.
   
   That said, the JBS synopsis for 8266666 suits those tests just fine.
 - Remove superfluous editor-fold
 - Remove JEP link from SnippetTree
 - Merge branch 'master' into 8266666
 - Pass through FIXMEs and TODOs
   
   Downgrades FIXMEs that do not mark *feature issues* to TODOs, or removes those FIXMEs completely. For example, unlike Style hierarchy, Action hierarchy won't benefit from becoming sealed. So the respective FIXME is removed.
 - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
   
   Co-authored-by: Hannes Wallnoefer <hannesw at gmail.com>
 - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
   
   Co-authored-by: Hannes Wallnoefer <hannesw at gmail.com>
 - ... and 8 more: https://git.openjdk.java.net/jdk/compare/b17b821a...be7ffe5b

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

Changes: https://git.openjdk.java.net/jdk/pull/4795/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=14
  Stats: 4713 lines in 44 files changed: 4686 ins; 4 del; 23 mod
  Patch: https://git.openjdk.java.net/jdk/pull/4795.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/4795/head:pull/4795

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

From prappo at openjdk.java.net  Wed Aug 25 16:00:08 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 25 Aug 2021 16:00:08 GMT
Subject: RFR: 8266666: Implementation for snippets [v16]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <dhl5FfSX3vWJANDa5wnLKgSOgoiIftXG9UUeY27dZIM=.be5e5f30-e6b7-4944-844a-638368213b50@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

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

  Format code closer to the ambient style
  
  Makes new constructs look more natural in their context by adopting the surrounding style.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/be7ffe5b..6c33cb6a

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=15
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=14-15

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

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

From prappo at openjdk.java.net  Wed Aug 25 16:15:57 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 25 Aug 2021 16:15:57 GMT
Subject: RFR: 8266666: Implementation for snippets [v17]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <TJyQWZvPey5BOd1Gc3F7Wz8bW02ayYt6lHjqPQLUyyk=.d3832ec7-ab45-4d78-ae79-ccfddc409019@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

Pavel Rappo has refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR. The pull request contains one new commit since the last revision:

  Format code closer to the ambient style
  
  Makes new constructs look more natural in their context by adopting the surrounding style.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/6c33cb6a..9ab2cbdd

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=16
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=15-16

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

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

From prappo at openjdk.java.net  Wed Aug 25 16:16:00 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 25 Aug 2021 16:16:00 GMT
Subject: RFR: 8266666: Implementation for snippets [v16]
In-Reply-To: <dhl5FfSX3vWJANDa5wnLKgSOgoiIftXG9UUeY27dZIM=.be5e5f30-e6b7-4944-844a-638368213b50@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <dhl5FfSX3vWJANDa5wnLKgSOgoiIftXG9UUeY27dZIM=.be5e5f30-e6b7-4944-844a-638368213b50@github.com>
Message-ID: <xnnM14F4rW3lg3QsmSL68ew7Ng5sksi5XVbHgftcyfw=.94983f28-7538-4a30-af5f-cca9a5b0a213@github.com>

On Wed, 25 Aug 2021 16:00:08 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Format code closer to the ambient style
>   
>   Makes new constructs look more natural in their context by adopting the surrounding style.

Apologies for the recent series of consecutive force pushes. I had muddled the history with two commits before figured out that my IDE was reformatting doc comments behind my back. Every time I formatted the doc comment, the IDE reformatted it immediately before committing the change to the repo. I've configured the IDE not to do it from now on.

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

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

From prappo at openjdk.java.net  Wed Aug 25 16:21:55 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 25 Aug 2021 16:21:55 GMT
Subject: RFR: 8266666: Implementation for snippets [v18]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <Y6lmwI-YlP7eSnGAtu4nIGc8wCpJp23ovMLVbNMSlIs=.343fd6af-3a10-4cb8-baae-3ee1d3e333f0@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

Pavel Rappo has refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR. The pull request contains one new commit since the last revision:

  Format code closer to the ambient style
  
  Makes new constructs look more natural in their context by adopting the surrounding style.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/9ab2cbdd..87e765b0

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=17
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=16-17

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

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

From prappo at openjdk.java.net  Wed Aug 25 17:09:58 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 25 Aug 2021 17:09:58 GMT
Subject: RFR: 8266666: Implementation for snippets [v19]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <BKbgaMabuiLBQ-61VYCie5mHhAzPdtStYfdSU9N-Q0w=.c439de4a-341a-4186-a08e-414079c82336@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

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

  Recover from a sloppy merge
  
  Apparently, I've performed at least one sloppy merge while developing the feature in sandbox. As a result, some changes brought by e4d045402fa1992a1d91586bd4f67362d07f543c were discarded. The specdiff for the CSR actually shows this and has to be regenerated.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/87e765b0..0d9c53a6

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=18
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=17-18

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

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

From github.com+741251+turbanoff at openjdk.java.net  Wed Aug 25 17:25:37 2021
From: github.com+741251+turbanoff at openjdk.java.net (Andrey Turbanov)
Date: Wed, 25 Aug 2021 17:25:37 GMT
Subject: RFR: 8272992: Replace usages of Collections.sort with List.sort call
 in jdk.* modules
Message-ID: <9xbhI0rwD3XbAHZFfQAkJHYivbC5F4N085RuSVWx8HU=.8a470c93-5fee-4981-97e4-afb6cb1147b9@github.com>

Collections.sort is just a wrapper, so it is better to use an instance method directly.

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

Commit messages:
 - [PATCH] Replace usages of Collections.sort with List.sort call in jdk.* modules

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

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

From kcr at openjdk.java.net  Wed Aug 25 18:55:26 2021
From: kcr at openjdk.java.net (Kevin Rushforth)
Date: Wed, 25 Aug 2021 18:55:26 GMT
Subject: RFR: JDK-8272375: Improve phrasing of synthesized descriptions in
 JavaFX docs
In-Reply-To: <0J4gBHFP9GEbSUHYySTyJ3GnN8ADUtmSszCqbfQc4YE=.6559e11c-d74d-433f-8cb8-03d3ac226b4a@github.com>
References: <0J4gBHFP9GEbSUHYySTyJ3GnN8ADUtmSszCqbfQc4YE=.6559e11c-d74d-433f-8cb8-03d3ac226b4a@github.com>
Message-ID: <ahLSjdCyIMvwCllGmzdbIGdBTMbnHcNWhcOLBsRyFiw=.4c4a254e-23eb-4df0-95d5-fe73dced48d0@github.com>

On Tue, 24 Aug 2021 20:54:08 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a very simple change to the support for the synthesized method descriptions in JavaFX. 
> 
> The change is just to change the order of words in generated descriptions from  
>   _the property `NAME`_ 
> to 
>   _the `NAME` property_
> 
> As such, there are no changes to the mainstream code; just a change to the resource files and corresponding changes to some tests.

I tested it by generating the JavaFX docs using this version and it looks good.

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

Marked as reviewed by kcr (Author).

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

From prappo at openjdk.java.net  Wed Aug 25 21:15:35 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 25 Aug 2021 21:15:35 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <Th-1B_-MGbPpHryb-9t1qioxaoUnEjCCCxcTVEK-yb4=.dffe6e3a-0a32-43c8-862e-f38320730395@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
 <Th-1B_-MGbPpHryb-9t1qioxaoUnEjCCCxcTVEK-yb4=.dffe6e3a-0a32-43c8-862e-f38320730395@github.com>
Message-ID: <AW1onB1aO2vgsPv4wJxW_g91agtxmMsPsUkpHepeq9w=.8132126a-6565-433f-9244-f2f3b2d56165@github.com>

On Tue, 24 Aug 2021 21:56:05 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Generally impressive piece of work.
>
>> @jonathan-gibbons, do we need to mention the semantic change to `com.sun.source.doctree.AttributeTree` in the release notes? Before this PR, `AttributeTree` used to only represent HTML attributes. After this PR has been integrated, that interface will also represent attributes of the standard doclet tags. (Currently, the only such tag is `{@snippet}`.)
> 
> It doesn't seem worth a release note ... we're just using the tree in more places ... but it wouldn't be wrong to create one ... after all, I guess we did have to change doclint to accommodate the new usage.

@jonathan-gibbons, I'm currently cleaning up this PR of unrelated changes. What would you say if I ask you to extract this change of yours into a separate cleanup PR while I delete it from this PR?

https://github.com/openjdk/jdk-sandbox/commit/405c89c35076e73daf7b38d5a20ae83075fb8ae1#diff-e7650e24c581f8df74f8d2bc24110c15c22fd32308f690fba0349c7170f320dfR495-R499

Adding `tagletpath.parameters` and changing `tagletpath.description` has value, but I think you would agree that it's unrelated to snippets.

Separately, when extracting the diff note that that change is a bit inconsistent: while you changed the resource value to `The path for custom taglets`, the option doc comment still refers to `The path to Taglets`: https://github.com/openjdk/jdk-sandbox/blob/405c89c35076e73daf7b38d5a20ae83075fb8ae1/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java#L268

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

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

From jjg at openjdk.java.net  Wed Aug 25 21:53:30 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 25 Aug 2021 21:53:30 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <Th-1B_-MGbPpHryb-9t1qioxaoUnEjCCCxcTVEK-yb4=.dffe6e3a-0a32-43c8-862e-f38320730395@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
 <Th-1B_-MGbPpHryb-9t1qioxaoUnEjCCCxcTVEK-yb4=.dffe6e3a-0a32-43c8-862e-f38320730395@github.com>
Message-ID: <BBLT_jRwzEKk5i1p4KqaYOhFecjWa1dIzkSCQ9jdhi0=.197090cd-470a-4b35-9ad8-4eeeef753393@github.com>

On Tue, 24 Aug 2021 21:56:05 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Generally impressive piece of work.
>
>> @jonathan-gibbons, do we need to mention the semantic change to `com.sun.source.doctree.AttributeTree` in the release notes? Before this PR, `AttributeTree` used to only represent HTML attributes. After this PR has been integrated, that interface will also represent attributes of the standard doclet tags. (Currently, the only such tag is `{@snippet}`.)
> 
> It doesn't seem worth a release note ... we're just using the tree in more places ... but it wouldn't be wrong to create one ... after all, I guess we did have to change doclint to accommodate the new usage.

> @jonathan-gibbons, I'm currently cleaning up this PR of unrelated changes. What would you say if I ask you to extract this change of yours into a separate cleanup PR while I delete it from this PR?
> 
> [openjdk/jdk-sandbox at 405c89c#diff-e7650e24c581f8df74f8d2bc24110c15c22fd32308f690fba0349c7170f320dfR495-R499](https://github.com/openjdk/jdk-sandbox/commit/405c89c35076e73daf7b38d5a20ae83075fb8ae1#diff-e7650e24c581f8df74f8d2bc24110c15c22fd32308f690fba0349c7170f320dfR495-R499)
> 
> Adding `tagletpath.parameters` and changing `tagletpath.description` has value, but I think you would agree that it's unrelated to snippets.
> 
> Separately, when extracting the diff note that that change is a bit inconsistent: while you changed the resource value to `The path for custom taglets`, the option doc comment still refers to `The path to Taglets`: https://github.com/openjdk/jdk-sandbox/blob/405c89c35076e73daf7b38d5a20ae83075fb8ae1/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java#L268

So you're just suggesting that I should handle the parts related to tagletPath, right?  If so, OK.

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

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

From prappo at openjdk.java.net  Wed Aug 25 22:43:01 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 25 Aug 2021 22:43:01 GMT
Subject: RFR: 8266666: Implementation for snippets [v20]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <ZwmfYwxFqtJRFcjUQq7q0bH2chVbiQ1Iql8suGIEj8Q=.fd1cb624-e9a0-4bef-a479-e15352f74067@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

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

  Exclude unrelated changes to resources
  
  Also fixes a typo.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4795/files
  - new: https://git.openjdk.java.net/jdk/pull/4795/files/0d9c53a6..a473e9a1

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=19
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=18-19

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

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

From prappo at openjdk.java.net  Wed Aug 25 22:58:31 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 25 Aug 2021 22:58:31 GMT
Subject: RFR: 8266666: Implementation for snippets [v7]
In-Reply-To: <BBLT_jRwzEKk5i1p4KqaYOhFecjWa1dIzkSCQ9jdhi0=.197090cd-470a-4b35-9ad8-4eeeef753393@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
 <sttAKEX2er6tBMYoElGK8b8m5rA0KkFlPtyNsGBGuw4=.72d6bef9-1cb7-4e4c-aa5d-78acb1a9e6a7@github.com>
 <rj52rD6XSTMbMX864487MsQXC78OqwQvoWAvXpTntJs=.c39e9522-5b41-446a-877d-f6e329955f56@github.com>
 <Th-1B_-MGbPpHryb-9t1qioxaoUnEjCCCxcTVEK-yb4=.dffe6e3a-0a32-43c8-862e-f38320730395@github.com>
 <BBLT_jRwzEKk5i1p4KqaYOhFecjWa1dIzkSCQ9jdhi0=.197090cd-470a-4b35-9ad8-4eeeef753393@github.com>
Message-ID: <FeRej90YVxE4AWz8U9LFuRgU0S-sMsIbGalYYmn8ynU=.834ac70d-1047-41cc-a039-5468bf2979ed@github.com>

On Wed, 25 Aug 2021 21:50:34 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> So you're just suggesting that I should handle the parts related to tagletPath, right? If so, OK.

Yes, I am. I have created a separate bug, where I suggested a patch: https://bugs.openjdk.java.net/browse/JDK-8273001

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

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

From myano at openjdk.java.net  Fri Aug 27 08:26:24 2021
From: myano at openjdk.java.net (Masanori Yano)
Date: Fri, 27 Aug 2021 08:26:24 GMT
Subject: RFR: 8248001: javadoc generates invalid HTML pages whose ftp://
 links are broken
In-Reply-To: <8J8k9Tdirl2MjXOwdkXFQFv21zyayLOErvq4NMAV7Ug=.4fc6ce62-bb92-4504-8af4-5daa6e66cbb7@github.com>
References: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>
 <ahB3g8-B9SSJ4J-q0uW3itCswu7PGfYUhxR53btCAKk=.0255f3b4-a5c2-4c28-8bc7-724e42519e7e@github.com>
 <luwvXZ5xVJj1b5bjh4U_TTtbZGOS4N9TAIYDPLp46S4=.0a470613-04e9-4ad6-9a72-4707c12b0596@github.com>
 <uTXidQfq4LGpFMsxGiw_EzFuIRDMnIDR6hvAN3TjGiM=.7f0509f1-67a3-4926-afd0-a8ce9fdc8e18@github.com>
 <8J8k9Tdirl2MjXOwdkXFQFv21zyayLOErvq4NMAV7Ug=.4fc6ce62-bb92-4504-8af4-5daa6e66cbb7@github.com>
Message-ID: <KBUKm6KmZSZgPO3PHpdRqQIcWXP5LulFPDi0M-2p60M=.59366a25-eb67-4283-9020-624cbf1d34e4@github.com>

On Tue, 24 Aug 2021 09:59:59 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> That said a stricter regexp (unless I'm mistaken) could be: `^[a-zA-Z][a-zA-Z0-9+-.]*:.+$`
>> [ from RFC 2396:     scheme        = alpha *( alpha | digit | "+" | "-" | "." ) ]
>
> I would normally opt for a generic regexp-based solution such as proposed by @dfuch, but there is a security aspect to this as well (e.g. script invocation), so I'd go with the more conservative approach here to just add `ftp:` protocol to the list.

I decided the regex `^[^:/?#]+:.+$` from the description in RFC 2396.

B. Parsing a URI Reference with a Regular Expression

   The following line is the regular expression for breaking-down a URI
   reference into its components.

      ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(?([^#]*))?(#(.*))?
       12            3  4          5       6  7        8 9
  ...
   Therefore, we can determine the value of the four components and fragment as
  ...
      scheme    = $2

I agree that adding `ftp:` is better for the viewpoint of security. However, in addition to ftp, schemes such as javascript and git may be specified, so it's difficult to cover all commonly used schemes.

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

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

From dfuchs at openjdk.java.net  Fri Aug 27 09:15:25 2021
From: dfuchs at openjdk.java.net (Daniel Fuchs)
Date: Fri, 27 Aug 2021 09:15:25 GMT
Subject: RFR: 8248001: javadoc generates invalid HTML pages whose ftp://
 links are broken
In-Reply-To: <KBUKm6KmZSZgPO3PHpdRqQIcWXP5LulFPDi0M-2p60M=.59366a25-eb67-4283-9020-624cbf1d34e4@github.com>
References: <vH8ZHCh_G0HJIVxjR4MRyh4dqzlgzlxVb_KXqIWr_rk=.13961ae3-10ec-47be-9966-72383b32f647@github.com>
 <ahB3g8-B9SSJ4J-q0uW3itCswu7PGfYUhxR53btCAKk=.0255f3b4-a5c2-4c28-8bc7-724e42519e7e@github.com>
 <luwvXZ5xVJj1b5bjh4U_TTtbZGOS4N9TAIYDPLp46S4=.0a470613-04e9-4ad6-9a72-4707c12b0596@github.com>
 <uTXidQfq4LGpFMsxGiw_EzFuIRDMnIDR6hvAN3TjGiM=.7f0509f1-67a3-4926-afd0-a8ce9fdc8e18@github.com>
 <8J8k9Tdirl2MjXOwdkXFQFv21zyayLOErvq4NMAV7Ug=.4fc6ce62-bb92-4504-8af4-5daa6e66cbb7@github.com>
 <KBUKm6KmZSZgPO3PHpdRqQIcWXP5LulFPDi0M-2p60M=.59366a25-eb67-4283-9020-624cbf1d34e4@github.com>
Message-ID: <0-pcU4YYYJdjN38Mpg69qlWnSFLUtOcYL14kMupwLP0=.b5f48877-85f6-4fc1-a580-89049ff7fc47@github.com>

On Fri, 27 Aug 2021 08:23:17 GMT, Masanori Yano <myano at openjdk.org> wrote:

>> I would normally opt for a generic regexp-based solution such as proposed by @dfuch, but there is a security aspect to this as well (e.g. script invocation), so I'd go with the more conservative approach here to just add `ftp:` protocol to the list.
>
> I decided the regex `^[^:/?#]+:.+$` from the description in RFC 2396.
> 
> B. Parsing a URI Reference with a Regular Expression
> 
>    The following line is the regular expression for breaking-down a URI
>    reference into its components.
> 
>       ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(?([^#]*))?(#(.*))?
>        12            3  4          5       6  7        8 9
>   ...
>    Therefore, we can determine the value of the four components and fragment as
>   ...
>       scheme    = $2
> 
> I agree that adding `ftp:` is better for the viewpoint of security. However, in addition to ftp, schemes such as javascript and git may be specified, so it's difficult to cover all commonly used schemes.

That regexp will correctly break the URI  into its different components but it doesn't guarantee that each of the component is syntactically correct - as further syntax restriction may apply on each of the components.

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

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

From prappo at openjdk.java.net  Tue Aug 31 12:16:47 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 31 Aug 2021 12:16:47 GMT
Subject: RFR: 8266666: Implementation for snippets [v21]
In-Reply-To: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
References: <CY9Wn1HaWAEIQIj7vhgaAbCbSKSWdas50tzE7c8QqEA=.f3d14ccf-1421-4242-85ab-98f7262a7ca5@github.com>
Message-ID: <n1dGvv5VX_Pj9rvr1tsw8jte7jXjKPJGhfVPmcDjmS0=.5f9cdbd5-d6f5-4fed-bf14-66a36793e3f8@github.com>

> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.

Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 23 commits:

 - Merge branch 'master' into 8266666
 - Clean up tag parsing
   
   Removes two methods from an older implementation where HTML and javadoc tag attributes were modelled by different DocTree subtypes. Moves the `tagAttrs` method to TagParser responsible for parsing `@snippet` because `:` attribute terminator is specific to `@snippet`. Makes parser stop on `:`. Removes chatty discussion comments from code as suggested by Jonathan Gibbons.
 - Exclude unrelated changes to resources
   
   Also fixes a typo.
 - Recover from a sloppy merge
   
   Apparently, I've performed at least one sloppy merge while developing the feature in sandbox. As a result, some changes brought by e4d045402fa1992a1d91586bd4f67362d07f543c were discarded. The specdiff for the CSR actually shows this and has to be regenerated.
 - Format code closer to the ambient style
   
   Makes new constructs look more natural in their context by adopting the surrounding style.
 - Merge branch 'master' into 8266666
   
   Redoing a faulty merge and pushing the result forcefully.
 - Clarify the attributes order comment
 - Fix import layout and typos
 - Add @summary to tests
   
   From https://openjdk.java.net/jtreg/faq.html:
   
   The @summary tag describes the condition that is checked by the test. It is especially useful for non-regression tests, which by definition don't have bug numbers, but even if there's a bug number it's helpful to include a summary. Note that a test summary is generally not the same thing as a Bugtraq synopsis, since the latter describes the bug rather than the condition that the bug violates.
   
   That said, the JBS synopsis for 8266666 suits those tests just fine.
 - Remove superfluous editor-fold
 - ... and 13 more: https://git.openjdk.java.net/jdk/compare/5185dbde...b2b604fb

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

Changes: https://git.openjdk.java.net/jdk/pull/4795/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=4795&range=20
  Stats: 4657 lines in 44 files changed: 4631 ins; 4 del; 22 mod
  Patch: https://git.openjdk.java.net/jdk/pull/4795.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/4795/head:pull/4795

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