From jjg at openjdk.java.net  Fri Apr  2 17:43:56 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 2 Apr 2021 17:43:56 GMT
Subject: RFR: JDK-8264655: Minor internal doc comment cleanup
Message-ID: <EaqiduxH_JhQimjX_KUrO3FyrzpOuKNSJeTj0ht4ZB8=.6c5f25a3-0c27-4fe0-8c16-fcf70c1a058b@github.com>

Please review some minor updates to internal doc comments on javadoc code. 

In addition, since this is just a cleanup PR, some redundant modifiers noted by an IDE have been removed.

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

Commit messages:
 - JDK-8264655: Minor internal doc comment cleanup

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

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

From prappo at openjdk.java.net  Fri Apr  2 19:34:19 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Fri, 2 Apr 2021 19:34:19 GMT
Subject: RFR: JDK-8264655: Minor internal doc comment cleanup
In-Reply-To: <EaqiduxH_JhQimjX_KUrO3FyrzpOuKNSJeTj0ht4ZB8=.6c5f25a3-0c27-4fe0-8c16-fcf70c1a058b@github.com>
References: <EaqiduxH_JhQimjX_KUrO3FyrzpOuKNSJeTj0ht4ZB8=.6c5f25a3-0c27-4fe0-8c16-fcf70c1a058b@github.com>
Message-ID: <izzICj5eSdNQBow6U7j5D6ju625VBMzI5uQRsgFf1VM=.e67ba4cf-8a77-45f0-8460-65424b997d62@github.com>

On Fri, 2 Apr 2021 17:37:21 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review some minor updates to internal doc comments on javadoc code. 
> 
> In addition, since this is just a cleanup PR, some redundant modifiers noted by an IDE have been removed.

Looks good.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/HtmlTag.java line 56:

> 54:  * @see <a href="http://www.w3.org/TR/aria-in-html/#recommendations-table">WAI-ARIA Recommendations Table</a>
> 55:  * @author Bhavesh Patel
> 56:  * @author Jonathan Gibbons (revised)

Thanks for removing those two @author entries. Did they slip through the review of "8235435: Remove (obsolete) @author info from javadoc source and test" or this file was added later?

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

Marked as reviewed by prappo (Reviewer).

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

From jjg at openjdk.java.net  Fri Apr  2 19:37:30 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 2 Apr 2021 19:37:30 GMT
Subject: RFR: JDK-8264655: Minor internal doc comment cleanup
In-Reply-To: <izzICj5eSdNQBow6U7j5D6ju625VBMzI5uQRsgFf1VM=.e67ba4cf-8a77-45f0-8460-65424b997d62@github.com>
References: <EaqiduxH_JhQimjX_KUrO3FyrzpOuKNSJeTj0ht4ZB8=.6c5f25a3-0c27-4fe0-8c16-fcf70c1a058b@github.com>
 <izzICj5eSdNQBow6U7j5D6ju625VBMzI5uQRsgFf1VM=.e67ba4cf-8a77-45f0-8460-65424b997d62@github.com>
Message-ID: <R8EQ4EshYvtxDJ3CcpahYdKcx-gfX3lh-Wgt-1rrRL8=.5eed6835-05a2-4486-8154-d0e564b32cce@github.com>

On Fri, 2 Apr 2021 19:29:32 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Please review some minor updates to internal doc comments on javadoc code. 
>> 
>> In addition, since this is just a cleanup PR, some redundant modifiers noted by an IDE have been removed.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/HtmlTag.java line 56:
> 
>> 54:  * @see <a href="http://www.w3.org/TR/aria-in-html/#recommendations-table">WAI-ARIA Recommendations Table</a>
>> 55:  * @author Bhavesh Patel
>> 56:  * @author Jonathan Gibbons (revised)
> 
> Thanks for removing those two @author entries. Did they slip through the review of "8235435: Remove (obsolete) @author info from javadoc source and test" or this file was added later?

The file was moved here from the `jdk.compiler` module, where we have not removed the `@author` comments.

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

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

From jjg at openjdk.java.net  Fri Apr  2 20:52:21 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 2 Apr 2021 20:52:21 GMT
Subject: Integrated: JDK-8264655: Minor internal doc comment cleanup
In-Reply-To: <EaqiduxH_JhQimjX_KUrO3FyrzpOuKNSJeTj0ht4ZB8=.6c5f25a3-0c27-4fe0-8c16-fcf70c1a058b@github.com>
References: <EaqiduxH_JhQimjX_KUrO3FyrzpOuKNSJeTj0ht4ZB8=.6c5f25a3-0c27-4fe0-8c16-fcf70c1a058b@github.com>
Message-ID: <xjcGADjqGVlc3R7q7G6aDlk4tLpzBAF7_gP8tdmf5tw=.020709ed-075a-40c1-a013-d72ef6c96d99@github.com>

On Fri, 2 Apr 2021 17:37:21 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review some minor updates to internal doc comments on javadoc code. 
> 
> In addition, since this is just a cleanup PR, some redundant modifiers noted by an IDE have been removed.

This pull request has now been integrated.

Changeset: eb0ac86d
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/eb0ac86d
Stats:     18 lines in 4 files changed: 1 ins; 3 del; 14 mod

8264655: Minor internal doc comment cleanup

Reviewed-by: prappo

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

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

From hannesw at openjdk.java.net  Fri Apr  9 14:29:08 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 9 Apr 2021 14:29:08 GMT
Subject: RFR: JDK-8263507: Add links to page sections in sub-navigation of
 package summaries
Message-ID: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>

This adds a feature to add sub-navigation links to the package summary page, but ended up more like a refactoring of the code to generate sub-navigation links. The reason for this is that generation of these links was highly idiosyncratic. Every writer class that wanted to create sub-nav links deposited something of itself in the `Navigation` instance which was then responsible for generating these links. The new code introduces a `Navigation.SubNavLinks` interface that allows writers to provide a list of links into their page content.

As for the new feature in the package summary page itself, I chose an approach that is a bit different from the one we use for other types of pages. Instead of displaying the inactive label instead of the link when a section is not present on the page, only the active links are displayed. The reason for this is that the package summary page contains so many potential summary tables that the sub-nav area gets quite crowded if they are all shown. Just showing the actually present pieces looked better to me.

Like in other sub-nav sections, the link labels sometimes use abbreviated terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of "ENUM CLASSES". The full list of potential package sub-nav links is as follows:

    Package: Description | Related | Interfaces | Classes | Enums | Records | Exceptions | Errors | Annotations

An important implementation note is that I moved the code to compute package summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The reason for this is that the contents are required to determine which links to create, and I didn't want to re-compute this information that was previously computed on the fly in the builder class. The various summary items are now stored in collection fields in the writer class. 

I have tried to add all the new properties and constants in a sensible place, which usually means alphabetic order within the sub-group of related entries.

I chose to keep the markup structure of the package summary page mostly unchanged, adding only `id` attributes to the existing `<li>` elements for each summary table. I decided against adding `class` attributes as well as it seems very unlikely to me that somebody would want to apply different styles to the various summary tables. Even without them, it could be done using the `id`s.

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

Commit messages:
 - JDK-8263507: Simplify list creation
 - JDK-8263507: Rename some methods and add some docs
 - JDK-8263507: Add links to page sections in sub-navigation of package summaries

Changes: https://git.openjdk.java.net/jdk/pull/3413/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3413&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8263507
  Stats: 1106 lines in 24 files changed: 525 ins; 480 del; 101 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3413.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3413/head:pull/3413

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

From jonathan.gibbons at oracle.com  Fri Apr  9 15:22:02 2021
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 9 Apr 2021 08:22:02 -0700
Subject: RFR: JDK-8263507: Add links to page sections in sub-navigation of
 package summaries
In-Reply-To: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
Message-ID: <b6aa1997-e441-17fe-bcd5-7ae502c6d1e8@oracle.com>

Hannes,

Reading your email, and the comments about the number of tables, reminds 
me of the suggestion to merge most of the tables (all those for 
different kinds of classes and interfaces) into a single tabbed table, 
as is now becoming more prevalent through the rest of the output.? This 
would simplify the package summary page to two(?) tables, one for 
"related packages" (no tabs) and one for "classes and interfaces" (with 
tabs for the kind)

This is not meant to invalidate the general work you have done to 
improve the code in Navigation, but it might simplify the use of the new 
code.? The package sub-nav would have 3(?) entries, for Description, 
Related, Classes-and-Interfaces

-- Jon

On 4/9/21 7:29 AM, Hannes Walln?fer wrote:
> This adds a feature to add sub-navigation links to the package summary page, but ended up more like a refactoring of the code to generate sub-navigation links. The reason for this is that generation of these links was highly idiosyncratic. Every writer class that wanted to create sub-nav links deposited something of itself in the `Navigation` instance which was then responsible for generating these links. The new code introduces a `Navigation.SubNavLinks` interface that allows writers to provide a list of links into their page content.
>
> As for the new feature in the package summary page itself, I chose an approach that is a bit different from the one we use for other types of pages. Instead of displaying the inactive label instead of the link when a section is not present on the page, only the active links are displayed. The reason for this is that the package summary page contains so many potential summary tables that the sub-nav area gets quite crowded if they are all shown. Just showing the actually present pieces looked better to me.
>
> Like in other sub-nav sections, the link labels sometimes use abbreviated terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of "ENUM CLASSES". The full list of potential package sub-nav links is as follows:
>
>      Package: Description | Related | Interfaces | Classes | Enums | Records | Exceptions | Errors | Annotations
>
> An important implementation note is that I moved the code to compute package summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The reason for this is that the contents are required to determine which links to create, and I didn't want to re-compute this information that was previously computed on the fly in the builder class. The various summary items are now stored in collection fields in the writer class.
>
> I have tried to add all the new properties and constants in a sensible place, which usually means alphabetic order within the sub-group of related entries.
>
> I chose to keep the markup structure of the package summary page mostly unchanged, adding only `id` attributes to the existing `<li>` elements for each summary table. I decided against adding `class` attributes as well as it seems very unlikely to me that somebody would want to apply different styles to the various summary tables. Even without them, it could be done using the `id`s.
>
> -------------
>
> Commit messages:
>   - JDK-8263507: Simplify list creation
>   - JDK-8263507: Rename some methods and add some docs
>   - JDK-8263507: Add links to page sections in sub-navigation of package summaries
>
> Changes: https://git.openjdk.java.net/jdk/pull/3413/files
>   Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3413&range=00
>    Issue: https://bugs.openjdk.java.net/browse/JDK-8263507
>    Stats: 1106 lines in 24 files changed: 525 ins; 480 del; 101 mod
>    Patch: https://git.openjdk.java.net/jdk/pull/3413.diff
>    Fetch: git fetch https://git.openjdk.java.net/jdk pull/3413/head:pull/3413
>
> PR: https://git.openjdk.java.net/jdk/pull/3413

From hannes.wallnoefer at oracle.com  Fri Apr  9 19:59:26 2021
From: hannes.wallnoefer at oracle.com (Hannes Wallnoefer)
Date: Fri, 9 Apr 2021 19:59:26 +0000
Subject: RFR: JDK-8263507: Add links to page sections in sub-navigation of
 package summaries
In-Reply-To: <b6aa1997-e441-17fe-bcd5-7ae502c6d1e8@oracle.com>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
 <b6aa1997-e441-17fe-bcd5-7ae502c6d1e8@oracle.com>
Message-ID: <C6575583-863E-47BC-8135-533F29C01781@ORACLE.COM>

Am 09.04.2021 um 17:22 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
> 
> Hannes,
> 
> Reading your email, and the comments about the number of tables, reminds me of the suggestion to merge most of the tables (all those for different kinds of classes and interfaces) into a single tabbed table, as is now becoming more prevalent through the rest of the output.  This would simplify the package summary page to two(?) tables, one for "related packages" (no tabs) and one for "classes and interfaces" (with tabs for the kind)
> 
> This is not meant to invalidate the general work you have done to improve the code in Navigation, but it might simplify the use of the new code.  The package sub-nav would have 3(?) entries, for Description, Related, Classes-and-Interfaces
> 

Excellent idea! I wonder how this didn?t occur to me while working on the code. I?m not worried about the work I?ve done, as it will only reduce the number of links/ids.

Should this be done as part of this change, or filed as separate issue?

Hannes

> -- Jon
> 
> On 4/9/21 7:29 AM, Hannes Walln?fer wrote:
>> This adds a feature to add sub-navigation links to the package summary page, but ended up more like a refactoring of the code to generate sub-navigation links. The reason for this is that generation of these links was highly idiosyncratic. Every writer class that wanted to create sub-nav links deposited something of itself in the `Navigation` instance which was then responsible for generating these links. The new code introduces a `Navigation.SubNavLinks` interface that allows writers to provide a list of links into their page content.
>> 
>> As for the new feature in the package summary page itself, I chose an approach that is a bit different from the one we use for other types of pages. Instead of displaying the inactive label instead of the link when a section is not present on the page, only the active links are displayed. The reason for this is that the package summary page contains so many potential summary tables that the sub-nav area gets quite crowded if they are all shown. Just showing the actually present pieces looked better to me.
>> 
>> Like in other sub-nav sections, the link labels sometimes use abbreviated terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of "ENUM CLASSES". The full list of potential package sub-nav links is as follows:
>> 
>>     Package: Description | Related | Interfaces | Classes | Enums | Records | Exceptions | Errors | Annotations
>> 
>> An important implementation note is that I moved the code to compute package summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The reason for this is that the contents are required to determine which links to create, and I didn't want to re-compute this information that was previously computed on the fly in the builder class. The various summary items are now stored in collection fields in the writer class.
>> 
>> I have tried to add all the new properties and constants in a sensible place, which usually means alphabetic order within the sub-group of related entries.
>> 
>> I chose to keep the markup structure of the package summary page mostly unchanged, adding only `id` attributes to the existing `<li>` elements for each summary table. I decided against adding `class` attributes as well as it seems very unlikely to me that somebody would want to apply different styles to the various summary tables. Even without them, it could be done using the `id`s.
>> 
>> -------------
>> 
>> Commit messages:
>>  - JDK-8263507: Simplify list creation
>>  - JDK-8263507: Rename some methods and add some docs
>>  - JDK-8263507: Add links to page sections in sub-navigation of package summaries
>> 
>> Changes: https://git.openjdk.java.net/jdk/pull/3413/files
>>  Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3413&range=00
>>   Issue: https://bugs.openjdk.java.net/browse/JDK-8263507
>>   Stats: 1106 lines in 24 files changed: 525 ins; 480 del; 101 mod
>>   Patch: https://git.openjdk.java.net/jdk/pull/3413.diff
>>   Fetch: git fetch https://git.openjdk.java.net/jdk pull/3413/head:pull/3413
>> 
>> PR: https://git.openjdk.java.net/jdk/pull/3413


From jonathan.gibbons at oracle.com  Sat Apr 10 14:59:16 2021
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Sat, 10 Apr 2021 07:59:16 -0700
Subject: RFR: JDK-8263507: Add links to page sections in sub-navigation of
 package summaries
In-Reply-To: <C6575583-863E-47BC-8135-533F29C01781@ORACLE.COM>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
 <b6aa1997-e441-17fe-bcd5-7ae502c6d1e8@oracle.com>
 <C6575583-863E-47BC-8135-533F29C01781@ORACLE.COM>
Message-ID: <056830e3-2c04-695e-404e-1a6dd144236a@oracle.com>


On 4/9/21 12:59 PM, Hannes Wallnoefer wrote:
> Am 09.04.2021 um 17:22 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>> Hannes,
>>
>> Reading your email, and the comments about the number of tables, reminds me of the suggestion to merge most of the tables (all those for different kinds of classes and interfaces) into a single tabbed table, as is now becoming more prevalent through the rest of the output.  This would simplify the package summary page to two(?) tables, one for "related packages" (no tabs) and one for "classes and interfaces" (with tabs for the kind)
>>
>> This is not meant to invalidate the general work you have done to improve the code in Navigation, but it might simplify the use of the new code.  The package sub-nav would have 3(?) entries, for Description, Related, Classes-and-Interfaces
>>
> Excellent idea! I wonder how this didn?t occur to me while working on the code. I?m not worried about the work I?ve done, as it will only reduce the number of links/ids.
>
> Should this be done as part of this change, or filed as separate issue?

I think that's your call.

I think there are 2 JBS issues, but you could do a single PR for both, 
if that would be easier.

As two issues, maybe it would make sense to do the tabbed table first, 
followed by the subnav work, since that avoids an interim step with lots 
of links in the subnav.

-- Jon


>
> Hannes
>
>> -- Jon
>>
>> On 4/9/21 7:29 AM, Hannes Walln?fer wrote:
>>> This adds a feature to add sub-navigation links to the package summary page, but ended up more like a refactoring of the code to generate sub-navigation links. The reason for this is that generation of these links was highly idiosyncratic. Every writer class that wanted to create sub-nav links deposited something of itself in the `Navigation` instance which was then responsible for generating these links. The new code introduces a `Navigation.SubNavLinks` interface that allows writers to provide a list of links into their page content.
>>>
>>> As for the new feature in the package summary page itself, I chose an approach that is a bit different from the one we use for other types of pages. Instead of displaying the inactive label instead of the link when a section is not present on the page, only the active links are displayed. The reason for this is that the package summary page contains so many potential summary tables that the sub-nav area gets quite crowded if they are all shown. Just showing the actually present pieces looked better to me.
>>>
>>> Like in other sub-nav sections, the link labels sometimes use abbreviated terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of "ENUM CLASSES". The full list of potential package sub-nav links is as follows:
>>>
>>>      Package: Description | Related | Interfaces | Classes | Enums | Records | Exceptions | Errors | Annotations
>>>
>>> An important implementation note is that I moved the code to compute package summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The reason for this is that the contents are required to determine which links to create, and I didn't want to re-compute this information that was previously computed on the fly in the builder class. The various summary items are now stored in collection fields in the writer class.
>>>
>>> I have tried to add all the new properties and constants in a sensible place, which usually means alphabetic order within the sub-group of related entries.
>>>
>>> I chose to keep the markup structure of the package summary page mostly unchanged, adding only `id` attributes to the existing `<li>` elements for each summary table. I decided against adding `class` attributes as well as it seems very unlikely to me that somebody would want to apply different styles to the various summary tables. Even without them, it could be done using the `id`s.
>>>
>>> -------------
>>>
>>> Commit messages:
>>>   - JDK-8263507: Simplify list creation
>>>   - JDK-8263507: Rename some methods and add some docs
>>>   - JDK-8263507: Add links to page sections in sub-navigation of package summaries
>>>
>>> Changes: https://git.openjdk.java.net/jdk/pull/3413/files
>>>   Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3413&range=00
>>>    Issue: https://bugs.openjdk.java.net/browse/JDK-8263507
>>>    Stats: 1106 lines in 24 files changed: 525 ins; 480 del; 101 mod
>>>    Patch: https://git.openjdk.java.net/jdk/pull/3413.diff
>>>    Fetch: git fetch https://git.openjdk.java.net/jdk pull/3413/head:pull/3413
>>>
>>> PR: https://git.openjdk.java.net/jdk/pull/3413

From jonathan.gibbons at oracle.com  Sat Apr 10 15:55:59 2021
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Sat, 10 Apr 2021 08:55:59 -0700
Subject: RFR: JDK-8263507: Add links to page sections in sub-navigation of
 package summaries
In-Reply-To: <C6575583-863E-47BC-8135-533F29C01781@ORACLE.COM>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
 <b6aa1997-e441-17fe-bcd5-7ae502c6d1e8@oracle.com>
 <C6575583-863E-47BC-8135-533F29C01781@ORACLE.COM>
Message-ID: <8793e6b0-34d0-ed4c-e84d-1714e9a1dbc8@oracle.com>


On 4/9/21 12:59 PM, Hannes Wallnoefer wrote:
> Am 09.04.2021 um 17:22 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>> Hannes,
>>
>> Reading your email, and the comments about the number of tables, reminds me of the suggestion to merge most of the tables (all those for different kinds of classes and interfaces) into a single tabbed table, as is now becoming more prevalent through the rest of the output.  This would simplify the package summary page to two(?) tables, one for "related packages" (no tabs) and one for "classes and interfaces" (with tabs for the kind)
>>
>> This is not meant to invalidate the general work you have done to improve the code in Navigation, but it might simplify the use of the new code.  The package sub-nav would have 3(?) entries, for Description, Related, Classes-and-Interfaces
>>
> Excellent idea! I wonder how this didn?t occur to me while working on the code. I?m not worried about the work I?ve done, as it will only reduce the number of links/ids.


I see we already have a similar table in the All Classes page. Looking 
at that page I would suggest the following:

  * Change the page heading to "All Classes and Interfaces"
  * Change the first tab from "All Classes" to "All"
  * Drop the word "Summary" from the other tabs
  * Maybe pluralize all the tab names

-- Jon

>
> Should this be done as part of this change, or filed as separate issue?
>
> Hannes
>
>> -- Jon
>>
>> On 4/9/21 7:29 AM, Hannes Walln?fer wrote:
>>> This adds a feature to add sub-navigation links to the package summary page, but ended up more like a refactoring of the code to generate sub-navigation links. The reason for this is that generation of these links was highly idiosyncratic. Every writer class that wanted to create sub-nav links deposited something of itself in the `Navigation` instance which was then responsible for generating these links. The new code introduces a `Navigation.SubNavLinks` interface that allows writers to provide a list of links into their page content.
>>>
>>> As for the new feature in the package summary page itself, I chose an approach that is a bit different from the one we use for other types of pages. Instead of displaying the inactive label instead of the link when a section is not present on the page, only the active links are displayed. The reason for this is that the package summary page contains so many potential summary tables that the sub-nav area gets quite crowded if they are all shown. Just showing the actually present pieces looked better to me.
>>>
>>> Like in other sub-nav sections, the link labels sometimes use abbreviated terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of "ENUM CLASSES". The full list of potential package sub-nav links is as follows:
>>>
>>>      Package: Description | Related | Interfaces | Classes | Enums | Records | Exceptions | Errors | Annotations
>>>
>>> An important implementation note is that I moved the code to compute package summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The reason for this is that the contents are required to determine which links to create, and I didn't want to re-compute this information that was previously computed on the fly in the builder class. The various summary items are now stored in collection fields in the writer class.
>>>
>>> I have tried to add all the new properties and constants in a sensible place, which usually means alphabetic order within the sub-group of related entries.
>>>
>>> I chose to keep the markup structure of the package summary page mostly unchanged, adding only `id` attributes to the existing `<li>` elements for each summary table. I decided against adding `class` attributes as well as it seems very unlikely to me that somebody would want to apply different styles to the various summary tables. Even without them, it could be done using the `id`s.
>>>
>>> -------------
>>>
>>> Commit messages:
>>>   - JDK-8263507: Simplify list creation
>>>   - JDK-8263507: Rename some methods and add some docs
>>>   - JDK-8263507: Add links to page sections in sub-navigation of package summaries
>>>
>>> Changes: https://git.openjdk.java.net/jdk/pull/3413/files
>>>   Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3413&range=00
>>>    Issue: https://bugs.openjdk.java.net/browse/JDK-8263507
>>>    Stats: 1106 lines in 24 files changed: 525 ins; 480 del; 101 mod
>>>    Patch: https://git.openjdk.java.net/jdk/pull/3413.diff
>>>    Fetch: git fetch https://git.openjdk.java.net/jdk pull/3413/head:pull/3413
>>>
>>> PR: https://git.openjdk.java.net/jdk/pull/3413
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210410/13873030/attachment-0001.htm>

From hannes.wallnoefer at oracle.com  Mon Apr 12 15:59:08 2021
From: hannes.wallnoefer at oracle.com (Hannes Wallnoefer)
Date: Mon, 12 Apr 2021 15:59:08 +0000
Subject: RFR: JDK-8263507: Add links to page sections in sub-navigation of
 package summaries
In-Reply-To: <8793e6b0-34d0-ed4c-e84d-1714e9a1dbc8@oracle.com>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
 <b6aa1997-e441-17fe-bcd5-7ae502c6d1e8@oracle.com>
 <C6575583-863E-47BC-8135-533F29C01781@ORACLE.COM>
 <8793e6b0-34d0-ed4c-e84d-1714e9a1dbc8@oracle.com>
Message-ID: <72730D64-0C5A-4556-8593-26CCC357F069@ORACLE.COM>

I have imlemented the tabbed classes and interfaces table and playing around with the wording.

It looks like dropping the word ?Summary? would give us enough space to actually expand the first ?All Classes? tab to ?All Classes and Interfaces?, which I find more meaningful and correct. That is even with adding a ?Record Classes? tab which is currently missing on the ?All Classes? index page.

Below is.a screenshot of how that would look like:

[cid:CAA503F9-C160-4CA0-9439-2A5258DDD406 at fritz.box]

I would also suggest to use the same wording for the tabs on the ?All Classes? index page and the package summary pages, as I don?t see why they should be different.

Hannes


Am 10.04.2021 um 17:55 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com<mailto:jonathan.gibbons at oracle.com>>:

I see we already have a similar table in the All Classes page.  Looking at that page I would suggest the following:

? Change the page heading to "All Classes and Interfaces"
? Change the first tab from "All Classes" to "All"
? Drop the word "Summary" from the other tabs
? Maybe pluralize all the tab names
-- Jon

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210412/8f2341bc/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PastedGraphic-1.png
Type: image/png
Size: 39044 bytes
Desc: PastedGraphic-1.png
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210412/8f2341bc/PastedGraphic-1-0001.png>

From jonathan.gibbons at oracle.com  Tue Apr 13 05:22:06 2021
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 12 Apr 2021 22:22:06 -0700
Subject: RFR: JDK-8263507: Add links to page sections in sub-navigation of
 package summaries
In-Reply-To: <72730D64-0C5A-4556-8593-26CCC357F069@ORACLE.COM>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
 <b6aa1997-e441-17fe-bcd5-7ae502c6d1e8@oracle.com>
 <C6575583-863E-47BC-8135-533F29C01781@ORACLE.COM>
 <8793e6b0-34d0-ed4c-e84d-1714e9a1dbc8@oracle.com>
 <72730D64-0C5A-4556-8593-26CCC357F069@ORACLE.COM>
Message-ID: <eafbc927-ea07-cdf8-18e8-ad7c4f7b6c5f@oracle.com>

Looks good.

Agreed that the terminology and appearance should be the same on the 
"All Classes" page as on a package page.

If space becomes an issue, I think the first tab could be reduced to 
"All" provided there is a suitable heading above the table, such as "All 
Classes and Interfaces" /"Classes and Interfaces in Package ..." 
although even there, you could drop "in Package ..." given the context 
of the package page.

Agreed that "All Classes" is less than ideal. It should either be "All 
Classes and Interfaces" or just "All".

Just asking: does the "Classes" tab refer to "all classes, including 
enum classes, record classes, exceptions and errors", or "all classes 
except enum classes, record classes, exceptions and errors" ?

-- jon

On 4/12/21 8:59 AM, Hannes Wallnoefer wrote:
> I have imlemented the tabbed classes and interfaces table and playing 
> around with the wording.
>
> It looks like dropping the word ?Summary? would give us enough space 
> to actually expand the first ?All Classes? tab to ?All Classes and 
> Interfaces?, which I find more meaningful and correct. That is even 
> with adding a ?Record Classes? tab which is currently missing on the 
> ?All Classes? index page.
>
> Below is.a screenshot of how that would look like:
>
>
>
> I would also suggest to use the same wording for the tabs on the ?All 
> Classes? index page and the package summary pages, as I don?t see why 
> they should be different.
>
> Hannes
>
>
>> Am 10.04.2021 um 17:55 schrieb Jonathan Gibbons 
>> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>>:
>>
>> I see we already have a similar table in the All Classes 
>> page.??Looking at that page I would suggest the following:
>>
>> ? Change the page heading to "All Classes and Interfaces"
>> ? Change the first tab from "All Classes" to "All"
>> ? Drop the word "Summary" from the other tabs
>> ? Maybe pluralize all the tab names
>> -- Jon
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210412/b6a97086/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PastedGraphic-1.png
Type: image/png
Size: 39044 bytes
Desc: not available
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210412/b6a97086/PastedGraphic-1-0001.png>

From hannes.wallnoefer at oracle.com  Tue Apr 13 14:11:15 2021
From: hannes.wallnoefer at oracle.com (Hannes Wallnoefer)
Date: Tue, 13 Apr 2021 14:11:15 +0000
Subject: RFR: JDK-8263507: Add links to page sections in sub-navigation of
 package summaries
In-Reply-To: <eafbc927-ea07-cdf8-18e8-ad7c4f7b6c5f@oracle.com>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
 <b6aa1997-e441-17fe-bcd5-7ae502c6d1e8@oracle.com>
 <C6575583-863E-47BC-8135-533F29C01781@ORACLE.COM>
 <8793e6b0-34d0-ed4c-e84d-1714e9a1dbc8@oracle.com>
 <72730D64-0C5A-4556-8593-26CCC357F069@ORACLE.COM>
 <eafbc927-ea07-cdf8-18e8-ad7c4f7b6c5f@oracle.com>
Message-ID: <BBA6F224-FB10-4F6F-A608-9E7EF0B9C98D@ORACLE.COM>

Am 13.04.2021 um 07:22 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
> 
> Just asking: does the "Classes" tab refer to "all classes, including enum classes, record classes, exceptions and errors", or "all classes except enum classes, record classes, exceptions and errors" ?


It just includes ?ordinary? classes as identified by Utils.isOrdinaryClass(TypeElement), so interfaces, enum classes, exceptions, errors and annotation interfaces are excluded. But I just discovered record classes are not (matching the fact that there is currently no ?Record Classes? tab in the All Classes page).

Hannes

> -- jon
> 

From hannesw at openjdk.java.net  Mon Apr 19 08:54:28 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 19 Apr 2021 08:54:28 GMT
Subject: RFR: JDK-8263507: Add links to page sections in sub-navigation of
 package summaries [v2]
In-Reply-To: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
Message-ID: <_efIgtxW4wY_v7oE-V2mn5r1Jyp9intbz6DrWA3kJWI=.7e9b228d-6d7c-4598-9132-1c45bb15b299@github.com>

> This adds a feature to add sub-navigation links to the package summary page, but ended up more like a refactoring of the code to generate sub-navigation links. The reason for this is that generation of these links was highly idiosyncratic. Every writer class that wanted to create sub-nav links deposited something of itself in the `Navigation` instance which was then responsible for generating these links. The new code introduces a `Navigation.SubNavLinks` interface that allows writers to provide a list of links into their page content.
> 
> As for the new feature in the package summary page itself, I chose an approach that is a bit different from the one we use for other types of pages. Instead of displaying the inactive label instead of the link when a section is not present on the page, only the active links are displayed. The reason for this is that the package summary page contains so many potential summary tables that the sub-nav area gets quite crowded if they are all shown. Just showing the actually present pieces looked better to me.
> 
> Like in other sub-nav sections, the link labels sometimes use abbreviated terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of "ENUM CLASSES". The full list of potential package sub-nav links is as follows:
> 
>     Package: Description | Related | Interfaces | Classes | Enums | Records | Exceptions | Errors | Annotations
> 
> An important implementation note is that I moved the code to compute package summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The reason for this is that the contents are required to determine which links to create, and I didn't want to re-compute this information that was previously computed on the fly in the builder class. The various summary items are now stored in collection fields in the writer class. 
> 
> I have tried to add all the new properties and constants in a sensible place, which usually means alphabetic order within the sub-group of related entries.
> 
> I chose to keep the markup structure of the package summary page mostly unchanged, adding only `id` attributes to the existing `<li>` elements for each summary table. I decided against adding `class` attributes as well as it seems very unlikely to me that somebody would want to apply different styles to the various summary tables. Even without them, it could be done using the `id`s.

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

  JDK-8263507: Merge classes and interfaces in package summary into one tabbed table

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3413/files
  - new: https://git.openjdk.java.net/jdk/pull/3413/files/2f99340d..72887324

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

  Stats: 426 lines in 21 files changed: 57 ins; 229 del; 140 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3413.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3413/head:pull/3413

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

From hannesw at openjdk.java.net  Mon Apr 19 09:45:27 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 19 Apr 2021 09:45:27 GMT
Subject: RFR: JDK-8263507: Improve structure of package summary pages [v3]
In-Reply-To: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
Message-ID: <6XZXNSLtyLhCJ89InQlEzfSqDQGKynahstvpRZGuFbw=.915f8819-9b25-4635-b9c9-c108fa2e997c@github.com>

> This adds a feature to add sub-navigation links to the package summary page, but ended up more like a refactoring of the code to generate sub-navigation links. The reason for this is that generation of these links was highly idiosyncratic. Every writer class that wanted to create sub-nav links deposited something of itself in the `Navigation` instance which was then responsible for generating these links. The new code introduces a `Navigation.SubNavLinks` interface that allows writers to provide a list of links into their page content.
> 
> As for the new feature in the package summary page itself, I chose an approach that is a bit different from the one we use for other types of pages. Instead of displaying the inactive label instead of the link when a section is not present on the page, only the active links are displayed. The reason for this is that the package summary page contains so many potential summary tables that the sub-nav area gets quite crowded if they are all shown. Just showing the actually present pieces looked better to me.
> 
> Like in other sub-nav sections, the link labels sometimes use abbreviated terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of "ENUM CLASSES". The full list of potential package sub-nav links is as follows:
> 
>     Package: Description | Related | Interfaces | Classes | Enums | Records | Exceptions | Errors | Annotations
> 
> An important implementation note is that I moved the code to compute package summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The reason for this is that the contents are required to determine which links to create, and I didn't want to re-compute this information that was previously computed on the fly in the builder class. The various summary items are now stored in collection fields in the writer class. 
> 
> I have tried to add all the new properties and constants in a sensible place, which usually means alphabetic order within the sub-group of related entries.
> 
> I chose to keep the markup structure of the package summary page mostly unchanged, adding only `id` attributes to the existing `<li>` elements for each summary table. I decided against adding `class` attributes as well as it seems very unlikely to me that somebody would want to apply different styles to the various summary tables. Even without them, it could be done using the `id`s.

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

  JDK-8263507: Update JBS summary

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3413/files
  - new: https://git.openjdk.java.net/jdk/pull/3413/files/72887324..f21399d9

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

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

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

From hannesw at openjdk.java.net  Mon Apr 19 10:03:39 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 19 Apr 2021 10:03:39 GMT
Subject: RFR: JDK-8263507: Improve structure of package summary pages [v3]
In-Reply-To: <6XZXNSLtyLhCJ89InQlEzfSqDQGKynahstvpRZGuFbw=.915f8819-9b25-4635-b9c9-c108fa2e997c@github.com>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
 <6XZXNSLtyLhCJ89InQlEzfSqDQGKynahstvpRZGuFbw=.915f8819-9b25-4635-b9c9-c108fa2e997c@github.com>
Message-ID: <TYKSvkF_gQ-lZX-ue1_2fCxrGQyL5ri7mGAAE33GiR0=.950c519d-ce2a-435b-973b-cdf6eedbc35f@github.com>

On Mon, 19 Apr 2021 09:45:27 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This adds a feature to add sub-navigation links to the package summary page, but ended up more like a refactoring of the code to generate sub-navigation links. The reason for this is that generation of these links was highly idiosyncratic. Every writer class that wanted to create sub-nav links deposited something of itself in the `Navigation` instance which was then responsible for generating these links. The new code introduces a `Navigation.SubNavLinks` interface that allows writers to provide a list of links into their page content.
>> 
>> As for the new feature in the package summary page itself, I chose an approach that is a bit different from the one we use for other types of pages. Instead of displaying the inactive label instead of the link when a section is not present on the page, only the active links are displayed. The reason for this is that the package summary page contains so many potential summary tables that the sub-nav area gets quite crowded if they are all shown. Just showing the actually present pieces looked better to me.
>> 
>> Like in other sub-nav sections, the link labels sometimes use abbreviated terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of "ENUM CLASSES". The full list of potential package sub-nav links is as follows:
>> 
>>     Package: Description | Related | Interfaces | Classes | Enums | Records | Exceptions | Errors | Annotations
>> 
>> An important implementation note is that I moved the code to compute package summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The reason for this is that the contents are required to determine which links to create, and I didn't want to re-compute this information that was previously computed on the fly in the builder class. The various summary items are now stored in collection fields in the writer class. 
>> 
>> I have tried to add all the new properties and constants in a sensible place, which usually means alphabetic order within the sub-group of related entries.
>> 
>> I chose to keep the markup structure of the package summary page mostly unchanged, adding only `id` attributes to the existing `<li>` elements for each summary table. I decided against adding `class` attributes as well as it seems very unlikely to me that somebody would want to apply different styles to the various summary tables. Even without them, it could be done using the `id`s.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   JDK-8263507: Update JBS summary

I opted for doing the summary table merge within this same PR. I couldn't find an existing JBS issue for it, and splitting the work into two changesets and reverse their order seemed like a non-trivial amount of work.

I have updated the JBS summary to "Improve structure of package summary pages" to reflect the broader scope.

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

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

From jonathan.gibbons at oracle.com  Tue Apr 20 03:33:44 2021
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 19 Apr 2021 20:33:44 -0700
Subject: Snippet JEP Draft Update: https://openjdk.java.net/jeps/8201533
Message-ID: <970237f3-4e3b-13f8-68a2-7be3a2990100@oracle.com>

I've updated the text for the proposed JEP for javadoc snippets. Thanks 
to Pavel for his contributions to the text, and for his work on the 
design and implementation to date.

https://openjdk.java.net/jeps/8201533

-- Jon


From igraves at openjdk.java.net  Thu Apr 22 02:17:40 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Thu, 22 Apr 2021 02:17:40 GMT
Subject: RFR: 8261168: Convert javadoc tool to use Stream.toList()
Message-ID: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>

8261168: Convert javadoc tool to use Stream.toList()

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

Commit messages:
 - Updating to Stream.toLlist() from Collectors.toList()

Changes: https://git.openjdk.java.net/jdk/pull/3612/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3612&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8261168
  Stats: 48 lines in 9 files changed: 7 ins; 8 del; 33 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3612.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3612/head:pull/3612

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

From vromero at openjdk.java.net  Thu Apr 22 02:27:32 2021
From: vromero at openjdk.java.net (Vicente Romero)
Date: Thu, 22 Apr 2021 02:27:32 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in Java,
 javadoc changes
Message-ID: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>

Please review the javadoc related changes to make sealed classes a final feature in Java. The patch is mostly removing preview features related code that is not necessary anymore in javadoc.

TIA

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

Commit messages:
 - 8265684: implement Sealed Classes as a standard feature in Java, javadoc changes

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

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

From jjg at openjdk.java.net  Thu Apr 22 02:52:20 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 22 Apr 2021 02:52:20 GMT
Subject: RFR: 8261168: Convert javadoc tool to use Stream.toList()
In-Reply-To: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
References: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
Message-ID: <bBpE-NRpAYXPd_-bXVBqwW1gPBWbUVbiUs1cYiWTki4=.fece0f55-8cbf-481b-b8f0-43254798896a@github.com>

On Thu, 22 Apr 2021 02:11:35 GMT, Ian Graves <igraves at openjdk.org> wrote:

> 8261168: Convert javadoc tool to use Stream.toList()

This seems to be a lot more than just an automated IDE cleanup.

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

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

From igraves at openjdk.java.net  Thu Apr 22 04:09:17 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Thu, 22 Apr 2021 04:09:17 GMT
Subject: RFR: 8261168: Convert javadoc tool to use Stream.toList()
In-Reply-To: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
References: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
Message-ID: <T7Nk_eu7cDavObBmQApnVs0rcNETPdcnG6-FHTKkzFw=.0cb6af91-e6b1-4005-a36b-ad30f77ec9c7@github.com>

On Thu, 22 Apr 2021 02:11:35 GMT, Ian Graves <igraves at openjdk.org> wrote:

> 8261168: Convert javadoc tool to use Stream.toList()

That's correct. It's not an IDE cleanup, in fact. This is migrating the use of `Collectors.toList()` to `Stream.toList()` where the latter gains some performance benefits while properly enforcing immutability. So there is some hand-checking on my part to ensure that the conversion doesn't introduce immutability where it wasn't expected. This is a subtask of [JDK-8260559](https://bugs.openjdk.java.net/browse/JDK-8260559).

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

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

From igraves at openjdk.java.net  Thu Apr 22 04:19:50 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Thu, 22 Apr 2021 04:19:50 GMT
Subject: RFR: 8261168: Convert javadoc tool to use Stream.toList() [v2]
In-Reply-To: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
References: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
Message-ID: <2hsyHT6NX8Yv5X9X1niDZiBtjOJbY5gbZTzyRkiN0Yk=.9e9656ef-33b8-4ddb-adee-902012c69c2e@github.com>

> 8261168: Convert javadoc tool to use Stream.toList()

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

  Changing Collectors.toList() to an explicit ArrayList collection

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3612/files
  - new: https://git.openjdk.java.net/jdk/pull/3612/files/ba51d53a..ac354293

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

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

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

From prappo at openjdk.java.net  Thu Apr 22 09:38:24 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Thu, 22 Apr 2021 09:38:24 GMT
Subject: RFR: 8261168: Convert javadoc tool to use Stream.toList() [v2]
In-Reply-To: <2hsyHT6NX8Yv5X9X1niDZiBtjOJbY5gbZTzyRkiN0Yk=.9e9656ef-33b8-4ddb-adee-902012c69c2e@github.com>
References: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
 <2hsyHT6NX8Yv5X9X1niDZiBtjOJbY5gbZTzyRkiN0Yk=.9e9656ef-33b8-4ddb-adee-902012c69c2e@github.com>
Message-ID: <Gyn0zq_uZ1QhGF__APQBSPajlN5eLzRoDloQSknXpKk=.c1e372d7-0138-40ba-8dd5-10aee92ca553@github.com>

On Thu, 22 Apr 2021 04:19:50 GMT, Ian Graves <igraves at openjdk.org> wrote:

>> 8261168: Convert javadoc tool to use Stream.toList()
>
> Ian Graves has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Changing Collectors.toList() to an explicit ArrayList collection

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/VisibleMemberTable.java line 461:

> 459:                 .collect(Collectors.toList());
> 460: 
> 461:         // Prefix local results first

1. Could you incorporate this comment instead of deleting it?
2. Consider refactoring L502:L516 in a similar fashion, i.e. `a.addAll(0, b)` -> `Stream.concat(b, a)`.

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

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

From igraves at openjdk.java.net  Thu Apr 22 14:45:37 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Thu, 22 Apr 2021 14:45:37 GMT
Subject: RFR: 8263621: Convert jdk.compiler to use Stream.toList()
Message-ID: <Tuk9V_fzRD8idOrCGmhseD9QiEDMEgsqQfJxqB8oy_E=.896fab32-64ae-4f87-8f71-6faa5377e37b@github.com>

Converting use of `Collectors.toList()` to `Stream.toList()` where appropriate. Per [JDK-8260559](https://bugs.openjdk.java.net/browse/JDK-8260559).

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

Commit messages:
 - Converting to Stream.toList()

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

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

From mcimadamore at openjdk.java.net  Thu Apr 22 15:20:21 2021
From: mcimadamore at openjdk.java.net (Maurizio Cimadamore)
Date: Thu, 22 Apr 2021 15:20:21 GMT
Subject: RFR: 8263621: Convert jdk.compiler to use Stream.toList()
In-Reply-To: <Tuk9V_fzRD8idOrCGmhseD9QiEDMEgsqQfJxqB8oy_E=.896fab32-64ae-4f87-8f71-6faa5377e37b@github.com>
References: <Tuk9V_fzRD8idOrCGmhseD9QiEDMEgsqQfJxqB8oy_E=.896fab32-64ae-4f87-8f71-6faa5377e37b@github.com>
Message-ID: <b9ZGU8OGVGb9zsDNDWnFFBgoI9AnEvDMNUKUNruq6W8=.dd2cd666-660d-4b95-909c-c9fdde4c5171@github.com>

On Thu, 22 Apr 2021 14:35:29 GMT, Ian Graves <igraves at openjdk.org> wrote:

> Converting use of `Collectors.toList()` to `Stream.toList()` where appropriate. Per [JDK-8260559](https://bugs.openjdk.java.net/browse/JDK-8260559).

Looks good!

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

Marked as reviewed by mcimadamore (Reviewer).

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

From vromero at openjdk.java.net  Thu Apr 22 15:32:22 2021
From: vromero at openjdk.java.net (Vicente Romero)
Date: Thu, 22 Apr 2021 15:32:22 GMT
Subject: RFR: 8263621: Convert jdk.compiler to use Stream.toList()
In-Reply-To: <Tuk9V_fzRD8idOrCGmhseD9QiEDMEgsqQfJxqB8oy_E=.896fab32-64ae-4f87-8f71-6faa5377e37b@github.com>
References: <Tuk9V_fzRD8idOrCGmhseD9QiEDMEgsqQfJxqB8oy_E=.896fab32-64ae-4f87-8f71-6faa5377e37b@github.com>
Message-ID: <av_8Rj1VHDuoQVHReWtAUnXbWzRar1KroCOzxXMfdjo=.934d47bb-9a3a-45e8-82fc-495f5c3d8430@github.com>

On Thu, 22 Apr 2021 14:35:29 GMT, Ian Graves <igraves at openjdk.org> wrote:

> Converting use of `Collectors.toList()` to `Stream.toList()` where appropriate. Per [JDK-8260559](https://bugs.openjdk.java.net/browse/JDK-8260559).

looks good

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

Marked as reviewed by vromero (Reviewer).

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

From igraves at openjdk.java.net  Thu Apr 22 15:37:25 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Thu, 22 Apr 2021 15:37:25 GMT
Subject: RFR: 8263621: Convert jdk.compiler to use Stream.toList()
In-Reply-To: <Tuk9V_fzRD8idOrCGmhseD9QiEDMEgsqQfJxqB8oy_E=.896fab32-64ae-4f87-8f71-6faa5377e37b@github.com>
References: <Tuk9V_fzRD8idOrCGmhseD9QiEDMEgsqQfJxqB8oy_E=.896fab32-64ae-4f87-8f71-6faa5377e37b@github.com>
Message-ID: <polzWUYsfUQR1xmY9ummZ6wqARSWZMO7ZeYZf85k_tE=.4721a29e-fa3c-420f-9521-19c46c8b3656@github.com>

On Thu, 22 Apr 2021 14:35:29 GMT, Ian Graves <igraves at openjdk.org> wrote:

> Converting use of `Collectors.toList()` to `Stream.toList()` where appropriate. Per [JDK-8260559](https://bugs.openjdk.java.net/browse/JDK-8260559).

Thanks, all. Not a major change, ran tests last night and it was passing so given two reviewers I'll go ahead and integrate. This one will require a sponsor as I'm not a committer yet. If you want to wait for additional eyes on, that is fine by me too.

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

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

From igraves at openjdk.java.net  Thu Apr 22 16:10:31 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Thu, 22 Apr 2021 16:10:31 GMT
Subject: Integrated: 8263621: Convert jdk.compiler to use Stream.toList()
In-Reply-To: <Tuk9V_fzRD8idOrCGmhseD9QiEDMEgsqQfJxqB8oy_E=.896fab32-64ae-4f87-8f71-6faa5377e37b@github.com>
References: <Tuk9V_fzRD8idOrCGmhseD9QiEDMEgsqQfJxqB8oy_E=.896fab32-64ae-4f87-8f71-6faa5377e37b@github.com>
Message-ID: <-7yNaPlAlV2lSaGyXS65qPOo2eCo39O1RYKTksjqIUc=.33aa4310-ba5b-428e-b01d-fd8190d915ff@github.com>

On Thu, 22 Apr 2021 14:35:29 GMT, Ian Graves <igraves at openjdk.org> wrote:

> Converting use of `Collectors.toList()` to `Stream.toList()` where appropriate. Per [JDK-8260559](https://bugs.openjdk.java.net/browse/JDK-8260559).

This pull request has now been integrated.

Changeset: 33a86b9e
Author:    Ian Graves <igraves at openjdk.org>
Committer: Maurizio Cimadamore <mcimadamore at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/33a86b9e
Stats:     13 lines in 9 files changed: 0 ins; 0 del; 13 mod

8263621: Convert jdk.compiler to use Stream.toList()

Reviewed-by: mcimadamore, vromero

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

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

From igraves at openjdk.java.net  Thu Apr 22 17:06:40 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Thu, 22 Apr 2021 17:06:40 GMT
Subject: RFR: 8261168: Convert javadoc tool to use Stream.toList() [v3]
In-Reply-To: <Gyn0zq_uZ1QhGF__APQBSPajlN5eLzRoDloQSknXpKk=.c1e372d7-0138-40ba-8dd5-10aee92ca553@github.com>
References: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
 <2hsyHT6NX8Yv5X9X1niDZiBtjOJbY5gbZTzyRkiN0Yk=.9e9656ef-33b8-4ddb-adee-902012c69c2e@github.com>
 <Gyn0zq_uZ1QhGF__APQBSPajlN5eLzRoDloQSknXpKk=.c1e372d7-0138-40ba-8dd5-10aee92ca553@github.com>
Message-ID: <rQnoivjRp5Z8xe4mLufkybY8HID2sYvA-VIuJ2mN65I=.ca83a354-5184-4e0a-a42a-25c0546c4093@github.com>

On Thu, 22 Apr 2021 09:16:40 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Ian Graves has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Tweaking some comments and list/stream concatenation
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/VisibleMemberTable.java line 461:
> 
>> 459:                 .collect(Collectors.toList());
>> 460: 
>> 461:         // Prefix local results first
> 
> 1. Could you incorporate this comment instead of deleting it?
> 2. Consider refactoring L502:L516 in a similar fashion, i.e. `a.addAll(0, b)` -> `Stream.concat(b, a)`.

Done!

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

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

From igraves at openjdk.java.net  Thu Apr 22 17:06:39 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Thu, 22 Apr 2021 17:06:39 GMT
Subject: RFR: 8261168: Convert javadoc tool to use Stream.toList() [v3]
In-Reply-To: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
References: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
Message-ID: <H03kzJS7jVKksl_pT6WoW1mqNrlkUhfuK30zYa2w9to=.360d4359-8842-461e-85bb-bc496ff5b34f@github.com>

> 8261168: Convert javadoc tool to use Stream.toList()

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

  Tweaking some comments and list/stream concatenation

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3612/files
  - new: https://git.openjdk.java.net/jdk/pull/3612/files/ac354293..0c2cf58a

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

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

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

From jjg at openjdk.java.net  Thu Apr 22 21:26:28 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 22 Apr 2021 21:26:28 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in
 Java, javadoc changes
In-Reply-To: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
References: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
Message-ID: <9GHTt38e9diE7yvGkZcczQsXcDAX2JBk0SMwnp4medk=.0d5914a7-880d-41e3-a862-b587dd5e2089@github.com>

On Thu, 22 Apr 2021 02:21:14 GMT, Vicente Romero <vromero at openjdk.org> wrote:

> Please review the javadoc related changes to make sealed classes a final feature in Java. The patch is mostly removing preview features related code that is not necessary anymore in javadoc.
> 
> TIA

Generally, I think you have have deleted too much.

Although the code will work as you propose, at some point there will be new preview language features, and I think it would be better to leave a skeleton of the code in place, even if the set of preview language features is empty for now.

I think it would be better to limit the deletions to those lines of code that are specific to sealed classes and permits.

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

> 85:     private static final Set<String> previewModifiers
> 86:             = Set.of("sealed", "non-sealed");
> 87: 

Rather than delete those lines, for future support it might be better just to set previewModifiers to `Collections.emptySet()`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java line 193:

> 191:             }
> 192: 
> 193:             mods.add(modifiersPart);

See previous comment, to leave previewModifiers in place as an empty set

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

> 2240:         Set<TypeElement> reflectivePreviewAPI = new HashSet<>(previewAPITypes.reflectivePreviewAPI);
> 2241:         Set<TypeElement> declaredUsingPreviewFeature = new HashSet<>(previewAPITypes.declaredUsingPreviewFeature);
> 2242:         Set<DeclarationPreviewLanguageFeatures> previewLanguageFeatures = new HashSet<>();

consider not deleting this; just leave it empty

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

> 2259:             if (previewLanguageFeatures.contains(DeclarationPreviewLanguageFeatures.SEALED_PERMITS)) {
> 2260:                 previewLanguageFeatures.remove(DeclarationPreviewLanguageFeatures.SEALED);
> 2261:             }

These lines should go, because they specifically refer to SEALED stuff, but the rest of the block could stay

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

> 2293:                                    featureCodes);
> 2294:     }
> 2295: 

Nothing here seems specific to SEALED, so leave it

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

> 189:                                 classWriter.links.createLink(classWriter.htmlIds.forPreviewSection(typeElement),
> 190:                                                              classWriter.contents.previewMark);
> 191:                         permitsSpan.add(HtmlTree.SUP(link));

OK, yes, this is specific to permits, part of the sealed feature

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

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

From vromero at openjdk.java.net  Thu Apr 22 21:33:55 2021
From: vromero at openjdk.java.net (Vicente Romero)
Date: Thu, 22 Apr 2021 21:33:55 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in
 Java, javadoc changes [v2]
In-Reply-To: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
References: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
Message-ID: <cHxbmNC1Jkzi6MQlFOa_9CgPwXdNicSw9NByjEmr6Us=.34d2f0c9-20ea-4fb4-87dd-85c62f4a332f@github.com>

> Please review the javadoc related changes to make sealed classes a final feature in Java. The patch is mostly removing preview features related code that is not necessary anymore in javadoc.
> 
> TIA

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

 - Merge branch 'master' into JDK-8265684
 - 8265684: implement Sealed Classes as a standard feature in Java, javadoc changes

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3613/files
  - new: https://git.openjdk.java.net/jdk/pull/3613/files/2b7cee9e..7d0ba41c

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

  Stats: 38611 lines in 1297 files changed: 7670 ins; 26934 del; 4007 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3613.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3613/head:pull/3613

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

From vromero at openjdk.java.net  Fri Apr 23 02:57:50 2021
From: vromero at openjdk.java.net (Vicente Romero)
Date: Fri, 23 Apr 2021 02:57:50 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in
 Java, javadoc changes [v3]
In-Reply-To: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
References: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
Message-ID: <KaOXzL_ZhkxgN_MkizYtXiEnqMPBMZblVLnwa2Fygtw=.387e6ac0-f7cc-47e7-b857-147db6cf9a04@github.com>

> Please review the javadoc related changes to make sealed classes a final feature in Java. The patch is mostly removing preview features related code that is not necessary anymore in javadoc.
> 
> TIA

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

  addressing review comments

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3613/files
  - new: https://git.openjdk.java.net/jdk/pull/3613/files/7d0ba41c..dc1bd3fb

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

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

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

From vromero at openjdk.java.net  Fri Apr 23 03:20:58 2021
From: vromero at openjdk.java.net (Vicente Romero)
Date: Fri, 23 Apr 2021 03:20:58 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in
 Java, javadoc changes [v4]
In-Reply-To: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
References: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
Message-ID: <OOCpisQw2nIdV4QzqB03XFN5VM3SrKCdYKjt9T9ngnA=.e94aa427-c80f-4f6d-a9b6-e608e5d2989b@github.com>

> Please review the javadoc related changes to make sealed classes a final feature in Java. The patch is mostly removing preview features related code that is not necessary anymore in javadoc.
> 
> TIA

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

 - Merge branch 'master' into JDK-8265684
 - additional commit addressing review comments
 - addressing review comments
 - Merge branch 'master' into JDK-8265684
 - 8265684: implement Sealed Classes as a standard feature in Java, javadoc changes

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3613/files
  - new: https://git.openjdk.java.net/jdk/pull/3613/files/dc1bd3fb..5a139f57

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

  Stats: 2219 lines in 103 files changed: 1082 ins; 544 del; 593 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3613.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3613/head:pull/3613

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

From vromero at openjdk.java.net  Fri Apr 23 03:28:09 2021
From: vromero at openjdk.java.net (Vicente Romero)
Date: Fri, 23 Apr 2021 03:28:09 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in
 Java, javadoc changes [v5]
In-Reply-To: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
References: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
Message-ID: <eivIWe4Pv5zmnbyC_Y2v1jfJtxLR258FdHDkcOsBCDs=.6e9059cf-25fc-448e-a602-1176bb248f3e@github.com>

> Please review the javadoc related changes to make sealed classes a final feature in Java. The patch is mostly removing preview features related code that is not necessary anymore in javadoc.
> 
> TIA

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

  addressing indentation issues

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3613/files
  - new: https://git.openjdk.java.net/jdk/pull/3613/files/5a139f57..846d34b5

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

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

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

From hannesw at openjdk.java.net  Fri Apr 23 13:30:33 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 23 Apr 2021 13:30:33 GMT
Subject: RFR: JDK-8265613: False positives for "Related Packages"
Message-ID: <spRE3LBita-wFTnlpD5_CRp6SyChR-Uv7Cmftx-TEpQ=.579281f8-3cdf-4085-8111-166772aeca89@github.com>

The suggested simple fix to only include sibling packages if there is a common non-empty super package seems to work quite well. I have compiled a list to show the change in related packages listings generated for the JDK documentation (old output on the left, new output on the right).

https://gist.github.com/hns/d0f946255a69027405836201b047965d/revisions?diff=split

I updated the test to include an unlisted sibling package.

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

Commit messages:
 - JDK-8265613: False positives for "Related Packages"

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

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

From igraves at openjdk.java.net  Sat Apr 24 01:17:51 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Sat, 24 Apr 2021 01:17:51 GMT
Subject: RFR: 8261168: Convert javadoc tool to use Stream.toList() [v4]
In-Reply-To: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
References: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
Message-ID: <u5H6hMEKQKcS4QMd2lrL2ALthsyOREcYSCESITYrYjc=.1cecb151-2313-4731-a60b-64acc524b769@github.com>

> 8261168: Convert javadoc tool to use Stream.toList()

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

  Replacing one additional Collections.toList() with an explicit toCollection() call

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3612/files
  - new: https://git.openjdk.java.net/jdk/pull/3612/files/0c2cf58a..978f35da

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

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

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

From jjg at openjdk.java.net  Sat Apr 24 03:53:26 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Sat, 24 Apr 2021 03:53:26 GMT
Subject: RFR: JDK-8265613: False positives for "Related Packages"
In-Reply-To: <spRE3LBita-wFTnlpD5_CRp6SyChR-Uv7Cmftx-TEpQ=.579281f8-3cdf-4085-8111-166772aeca89@github.com>
References: <spRE3LBita-wFTnlpD5_CRp6SyChR-Uv7Cmftx-TEpQ=.579281f8-3cdf-4085-8111-166772aeca89@github.com>
Message-ID: <ByV7SsTLUgk-bHB1wUi8JGCzv3drMHytQw0n-6Nf5yk=.460b28f4-a0cb-4db3-a2ba-a055cc8e8e30@github.com>

On Fri, 23 Apr 2021 13:25:08 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> The suggested simple fix to only include sibling packages if there is a common non-empty super package seems to work quite well. I have compiled a list to show the change in related packages listings generated for the JDK documentation (old output on the left, new output on the right).
> 
> https://gist.github.com/hns/d0f946255a69027405836201b047965d/revisions?diff=split
> 
> I updated the test to include an unlisted sibling package.

I note that `com.sun.source.*` now falls off the list :-( but that's probably better than what we had before.

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

Marked as reviewed by jjg (Reviewer).

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

From hannesw at openjdk.java.net  Mon Apr 26 07:56:30 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 26 Apr 2021 07:56:30 GMT
Subject: Integrated: JDK-8265613: False positives for "Related Packages"
In-Reply-To: <spRE3LBita-wFTnlpD5_CRp6SyChR-Uv7Cmftx-TEpQ=.579281f8-3cdf-4085-8111-166772aeca89@github.com>
References: <spRE3LBita-wFTnlpD5_CRp6SyChR-Uv7Cmftx-TEpQ=.579281f8-3cdf-4085-8111-166772aeca89@github.com>
Message-ID: <773cZi8t96ZNizypeYm0ta1VygrkwSJrpfMIPkylUqg=.cbf351f2-9802-4bb8-ad68-9641fdf86b7f@github.com>

On Fri, 23 Apr 2021 13:25:08 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> The suggested simple fix to only include sibling packages if there is a common non-empty super package seems to work quite well. I have compiled a list to show the change in related packages listings generated for the JDK documentation (old output on the left, new output on the right).
> 
> https://gist.github.com/hns/d0f946255a69027405836201b047965d/revisions?diff=split
> 
> I updated the test to include an unlisted sibling package.

This pull request has now been integrated.

Changeset: a85f6cbb
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/a85f6cbb
Stats:     38 lines in 2 files changed: 4 ins; 0 del; 34 mod

8265613: False positives for "Related Packages"

Reviewed-by: jjg

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

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

From prappo at openjdk.java.net  Mon Apr 26 08:57:36 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Mon, 26 Apr 2021 08:57:36 GMT
Subject: RFR: 8261168: Convert javadoc tool to use Stream.toList() [v4]
In-Reply-To: <u5H6hMEKQKcS4QMd2lrL2ALthsyOREcYSCESITYrYjc=.1cecb151-2313-4731-a60b-64acc524b769@github.com>
References: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
 <u5H6hMEKQKcS4QMd2lrL2ALthsyOREcYSCESITYrYjc=.1cecb151-2313-4731-a60b-64acc524b769@github.com>
Message-ID: <PA7iys_0IAF7KZLg3C9WTn2c9h7um0uPp0CSYr171b0=.08a84c1c-0072-4f8a-bc1b-6fe68128baf0@github.com>

On Sat, 24 Apr 2021 01:17:51 GMT, Ian Graves <igraves at openjdk.org> wrote:

>> 8261168: Convert javadoc tool to use Stream.toList()
>
> Ian Graves has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Replacing one additional Collections.toList() with an explicit toCollection() call

Marked as reviewed by prappo (Reviewer).

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

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

From igraves at openjdk.java.net  Mon Apr 26 15:23:34 2021
From: igraves at openjdk.java.net (Ian Graves)
Date: Mon, 26 Apr 2021 15:23:34 GMT
Subject: Integrated: 8261168: Convert javadoc tool to use Stream.toList()
In-Reply-To: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
References: <gWyVuPCl0DBZGVn6MUGihHmYPK3-gIbinqhPl0yetaw=.b4629c3b-7bdc-4974-8d81-8d5f81834f64@github.com>
Message-ID: <LVAbmfRTaPUTityAHY9hDu88l_XAlOW2GoPFD64LKfY=.7accfc64-f470-408d-8f57-c2fc2705e247@github.com>

On Thu, 22 Apr 2021 02:11:35 GMT, Ian Graves <igraves at openjdk.org> wrote:

> 8261168: Convert javadoc tool to use Stream.toList()

This pull request has now been integrated.

Changeset: fb8f0c5d
Author:    Ian Graves <igraves at openjdk.org>
Committer: Pavel Rappo <prappo at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/fb8f0c5d
Stats:     63 lines in 10 files changed: 10 ins; 12 del; 41 mod

8261168: Convert javadoc tool to use Stream.toList()

Reviewed-by: prappo

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

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

From hannesw at openjdk.java.net  Tue Apr 27 09:53:00 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 27 Apr 2021 09:53:00 GMT
Subject: RFR: JDK-8258602: JavaDoc field summary does not indicate final
 modifier
Message-ID: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>

I found that adding the `final` modifier does not add too much visual noise to the documentation. I didn't find any occurrence where there were more than two modifiers on a member summary (usually either `static final` or `protected final`). 

On the other hand, I do think the `final` modifier adds important information about the member. Although this is more true for fields than for other members, for reasons of consistency I decided to show it for all kinds of members except for those where it is defined implicitly (such as enums).

To my surprise I also noticed that there weren't any test cases for field summaries, so I added a new test.

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

Commit messages:
 - JDK-8258602: JavaDoc field summary does not indicate final modifier

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

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

From hannesw at openjdk.java.net  Tue Apr 27 10:29:05 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 27 Apr 2021 10:29:05 GMT
Subject: RFR: JDK-8258602: JavaDoc field summary does not indicate final
 modifier [v2]
In-Reply-To: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
References: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
Message-ID: <3uRQTDZ9FVmSKZGl0WSY5bkXHn8lEVga1UsRJ4sJTmM=.5c3498e7-67fc-4bfd-8a25-c83f7b5c114a@github.com>

> I found that adding the `final` modifier does not add too much visual noise to the documentation. I didn't find any occurrence where there were more than two modifiers on a member summary (usually either `static final` or `protected final`). 
> 
> On the other hand, I do think the `final` modifier adds important information about the member. Although this is more true for fields than for other members, for reasons of consistency I decided to show it for all kinds of members except for those where it is not allowed (such as for enums).
> 
> To my surprise I also noticed that there weren't any test cases for field summaries, so I added a new test.

Hannes Walln?fer 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:

  JDK-8258602: JavaDoc field summary does not indicate final modifier

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3716/files
  - new: https://git.openjdk.java.net/jdk/pull/3716/files/074b7326..a6a9d202

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

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

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

From dfuchs at openjdk.java.net  Tue Apr 27 13:08:37 2021
From: dfuchs at openjdk.java.net (Daniel Fuchs)
Date: Tue, 27 Apr 2021 13:08:37 GMT
Subject: RFR: JDK-8258602: JavaDoc field summary does not indicate final
 modifier [v2]
In-Reply-To: <3uRQTDZ9FVmSKZGl0WSY5bkXHn8lEVga1UsRJ4sJTmM=.5c3498e7-67fc-4bfd-8a25-c83f7b5c114a@github.com>
References: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
 <3uRQTDZ9FVmSKZGl0WSY5bkXHn8lEVga1UsRJ4sJTmM=.5c3498e7-67fc-4bfd-8a25-c83f7b5c114a@github.com>
Message-ID: <9feFIYleVAoJYzqt5LUUvfkJwn7drQsB8wfiAbRT6X4=.ef4e1d20-6ef5-481c-b285-216380c5c256@github.com>

On Tue, 27 Apr 2021 10:29:05 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> I found that adding the `final` modifier does not add too much visual noise to the documentation. I didn't find any occurrence where there were more than two modifiers on a member summary (usually either `static final` or `protected final`). 
>> 
>> On the other hand, I do think the `final` modifier adds important information about the member. Although this is more true for fields than for other members, for reasons of consistency I decided to show it for all kinds of members except for those where it is not allowed (such as for enums).
>> 
>> To my surprise I also noticed that there weren't any test cases for field summaries, so I added a new test.
>
> Hannes Walln?fer 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:
> 
>   JDK-8258602: JavaDoc field summary does not indicate final modifier

Hi Hannes, out of curiosity - for a final class, will all members (or none) appear final in the generated documentation? Or will it depend on whether a redundant `final` keyword appears in the code or not? From your code changes, I guess it will be the latter - which makes me wonder whether we want to go that far in the API documentation.

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

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

From hannesw at openjdk.java.net  Tue Apr 27 19:02:34 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 27 Apr 2021 19:02:34 GMT
Subject: RFR: JDK-8258602: JavaDoc field summary does not indicate final
 modifier [v2]
In-Reply-To: <9feFIYleVAoJYzqt5LUUvfkJwn7drQsB8wfiAbRT6X4=.ef4e1d20-6ef5-481c-b285-216380c5c256@github.com>
References: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
 <3uRQTDZ9FVmSKZGl0WSY5bkXHn8lEVga1UsRJ4sJTmM=.5c3498e7-67fc-4bfd-8a25-c83f7b5c114a@github.com>
 <9feFIYleVAoJYzqt5LUUvfkJwn7drQsB8wfiAbRT6X4=.ef4e1d20-6ef5-481c-b285-216380c5c256@github.com>
Message-ID: <T3IOSX75Vcp_vt-oBB-4BO8pfjVNM6g0Z4X0vNccIoA=.215fa21a-38f6-430d-9162-57c5d5ed998e@github.com>

On Tue, 27 Apr 2021 13:05:54 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

> Hi Hannes, out of curiosity - for a final class, will all members (or none) appear final in the generated documentation? Or will it depend on whether a redundant `final` keyword appears in the code or not? From your code changes, I guess it will be the latter - which makes me wonder whether we want to go that far in the API documentation. Maybe `final` should be omitted for members of a final class.

Yes, `final` will appear as it is used in the source code for method summaries of final classes. In my mind this is acceptable, analogous to both ways being allowed in the source code.

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

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

From hannesw at openjdk.java.net  Wed Apr 28 07:55:06 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 28 Apr 2021 07:55:06 GMT
Subject: RFR: JDK-8250766: javadoc adds redundant spaces when @see program
 element is wrapped
Message-ID: <7wye6atnCwJUKEfWuXSLLTEmGbDNn6XAFCgNyjvLViQ=.6e136191-2a46-4168-b1c4-a88f4687fb7a@github.com>

This changes reference parsing in `DocCommentParser` to normalize whitespace in signatures to a large extent. In particular, multiple whitespace characters are coalesced into a single space character, and whitespace after opening parentheses and angle brackets are suppressed.

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

Commit messages:
 - JDK-8250766: javadoc adds redundant spaces when @see program element is wrapped

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

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

From prappo at openjdk.java.net  Wed Apr 28 10:18:53 2021
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 28 Apr 2021 10:18:53 GMT
Subject: RFR: JDK-8250766: javadoc adds redundant spaces when @see program
 element is wrapped
In-Reply-To: <7wye6atnCwJUKEfWuXSLLTEmGbDNn6XAFCgNyjvLViQ=.6e136191-2a46-4168-b1c4-a88f4687fb7a@github.com>
References: <7wye6atnCwJUKEfWuXSLLTEmGbDNn6XAFCgNyjvLViQ=.6e136191-2a46-4168-b1c4-a88f4687fb7a@github.com>
Message-ID: <tZ4VN9BbC_KglzqodXyT1tpI-GyNGUrjao8sMAcyr7w=.557b9dc8-ce62-49a8-b948-7405b82f5a31@github.com>

On Wed, 28 Apr 2021 07:47:23 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This changes reference parsing in `DocCommentParser` to normalize whitespace in signatures to a large extent. In particular, multiple whitespace characters are coalesced into a single space character, and whitespace after opening parentheses and angle brackets are suppressed.

I have marked [8252039](https://bugs.openjdk.java.net/browse/JDK-8252039) as a duplicate of this bug. The fix looks nice and clean. That said, I wonder if it introduces any harmful discrepancies between the signature string and the start and end positions of DCReference.

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

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

From mark.reinhold at oracle.com  Wed Apr 28 21:40:31 2021
From: mark.reinhold at oracle.com (mark.reinhold at oracle.com)
Date: Wed, 28 Apr 2021 14:40:31 -0700 (PDT)
Subject: New candidate JEP: 413: Code Snippets in Java API Documentation
Message-ID: <20210428214031.EE8113E1E4E@eggemoggin.niobe.net>

https://openjdk.java.net/jeps/413

  Summary: Introduce an @snippet tag for JavaDoc's Standard Doclet, to
  simplify the inclusion of example source code in API documentation.

- Mark

From hannesw at openjdk.java.net  Thu Apr 29 08:07:05 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 29 Apr 2021 08:07:05 GMT
Subject: RFR: JDK-8249903:
 jdk/javadoc/doclet/testSerializedForm/TestSerializedForm.java needs to be
 updated after 8146022 got closed
Message-ID: <y2kfMpXbzxtzatpfNooSuBAb0_2Y176zLQEn79lqfFY=.4fdd06fc-9533-4c3a-8728-21cc58de45fe@github.com>

I don't know why this test was disabled because of JDK-8146022, in fact I wasn't able to understand what JDK-8146022 was all about as I didn't find a commit for it. However, the test runs fine when updated to the current output format, so I guess whatever bug caused it to fail has been fixed in the meantime. I also removed some vestiges of an old test framework nearby that has been commented out from time immemorial.

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

Commit messages:
 - JDK-8249903: jdk/javadoc/doclet/testSerializedForm/TestSerializedForm.java needs to be updated after 8146022 got closed

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

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

From jjg at openjdk.java.net  Fri Apr 30 02:53:52 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 30 Apr 2021 02:53:52 GMT
Subject: RFR: JDK-8249903:
 jdk/javadoc/doclet/testSerializedForm/TestSerializedForm.java needs to be
 updated after 8146022 got closed
In-Reply-To: <y2kfMpXbzxtzatpfNooSuBAb0_2Y176zLQEn79lqfFY=.4fdd06fc-9533-4c3a-8728-21cc58de45fe@github.com>
References: <y2kfMpXbzxtzatpfNooSuBAb0_2Y176zLQEn79lqfFY=.4fdd06fc-9533-4c3a-8728-21cc58de45fe@github.com>
Message-ID: <K0rVmCYU63V540brpuvlqP0EWmoAU_zPC2MLeQNFwDo=.8b522591-82b5-445f-8bdb-980bcefc4bcf@github.com>

On Thu, 29 Apr 2021 08:00:18 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> I don't know why this test was disabled because of JDK-8146022, in fact I wasn't able to understand what JDK-8146022 was all about as I didn't find a commit for it. However, the test runs fine when updated to the current output format, so I guess whatever bug caused it to fail has been fixed in the meantime. I also removed some vestiges of an old test framework nearby that has been commented out from time immemorial.

FWIW, the way I see the history here ... a bug was filed because of a resource issue, and this test was disabled because of the bug. Using `@ignore` was a precursor/alternate to using the problem list file.
Separately, refactoring and cleanup fixed the resource issue, using separate independent cleanup RFEs.  So, JDK-8146022 was closed (without needing a changeset), and without removing the `@ignore` here.

Lines 49-51 are a reminder of life before `JavadocTester`.

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

Marked as reviewed by jjg (Reviewer).

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

From jjg at openjdk.java.net  Fri Apr 30 03:15:57 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 30 Apr 2021 03:15:57 GMT
Subject: RFR: JDK-8250766: javadoc adds redundant spaces when @see program
 element is wrapped
In-Reply-To: <7wye6atnCwJUKEfWuXSLLTEmGbDNn6XAFCgNyjvLViQ=.6e136191-2a46-4168-b1c4-a88f4687fb7a@github.com>
References: <7wye6atnCwJUKEfWuXSLLTEmGbDNn6XAFCgNyjvLViQ=.6e136191-2a46-4168-b1c4-a88f4687fb7a@github.com>
Message-ID: <im2VZvZ2g8Fm8sZ-sorhOuEuo8_bPm7ifE99PDpauL0=.d61a141b-d727-4ba9-9bfd-dc79791ded3d@github.com>

On Wed, 28 Apr 2021 07:47:23 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This changes reference parsing in `DocCommentParser` to normalize whitespace in signatures to a large extent. In particular, multiple whitespace characters are coalesced into a single space character, and whitespace after opening parentheses and angle brackets are suppressed.

This is against the general philosophy of `DocCommentParser`, which is to try and retain input formatting as much as possible. 

It would be better to normalize the whitespace downstream (i.e. in javadoc HTML world) when creating output based on the signature.

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

Changes requested by jjg (Reviewer).

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

From jjg at openjdk.java.net  Fri Apr 30 03:27:51 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 30 Apr 2021 03:27:51 GMT
Subject: RFR: JDK-8258602: JavaDoc field summary does not indicate final
 modifier [v2]
In-Reply-To: <T3IOSX75Vcp_vt-oBB-4BO8pfjVNM6g0Z4X0vNccIoA=.215fa21a-38f6-430d-9162-57c5d5ed998e@github.com>
References: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
 <3uRQTDZ9FVmSKZGl0WSY5bkXHn8lEVga1UsRJ4sJTmM=.5c3498e7-67fc-4bfd-8a25-c83f7b5c114a@github.com>
 <9feFIYleVAoJYzqt5LUUvfkJwn7drQsB8wfiAbRT6X4=.ef4e1d20-6ef5-481c-b285-216380c5c256@github.com>
 <T3IOSX75Vcp_vt-oBB-4BO8pfjVNM6g0Z4X0vNccIoA=.215fa21a-38f6-430d-9162-57c5d5ed998e@github.com>
Message-ID: <yQMJSY0u11hleQ-0LHJTWrZMWuThFh3hEGF8J6eU4wU=.92e2d3e0-503d-4932-8658-7299896e266c@github.com>

On Tue, 27 Apr 2021 19:00:10 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> > Hi Hannes, out of curiosity - for a final class, will all members (or none) appear final in the generated documentation? Or will it depend on whether a redundant `final` keyword appears in the code or not? From your code changes, I guess it will be the latter - which makes me wonder whether we want to go that far in the API documentation. Maybe `final` should be omitted for members of a final class.
> 
> Yes, `final` will appear as it is used in the source code for method summaries of final classes. In my mind this is acceptable, analogous to both ways being allowed in the source code.

This seems surprising and maybe questionable, since in other places, javadoc tries to present a normalized view of modifiers. But, I agree it is in line with existing behavior, and this issue is not about changing that behavior at this time.

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

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

From jjg at openjdk.java.net  Fri Apr 30 03:30:50 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 30 Apr 2021 03:30:50 GMT
Subject: RFR: JDK-8258602: JavaDoc field summary does not indicate final
 modifier [v2]
In-Reply-To: <3uRQTDZ9FVmSKZGl0WSY5bkXHn8lEVga1UsRJ4sJTmM=.5c3498e7-67fc-4bfd-8a25-c83f7b5c114a@github.com>
References: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
 <3uRQTDZ9FVmSKZGl0WSY5bkXHn8lEVga1UsRJ4sJTmM=.5c3498e7-67fc-4bfd-8a25-c83f7b5c114a@github.com>
Message-ID: <I7n0YNXDOTJAX0PiNvrLDRbVx_AxkDdWBAThJsp-yBk=.64e9dd23-9062-4b8b-85de-b036fce4237c@github.com>

On Tue, 27 Apr 2021 10:29:05 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> I found that adding the `final` modifier does not add too much visual noise to the documentation. I didn't find any occurrence where there were more than two modifiers on a member summary (usually either `static final` or `protected final`). 
>> 
>> On the other hand, I do think the `final` modifier adds important information about the member. Although this is more true for fields than for other members, for reasons of consistency I decided to show it for all kinds of members except for those where it is not allowed (such as for enums).
>> 
>> To my surprise I also noticed that there weren't any test cases for field summaries, so I added a new test.
>
> Hannes Walln?fer 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:
> 
>   JDK-8258602: JavaDoc field summary does not indicate final modifier

OK, but we might want to think about the pros and cons of normalizing modifiers.

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

Marked as reviewed by jjg (Reviewer).

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

From jjg at openjdk.java.net  Fri Apr 30 03:37:51 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 30 Apr 2021 03:37:51 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in
 Java, javadoc changes [v5]
In-Reply-To: <eivIWe4Pv5zmnbyC_Y2v1jfJtxLR258FdHDkcOsBCDs=.6e9059cf-25fc-448e-a602-1176bb248f3e@github.com>
References: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
 <eivIWe4Pv5zmnbyC_Y2v1jfJtxLR258FdHDkcOsBCDs=.6e9059cf-25fc-448e-a602-1176bb248f3e@github.com>
Message-ID: <TklFYaBmYDyKD7UwR4XZ0CwhXDgeu4QAFP6666Er89k=.32d3b45b-887d-44ce-9bcc-3a164a5a0ae1@github.com>

On Fri, 23 Apr 2021 03:28:09 GMT, Vicente Romero <vromero at openjdk.org> wrote:

>> Please review the javadoc related changes to make sealed classes a final feature in Java. The patch is mostly removing preview features related code that is not necessary anymore in javadoc.
>> 
>> TIA
>
> Vicente Romero has updated the pull request incrementally with one additional commit since the last revision:
> 
>   addressing indentation issues

Depending who goes first, there may be a merge conflict with removing some of
the `@SuppressWarnings` annotations.

test/langtools/jdk/javadoc/doclet/testSealedTypes/TestSealedTypes.java line 251:

> 249:                 "package p; public final  class B extends A { }",
> 250:                 "package p; public final  class C extends A { }",
> 251:                 "package p; sealed class D extends A permits D1, D2 { }",

(minor)   don't delete the spaces; the class names were previously vertically aligned

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

Marked as reviewed by jjg (Reviewer).

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

From jjg at openjdk.java.net  Fri Apr 30 04:33:58 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 30 Apr 2021 04:33:58 GMT
Subject: RFR: JDK-8263507: Improve structure of package summary pages [v3]
In-Reply-To: <6XZXNSLtyLhCJ89InQlEzfSqDQGKynahstvpRZGuFbw=.915f8819-9b25-4635-b9c9-c108fa2e997c@github.com>
References: <qXeYGPpy9OsGVJ8RGQ9g00tz3n321DwW_3Tw8iwpIZI=.2f914b8a-13c2-4ae0-9505-68a0f2e50c5a@github.com>
 <6XZXNSLtyLhCJ89InQlEzfSqDQGKynahstvpRZGuFbw=.915f8819-9b25-4635-b9c9-c108fa2e997c@github.com>
Message-ID: <gFOO7zD08BsNznqA-evLvzIRUDaTGDFKx8HXSVMIKeA=.518cb1a7-c0bc-4a32-a776-84fd6eb09744@github.com>

On Mon, 19 Apr 2021 09:45:27 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This adds a feature to add sub-navigation links to the package summary page, but ended up more like a refactoring of the code to generate sub-navigation links. The reason for this is that generation of these links was highly idiosyncratic. Every writer class that wanted to create sub-nav links deposited something of itself in the `Navigation` instance which was then responsible for generating these links. The new code introduces a `Navigation.SubNavLinks` interface that allows writers to provide a list of links into their page content.
>> 
>> As for the new feature in the package summary page itself, I chose an approach that is a bit different from the one we use for other types of pages. Instead of displaying the inactive label instead of the link when a section is not present on the page, only the active links are displayed. The reason for this is that the package summary page contains so many potential summary tables that the sub-nav area gets quite crowded if they are all shown. Just showing the actually present pieces looked better to me.
>> 
>> Like in other sub-nav sections, the link labels sometimes use abbreviated terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of "ENUM CLASSES". The full list of potential package sub-nav links is as follows:
>> 
>>     Package: Description | Related | Interfaces | Classes | Enums | Records | Exceptions | Errors | Annotations
>> 
>> An important implementation note is that I moved the code to compute package summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The reason for this is that the contents are required to determine which links to create, and I didn't want to re-compute this information that was previously computed on the fly in the builder class. The various summary items are now stored in collection fields in the writer class. 
>> 
>> I have tried to add all the new properties and constants in a sensible place, which usually means alphabetic order within the sub-group of related entries.
>> 
>> I chose to keep the markup structure of the package summary page mostly unchanged, adding only `id` attributes to the existing `<li>` elements for each summary table. I decided against adding `class` attributes as well as it seems very unlikely to me that somebody would want to apply different styles to the various summary tables. Even without them, it could be done using the `id`s.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   JDK-8263507: Update JBS summary

I've read the source changes, but only skimmed through the tests at this point.

Various suggestions for your consideration or feedback.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesIndexWriter.java line 125:

> 123:                 .addTab(contents.exceptionsString, e -> utils.isException((TypeElement)e))
> 124:                 .addTab(contents.errorsString, e -> utils.isError((TypeElement)e))
> 125:                 .addTab(contents.annotationTypesString, utils::isAnnotationType);

I can't say I'm a big fan of the new-style `String` suffix, but  I guess it is OK for now; we need a cleanup on the names of members in `Contents` anyway.  More comments in `Contents`.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java line 194:

> 192:     public final String interfacesString;
> 193:     public final String packageSummary;
> 194:     public final String recordsString;

The new-style `String` suffix looks weird, and iut's unexpected to see `String` constants here, but, I see the constants were there before, and (worse) I added them!
I guess we generally need to separate these names from equivalent `Content` objects. OK for now, but worth re-examining in a future cleanup.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java line 143:

> 141:                 // in doclets.properties
> 142:                 { "doclet.Annotation_Types_Summary", "doclet.Annotation_Interfaces_Summary" },
> 143:                 { "doclet.Enum_Summary", "doclet.Enum_Class_Summary" },

given you're changing this table, you should at least check manually if not in a test that you get old-style terminology with `--release 16` or older, and new-style terminology with `--release 17` or later.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java line 209:

> 207:                         HtmlTree.LI(links.createLink(HtmlIds.SERVICES, contents.navServices,
> 208:                             displayServices(uses, usesTrees) || displayServices(provides.keySet(), providesTrees)))
> 209:                 ));

In general, I like the new `.setSubNavLinks` method. :-)
Do you need the `HtmlTree.LI` wrappers, or is it enough to pass in a list of `links.createLink` calls?
The `HtmlTree.LI` are really internal detail of the subnavbar implementation ... i.e. a `ul` of `li` elements.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java line 107:

> 105:          * {@return a list of links to display in the sub-navigation area}
> 106:          * Links should be wrapped in {@code HtmlTree.LI} elements as they are
> 107:          * displayed within an unordered list.

As noted above, this class could do the wrapping with `LI` elements.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java line 144:

> 142:     }
> 143: 
> 144:     public Navigation setMemberSummaryBuilder(MemberSummaryBuilder memberSummaryBuilder) {

General comment for this and all the following red lines: yay!

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java line 343:

> 341:             case PACKAGE:
> 342:             case CLASS:
> 343:             case HELP:

style comment ... since you're using new-style switch, do you want to do so here as well?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java line 344:

> 342:             case CLASS:
> 343:             case HELP:
> 344:                 List<Content> listContents = subNavLinks.getSubNavLinks();

I think this looks like where you could stream the list, wrap the entries in `LI` and convert back to a list.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java line 186:

> 184:                 packages.addAll(siblings);
> 185:             }
> 186:         }

Hmmm, I foresee downstream JBS issues ... "javadoc bug: I added a package to my code and the table disappeared".  Should there be a warning and a way to change the limit? (Eventually?)

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java line 260:

> 258:                 .addTab(contents.exceptionsString, e -> utils.isException((TypeElement)e))
> 259:                 .addTab(contents.errorsString, e -> utils.isError((TypeElement)e))
> 260:                 .addTab(contents.annotationTypesString, utils::isAnnotationType);

should we normalize the `utils.is...` methods so that we do not need the casts?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/PackageSummaryWriter.java line 130:

> 128:      * @param summaryContentTree the content tree to which the summaries will be added
> 129:      */
> 130:     void addAnnotationTypeSummary(SortedSet<TypeElement> annoTypes, Content summaryContentTree);

Nice cleanup!

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/VisibleMemberTable.java line 111:

> 109: 
> 110:         private static final EnumSet<Kind> defaultSummarySet = EnumSet.of(
> 111:                 INNER_CLASSES, FIELDS, CONSTRUCTORS, METHODS);

Picky, maybe for another time: the correct term is probably `NESTED_CLASSES`.  Inner classes are a subset of nested classes that have an `outer` instance. (i.e. they're not `static` nested classes.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/VisibleMemberTable.java line 119:

> 117:                 FIELDS, CONSTRUCTORS, METHODS);
> 118:         private static final EnumSet<Kind> enumDetailSet = EnumSet.of(
> 119:                 ENUM_CONSTANTS, FIELDS, METHODS);

I'm a bit surprised by this, if only because we've had problems with tables like this in the past.

Is it possible to have a single combined list where some of the entries will give effectively empty tables which can be suppressed?

Case in point for an issue: why does `enumSummarySet` have `INNER_CLASSES` but `annotationSummarySet` does not.

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

Changes requested by jjg (Reviewer).

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

From hannesw at openjdk.java.net  Fri Apr 30 07:50:55 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 30 Apr 2021 07:50:55 GMT
Subject: Integrated: JDK-8249903:
 jdk/javadoc/doclet/testSerializedForm/TestSerializedForm.java needs to be
 updated after 8146022 got closed
In-Reply-To: <y2kfMpXbzxtzatpfNooSuBAb0_2Y176zLQEn79lqfFY=.4fdd06fc-9533-4c3a-8728-21cc58de45fe@github.com>
References: <y2kfMpXbzxtzatpfNooSuBAb0_2Y176zLQEn79lqfFY=.4fdd06fc-9533-4c3a-8728-21cc58de45fe@github.com>
Message-ID: <id0FRNsWjOX-wJ4XyCXNR-e53MRJToVIxOx9WTVbBb4=.1ef532d0-02bf-472d-894f-065d074fe0c6@github.com>

On Thu, 29 Apr 2021 08:00:18 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> I don't know why this test was disabled because of JDK-8146022, in fact I wasn't able to understand what JDK-8146022 was all about as I didn't find a commit for it. However, the test runs fine when updated to the current output format, so I guess whatever bug caused it to fail has been fixed in the meantime. I also removed some vestiges of an old test framework nearby that has been commented out from time immemorial.

This pull request has now been integrated.

Changeset: 4d771715
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/4d771715406bff2d751b4b0da0577e141c526eff
Stats:     28 lines in 1 file changed: 9 ins; 9 del; 10 mod

8249903: jdk/javadoc/doclet/testSerializedForm/TestSerializedForm.java needs to be updated after 8146022 got closed

Reviewed-by: jjg

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

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

From hannesw at openjdk.java.net  Fri Apr 30 09:50:52 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 30 Apr 2021 09:50:52 GMT
Subject: RFR: JDK-8258602: JavaDoc field summary does not indicate final
 modifier [v2]
In-Reply-To: <I7n0YNXDOTJAX0PiNvrLDRbVx_AxkDdWBAThJsp-yBk=.64e9dd23-9062-4b8b-85de-b036fce4237c@github.com>
References: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
 <3uRQTDZ9FVmSKZGl0WSY5bkXHn8lEVga1UsRJ4sJTmM=.5c3498e7-67fc-4bfd-8a25-c83f7b5c114a@github.com>
 <I7n0YNXDOTJAX0PiNvrLDRbVx_AxkDdWBAThJsp-yBk=.64e9dd23-9062-4b8b-85de-b036fce4237c@github.com>
Message-ID: <XuToYBRLv_CDsTeZiRykUo-PN1B_7Nk9n04zSpSw67o=.2709645c-26be-4331-933c-b6a61d45d61e@github.com>

On Fri, 30 Apr 2021 03:28:20 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> OK, but we might want to think about the pros and cons of normalizing modifiers.

Thanks for the review; I agree we should think about normalizing modifiers. 

FWIW, the JLS describes methods in final classes as merely "behaving as if they were final" (8.4.3.3.), so at least technically it is still the modifier that decides. Other constructs are actually declared as implicitly final, with some of them allowing the modifier (such as constants in interfaces) and some not (enums). Here I think we usually show modifiers if they are allowed, although I haven't done a systematic review.

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

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

From hannesw at openjdk.java.net  Fri Apr 30 09:50:54 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 30 Apr 2021 09:50:54 GMT
Subject: Integrated: JDK-8258602: JavaDoc field summary does not indicate
 final modifier
In-Reply-To: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
References: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
Message-ID: <ZFR3tF_JlhUEdDsLZcKE1FIW4ax5Xhlpx6mpx3Kutq8=.4e17e698-fac1-4b23-b634-fc3597b5e803@github.com>

On Tue, 27 Apr 2021 09:45:05 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> I found that adding the `final` modifier does not add too much visual noise to the documentation. I didn't find any occurrence where there were more than two modifiers on a member summary (usually either `static final` or `protected final`). 
> 
> On the other hand, I do think the `final` modifier adds important information about the member. Although this is more true for fields than for other members, for reasons of consistency I decided to show it for all kinds of members except for those where it is not allowed (such as for enums).
> 
> To my surprise I also noticed that there weren't any test cases for field summaries, so I added a new test.

This pull request has now been integrated.

Changeset: 07ecd421
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/07ecd421d1538ae53ffbea65eccfa938e19a9f0f
Stats:     174 lines in 8 files changed: 159 ins; 0 del; 15 mod

8258602: JavaDoc field summary does not indicate final modifier

Reviewed-by: jjg

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

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

From dfuchs at openjdk.java.net  Fri Apr 30 10:06:53 2021
From: dfuchs at openjdk.java.net (Daniel Fuchs)
Date: Fri, 30 Apr 2021 10:06:53 GMT
Subject: RFR: JDK-8258602: JavaDoc field summary does not indicate final
 modifier [v2]
In-Reply-To: <XuToYBRLv_CDsTeZiRykUo-PN1B_7Nk9n04zSpSw67o=.2709645c-26be-4331-933c-b6a61d45d61e@github.com>
References: <3-pDeAkwhFmHiZiBP-1nzrstBaFPRVp1FA4_nakFxfA=.4aa5f3bd-30c8-42c4-9fd2-5963488d858b@github.com>
 <3uRQTDZ9FVmSKZGl0WSY5bkXHn8lEVga1UsRJ4sJTmM=.5c3498e7-67fc-4bfd-8a25-c83f7b5c114a@github.com>
 <I7n0YNXDOTJAX0PiNvrLDRbVx_AxkDdWBAThJsp-yBk=.64e9dd23-9062-4b8b-85de-b036fce4237c@github.com>
 <XuToYBRLv_CDsTeZiRykUo-PN1B_7Nk9n04zSpSw67o=.2709645c-26be-4331-933c-b6a61d45d61e@github.com>
Message-ID: <PeiRzxIjW6yjKC-9NJ3duj9dMr_85QQyoYdJet0Dvok=.68aae3ef-1857-4aed-9692-af65865ae9be@github.com>

On Fri, 30 Apr 2021 09:46:08 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Thanks for the review; I agree we should think about normalizing modifiers.
> 
> FWIW, the JLS describes methods in final classes as merely "behaving as if they were final" (8.4.3.3.), so at least technically it is still the modifier that decides. Other constructs are actually declared as implicitly final, with some of them allowing the modifier (such as constants in interfaces) and some not (enums). Here I think we usually show modifiers if they are allowed, although I haven't done a systematic review.

I would be concerned that adding (or removing) a redundant `final` keyword could be perceived as a specification change if it's reflected in the API documentation. But I am happy for the normalization issue to be revisited later.

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

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

From hannesw at openjdk.java.net  Fri Apr 30 14:13:08 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 30 Apr 2021 14:13:08 GMT
Subject: RFR: JDK-8232644: bugs in serialized-form.html
Message-ID: <8-UfnGEMuEtXC-ysMz6gDEFHCi1XO_yuW8nah5YlxUI=.9f6a7196-ceff-41dd-91da-6b05136b53a6@github.com>

This implements most suggestions implemented in the JBS issue. The heading for class entries in the page is shortened to "<element-type-kind> <name>", followed by a simplified signature line like "class X extends Y implements Serializable".

Furthermore, package names in package headings now link to the package page, `@param` info is added to the methods, Externalizable is used for classes that implement it. I also added a check for content in `@serial` tags to avoid spurious empty `&nbsp;` lines in the output.

I increased the font size for headings `h4` to `h6` in the stylesheets because their size was smaller than the default text size, which looked strange. Although the change in font size from `h3` to `h4` and beyond is now smaller I think it's still recognizable. Headings `h4` to `h5` are used very little in Javadoc (mostly static doc files and the serialized-form page). I looked at some of the static files and they looked good to me with the new larger heading fonts.

Although I didn't end up using the `Signatures` class to generate the class signatures (they're just too simple and too specific in what they list), I left in some cleanup of `Signatures.TypeSignature`, most significantly moving the processing of modifiers from `ClassWriterImpl` to `Signatures.TypeSignature`.

I only removed the obsolete resources from the English resource file out of habit of not touching the Chinese and Japanese ones. I guess I could remove it there too.

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

Commit messages:
 - JDK-8232644: bugs in serialized-form.html

Changes: https://git.openjdk.java.net/jdk/pull/3817/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3817&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8232644
  Stats: 178 lines in 19 files changed: 56 ins; 43 del; 79 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3817.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3817/head:pull/3817

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

From hannesw at openjdk.java.net  Fri Apr 30 14:13:08 2021
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 30 Apr 2021 14:13:08 GMT
Subject: RFR: JDK-8232644: bugs in serialized-form.html
In-Reply-To: <8-UfnGEMuEtXC-ysMz6gDEFHCi1XO_yuW8nah5YlxUI=.9f6a7196-ceff-41dd-91da-6b05136b53a6@github.com>
References: <8-UfnGEMuEtXC-ysMz6gDEFHCi1XO_yuW8nah5YlxUI=.9f6a7196-ceff-41dd-91da-6b05136b53a6@github.com>
Message-ID: <MUcR3duRKD73SfLa7FcGYS0VZ2u31_k08skIplMJC04=.cf8cdcf0-99b8-4e93-b5bd-5274c2600911@github.com>

On Fri, 30 Apr 2021 14:06:13 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This implements most suggestions implemented in the JBS issue. The heading for class entries in the page is shortened to "<element-type-kind> <name>", followed by a simplified signature line like "class X extends Y implements Serializable".
> 
> Furthermore, package names in package headings now link to the package page, `@param` info is added to the methods, Externalizable is used for classes that implement it. I also added a check for content in `@serial` tags to avoid spurious empty `&nbsp;` lines in the output.
> 
> I increased the font size for headings `h4` to `h6` in the stylesheets because their size was smaller than the default text size, which looked strange. Although the change in font size from `h3` to `h4` and beyond is now smaller I think it's still recognizable. Headings `h4` to `h5` are used very little in Javadoc (mostly static doc files and the serialized-form page). I looked at some of the static files and they looked good to me with the new larger heading fonts.
> 
> Although I didn't end up using the `Signatures` class to generate the class signatures (they're just too simple and too specific in what they list), I left in some cleanup of `Signatures.TypeSignature`, most significantly moving the processing of modifiers from `ClassWriterImpl` to `Signatures.TypeSignature`.
> 
> I only removed the obsolete resources from the English resource file out of habit of not touching the Chinese and Japanese ones. I guess I could remove it there too.

The new `serialized-form.html` page including the stylesheet changes can be viewed here:

http://cr.openjdk.java.net/~hannesw/8232644/api.00/serialized-form.html

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

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

From jjg at openjdk.java.net  Fri Apr 30 16:45:22 2021
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 30 Apr 2021 16:45:22 GMT
Subject: RFR: JDK-8265042: javadoc HTML files not generated for types nested
 in records
Message-ID: <e73qg04rzAR2HWz7OZd_L7yATL-0n8Jl2Ba-DY_u53g=.350f20f2-d45a-4a9e-81dc-d43c2a85f29b@github.com>

This addresses an oversight in the support for records.

The fix could have been as simple as a one-word addition to a list of element kinds to check for nested classes. However, instead of that, the fix is more of a cleanup of a group of methods in `Utils` to fix this issue and to reduce the likelihood of anything similar happening again, when the next new kind of class is added.

The cleanup uses new code idioms using lambdas, predicates, and generic methods to replace varargs and temporary sets and copying lists.  The naming is somewhat cleaned up as well, but it was a self-imposed restriction that the cleanup is limited to the `Utils` class, and does not leak into clients of the class.

There is a core `getItems` method which is somewhat multi-purpose, supporting recursive and non-recursive use, and examining either just documented members or all members, including members that are not directly documented. (The latter occurs mostly in serialization.)   It is possible there is a future refactoring to further improve this method, perhaps to break it into different methods.  With that in mind, the signature of some methods was narrowed from accepting any `Element` to a specific kind of element: generally, one of `PackageElement` or `TypeElement`.

A new test is provided that checks that all the expected files are generated for various kinds of nested classes and interfaces in all kinds of classes and interfaces. The test is designed to fail if a new kind of class or interface is added in future without a corresponding update to the test.

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

Commit messages:
 - JDK-8265042: javadoc HTML files not generated for types nested in records

Changes: https://git.openjdk.java.net/jdk/pull/3821/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3821&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8265042
  Stats: 480 lines in 2 files changed: 265 ins; 102 del; 113 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3821.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3821/head:pull/3821

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

From vromero at openjdk.java.net  Fri Apr 30 17:42:34 2021
From: vromero at openjdk.java.net (Vicente Romero)
Date: Fri, 30 Apr 2021 17:42:34 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in
 Java, javadoc changes [v6]
In-Reply-To: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
References: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
Message-ID: <xeHvQUfGkEt_bx6PkmiTKOcEvFX8AQnc-vQjv3cBeCg=.47a32b46-5de1-4f61-82fb-b7b4a03d23de@github.com>

> Please review the javadoc related changes to make sealed classes a final feature in Java. The patch is mostly removing preview features related code that is not necessary anymore in javadoc.
> 
> TIA

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

 - Merge branch 'master' into JDK-8265684
 - addressing indentation issues
 - Merge branch 'master' into JDK-8265684
 - additional commit addressing review comments
 - addressing review comments
 - Merge branch 'master' into JDK-8265684
 - 8265684: implement Sealed Classes as a standard feature in Java, javadoc changes

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3613/files
  - new: https://git.openjdk.java.net/jdk/pull/3613/files/846d34b5..436a75c6

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

  Stats: 506473 lines in 3844 files changed: 20558 ins; 483521 del; 2394 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3613.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3613/head:pull/3613

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

From vromero at openjdk.java.net  Fri Apr 30 17:54:18 2021
From: vromero at openjdk.java.net (Vicente Romero)
Date: Fri, 30 Apr 2021 17:54:18 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in
 Java, javadoc changes [v7]
In-Reply-To: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
References: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
Message-ID: <eNtlbYYvaW-v7xjPYc5oLq79HhYKmQ4_5x6CAent9Qc=.8e040fb7-38d6-4213-b2dc-a48efe92cb2b@github.com>

> Please review the javadoc related changes to make sealed classes a final feature in Java. The patch is mostly removing preview features related code that is not necessary anymore in javadoc.
> 
> TIA

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

  fixing indentation: review comment

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3613/files
  - new: https://git.openjdk.java.net/jdk/pull/3613/files/436a75c6..688d5647

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

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

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

From vromero at openjdk.java.net  Fri Apr 30 17:54:19 2021
From: vromero at openjdk.java.net (Vicente Romero)
Date: Fri, 30 Apr 2021 17:54:19 GMT
Subject: RFR: 8265684: implement Sealed Classes as a standard feature in
 Java, javadoc changes [v5]
In-Reply-To: <TklFYaBmYDyKD7UwR4XZ0CwhXDgeu4QAFP6666Er89k=.32d3b45b-887d-44ce-9bcc-3a164a5a0ae1@github.com>
References: <yENRE3P7QNwIBF_wt0yQnXe7_mdHbpVmCHLWzW32Pgg=.374ad9a7-051d-431f-b9c9-519d70189459@github.com>
 <eivIWe4Pv5zmnbyC_Y2v1jfJtxLR258FdHDkcOsBCDs=.6e9059cf-25fc-448e-a602-1176bb248f3e@github.com>
 <TklFYaBmYDyKD7UwR4XZ0CwhXDgeu4QAFP6666Er89k=.32d3b45b-887d-44ce-9bcc-3a164a5a0ae1@github.com>
Message-ID: <OSvvs8USZDxbqx6GM4BkTARLFeu6kAgwVoLg8ZO8dww=.e448e7ba-9980-491e-92aa-315c6600928b@github.com>

On Fri, 30 Apr 2021 03:33:57 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Vicente Romero has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   addressing indentation issues
>
> test/langtools/jdk/javadoc/doclet/testSealedTypes/TestSealedTypes.java line 251:
> 
>> 249:                 "package p; public final  class B extends A { }",
>> 250:                 "package p; public final  class C extends A { }",
>> 251:                 "package p; sealed class D extends A permits D1, D2 { }",
> 
> (minor)   don't delete the spaces; the class names were previously vertically aligned

sure, done, thank for the review

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

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

From gunnar at hibernate.org  Fri Apr 30 10:40:50 2021
From: gunnar at hibernate.org (Gunnar Morling)
Date: Fri, 30 Apr 2021 12:40:50 +0200
Subject: JEP 413: Code Snippets in Java API Documentation
Message-ID: <CADGJaX-R5dBPRg3NrYst_n0GSggnvqgkF-9D1EhP64y8Zr8bwA@mail.gmail.com>

Hi all,

It's with great interest that I've learned about JEP 413, I think this will
be a great improvement to the user experience of JavaDoc!

When sharing this online, there was feedback from several folks [1] that
alignment for the region  selection syntax with that one of AsciiDoc would
be desirable [2]. That way, one could easily include the same snippet into
JavaDoc and other documentation like a developer guide at the same time. I
believe that'd make lots of sense, so I thought I'd relay this feedback
here.

Best,

--Gunnar

[1] https://twitter.com/maxandersen/status/1388018227868049408
[2]
https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210430/381e391f/attachment.htm>