From prappo at openjdk.java.net  Tue Dec  1 17:11:55 2020
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 1 Dec 2020 17:11:55 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations.
In-Reply-To: <uf_6tcbpe0dLHA39qxAIGEgXb_VYKnfAANdGOLZOvQs=.e96cefa3-4deb-4a5f-ac7f-975b91fd8a1e@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <uf_6tcbpe0dLHA39qxAIGEgXb_VYKnfAANdGOLZOvQs=.e96cefa3-4deb-4a5f-ac7f-975b91fd8a1e@github.com>
Message-ID: <CUEB3J-W10h-QXmNang8FidRvp86egN-p5N3V0P85Ks=.50cd30f4-7575-4837-b3db-c2ebe2cb4e08@github.com>

On Fri, 27 Nov 2020 16:33:27 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
>> 
>> The goal is to be able to simplify the following common pattern:
>> 
>>     /**
>>      * Returns the result. Optional additional text.
>>      * @return the result
>>      */
>>     int method() { 
>> 
>> by 
>> 
>>     /**
>>      * {@return the result} Optional additional text.
>>      */
>>     int method() { 
>> 
>> Note:
>> 
>> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
>> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
>> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
>> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.
>
> /**
>   * {@return the result} Optional additional text.
>   */
>  ```
> The java source looks a bit odd/unusual because the "first sentence" does not appear to end with a period.
> Though it seems like a convenience to include the '.' in the expansion, the source might be clearer if it did not, as in:
> /**
>   * {@return the result}. Optional additional text.
>   */ 
> Similarly, prepending the "Returns", forces the verb, which is conventional but always the most appropriate word.
> Changing the expansion to be only the contents of @ return would allow more flexible use.
> It would put more responsibility on the developer to form the first sentence. (With "Returns"... and the "." outside the tag.

@RogerRiggs ,

1. I agree on that the lack of `.` after `}` looks unnatural:

/**
 * {@return the result} Optional additional text.
 */
int method() { 

2. I disagree on allowing a flexible expansion. This enhancement aims to support a very particular case of redundancy in doc comments. I believe that the proportion of redundant doc comments that use some other verb (instead of "Return(s)") is smaller than it needs to be to support the increase in tag's complexity.

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

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

From rriggs at openjdk.java.net  Wed Dec  2 15:42:54 2020
From: rriggs at openjdk.java.net (Roger Riggs)
Date: Wed, 2 Dec 2020 15:42:54 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations.
In-Reply-To: <CUEB3J-W10h-QXmNang8FidRvp86egN-p5N3V0P85Ks=.50cd30f4-7575-4837-b3db-c2ebe2cb4e08@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <uf_6tcbpe0dLHA39qxAIGEgXb_VYKnfAANdGOLZOvQs=.e96cefa3-4deb-4a5f-ac7f-975b91fd8a1e@github.com>
 <CUEB3J-W10h-QXmNang8FidRvp86egN-p5N3V0P85Ks=.50cd30f4-7575-4837-b3db-c2ebe2cb4e08@github.com>
Message-ID: <7FdWCF7I1N4ax_xlTUi9Edbr8C-C5pHdpFFI3uSokMg=.d8097e28-2d47-40b9-ac21-8d41f66ecfc6@github.com>

On Tue, 1 Dec 2020 17:09:25 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> /**
>>   * {@return the result} Optional additional text.
>>   */
>>  ```
>> The java source looks a bit odd/unusual because the "first sentence" does not appear to end with a period.
>> Though it seems like a convenience to include the '.' in the expansion, the source might be clearer if it did not, as in:
>> /**
>>   * {@return the result}. Optional additional text.
>>   */ 
>> Similarly, prepending the "Returns", forces the verb, which is conventional but always the most appropriate word.
>> Changing the expansion to be only the contents of @ return would allow more flexible use.
>> It would put more responsibility on the developer to form the first sentence. (With "Returns"... and the "." outside the tag.
>
> @RogerRiggs ,
> 
> 1. I agree on that the lack of `.` after `}` looks unnatural:
> 
> /**
>  * {@return the result} Optional additional text.
>  */
> int method() { 
> 
> 2. I disagree on allowing a flexible expansion. This enhancement aims to support a very particular case of redundancy in doc comments. I believe that the proportion of redundant doc comments that use some other verb (instead of "Return(s)") is smaller than it needs to be to support the increase in tag's complexity.

There is lots of other duplication/repetition in most javadoc. I'd rather see some kind of text macro that would allow a single definition of a string that can be repeated.  The source would be a bit less readable, but it would be lower maintenance when the same phrase or sentence is repeated to make the javadoc more locally complete and easier to read in isolation. Now many times do you have to say "throws NullPointerException when the reference is null" or similar assertion.

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

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

From prappo at openjdk.java.net  Wed Dec  2 15:48:53 2020
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Wed, 2 Dec 2020 15:48:53 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations.
In-Reply-To: <7FdWCF7I1N4ax_xlTUi9Edbr8C-C5pHdpFFI3uSokMg=.d8097e28-2d47-40b9-ac21-8d41f66ecfc6@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <uf_6tcbpe0dLHA39qxAIGEgXb_VYKnfAANdGOLZOvQs=.e96cefa3-4deb-4a5f-ac7f-975b91fd8a1e@github.com>
 <CUEB3J-W10h-QXmNang8FidRvp86egN-p5N3V0P85Ks=.50cd30f4-7575-4837-b3db-c2ebe2cb4e08@github.com>
 <7FdWCF7I1N4ax_xlTUi9Edbr8C-C5pHdpFFI3uSokMg=.d8097e28-2d47-40b9-ac21-8d41f66ecfc6@github.com>
Message-ID: <tuzR4-NnTC_-2GRoJxPiZT1SY7E5YVUNMfnPwlH6APo=.e481d268-acb1-4b98-8379-1608ad48186c@github.com>

On Wed, 2 Dec 2020 15:39:56 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> @RogerRiggs ,
>> 
>> 1. I agree on that the lack of `.` after `}` looks unnatural:
>> 
>> /**
>>  * {@return the result} Optional additional text.
>>  */
>> int method() { 
>> 
>> 2. I disagree on allowing a flexible expansion. This enhancement aims to support a very particular case of redundancy in doc comments. I believe that the proportion of redundant doc comments that use some other verb (instead of "Return(s)") is smaller than it needs to be to support the increase in tag's complexity.
>
> There is lots of other duplication/repetition in most javadoc. I'd rather see some kind of text macro that would allow a single definition of a string that can be repeated.  The source would be a bit less readable, but it would be lower maintenance when the same phrase or sentence is repeated to make the javadoc more locally complete and easier to read in isolation. Now many times do you have to say "throws NullPointerException when the reference is null" or similar assertion.

@RogerRiggs,

Here are some more thoughts on flexible expansion (i.e. not forcing a particular verb). To understand the nature and estimate the prevalence of cases where "Return(s)" was inappropriate as the first word of an internally repetitive doc comment, I conducted the following experiment in JDK.

I searched for doc comments whose first sentence was at least 90% similar to the contents of `@ return` tag. My program ignored differences in markup and compared contents as strings using normalized Levenshtein similarity; I got 3432 results. Then I modified the program to ignore those doc comments whose first sentence case-insensitively started with "return"; I got 194 results.

While more analysis might be required, I can preliminary see that we are talking about 5% of the cases. Which is not much, if you ask me. Here are a few findings made by the modified program:


/**
 * Cleaner for use within system modules.
 ...
 * @return a Cleaner for use within system modules
 */
public static Cleaner cleaner() {

/**
 * Get the localization resource bundle
 ...
 * @return the localization resource bundle
 */
public ResourceBundle getResourceBundle() {

/**
 * Obtains a line that is available for use and that matches the description
 * in the specified {@code Line.Info} object.
 ...
 * @return a line that is available for use and that matches the description
 *         in the specified {@code Line.Info} object
 ...
 */
Line getLine(Line.Info info) throws LineUnavailableException;

/**
 * The description of this filter. For example: "JPG and GIF Images."
 *
 * @return the description of this filter
 */
public String getDescription() {

/**
 * Fetch the object representing the layout state of
 * of the child at the given index.
 ...
 * @return the object representing the layout state of
 * of the child at the given index
 */
protected ChildState getChildState(int index) {

/**
 * Creates a new instance of the {@code DatatypeFactory} {@linkplain
 * #DATATYPEFACTORY_IMPLEMENTATION_CLASS builtin system-default
 * implementation}.
 *
 * @return A new instance of the {@code DatatypeFactory} builtin
 *         system-default implementation.
 ...
 */
public static DatatypeFactory newDefaultInstance() {

/**
 * True if this iterator has a reversed axis.
 *
 * @return <code>true</code> if this iterator is a reversed axis.
 */
public boolean isReverse() {

/**
 * Check if the annotation contains an array of annotation as a value. This
 * check is to verify if a repeatable type annotation is present or not.
 ...
 * @return true if the annotation contains an array of annotation as a value.
 */
private boolean isAnnotationArray(Map<? extends ExecutableElement, ? extends AnnotationValue> pairs) {

...

The most frequent first word in those 194 results was "Get(s)".

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

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

From hannesw at openjdk.java.net  Thu Dec  3 06:58:05 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 3 Dec 2020 06:58:05 GMT
Subject: RFR: 8257617: TestLinkPlatform fails with new Java source version
Message-ID: <znCy80mXmfz9ubADGDqSysbNUdu1ZXWgz7PNOPuYnt4=.2eda7c8c-c2b4-4bb1-a759-c4ef8a9c4980@github.com>

This fixes the problem that some tests in TestLinkPlatform.java rely on a static list of properties, causing them to fail when a new Java source version is added. The solution is to create the properties file on the fly. 

I also replaced the custom documentation domain with "example.com" as suggested in the original PR.

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

Commit messages:
 - JDK-8257617: TestLinkPlatform fails with new Java source version

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

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

From darcy at openjdk.java.net  Thu Dec  3 07:05:54 2020
From: darcy at openjdk.java.net (Joe Darcy)
Date: Thu, 3 Dec 2020 07:05:54 GMT
Subject: RFR: 8257617: TestLinkPlatform fails with new Java source version
In-Reply-To: <znCy80mXmfz9ubADGDqSysbNUdu1ZXWgz7PNOPuYnt4=.2eda7c8c-c2b4-4bb1-a759-c4ef8a9c4980@github.com>
References: <znCy80mXmfz9ubADGDqSysbNUdu1ZXWgz7PNOPuYnt4=.2eda7c8c-c2b4-4bb1-a759-c4ef8a9c4980@github.com>
Message-ID: <3K--EwgLb6QCcO_JMXWQ_HvVaevRNAex5rviUJPL9Y0=.b6310591-302f-49f1-abbf-e1550e477892@github.com>

On Thu, 3 Dec 2020 06:52:49 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This fixes the problem that some tests in TestLinkPlatform.java rely on a static list of properties, causing them to fail when a new Java source version is added. The solution is to create the properties file on the fly. 
> 
> I also replaced the custom documentation domain with "example.com" as suggested in the original PR.

Thanks for the fix. The test passes with this change when run in my in-development JDK 17 build.

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

Marked as reviewed by darcy (Reviewer).

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

From hannesw at openjdk.java.net  Thu Dec  3 07:15:55 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 3 Dec 2020 07:15:55 GMT
Subject: Integrated: 8257617: TestLinkPlatform fails with new Java source
 version
In-Reply-To: <znCy80mXmfz9ubADGDqSysbNUdu1ZXWgz7PNOPuYnt4=.2eda7c8c-c2b4-4bb1-a759-c4ef8a9c4980@github.com>
References: <znCy80mXmfz9ubADGDqSysbNUdu1ZXWgz7PNOPuYnt4=.2eda7c8c-c2b4-4bb1-a759-c4ef8a9c4980@github.com>
Message-ID: <Hmpzo18IO855cgRYXIiOvNrf6tVRN4_I_Mr6oJCrIY0=.0c8d7e2a-1348-4204-91a7-698bddfff4a3@github.com>

On Thu, 3 Dec 2020 06:52:49 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This fixes the problem that some tests in TestLinkPlatform.java rely on a static list of properties, causing them to fail when a new Java source version is added. The solution is to create the properties file on the fly. 
> 
> I also replaced the custom documentation domain with "example.com" as suggested in the original PR.

This pull request has now been integrated.

Changeset: a5a034b7
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/a5a034b7
Stats:     28 lines in 2 files changed: 13 ins; 10 del; 5 mod

8257617: TestLinkPlatform fails with new Java source version

Reviewed-by: darcy

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

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

From jjg at openjdk.java.net  Thu Dec  3 19:44:17 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 3 Dec 2020 19:44:17 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v5]
In-Reply-To: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
Message-ID: <GjHF5xdbl6KH9h_GF9ZVLh5mUrsqvRoBQ6sAk5hS-bs=.e8c8bd3d-c17e-4bcd-87ca-88c5c1a51c50@github.com>

> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
> 
> The goal is to be able to simplify the following common pattern:
> 
>     /**
>      * Returns the result. Optional additional text.
>      * @return the result
>      */
>     int method() { 
> 
> by 
> 
>     /**
>      * {@return the result} Optional additional text.
>      */
>     int method() { 
> 
> Note:
> 
> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.

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

 - Update JShell to handle inline `{@return}`
 - Merge remote-tracking branch 'upstream/master' into new-return
 - fix test
 - Update for new `@return` tag
 - Merge remote-tracking branch 'upstream/master' into new-return
 - Update DocCommentParser to permit nested inline tags in specified cases: @return
 - Add default impl for new method
 - Fix test failure
 - Fix trailing whitespace in test
 - Merge master
 - ... and 1 more: https://git.openjdk.java.net/jdk/compare/4de14b11...60ff9839

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/1355/files
  - new: https://git.openjdk.java.net/jdk/pull/1355/files/5703d83b..60ff9839

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

  Stats: 5899 lines in 160 files changed: 4319 ins; 407 del; 1173 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1355.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1355/head:pull/1355

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

From darcy at openjdk.java.net  Thu Dec  3 21:21:55 2020
From: darcy at openjdk.java.net (Joe Darcy)
Date: Thu, 3 Dec 2020 21:21:55 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations.
In-Reply-To: <7FdWCF7I1N4ax_xlTUi9Edbr8C-C5pHdpFFI3uSokMg=.d8097e28-2d47-40b9-ac21-8d41f66ecfc6@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <uf_6tcbpe0dLHA39qxAIGEgXb_VYKnfAANdGOLZOvQs=.e96cefa3-4deb-4a5f-ac7f-975b91fd8a1e@github.com>
 <CUEB3J-W10h-QXmNang8FidRvp86egN-p5N3V0P85Ks=.50cd30f4-7575-4837-b3db-c2ebe2cb4e08@github.com>
 <7FdWCF7I1N4ax_xlTUi9Edbr8C-C5pHdpFFI3uSokMg=.d8097e28-2d47-40b9-ac21-8d41f66ecfc6@github.com>
Message-ID: <uRJn3oaeSimBRXejywlSizOPGJtHNzsQyVlEPC51PpA=.dbf0afde-8926-4653-a6c1-ab4d623c951e@github.com>

On Wed, 2 Dec 2020 15:39:56 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

> 
> 
> There is lots of other duplication/repetition in most javadoc. I'd rather see some kind of text macro that would allow a single definition of a string that can be repeated. The source would be a bit less readable, but it would be lower maintenance when the same phrase or sentence is repeated to make the javadoc more locally complete and easier to read in isolation. Now many times do you have to say "throws NullPointerException when the reference is null" or similar assertion.

IMO this is a case to avoid the perfect being the enemy of the good. There are many structural cases of repeated or nearly repeated return information in the first sentence and @return tag. Therefore, I think it is reasonable for don't-repeat-yourself purposes to have dedicated support for this usage pattern.

Separately, I agree it would be helpful to have a more general facility to allow structured placement of repeated text blocks.

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

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

From darcy at openjdk.java.net  Thu Dec  3 21:21:54 2020
From: darcy at openjdk.java.net (Joe Darcy)
Date: Thu, 3 Dec 2020 21:21:54 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations.
In-Reply-To: <uf_6tcbpe0dLHA39qxAIGEgXb_VYKnfAANdGOLZOvQs=.e96cefa3-4deb-4a5f-ac7f-975b91fd8a1e@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <uf_6tcbpe0dLHA39qxAIGEgXb_VYKnfAANdGOLZOvQs=.e96cefa3-4deb-4a5f-ac7f-975b91fd8a1e@github.com>
Message-ID: <4j63ORDSQ307ihTZ5qnTrun-P9QdgWDne_y7SuNgFGY=.37115171-05b4-4f79-804c-7fa998f9fd5b@github.com>

On Fri, 27 Nov 2020 16:33:27 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

> 
> 
> ```
> /**
>   * {@return the result} Optional additional text.
>   */
> ```
> 
> The java source looks a bit odd/unusual because the "first sentence" does not appear to end with a period.
> Though it seems like a convenience to include the '.' in the expansion, the source might be clearer if it did not, as in:
> 
> ```
> /**
>   * {@return the result}. Optional additional text.
>   */ 
> ```
> 
> Similarly, prepending the "Returns", forces the verb, which is conventional but always the most appropriate word.
> Changing the expansion to be only the contents of @ return would allow more flexible use.
> It would put more responsibility on the developer to form the first sentence. (With "Returns"... and the "." outside the tag.

I've done a trial use of this feature in the java.compiler API. While initially I found the lack of a period after "{@return ...}" odd, I quickly adapted to this usage.

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

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

From jjg at openjdk.java.net  Thu Dec  3 21:31:55 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 3 Dec 2020 21:31:55 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations.
In-Reply-To: <uRJn3oaeSimBRXejywlSizOPGJtHNzsQyVlEPC51PpA=.dbf0afde-8926-4653-a6c1-ab4d623c951e@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <uf_6tcbpe0dLHA39qxAIGEgXb_VYKnfAANdGOLZOvQs=.e96cefa3-4deb-4a5f-ac7f-975b91fd8a1e@github.com>
 <CUEB3J-W10h-QXmNang8FidRvp86egN-p5N3V0P85Ks=.50cd30f4-7575-4837-b3db-c2ebe2cb4e08@github.com>
 <7FdWCF7I1N4ax_xlTUi9Edbr8C-C5pHdpFFI3uSokMg=.d8097e28-2d47-40b9-ac21-8d41f66ecfc6@github.com>
 <uRJn3oaeSimBRXejywlSizOPGJtHNzsQyVlEPC51PpA=.dbf0afde-8926-4653-a6c1-ab4d623c951e@github.com>
Message-ID: <5Ialjqp4jrEQ9QTm_19pujYWByiYqi6ldiVRtdqyiCo=.9d03a49e-151b-4be4-8cb3-329730cbd7d9@github.com>

On Thu, 3 Dec 2020 21:19:38 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> There is lots of other duplication/repetition in most javadoc. I'd rather see some kind of text macro that would allow a single definition of a string that can be repeated.  The source would be a bit less readable, but it would be lower maintenance when the same phrase or sentence is repeated to make the javadoc more locally complete and easier to read in isolation. Now many times do you have to say "throws NullPointerException when the reference is null" or similar assertion.
>
>> 
>> 
>> There is lots of other duplication/repetition in most javadoc. I'd rather see some kind of text macro that would allow a single definition of a string that can be repeated. The source would be a bit less readable, but it would be lower maintenance when the same phrase or sentence is repeated to make the javadoc more locally complete and easier to read in isolation. Now many times do you have to say "throws NullPointerException when the reference is null" or similar assertion.
> 
> IMO this is a case to avoid the perfect being the enemy of the good. There are many structural cases of repeated or nearly repeated return information in the first sentence and @return tag. Therefore, I think it is reasonable for don't-repeat-yourself purposes to have dedicated support for this usage pattern.
> 
> Separately, I agree it would be helpful to have a more general facility to allow structured placement of repeated text blocks.

Yes, there are two patterns being discussed here.

1. The pattern being directly addressed here, which is the local 
pairwise repetition of
 ???? Returns the result.
 ???? @return the result
 ??? where the repetition is unlikely to occur elsewhere

2. "Disjoint repetition", such as repeated occurrences of
 ???? @throws IOException if something occurrs
 ??? which will be found at most once per method, but may appear on many 
methods

We can (separately) discuss #2, preferably in the context of a different 
JBS issue, and wearing sticky rubber shoes to avoid falling down the 
cliff of a general macro-substitution language.

-- Jon

On 12/3/20 1:19 PM, Joe Darcy wrote:
>
>     There is lots of other duplication/repetition in most javadoc. I'd
>     rather see some kind of text macro that would allow a single
>     definition of a string that can be repeated. The source would be a
>     bit less readable, but it would be lower maintenance when the same
>     phrase or sentence is repeated to make the javadoc more locally
>     complete and easier to read in isolation. Now many times do you
>     have to say "throws NullPointerException when the reference is
>     null" or similar assertion.
>
> IMO this is a case to avoid the perfect being the enemy of the good. 
> There are many structural cases of repeated or nearly repeated return 
> information in the first sentence and @return 
> <https://urldefense.com/v3/__https://github.com/return__;!!GqivPVa7Brio!IUSEgZPlNh-w3R__hVpDuJiQuNZLQOKs4VXEe9tW9B3d2Aem9DM3WVH-17FJKDhTvrReYw$> 
> tag. Therefore, I think it is reasonable for don't-repeat-yourself 
> purposes to have dedicated support for this usage pattern.
>
> Separately, I agree it would be helpful to have a more general 
> facility to allow structured placement of repeated text blocks.
>
> ?
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub 
> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/1355*issuecomment-738325017__;Iw!!GqivPVa7Brio!IUSEgZPlNh-w3R__hVpDuJiQuNZLQOKs4VXEe9tW9B3d2Aem9DM3WVH-17FJKDh4e-tvuw$>, 
> or unsubscribe 
> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRT2VKB4GPG5D2FQJBDSS76HVANCNFSM4T5BHLXA__;!!GqivPVa7Brio!IUSEgZPlNh-w3R__hVpDuJiQuNZLQOKs4VXEe9tW9B3d2Aem9DM3WVH-17FJKDjzD260_w$>.
>

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

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

From dlsmith at openjdk.java.net  Sat Dec  5 01:52:21 2020
From: dlsmith at openjdk.java.net (Dan Smith)
Date: Sat, 5 Dec 2020 01:52:21 GMT
Subject: RFR: 8252180: [JEP 390] Deprecate wrapper class constructors for
 removal
Message-ID: <14WC4YuIN1sJ3jl5_htTC7wkzyzjpt540r7tmEQ85Lc=.4c5ac2b3-d24a-4aae-886b-b07e671f2948@github.com>

Integration of JEP 390, addressing the following issues:

8252180: [JEP 390] Deprecate wrapper class constructors for removal
8254047: [JEP 390] Revise "value-based class" & apply to wrappers
8252181: [JEP 390] Define & apply annotation jdk.internal.ValueBased
8252183: [JEP 390] Add 'lint' warning for @ValueBased classes
8257027: [JEP 390] Diagnose synchronization on @ValueBased classes

See https://github.com/openjdk/valhalla/tree/jep390 for development history.

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

Commit messages:
 - Merge
 - 8257776: [valhalla:jep390] Add disclaimer about future changes to value-based classes
 - 8254275: [valhalla/jep390] Revise "value-based class" & apply to wrappers
 - 8252182: [JEP 390] Diagnose synchronization on @ValueBased classes
 - Merge
 - 8256663: [test] Deprecated use of new Double in jshell ImportTest
 - 8253962: Add @ValueBased to unmodifable Collection implementation classes
 - 8256002: Cleanup of Wrapper changes
 - Merge
 - 8254271: Development to deprecate wrapper class constructors for removal
 - ... and 2 more: https://git.openjdk.java.net/jdk/compare/93b6ab56...7c5e5bfe

Changes: https://git.openjdk.java.net/jdk/pull/1636/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=1636&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8252180
  Stats: 902 lines in 114 files changed: 489 ins; 121 del; 292 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1636.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1636/head:pull/1636

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

From dlsmith at openjdk.java.net  Sat Dec  5 03:07:11 2020
From: dlsmith at openjdk.java.net (Dan Smith)
Date: Sat, 5 Dec 2020 03:07:11 GMT
Subject: RFR: 8252180: [JEP 390] Deprecate wrapper class constructors for
 removal
In-Reply-To: <14WC4YuIN1sJ3jl5_htTC7wkzyzjpt540r7tmEQ85Lc=.4c5ac2b3-d24a-4aae-886b-b07e671f2948@github.com>
References: <14WC4YuIN1sJ3jl5_htTC7wkzyzjpt540r7tmEQ85Lc=.4c5ac2b3-d24a-4aae-886b-b07e671f2948@github.com>
Message-ID: <ame4i0yLoLSpT6rwqcO20lQzYRBLR9FiyD7EKHAKltA=.b12c8d8b-e470-45df-bb0c-1f7330be9545@github.com>

On Sat, 5 Dec 2020 01:46:31 GMT, Dan Smith <dlsmith at openjdk.org> wrote:

> Integration of [JEP 390](https://bugs.openjdk.java.net/browse/JDK-8249100).
> 
> Development has been broken into 5 tasks, each with its own JBS issue:
> - Deprecate wrapper class constructors for removal
> - Revise "value-based class" & apply to wrappers
> - Define & apply annotation jdk.internal.ValueBased
> - Add 'lint' warning for @ValueBased classes
> - Diagnose synchronization on @ValueBased classes
> 
> All changes have been previously reviewed and integrated into the [`jep390` branch](https://github.com/openjdk/valhalla/tree/jep390) of the `valhalla` repository. See the subtasks of the 5 JBS issues for these changes, including discussion and links to reviews. (Reviewers: mchung, dlsmith, jlaskey, rriggs, lfoltan, fparain, hseigel.)
> 
> CSRs have also been completed or are nearly complete:
> 
> - [JDK-8254324](https://bugs.openjdk.java.net/browse/JDK-8254324) for wrapper class constructor deprecation
> - [JDK-8254944](https://bugs.openjdk.java.net/browse/JDK-8254944) for revisions to "value-based class"
> - [JDK-8256023](https://bugs.openjdk.java.net/browse/JDK-8256023) for new `javac` lint warnings
> 
> Here's an overview of the files changed:
> 
> - `src/hotspot`: implementing diagnostics when `monitorenter` is applied to an instance of a class tagged with `jdk.internal.ValueBased`. This enhances previous work that produced such diagnostics for the primitive wrapper classes.
> 
> - `src/java.base/share/classes/java/lang`: deprecating for removal the wrapper class constructors; revising the definition of "value-based class" in `ValueBased.html` and the description used by linking classes; applying "value-based class" to the primitive wrapper classes; marking value-based classes with `@jdk.internal.ValueBased`.
> 
> - `src/java.base/share/classes/java/lang/constant`: no longer designating these classes as "value-based", since they rely heavily on field inheritance.
> 
> - `src/java.base/share/classes/java/time`: revising the description used to link to `ValueBased.html`; marking value-based classes with `@jdk.internal.ValueBased`.
> 
> - `src/java.base/share/classes/java/util`: revising the description used to link to `ValueBased.html`; marking value-based classes with `@jdk.internal.ValueBased`.
> 
> - `src/java.base/share/classes/jdk/internal`: define the `@jdk.internal.ValueBased` annotation.
> 
> - `src/java.management.rmi`: removing uses of wrapper class constructors.
> 
> - `src/java.xml`: removing uses of wrapper class constructors.
> 
> - `src/jdk.compiler`: implementing the `synchronization` lint category, which reports attempts to synchronize on classes and interfaces annotated with `@jdk.internal.ValueBased`.
> 
> - `src/jdk.incubator.foreign`: revising the description used to link to `ValueBased.html`. (Applying `@jdk.internal.ValueBased` would require a special module export, which was not deemed necessary for an incubating API.)
> 
> - `src/jdk.internal.vm.compiler`: suppressing `javac` deprecation and synchronization warnings in tests
> 
> - `src/jdk.jfr`: supplementary changes for HotSpot diagnostics
> 
> - `test`: testing new `javac` and HotSpot behavior; removing usages of deprecated wrapper class constructors from tests, or suppressing deprecation warnings; revising the description used to link to `ValueBased.html`.

I've updated the description to provide an overview for those unfamiliar with this work. Reviewers are welcome, including those who have previously reviewed a subset of these changes.

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

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

From rriggs at openjdk.java.net  Mon Dec  7 15:08:12 2020
From: rriggs at openjdk.java.net (Roger Riggs)
Date: Mon, 7 Dec 2020 15:08:12 GMT
Subject: RFR: 8252180: [JEP 390] Deprecate wrapper class constructors for
 removal
In-Reply-To: <14WC4YuIN1sJ3jl5_htTC7wkzyzjpt540r7tmEQ85Lc=.4c5ac2b3-d24a-4aae-886b-b07e671f2948@github.com>
References: <14WC4YuIN1sJ3jl5_htTC7wkzyzjpt540r7tmEQ85Lc=.4c5ac2b3-d24a-4aae-886b-b07e671f2948@github.com>
Message-ID: <Fl-cWTaz17dK2mrEvx318D5ScjkL-up3gtWVzo9x9d4=.83b8febf-1f03-43f6-b836-b44c648e5801@github.com>

On Sat, 5 Dec 2020 01:46:31 GMT, Dan Smith <dlsmith at openjdk.org> wrote:

> Integration of [JEP 390](https://bugs.openjdk.java.net/browse/JDK-8249100).
> 
> Development has been broken into 5 tasks, each with its own JBS issue:
> - Deprecate wrapper class constructors for removal (rriggs)
> - Revise "value-based class" & apply to wrappers (dlsmith)
> - Define & apply annotation jdk.internal.ValueBased (rriggs)
> - Add 'lint' warning for @ValueBased classes (sadayapalam)
> - Diagnose synchronization on @ValueBased classes (lfoltan)
> 
> All changes have been previously reviewed and integrated into the [`jep390` branch](https://github.com/openjdk/valhalla/tree/jep390) of the `valhalla` repository. See the subtasks of the 5 JBS issues for these changes, including discussion and links to reviews. (Reviewers: mchung, dlsmith, jlaskey, rriggs, lfoltan, fparain, hseigel.)
> 
> CSRs have also been completed or are nearly complete:
> 
> - [JDK-8254324](https://bugs.openjdk.java.net/browse/JDK-8254324) for wrapper class constructor deprecation
> - [JDK-8254944](https://bugs.openjdk.java.net/browse/JDK-8254944) for revisions to "value-based class"
> - [JDK-8256023](https://bugs.openjdk.java.net/browse/JDK-8256023) for new `javac` lint warnings
> 
> Here's an overview of the files changed:
> 
> - `src/hotspot`: implementing diagnostics when `monitorenter` is applied to an instance of a class tagged with `jdk.internal.ValueBased`. This enhances previous work that produced such diagnostics for the primitive wrapper classes.
> 
> - `src/java.base/share/classes/java/lang`: deprecating for removal the wrapper class constructors; revising the definition of "value-based class" in `ValueBased.html` and the description used by linking classes; applying "value-based class" to the primitive wrapper classes; marking value-based classes with `@jdk.internal.ValueBased`.
> 
> - `src/java.base/share/classes/java/lang/constant`: no longer designating these classes as "value-based", since they rely heavily on field inheritance.
> 
> - `src/java.base/share/classes/java/time`: revising the description used to link to `ValueBased.html`; marking value-based classes with `@jdk.internal.ValueBased`.
> 
> - `src/java.base/share/classes/java/util`: revising the description used to link to `ValueBased.html`; marking value-based classes with `@jdk.internal.ValueBased`.
> 
> - `src/java.base/share/classes/jdk/internal`: define the `@jdk.internal.ValueBased` annotation.
> 
> - `src/java.management.rmi`: removing uses of wrapper class constructors.
> 
> - `src/java.xml`: removing uses of wrapper class constructors.
> 
> - `src/jdk.compiler`: implementing the `synchronization` lint category, which reports attempts to synchronize on classes and interfaces annotated with `@jdk.internal.ValueBased`.
> 
> - `src/jdk.incubator.foreign`: revising the description used to link to `ValueBased.html`. (Applying `@jdk.internal.ValueBased` would require a special module export, which was not deemed necessary for an incubating API.)
> 
> - `src/jdk.internal.vm.compiler`: suppressing `javac` deprecation and synchronization warnings in tests
> 
> - `src/jdk.jfr`: supplementary changes for HotSpot diagnostics
> 
> - `test`: testing new `javac` and HotSpot behavior; removing usages of deprecated wrapper class constructors from tests, or suppressing deprecation warnings; revising the description used to link to `ValueBased.html`.

For the core libraries parts looks ok.

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

Marked as reviewed by rriggs (Reviewer).

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

From hseigel at openjdk.java.net  Mon Dec  7 15:53:14 2020
From: hseigel at openjdk.java.net (Harold Seigel)
Date: Mon, 7 Dec 2020 15:53:14 GMT
Subject: RFR: 8252180: [JEP 390] Deprecate wrapper class constructors for
 removal
In-Reply-To: <14WC4YuIN1sJ3jl5_htTC7wkzyzjpt540r7tmEQ85Lc=.4c5ac2b3-d24a-4aae-886b-b07e671f2948@github.com>
References: <14WC4YuIN1sJ3jl5_htTC7wkzyzjpt540r7tmEQ85Lc=.4c5ac2b3-d24a-4aae-886b-b07e671f2948@github.com>
Message-ID: <DBXljSbfnxVvTWaB3vWYuroiHOTlz8ZVqocZR4JffNw=.1fbca489-56da-4190-ad5a-2fd42512ff59@github.com>

On Sat, 5 Dec 2020 01:46:31 GMT, Dan Smith <dlsmith at openjdk.org> wrote:

> Integration of [JEP 390](https://bugs.openjdk.java.net/browse/JDK-8249100).
> 
> Development has been broken into 5 tasks, each with its own JBS issue:
> - Deprecate wrapper class constructors for removal (rriggs)
> - Revise "value-based class" & apply to wrappers (dlsmith)
> - Define & apply annotation jdk.internal.ValueBased (rriggs)
> - Add 'lint' warning for @ValueBased classes (sadayapalam)
> - Diagnose synchronization on @ValueBased classes (lfoltan)
> 
> All changes have been previously reviewed and integrated into the [`jep390` branch](https://github.com/openjdk/valhalla/tree/jep390) of the `valhalla` repository. See the subtasks of the 5 JBS issues for these changes, including discussion and links to reviews. (Reviewers: mchung, dlsmith, jlaskey, rriggs, lfoltan, fparain, hseigel.)
> 
> CSRs have also been completed or are nearly complete:
> 
> - [JDK-8254324](https://bugs.openjdk.java.net/browse/JDK-8254324) for wrapper class constructor deprecation
> - [JDK-8254944](https://bugs.openjdk.java.net/browse/JDK-8254944) for revisions to "value-based class"
> - [JDK-8256023](https://bugs.openjdk.java.net/browse/JDK-8256023) for new `javac` lint warnings
> 
> Here's an overview of the files changed:
> 
> - `src/hotspot`: implementing diagnostics when `monitorenter` is applied to an instance of a class tagged with `jdk.internal.ValueBased`. This enhances previous work that produced such diagnostics for the primitive wrapper classes.
> 
> - `src/java.base/share/classes/java/lang`: deprecating for removal the wrapper class constructors; revising the definition of "value-based class" in `ValueBased.html` and the description used by linking classes; applying "value-based class" to the primitive wrapper classes; marking value-based classes with `@jdk.internal.ValueBased`.
> 
> - `src/java.base/share/classes/java/lang/constant`: no longer designating these classes as "value-based", since they rely heavily on field inheritance.
> 
> - `src/java.base/share/classes/java/time`: revising the description used to link to `ValueBased.html`; marking value-based classes with `@jdk.internal.ValueBased`.
> 
> - `src/java.base/share/classes/java/util`: revising the description used to link to `ValueBased.html`; marking value-based classes with `@jdk.internal.ValueBased`.
> 
> - `src/java.base/share/classes/jdk/internal`: define the `@jdk.internal.ValueBased` annotation.
> 
> - `src/java.management.rmi`: removing uses of wrapper class constructors.
> 
> - `src/java.xml`: removing uses of wrapper class constructors.
> 
> - `src/jdk.compiler`: implementing the `synchronization` lint category, which reports attempts to synchronize on classes and interfaces annotated with `@jdk.internal.ValueBased`.
> 
> - `src/jdk.incubator.foreign`: revising the description used to link to `ValueBased.html`. (Applying `@jdk.internal.ValueBased` would require a special module export, which was not deemed necessary for an incubating API.)
> 
> - `src/jdk.internal.vm.compiler`: suppressing `javac` deprecation and synchronization warnings in tests
> 
> - `src/jdk.jfr`: supplementary changes for HotSpot diagnostics
> 
> - `test`: testing new `javac` and HotSpot behavior; removing usages of deprecated wrapper class constructors from tests, or suppressing deprecation warnings; revising the description used to link to `ValueBased.html`.

The hotspot changes look good.  In a future change, could you add additional classes, such as ProcessHandle to test TestSyncOnValueBasedClassEvent.  Currently, it only tests primitive classes.

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

Marked as reviewed by hseigel (Reviewer).

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

From lfoltan at openjdk.java.net  Mon Dec  7 16:25:13 2020
From: lfoltan at openjdk.java.net (Lois Foltan)
Date: Mon, 7 Dec 2020 16:25:13 GMT
Subject: RFR: 8252180: [JEP 390] Deprecate wrapper class constructors for
 removal
In-Reply-To: <DBXljSbfnxVvTWaB3vWYuroiHOTlz8ZVqocZR4JffNw=.1fbca489-56da-4190-ad5a-2fd42512ff59@github.com>
References: <14WC4YuIN1sJ3jl5_htTC7wkzyzjpt540r7tmEQ85Lc=.4c5ac2b3-d24a-4aae-886b-b07e671f2948@github.com>
 <DBXljSbfnxVvTWaB3vWYuroiHOTlz8ZVqocZR4JffNw=.1fbca489-56da-4190-ad5a-2fd42512ff59@github.com>
Message-ID: <daRqe8BueKkQgPH9tjRo4guncvyjbw6wdG6szQDOXgY=.be84a3cc-ec84-47c6-8633-19206ee7525b@github.com>

On Mon, 7 Dec 2020 15:50:55 GMT, Harold Seigel <hseigel at openjdk.org> wrote:

>> Integration of [JEP 390](https://bugs.openjdk.java.net/browse/JDK-8249100).
>> 
>> Development has been broken into 5 tasks, each with its own JBS issue:
>> - Deprecate wrapper class constructors for removal (rriggs)
>> - Revise "value-based class" & apply to wrappers (dlsmith)
>> - Define & apply annotation jdk.internal.ValueBased (rriggs)
>> - Add 'lint' warning for @ValueBased classes (sadayapalam)
>> - Diagnose synchronization on @ValueBased classes (lfoltan)
>> 
>> All changes have been previously reviewed and integrated into the [`jep390` branch](https://github.com/openjdk/valhalla/tree/jep390) of the `valhalla` repository. See the subtasks of the 5 JBS issues for these changes, including discussion and links to reviews. (Reviewers: mchung, dlsmith, jlaskey, rriggs, lfoltan, fparain, hseigel.)
>> 
>> CSRs have also been completed or are nearly complete:
>> 
>> - [JDK-8254324](https://bugs.openjdk.java.net/browse/JDK-8254324) for wrapper class constructor deprecation
>> - [JDK-8254944](https://bugs.openjdk.java.net/browse/JDK-8254944) for revisions to "value-based class"
>> - [JDK-8256023](https://bugs.openjdk.java.net/browse/JDK-8256023) for new `javac` lint warnings
>> 
>> Here's an overview of the files changed:
>> 
>> - `src/hotspot`: implementing diagnostics when `monitorenter` is applied to an instance of a class tagged with `jdk.internal.ValueBased`. This enhances previous work that produced such diagnostics for the primitive wrapper classes.
>> 
>> - `src/java.base/share/classes/java/lang`: deprecating for removal the wrapper class constructors; revising the definition of "value-based class" in `ValueBased.html` and the description used by linking classes; applying "value-based class" to the primitive wrapper classes; marking value-based classes with `@jdk.internal.ValueBased`.
>> 
>> - `src/java.base/share/classes/java/lang/constant`: no longer designating these classes as "value-based", since they rely heavily on field inheritance.
>> 
>> - `src/java.base/share/classes/java/time`: revising the description used to link to `ValueBased.html`; marking value-based classes with `@jdk.internal.ValueBased`.
>> 
>> - `src/java.base/share/classes/java/util`: revising the description used to link to `ValueBased.html`; marking value-based classes with `@jdk.internal.ValueBased`.
>> 
>> - `src/java.base/share/classes/jdk/internal`: define the `@jdk.internal.ValueBased` annotation.
>> 
>> - `src/java.management.rmi`: removing uses of wrapper class constructors.
>> 
>> - `src/java.xml`: removing uses of wrapper class constructors.
>> 
>> - `src/jdk.compiler`: implementing the `synchronization` lint category, which reports attempts to synchronize on classes and interfaces annotated with `@jdk.internal.ValueBased`.
>> 
>> - `src/jdk.incubator.foreign`: revising the description used to link to `ValueBased.html`. (Applying `@jdk.internal.ValueBased` would require a special module export, which was not deemed necessary for an incubating API.)
>> 
>> - `src/jdk.internal.vm.compiler`: suppressing `javac` deprecation and synchronization warnings in tests
>> 
>> - `src/jdk.jfr`: supplementary changes for HotSpot diagnostics
>> 
>> - `test`: testing new `javac` and HotSpot behavior; removing usages of deprecated wrapper class constructors from tests, or suppressing deprecation warnings; revising the description used to link to `ValueBased.html`.
>
> The hotspot changes look good.  In a future change, could you add additional classes, such as ProcessHandle to test TestSyncOnValueBasedClassEvent.  Currently, it only tests primitive classes.

@hseigel thank you for the review.  I have created https://bugs.openjdk.java.net/browse/JDK-8257836 as an RFE to address additional testing.
Lois

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

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

From jjg at openjdk.java.net  Mon Dec  7 18:37:37 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 7 Dec 2020 18:37:37 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v6]
In-Reply-To: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
Message-ID: <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>

> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
> 
> The goal is to be able to simplify the following common pattern:
> 
>     /**
>      * Returns the result. Optional additional text.
>      * @return the result
>      */
>     int method() { 
> 
> by 
> 
>     /**
>      * {@return the result} Optional additional text.
>      */
>     int method() { 
> 
> Note:
> 
> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.

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

 - Merge remote-tracking branch 'upstream/master' into new-return
 - Update JShell to handle inline `{@return}`
 - Merge remote-tracking branch 'upstream/master' into new-return
 - fix test
 - Update for new `@return` tag
 - Merge remote-tracking branch 'upstream/master' into new-return
 - Update DocCommentParser to permit nested inline tags in specified cases: @return
 - Add default impl for new method
 - Fix test failure
 - Fix trailing whitespace in test
 - ... and 2 more: https://git.openjdk.java.net/jdk/compare/096e9a24...a25dadca

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/1355/files
  - new: https://git.openjdk.java.net/jdk/pull/1355/files/60ff9839..a25dadca

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

  Stats: 20689 lines in 549 files changed: 14531 ins; 4346 del; 1812 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1355.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1355/head:pull/1355

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

From prappo at openjdk.java.net  Tue Dec  8 17:59:24 2020
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 8 Dec 2020 17:59:24 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v6]
In-Reply-To: <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>
Message-ID: <6F0Kz14Rd1Wdz6odAtI3AcTeG-gD04RQuYFVO2gG8VA=.dd398953-4084-4fe0-99d4-e0f927b8c93b@github.com>

On Mon, 7 Dec 2020 18:37:37 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
>> 
>> The goal is to be able to simplify the following common pattern:
>> 
>>     /**
>>      * Returns the result. Optional additional text.
>>      * @return the result
>>      */
>>     int method() { 
>> 
>> by 
>> 
>>     /**
>>      * {@return the result} Optional additional text.
>>      */
>>     int method() { 
>> 
>> Note:
>> 
>> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
>> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
>> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
>> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 12 additional commits since the last revision:
> 
>  - Merge remote-tracking branch 'upstream/master' into new-return
>  - Update JShell to handle inline `{@return}`
>  - Merge remote-tracking branch 'upstream/master' into new-return
>  - fix test
>  - Update for new `@return` tag
>  - Merge remote-tracking branch 'upstream/master' into new-return
>  - Update DocCommentParser to permit nested inline tags in specified cases: @return
>  - Add default impl for new method
>  - Fix test failure
>  - Fix trailing whitespace in test
>  - ... and 2 more: https://git.openjdk.java.net/jdk/compare/8343a9ff...a25dadca

1. Although the change generally looks good, there are some issues that should be fixed.
2. I have NOT reviewed the `jdk.internal.shellsupport.doc` portion of the change in detail; please ask someone else to do that.
3. When I run this change through our CI, the `tools/javac/diags/CheckExamples.java` test fails consistently on all platforms. Try to merge with the latest `master` to rule out this PR as a cause.
4. Consider updating the copyright years when addressing this feedback.

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line 277:

> 275:      * @param description the description of the return value of a method
> 276:      * @return a {@code ReturnTree} object
> 277:      * @throws UnsupportedOperationException if inline {@code {@return} } tags are

To be consistent with the rest of the file, I suggest using `{@code {@return }}` instead of `{@code {@return} }` (note the position of the whitespace).

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

> 273:                         return tp.parse(p, TagParser.Kind.BLOCK);
> 274:                     } else {
> 275:                             return erroneous("dc.bad.inline.tag", p);

This indentation fits the current `switch` but not the proposed `if` statement.

src/jdk.compiler/share/classes/com/sun/source/doctree/ReturnTree.java line 44:

> 42:      * Returns whether this instance is an inline tag.
> 43:      *
> 44:      * @return {@code true} if this instance is an inline tag

Although I'm not sure how `boolean` queries are generally specified in the `DocTree` API, consider explicitly specifying that this method returns `false` if called on a non-inline instance.

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

> 331:                     DCTree text = inlineText(WhitespaceRetentionPolicy.REMOVE_ALL); // skip content
> 332:                     nextChar();
> 333:                     return m.at(p).newUnknownInlineTagTree(name, List.of(text)).setEndPos(bp);

There's a discrepancy between the inline comment and code. While the comment says that the `else` clause handles a block tag, the returned tree corresponds to an (unknown) inline tag.

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

> 1130: 
> 1131:     /**
> 1132:      * @see <a href="https://docs.oracle.com/en/java/javase/14/docs/specs/javadoc/doc-comment-spec.html">JavaDoc Tags</a>

Consider updating the version to 15. Later, we'd hopefully be able to use the [`@spec` tag](https://bugs.openjdk.java.net/browse/JDK-8226279) here.

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

> 1124:             return parse(pos);
> 1125:         }
> 1126:         DCTree parse(int pos) throws ParseException {

Please add an empty line between those two to separate the methods.

src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java line 690:

> 688: 
> 689:         @Override
> 690:         public String getTagName() {

Isn't this method missing `@DefinedBy(Api.COMPILER_TREE)`?

src/jdk.compiler/share/classes/jdk/internal/shellsupport/doc/JavadocFormatter.java line 268:

> 266:         /**
> 267:          * {@inheritDoc}
> 268:          * {@code @return} is a bimodfal tage and can be used as either a block tag or an inline

Fix the typos in "bimodfal tage".

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 60:

> 58: dc.param.name.not.found = @param name not found
> 59: dc.ref.not.found = reference not found
> 60: dc.return.not.first = '{@return'} not at beginning of description

I can see an inconsistency here. While the templates for `@return` and `@code` put an apostrophe immediately before the closing `}`, the template for `@value` (further below in this file) puts an apostrophe immediately after the closing `}`.

test/langtools/jdk/internal/shellsupport/doc/JavadocFormatterTest.java line 140:

> 138:                    "1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234\n" +
> 139:                    "1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234\n" +
> 140:                    "1234 1234 1234 1234 1234 1234 1234 1234 1234 \n";

What's that about? I mean is it related to this work on `{@return}`?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java line 76:

> 74:         } else {
> 75:             List<? extends DocTree> firstSentence = utils.getFirstSentenceTrees(input.element);
> 76:             if (firstSentence.size() == 1 && firstSentence.get(0).getKind() == DocTree.Kind.RETURN) {

There's one more place where `firstSentence.size() == 1` is checked. I wonder if it could be a simpler `!firstSentence.isEmpty()` check?

Are there any non-trivial cases which might bite us later, should we change that check?

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

Changes requested by prappo (Reviewer).

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

From jjg at openjdk.java.net  Tue Dec  8 19:23:44 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 8 Dec 2020 19:23:44 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v6]
In-Reply-To: <6F0Kz14Rd1Wdz6odAtI3AcTeG-gD04RQuYFVO2gG8VA=.dd398953-4084-4fe0-99d4-e0f927b8c93b@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>
 <6F0Kz14Rd1Wdz6odAtI3AcTeG-gD04RQuYFVO2gG8VA=.dd398953-4084-4fe0-99d4-e0f927b8c93b@github.com>
Message-ID: <BPErLUd1SVfqJPhQGYSya8GbuKRYBJ3JX-Lt3sgY59E=.d2c83ac6-38a9-49a7-bbd7-4ff567fc159d@github.com>

On Tue, 8 Dec 2020 13:14:19 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 12 additional commits since the last revision:
>> 
>>  - Merge remote-tracking branch 'upstream/master' into new-return
>>  - Update JShell to handle inline `{@return}`
>>  - Merge remote-tracking branch 'upstream/master' into new-return
>>  - fix test
>>  - Update for new `@return` tag
>>  - Merge remote-tracking branch 'upstream/master' into new-return
>>  - Update DocCommentParser to permit nested inline tags in specified cases: @return
>>  - Add default impl for new method
>>  - Fix test failure
>>  - Fix trailing whitespace in test
>>  - ... and 2 more: https://git.openjdk.java.net/jdk/compare/c3337822...a25dadca
>
> src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line 277:
> 
>> 275:      * @param description the description of the return value of a method
>> 276:      * @return a {@code ReturnTree} object
>> 277:      * @throws UnsupportedOperationException if inline {@code {@return} } tags are
> 
> To be consistent with the rest of the file, I suggest using `{@code {@return }}` instead of `{@code {@return} }` (note the position of the whitespace).

fixed

> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 275:
> 
>> 273:                         return tp.parse(p, TagParser.Kind.BLOCK);
>> 274:                     } else {
>> 275:                             return erroneous("dc.bad.inline.tag", p);
> 
> This indentation fits the current `switch` but not the proposed `if` statement.

fixed

> src/jdk.compiler/share/classes/com/sun/source/doctree/ReturnTree.java line 44:
> 
>> 42:      * Returns whether this instance is an inline tag.
>> 43:      *
>> 44:      * @return {@code true} if this instance is an inline tag
> 
> Although I'm not sure how `boolean` queries are generally specified in the `DocTree` API, consider explicitly specifying that this method returns `false` if called on a non-inline instance.

hmm, OK, seems a bit redundant but will add `and {@code false} otherwise`

> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 333:
> 
>> 331:                     DCTree text = inlineText(WhitespaceRetentionPolicy.REMOVE_ALL); // skip content
>> 332:                     nextChar();
>> 333:                     return m.at(p).newUnknownInlineTagTree(name, List.of(text)).setEndPos(bp);
> 
> There's a discrepancy between the inline comment and code. While the comment says that the `else` clause handles a block tag, the returned tree corresponds to an (unknown) inline tag.

The code is correct, and even the comment: which refers to "block tags in inline content".
The case being handled is one like this:

`
    /**
     * This is a bad comment. {@see Object} or {@since 7}.
     */
`

> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1132:
> 
>> 1130: 
>> 1131:     /**
>> 1132:      * @see <a href="https://docs.oracle.com/en/java/javase/14/docs/specs/javadoc/doc-comment-spec.html">JavaDoc Tags</a>
> 
> Consider updating the version to 15. Later, we'd hopefully be able to use the [`@spec` tag](https://bugs.openjdk.java.net/browse/JDK-8226279) here.

done

Yes, this could eventually be a use of the proposed `@spec` tag with a relative URL

> src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java line 690:
> 
>> 688: 
>> 689:         @Override
>> 690:         public String getTagName() {
> 
> Isn't this method missing `@DefinedBy(Api.COMPILER_TREE)`?

Oops, yes; fixed; I guess I'm mildly surprised the checker didn't catch it, but that's a different issue

> src/jdk.compiler/share/classes/jdk/internal/shellsupport/doc/JavadocFormatter.java line 268:
> 
>> 266:         /**
>> 267:          * {@inheritDoc}
>> 268:          * {@code @return} is a bimodfal tage and can be used as either a block tag or an inline
> 
> Fix the typos in "bimodfal tage".

Oops, also fixed an instance of `null` to `{@code null}`

> test/langtools/jdk/internal/shellsupport/doc/JavadocFormatterTest.java line 140:
> 
>> 138:                    "1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234\n" +
>> 139:                    "1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234\n" +
>> 140:                    "1234 1234 1234 1234 1234 1234 1234 1234 1234 \n";
> 
> What's that about? I mean is it related to this work on `{@return}`?

It was needed to fix a test failure

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

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

From jjg at openjdk.java.net  Tue Dec  8 19:31:49 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 8 Dec 2020 19:31:49 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v6]
In-Reply-To: <6F0Kz14Rd1Wdz6odAtI3AcTeG-gD04RQuYFVO2gG8VA=.dd398953-4084-4fe0-99d4-e0f927b8c93b@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>
 <6F0Kz14Rd1Wdz6odAtI3AcTeG-gD04RQuYFVO2gG8VA=.dd398953-4084-4fe0-99d4-e0f927b8c93b@github.com>
Message-ID: <Hu07LLzaL2T4Mce31UlhLUFYqA6ht6OPCOEv777eyx8=.ffcdbb13-f14d-4211-9658-7186c03c71c8@github.com>

On Tue, 8 Dec 2020 17:52:14 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 12 additional commits since the last revision:
>> 
>>  - Merge remote-tracking branch 'upstream/master' into new-return
>>  - Update JShell to handle inline `{@return}`
>>  - Merge remote-tracking branch 'upstream/master' into new-return
>>  - fix test
>>  - Update for new `@return` tag
>>  - Merge remote-tracking branch 'upstream/master' into new-return
>>  - Update DocCommentParser to permit nested inline tags in specified cases: @return
>>  - Add default impl for new method
>>  - Fix test failure
>>  - Fix trailing whitespace in test
>>  - ... and 2 more: https://git.openjdk.java.net/jdk/compare/695b9bdc...a25dadca
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java line 76:
> 
>> 74:         } else {
>> 75:             List<? extends DocTree> firstSentence = utils.getFirstSentenceTrees(input.element);
>> 76:             if (firstSentence.size() == 1 && firstSentence.get(0).getKind() == DocTree.Kind.RETURN) {
> 
> There's one more place where `firstSentence.size() == 1` is checked. I wonder if it could be a simpler `!firstSentence.isEmpty()` check?
> 
> Are there any non-trivial cases which might bite us later, should we change that check?

I think the code is better as is.  It would be wrong to have a firstSentence containing multiple items, beginning with `{@return}` and then to only return the first one in the following line of code. Arguably, a better form may be to use `isEmpty()` and then subsequently assert (somehow) that the size is exactly 1, but using assertions like that is a different discussion (as you know!)

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 60:
> 
>> 58: dc.param.name.not.found = @param name not found
>> 59: dc.ref.not.found = reference not found
>> 60: dc.return.not.first = '{@return'} not at beginning of description
> 
> I can see an inconsistency here. While the templates for `@return` and `@code` put an apostrophe immediately before the closing `}`, the template for `@value` (further below in this file) puts an apostrophe immediately after the closing `}`.

I'll investigate and follow up.  It looks like general confusion whether to escape the curly braces, or to quote the enclosed text in the generated message.

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

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

From jlahoda at openjdk.java.net  Tue Dec  8 19:35:03 2020
From: jlahoda at openjdk.java.net (Jan Lahoda)
Date: Tue, 8 Dec 2020 19:35:03 GMT
Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12
 [v12]
In-Reply-To: <RRMAPzh6xcVcxOj2S_VW_r50YvZz-3Imaj46bDi8e9U=.9347534e-d482-468a-8668-132d5516bb76@github.com>
References: <RRMAPzh6xcVcxOj2S_VW_r50YvZz-3Imaj46bDi8e9U=.9347534e-d482-468a-8668-132d5516bb76@github.com>
Message-ID: <mCFx_-zaZljumWnBwZfRwVqIs2zBHbQXMec4CBaQKS8=.f75babcd-333b-427d-9152-6f386736bb7f@github.com>

> This is an update to javac and javadoc, to introduce support for Preview APIs, and generally improve javac and javadoc behavior to more closely adhere to JEP 12.
> 
> The notable changes are:
> 
>  * adding support for Preview APIs (javac until now supported primarily only preview language features, and APIs associated with preview language features). This includes:
>      * the @PreviewFeature annotation has boolean attribute "reflective", which should be true for reflective Preview APIs, false otherwise. This replaces the existing "essentialAPI" attribute with roughly inverted meaning.
>      * the preview warnings for preview APIs are auto-suppressed as described in the JEP 12. E.g. the module that declares the preview API is free to use it without warnings
>  * improving error/warning messages. Please see [1] for a list of cases/examples.
>  * class files are only marked as preview if they are using a preview feature. [1] also shows if a class file is marked as preview or not.
>  * the PreviewFeature annotation has been moved to jdk.internal.javac package (originally was in the jdk.internal package).
>  * Preview API in JDK's javadoc no longer needs to specify @preview tag in the source files. javadoc will auto-generate a note for @PreviewFeature elements, see e.g. [2] and [3] (non-reflective and reflective API, respectively). A summary of preview elements is also provided [4]. Existing uses of @preview have been updated/removed.
>  * non-JDK javadoc is also enhanced to auto-generate preview notes for uses of Preview elements, and for declaring elements using preview language features [5].
>  
>  Please also see the CSR [6] for more information.
>  
>  [1] http://cr.openjdk.java.net/~jlahoda/8250768/JEP12-errors-warnings-v6.html
>  [2] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.base/java/lang/Record.html
>  [3] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.compiler/javax/lang/model/element/RecordComponentElement.html
>  [4] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/preview-list.html
>  [5] http://cr.openjdk.java.net/~jlahoda/8250768/test.javadoc.00/
>  [6] https://bugs.openjdk.java.net/browse/JDK-8250769

Jan Lahoda has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 55 commits:

 - Merging recent master changes into JDK-8250768
 - Fixing navigator for the PREVIEW page.
 - Fixing typo.
 - Removing obsolette @PreviewFeature.
 - Merging master into JDK-8250768
 - Removing unnecessary property keys.
 - Cleanup - removing unnecessary code.
 - Merging master into JDK-8250768-dev4
 - Reflecting review comments.
 - Removing trailing whitespace.
 - ... and 45 more: https://git.openjdk.java.net/jdk/compare/044616bd...0c1c4d57

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

Changes: https://git.openjdk.java.net/jdk/pull/703/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=11
  Stats: 3711 lines in 132 files changed: 2726 ins; 692 del; 293 mod
  Patch: https://git.openjdk.java.net/jdk/pull/703.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/703/head:pull/703

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

From jjg at openjdk.java.net  Tue Dec  8 19:39:34 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 8 Dec 2020 19:39:34 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v6]
In-Reply-To: <Hu07LLzaL2T4Mce31UlhLUFYqA6ht6OPCOEv777eyx8=.ffcdbb13-f14d-4211-9658-7186c03c71c8@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>
 <6F0Kz14Rd1Wdz6odAtI3AcTeG-gD04RQuYFVO2gG8VA=.dd398953-4084-4fe0-99d4-e0f927b8c93b@github.com>
 <Hu07LLzaL2T4Mce31UlhLUFYqA6ht6OPCOEv777eyx8=.ffcdbb13-f14d-4211-9658-7186c03c71c8@github.com>
Message-ID: <o_s2YWGXPZW407TYuwVobzRSb2tHHod3h77Z13Xc4VA=.533ca947-c406-4a13-b506-2b5edfc1302d@github.com>

On Tue, 8 Dec 2020 19:29:15 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 60:
>> 
>>> 58: dc.param.name.not.found = @param name not found
>>> 59: dc.ref.not.found = reference not found
>>> 60: dc.return.not.first = '{@return'} not at beginning of description
>> 
>> I can see an inconsistency here. While the templates for `@return` and `@code` put an apostrophe immediately before the closing `}`, the template for `@value` (further below in this file) puts an apostrophe immediately after the closing `}`.
>
> I'll investigate and follow up.  It looks like general confusion whether to escape the curly braces, or to quote the enclosed text in the generated message.

It looks like the quotes are never needed. I'll remove all of them.

`
/**
 * This is a comment.
 * This is a bad {@return fred}
 * This is a bad {@value}
 * This is a bad <code>{@code code}</code>.
 */
public class C { }
`

`
play/doclint-msgs/src/C.java:3: warning: {@return} not at beginning of description
 * This is a bad {@return fred}
                 ^
play/doclint-msgs/src/C.java:3: error: invalid use of @return
 * This is a bad {@return fred}
                 ^
play/doclint-msgs/src/C.java:4: error: {@value} not allowed here
 * This is a bad {@value}
                 ^
play/doclint-msgs/src/C.java:5: warning: {@code} within <code>
 * This is a bad <code>{@code code}</code>.
                       ^
2 errors
2 warnings
`

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

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

From jlahoda at openjdk.java.net  Tue Dec  8 20:34:42 2020
From: jlahoda at openjdk.java.net (Jan Lahoda)
Date: Tue, 8 Dec 2020 20:34:42 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v6]
In-Reply-To: <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>
Message-ID: <cbBEBOyQa9TuERImoX5p141C30qmLcyGZbz1u754r4I=.42841c51-d38b-4fff-8599-c1a27efcba00@github.com>

On Mon, 7 Dec 2020 18:37:37 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
>> 
>> The goal is to be able to simplify the following common pattern:
>> 
>>     /**
>>      * Returns the result. Optional additional text.
>>      * @return the result
>>      */
>>     int method() { 
>> 
>> by 
>> 
>>     /**
>>      * {@return the result} Optional additional text.
>>      */
>>     int method() { 
>> 
>> Note:
>> 
>> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
>> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
>> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
>> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 12 additional commits since the last revision:
> 
>  - Merge remote-tracking branch 'upstream/master' into new-return
>  - Update JShell to handle inline `{@return}`
>  - Merge remote-tracking branch 'upstream/master' into new-return
>  - fix test
>  - Update for new `@return` tag
>  - Merge remote-tracking branch 'upstream/master' into new-return
>  - Update DocCommentParser to permit nested inline tags in specified cases: @return
>  - Add default impl for new method
>  - Fix test failure
>  - Fix trailing whitespace in test
>  - ... and 2 more: https://git.openjdk.java.net/jdk/compare/d5251c03...a25dadca

The javac/jshell changes look sensible to me.

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

Marked as reviewed by jlahoda (Reviewer).

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

From jlahoda at openjdk.java.net  Tue Dec  8 20:34:45 2020
From: jlahoda at openjdk.java.net (Jan Lahoda)
Date: Tue, 8 Dec 2020 20:34:45 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v6]
In-Reply-To: <BPErLUd1SVfqJPhQGYSya8GbuKRYBJ3JX-Lt3sgY59E=.d2c83ac6-38a9-49a7-bbd7-4ff567fc159d@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>
 <6F0Kz14Rd1Wdz6odAtI3AcTeG-gD04RQuYFVO2gG8VA=.dd398953-4084-4fe0-99d4-e0f927b8c93b@github.com>
 <BPErLUd1SVfqJPhQGYSya8GbuKRYBJ3JX-Lt3sgY59E=.d2c83ac6-38a9-49a7-bbd7-4ff567fc159d@github.com>
Message-ID: <JnQtc3k2pGLwvCgsDVXMJqmkEDw-yHZN8lEDFt_F_O8=.d18d689c-8ca4-4cbf-a367-9f32dffff3b0@github.com>

On Tue, 8 Dec 2020 19:21:10 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> test/langtools/jdk/internal/shellsupport/doc/JavadocFormatterTest.java line 140:
>> 
>>> 138:                    "1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234\n" +
>>> 139:                    "1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234 1234\n" +
>>> 140:                    "1234 1234 1234 1234 1234 1234 1234 1234 1234 \n";
>> 
>> What's that about? I mean is it related to this work on `{@return}`?
>
> It was needed to fix a test failure

FWIW, I believe the reason is that JavadocFormatter.scan (around line 580 in the new code) is checking for inline tags using the instanceof operator, and adds a space for inline tags. We could add a test to prevent that (i.e. not add the space , but not sure if there is a real problem with generating the space.

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

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

From jjg at openjdk.java.net  Tue Dec  8 21:07:00 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 8 Dec 2020 21:07:00 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v7]
In-Reply-To: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
Message-ID: <mxzmCSyd8Tsa_oLe3y6UyWZQ3TnGesro59Pw8uWA8R4=.190db47e-27d1-4710-a20f-f1202017cc2f@github.com>

> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
> 
> The goal is to be able to simplify the following common pattern:
> 
>     /**
>      * Returns the result. Optional additional text.
>      * @return the result
>      */
>     int method() { 
> 
> by 
> 
>     /**
>      * {@return the result} Optional additional text.
>      */
>     int method() { 
> 
> Note:
> 
> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.

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

 - Merge remote-tracking branch 'upstream/master' into new-return
 - Merge remote-tracking branch 'upstream/master' into new-return
 - Update JShell to handle inline `{@return}`
 - Merge remote-tracking branch 'upstream/master' into new-return
 - fix test
 - Update for new `@return` tag
 - Merge remote-tracking branch 'upstream/master' into new-return
 - Update DocCommentParser to permit nested inline tags in specified cases: @return
 - Add default impl for new method
 - Fix test failure
 - ... and 3 more: https://git.openjdk.java.net/jdk/compare/8575ca29...95e21512

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/1355/files
  - new: https://git.openjdk.java.net/jdk/pull/1355/files/a25dadca..95e21512

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

  Stats: 2176 lines in 64 files changed: 1570 ins; 338 del; 268 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1355.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1355/head:pull/1355

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

From jjg at openjdk.java.net  Tue Dec  8 21:10:56 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 8 Dec 2020 21:10:56 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v8]
In-Reply-To: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
Message-ID: <634yP2cV-UXVQEBl4kwtb24ktGnQecgdVpAMb_AiZks=.828a786e-374d-4d1f-b8b9-7d5df67fc4ac@github.com>

> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
> 
> The goal is to be able to simplify the following common pattern:
> 
>     /**
>      * Returns the result. Optional additional text.
>      * @return the result
>      */
>     int method() { 
> 
> by 
> 
>     /**
>      * {@return the result} Optional additional text.
>      */
>     int method() { 
> 
> Note:
> 
> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.

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

  address review comments

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/1355/files
  - new: https://git.openjdk.java.net/jdk/pull/1355/files/95e21512..8f62f5a9

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

  Stats: 15 lines in 9 files changed: 1 ins; 0 del; 14 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1355.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1355/head:pull/1355

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

From jjg at openjdk.java.net  Tue Dec  8 22:03:40 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 8 Dec 2020 22:03:40 GMT
Subject: RFR: 8256580: Fault in new grid display
In-Reply-To: <Ff4ormFbLQifLdgBYcydHyFtlXOnCXIvQrsbu_9Zngo=.edc5cdb3-9ac9-444d-9445-75a8d3705d07@github.com>
References: <Ff4ormFbLQifLdgBYcydHyFtlXOnCXIvQrsbu_9Zngo=.edc5cdb3-9ac9-444d-9445-75a8d3705d07@github.com>
Message-ID: <mrY3WZg9yZk-A7aHUwK3GqRG2j9UOdyuTZ8esz-Ytzo=.dba22d08-e533-4e81-afb4-8bc91dbe007e@github.com>

On Wed, 25 Nov 2020 15:58:50 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This change makes sure empty cells in summary tables are not dropped, which was the case when the `-nocomment` option was used. 
> 
> It also adds tests to check summary table contents both in normal operation and with `-nocomment` option.

Marked as reviewed by jjg (Reviewer).

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

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

From prappo at openjdk.java.net  Tue Dec  8 22:42:36 2020
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 8 Dec 2020 22:42:36 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v6]
In-Reply-To: <Hu07LLzaL2T4Mce31UlhLUFYqA6ht6OPCOEv777eyx8=.ffcdbb13-f14d-4211-9658-7186c03c71c8@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <r6x0B8EUk4UVr8bP6gCQ4FS63wxnQLg6uhDHyjQ5cvA=.b27e6dc8-35c1-4360-b62d-e0aa196e6f4a@github.com>
 <6F0Kz14Rd1Wdz6odAtI3AcTeG-gD04RQuYFVO2gG8VA=.dd398953-4084-4fe0-99d4-e0f927b8c93b@github.com>
 <Hu07LLzaL2T4Mce31UlhLUFYqA6ht6OPCOEv777eyx8=.ffcdbb13-f14d-4211-9658-7186c03c71c8@github.com>
Message-ID: <4j3lZSRTfTYC5-97JUGuY0sYDP3c8h_VOSK3XuGWAGw=.0b3cf943-207a-43b9-a9a7-15fd361d109b@github.com>

On Tue, 8 Dec 2020 19:27:32 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java line 76:
>> 
>>> 74:         } else {
>>> 75:             List<? extends DocTree> firstSentence = utils.getFirstSentenceTrees(input.element);
>>> 76:             if (firstSentence.size() == 1 && firstSentence.get(0).getKind() == DocTree.Kind.RETURN) {
>> 
>> There's one more place where `firstSentence.size() == 1` is checked. I wonder if it could be a simpler `!firstSentence.isEmpty()` check?
>> 
>> Are there any non-trivial cases which might bite us later, should we change that check?
>
> I think the code is better as is.  It would be wrong to have a firstSentence containing multiple items, beginning with `{@return}` and then to only return the first one in the following line of code. Arguably, a better form may be to use `isEmpty()` and then subsequently assert (somehow) that the size is exactly 1, but using assertions like that is a different discussion (as you know!)

I guess I was thinking about a corner case like `{@summary {@return ...} ...}` which this patch and the complementary specification consider illegal anyway.

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

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

From prappo at openjdk.java.net  Tue Dec  8 22:58:36 2020
From: prappo at openjdk.java.net (Pavel Rappo)
Date: Tue, 8 Dec 2020 22:58:36 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v8]
In-Reply-To: <634yP2cV-UXVQEBl4kwtb24ktGnQecgdVpAMb_AiZks=.828a786e-374d-4d1f-b8b9-7d5df67fc4ac@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
 <634yP2cV-UXVQEBl4kwtb24ktGnQecgdVpAMb_AiZks=.828a786e-374d-4d1f-b8b9-7d5df67fc4ac@github.com>
Message-ID: <XTY6lPbLJn623b7zk4vK2rzR84wmFyWCSG9g0-paNmQ=.40ef6310-690c-41ee-8ade-a0b55ed163c0@github.com>

On Tue, 8 Dec 2020 21:10:56 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
>> 
>> The goal is to be able to simplify the following common pattern:
>> 
>>     /**
>>      * Returns the result. Optional additional text.
>>      * @return the result
>>      */
>>     int method() { 
>> 
>> by 
>> 
>>     /**
>>      * {@return the result} Optional additional text.
>>      */
>>     int method() { 
>> 
>> Note:
>> 
>> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
>> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
>> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
>> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   address review comments

Thanks for considering my feedback.

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

Marked as reviewed by prappo (Reviewer).

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

From jjg at openjdk.java.net  Tue Dec  8 23:29:52 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 8 Dec 2020 23:29:52 GMT
Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return
 information in simple situations. [v9]
In-Reply-To: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
Message-ID: <6rIohEbesequmBRim0-RlliTSWpOD4_gkEKHUggfxLc=.ce34ae75-952c-4c7c-bb3c-9d3dcaece7f3@github.com>

> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
> 
> The goal is to be able to simplify the following common pattern:
> 
>     /**
>      * Returns the result. Optional additional text.
>      * @return the result
>      */
>     int method() { 
> 
> by 
> 
>     /**
>      * {@return the result} Optional additional text.
>      */
>     int method() { 
> 
> Note:
> 
> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.

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

  fix whitespace

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/1355/files
  - new: https://git.openjdk.java.net/jdk/pull/1355/files/8f62f5a9..58a6e7ed

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

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

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

From jjg at openjdk.java.net  Tue Dec  8 23:29:53 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 8 Dec 2020 23:29:53 GMT
Subject: Integrated: JDK-8075778: Add javadoc tag to avoid duplication of
 return information in simple situations.
In-Reply-To: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
References: <fZzUIlQpgbewvdAaP7Bkwh-z_IHxJvxVznbKkFj7CVM=.677c60ee-19f8-43bd-bc3a-339519e5da7f@github.com>
Message-ID: <g5PLwdDcYAhThp-7DESph5GUCyCYhfIjDGImiXPGQWQ=.70b17b5f-efff-4cd4-9639-40f10d1acd0b@github.com>

On Fri, 20 Nov 2020 17:15:22 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description.
> 
> The goal is to be able to simplify the following common pattern:
> 
>     /**
>      * Returns the result. Optional additional text.
>      * @return the result
>      */
>     int method() { 
> 
> by 
> 
>     /**
>      * {@return the result} Optional additional text.
>      */
>     int method() { 
> 
> Note:
> 
> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere.
> * The expansion of the inline tag is `Returns " _content_ `.`  where _content_ is the content of the tag. 
> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description
> * The inline tag can be inherited into overriding methods as if it was provided as a block tag.

This pull request has now been integrated.

Changeset: b29f9cd7
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/b29f9cd7
Stats:     696 lines in 21 files changed: 584 ins; 29 del; 83 mod

8075778: Add javadoc tag to avoid duplication of return information in simple situations.

Reviewed-by: prappo, jlahoda

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

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

From hannesw at openjdk.java.net  Wed Dec  9 09:24:35 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 9 Dec 2020 09:24:35 GMT
Subject: Integrated: 8256580: Fault in new grid display
In-Reply-To: <Ff4ormFbLQifLdgBYcydHyFtlXOnCXIvQrsbu_9Zngo=.edc5cdb3-9ac9-444d-9445-75a8d3705d07@github.com>
References: <Ff4ormFbLQifLdgBYcydHyFtlXOnCXIvQrsbu_9Zngo=.edc5cdb3-9ac9-444d-9445-75a8d3705d07@github.com>
Message-ID: <DeJ7p2YgXctsJ18-6It0oW4nfDqul_ZnlIkcl-KWLfY=.5e655069-a20e-415f-9f39-06e5f08e791f@github.com>

On Wed, 25 Nov 2020 15:58:50 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This change makes sure empty cells in summary tables are not dropped, which was the case when the `-nocomment` option was used. 
> 
> It also adds tests to check summary table contents both in normal operation and with `-nocomment` option.

This pull request has now been integrated.

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

8256580: Fault in new grid display

Reviewed-by: jjg

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

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

From ihse at openjdk.java.net  Wed Dec  9 13:32:43 2020
From: ihse at openjdk.java.net (Magnus Ihse Bursie)
Date: Wed, 9 Dec 2020 13:32:43 GMT
Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12
 [v12]
In-Reply-To: <mCFx_-zaZljumWnBwZfRwVqIs2zBHbQXMec4CBaQKS8=.f75babcd-333b-427d-9152-6f386736bb7f@github.com>
References: <RRMAPzh6xcVcxOj2S_VW_r50YvZz-3Imaj46bDi8e9U=.9347534e-d482-468a-8668-132d5516bb76@github.com>
 <mCFx_-zaZljumWnBwZfRwVqIs2zBHbQXMec4CBaQKS8=.f75babcd-333b-427d-9152-6f386736bb7f@github.com>
Message-ID: <k1SYjoM2awbCbJ9aK3_biTQRgLTIa62VlyOOqi1-IHQ=.c33493b3-4c7e-409e-b02d-13cdc467d71f@github.com>

On Tue, 8 Dec 2020 19:35:03 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

>> This is an update to javac and javadoc, to introduce support for Preview APIs, and generally improve javac and javadoc behavior to more closely adhere to JEP 12.
>> 
>> The notable changes are:
>> 
>>  * adding support for Preview APIs (javac until now supported primarily only preview language features, and APIs associated with preview language features). This includes:
>>      * the @PreviewFeature annotation has boolean attribute "reflective", which should be true for reflective Preview APIs, false otherwise. This replaces the existing "essentialAPI" attribute with roughly inverted meaning.
>>      * the preview warnings for preview APIs are auto-suppressed as described in the JEP 12. E.g. the module that declares the preview API is free to use it without warnings
>>  * improving error/warning messages. Please see [1] for a list of cases/examples.
>>  * class files are only marked as preview if they are using a preview feature. [1] also shows if a class file is marked as preview or not.
>>  * the PreviewFeature annotation has been moved to jdk.internal.javac package (originally was in the jdk.internal package).
>>  * Preview API in JDK's javadoc no longer needs to specify @preview tag in the source files. javadoc will auto-generate a note for @PreviewFeature elements, see e.g. [2] and [3] (non-reflective and reflective API, respectively). A summary of preview elements is also provided [4]. Existing uses of @preview have been updated/removed.
>>  * non-JDK javadoc is also enhanced to auto-generate preview notes for uses of Preview elements, and for declaring elements using preview language features [5].
>>  
>>  Please also see the CSR [6] for more information.
>>  
>>  [1] http://cr.openjdk.java.net/~jlahoda/8250768/JEP12-errors-warnings-v6.html
>>  [2] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.base/java/lang/Record.html
>>  [3] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.compiler/javax/lang/model/element/RecordComponentElement.html
>>  [4] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/preview-list.html
>>  [5] http://cr.openjdk.java.net/~jlahoda/8250768/test.javadoc.00/
>>  [6] https://bugs.openjdk.java.net/browse/JDK-8250769
>
> Jan Lahoda has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 55 commits:
> 
>  - Merging recent master changes into JDK-8250768
>  - Fixing navigator for the PREVIEW page.
>  - Fixing typo.
>  - Removing obsolette @PreviewFeature.
>  - Merging master into JDK-8250768
>  - Removing unnecessary property keys.
>  - Cleanup - removing unnecessary code.
>  - Merging master into JDK-8250768-dev4
>  - Reflecting review comments.
>  - Removing trailing whitespace.
>  - ... and 45 more: https://git.openjdk.java.net/jdk/compare/044616bd...0c1c4d57

Build changes still good.

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

Marked as reviewed by ihse (Reviewer).

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

From hannesw at openjdk.java.net  Thu Dec 10 13:25:48 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 10 Dec 2020 13:25:48 GMT
Subject: RFR: 8223607: --override-methods=summary ignores some signature
 changes
Message-ID: <h5-58f5Q1E-u5-z14_MedqI_uzzzKDZjRVl1Hv4DC_k=.24aa42fc-ac49-476d-a504-b1ef8c740066@github.com>

This change causes overriding methods to be documented in the details section under some conditions even when javadoc is run with `--override-methods=summary` and the method does not have a doc comment. Previously this already happened when the overriding method had a covariant return type (JDK-8219147). The following conditions will now trigger the same behaviour:

 - method visibility changes from `protected` to `public`
 - any change in thrown exceptions
 - change in documented annotations anywhere in the method signature

The conditions are simple by intention as we don't want to do checks that add to much complexity (such as distinguishing between checked and unchecked exceptions) and instead want to set the bar for inclusion in the details section relatively low.

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

Commit messages:
 - JDK-8223607: --overridden-methods=summary ignores some signature changes

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

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

From iignatyev at openjdk.java.net  Thu Dec 10 18:13:06 2020
From: iignatyev at openjdk.java.net (Igor Ignatyev)
Date: Thu, 10 Dec 2020 18:13:06 GMT
Subject: RFR: 8258056:
 jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java fails against
 jdk17
Message-ID: <PazMh3FhCkLfyWIyoBFRcCjmOysCmL7Q0a7gn0hPQfw=.27accea1-2be4-4249-8927-5410ba228526@github.com>

Hi all,

could you pleaes review this small and trivial fix for `jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java` test? the test faled to find "https://download.java.net/java/early_access/jdk16/" string after we switched to jdk17, the patch is basically `s/jdk16/jdk17/g`.

testing: `test/langtools/jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java`

Thanks,
-- Igor

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

Commit messages:
 - 8258056: jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java fails against jdk17

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

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

From jwilhelm at openjdk.java.net  Thu Dec 10 20:20:56 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 10 Dec 2020 20:20:56 GMT
Subject: RFR: 8258056:
 jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java fails against
 jdk17
In-Reply-To: <PazMh3FhCkLfyWIyoBFRcCjmOysCmL7Q0a7gn0hPQfw=.27accea1-2be4-4249-8927-5410ba228526@github.com>
References: <PazMh3FhCkLfyWIyoBFRcCjmOysCmL7Q0a7gn0hPQfw=.27accea1-2be4-4249-8927-5410ba228526@github.com>
Message-ID: <SEwBdluivvsqSTxPtFD-r6E34TynkDSGxcrvdYG5yq4=.5a53dfb0-5b89-4687-89f0-b543c2b01576@github.com>

On Thu, 10 Dec 2020 18:07:32 GMT, Igor Ignatyev <iignatyev at openjdk.org> wrote:

> Hi all,
> 
> could you pleaes review this small and trivial fix for `jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java` test? the test faled to find "https://download.java.net/java/early_access/jdk16/" string after we switched to jdk17, the patch is basically `s/jdk16/jdk17/g`.
> 
> testing: `test/langtools/jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java`
> 
> Thanks,
> -- Igor

Looks good to me.

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

Marked as reviewed by jwilhelm (Reviewer).

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

From iignatyev at openjdk.java.net  Thu Dec 10 20:24:54 2020
From: iignatyev at openjdk.java.net (Igor Ignatyev)
Date: Thu, 10 Dec 2020 20:24:54 GMT
Subject: RFR: 8258056:
 jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java fails against
 jdk17
In-Reply-To: <SEwBdluivvsqSTxPtFD-r6E34TynkDSGxcrvdYG5yq4=.5a53dfb0-5b89-4687-89f0-b543c2b01576@github.com>
References: <PazMh3FhCkLfyWIyoBFRcCjmOysCmL7Q0a7gn0hPQfw=.27accea1-2be4-4249-8927-5410ba228526@github.com>
 <SEwBdluivvsqSTxPtFD-r6E34TynkDSGxcrvdYG5yq4=.5a53dfb0-5b89-4687-89f0-b543c2b01576@github.com>
Message-ID: <XwuX2eSnIDnXlNrg6Sjrsl9WdeV48TNjezTbQiy3rVQ=.6b2b8566-8f93-4ff3-9051-3ffe45d1742e@github.com>

On Thu, 10 Dec 2020 20:18:26 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Hi all,
>> 
>> could you pleaes review this small and trivial fix for `jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java` test? the test faled to find "https://download.java.net/java/early_access/jdk16/" string after we switched to jdk17, the patch is basically `s/jdk16/jdk17/g`.
>> 
>> testing: `test/langtools/jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java`
>> 
>> Thanks,
>> -- Igor
>
> Looks good to me.

Thanks Jesper.

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

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

From iignatyev at openjdk.java.net  Thu Dec 10 20:24:55 2020
From: iignatyev at openjdk.java.net (Igor Ignatyev)
Date: Thu, 10 Dec 2020 20:24:55 GMT
Subject: Integrated: 8258056:
 jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java fails against
 jdk17
In-Reply-To: <PazMh3FhCkLfyWIyoBFRcCjmOysCmL7Q0a7gn0hPQfw=.27accea1-2be4-4249-8927-5410ba228526@github.com>
References: <PazMh3FhCkLfyWIyoBFRcCjmOysCmL7Q0a7gn0hPQfw=.27accea1-2be4-4249-8927-5410ba228526@github.com>
Message-ID: <90PF3PLs7PeUdTwAG1oM3iNWee-gWBySJI6O2u2VwGY=.a5285477-2de2-49da-b831-fadd9d5af3d5@github.com>

On Thu, 10 Dec 2020 18:07:32 GMT, Igor Ignatyev <iignatyev at openjdk.org> wrote:

> Hi all,
> 
> could you pleaes review this small and trivial fix for `jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java` test? the test faled to find "https://download.java.net/java/early_access/jdk16/" string after we switched to jdk17, the patch is basically `s/jdk16/jdk17/g`.
> 
> testing: `test/langtools/jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java`
> 
> Thanks,
> -- Igor

This pull request has now been integrated.

Changeset: 164c55be
Author:    Igor Ignatyev <iignatyev at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/164c55be
Stats:     2 lines in 1 file changed: 0 ins; 0 del; 2 mod

8258056: jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java fails against jdk17

Reviewed-by: jwilhelm

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

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

From xliu at openjdk.java.net  Thu Dec 10 23:35:57 2020
From: xliu at openjdk.java.net (Xin Liu)
Date: Thu, 10 Dec 2020 23:35:57 GMT
Subject: RFR: 8258056:
 jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java fails against
 jdk17
In-Reply-To: <XwuX2eSnIDnXlNrg6Sjrsl9WdeV48TNjezTbQiy3rVQ=.6b2b8566-8f93-4ff3-9051-3ffe45d1742e@github.com>
References: <PazMh3FhCkLfyWIyoBFRcCjmOysCmL7Q0a7gn0hPQfw=.27accea1-2be4-4249-8927-5410ba228526@github.com>
 <SEwBdluivvsqSTxPtFD-r6E34TynkDSGxcrvdYG5yq4=.5a53dfb0-5b89-4687-89f0-b543c2b01576@github.com>
 <XwuX2eSnIDnXlNrg6Sjrsl9WdeV48TNjezTbQiy3rVQ=.6b2b8566-8f93-4ff3-9051-3ffe45d1742e@github.com>
Message-ID: <R7SST41sG5AhEQBQT7R1zrzdpBVXCmITyzxQHcoZLtk=.bb27f32c-4e34-4930-91fe-15c587ec3cad@github.com>

On Thu, 10 Dec 2020 20:20:57 GMT, Igor Ignatyev <iignatyev at openjdk.org> wrote:

>> Looks good to me.
>
> Thanks Jesper.

This commit seems not to pass your workflow. 
https://github.com/iignatev/jdk/actions/runs/413640509

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

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

From iignatyev at openjdk.java.net  Thu Dec 10 23:47:56 2020
From: iignatyev at openjdk.java.net (Igor Ignatyev)
Date: Thu, 10 Dec 2020 23:47:56 GMT
Subject: RFR: 8258056:
 jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java fails against
 jdk17
In-Reply-To: <R7SST41sG5AhEQBQT7R1zrzdpBVXCmITyzxQHcoZLtk=.bb27f32c-4e34-4930-91fe-15c587ec3cad@github.com>
References: <PazMh3FhCkLfyWIyoBFRcCjmOysCmL7Q0a7gn0hPQfw=.27accea1-2be4-4249-8927-5410ba228526@github.com>
 <SEwBdluivvsqSTxPtFD-r6E34TynkDSGxcrvdYG5yq4=.5a53dfb0-5b89-4687-89f0-b543c2b01576@github.com>
 <XwuX2eSnIDnXlNrg6Sjrsl9WdeV48TNjezTbQiy3rVQ=.6b2b8566-8f93-4ff3-9051-3ffe45d1742e@github.com>
 <R7SST41sG5AhEQBQT7R1zrzdpBVXCmITyzxQHcoZLtk=.bb27f32c-4e34-4930-91fe-15c587ec3cad@github.com>
Message-ID: <r8y03m_mlpJIsQQaNiKouMre8COrejK5Aj-hSJ7BZ_0=.14a6dfd2-08c7-4716-afc5-298a5b4db416@github.com>

On Thu, 10 Dec 2020 23:32:43 GMT, Xin Liu <xliu at openjdk.org> wrote:

> This commit seems not to pass your workflow.
> https://github.com/iignatev/jdk/actions/runs/413640509

thanks for letting me know, the failures you linked to are b/c of [8258054](https://bugs.openjdk.java.net/browse/JDK-8258054) which got fixed by #1738

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

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

From jjg at openjdk.java.net  Fri Dec 11 07:23:15 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 11 Dec 2020 07:23:15 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
In-Reply-To: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
Message-ID: <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>

On Wed, 28 Oct 2020 03:26:16 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

> HTML4 is no longer supported in javadoc.
> 
> doclint needs to drop HTML4 support as well.
> The changes consist of:
> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
> * Modifying test code and expected outputs to be checked in HTML5

Generally nice; congratulations on figuring this all out.

Some comments in files need response and/or action.

Please make the review non-draft as well

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint_zh_CN.properties line 30:

> 28: dc.attr.lacks.value = \u5C5E\u6027\u7F3A\u5C11\u503C
> 29: dc.attr.not.number = \u5C5E\u6027\u503C\u4E0D\u662F\u6570\u5B57
> 30: dc.attr.not.supported.html4 = \u5C5E\u6027\u5728 HTML4 \u4E2D\u4E0D\u53D7\u652F\u6301: {0}

In general, we (Dev) do not edit any localized resource files. That happens "automatically" by the localization team.

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

> 408:         OBSOLETE,
> 409:         UNSUPPORTED
> 410:     }

On one hand, I don't think we need this level of detail, but on the other, I see it closely matches `AttrKind`, so OK.

Is there are useful distinction between INVALID / OBSOLETE / UNSUPPORTED ?

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

> 690:                                 }
> 691:                             } catch (NumberFormatException ex) {
> 692:                                 env.messages.error(HTML, tree, "dc.attr.img.border", attr);

It's generally better practice to use unique message keys at each call site.  This is so that if there is a downstream problem when someone reports a problem with an error message, we know the exact single place in the code where the message comes from.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java line 229:

> 227:                 String argVersion = arg.substring(arg.indexOf(":") + 1);
> 228:                 if (argVersion == null || !argVersion.equals("html5")) {
> 229:                     throw new BadArgs("dc.bad.value.for.option", arg, argVersion);

It might be friendly to give a warning when this option is used, saying that `html5` is the default and only supported version, and that this option may be removed in a future release.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java line 348:

> 346:                 String argVersion = arg.substring(arg.indexOf(":") + 1);
> 347:                 if (argVersion == null || !argVersion.equals("html5")) {
> 348:                     throw new IllegalArgumentException(argVersion);

These lines are only used when invoked from javac/javadoc etc, so it would be reasonable to delete them entirely, provided those tools never try and use this option.

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

> 49:  * public.
> 50:  *
> 51:  * @see <a href="http://www.w3.org/TR/REC-html40/">HTML 4.01 Specification</a>

Given the presence of UNSUPPORTED in the ensuing code, I'd recommend leaving this link, for historical purposes.

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

> 358:             attrs(AttrKind.OK, COLSPAN, ROWSPAN, HEADERS, SCOPE, Attr.ABBR),
> 359:             attrs(AttrKind.UNSUPPORTED, WIDTH, BGCOLOR, HEIGHT, NOWRAP, AXIS, ALIGN, CHAR, CHAROFF),
> 360:             attrs(AttrKind.OK, VALIGN)), // Removed after JDK-8255214 fixed.

Does this need attention? JDK-8255215 has been fixed

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

> 539:         OBSOLETE,
> 540:         UNSUPPORTED
> 541:     }

Is there a useful distinction between INVALID / OBSOLETE / UNSUPPORTED ?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/HtmlVersion.java line 1:

> 1: /*

Yay!

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 32:

> 30: dc.attr.not.supported.html5 = attribute not supported in HTML5: {0}
> 31: dc.attr.obsolete = attribute obsolete: {0}
> 32: dc.attr.obsolete.use.css = attribute obsolete, use CSS instead: {0}

Is this still required?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 35:

> 33: dc.attr.repeated = repeated attribute: {0}
> 34: dc.attr.img.border = attribute border for img only accepts "0", use CSS instead: {0}
> 35: dc.attr.table.border = attribute border for table only accepts "" or "1", use CSS instead: {0}

I suggest quoting the attribute name "border"

test/langtools/tools/doclint/AccessibilityTest.out line 28:

> 26:      * <table><tr><th>head<tr><td>data</table>
> 27:                                       ^
> 28: AccessibilityTest.java:66: error: no summary or caption for table

summary is not a valid attribute in HTML5, so I would omit it from the message.

test/langtools/tools/doclint/AnchorTest.java line 3:

> 1: /*
> 2:  * @test /nodynamiccopyright/
> 3:  * @bug 8004832 8247957

The bug number should only be added when the test can be considered to be a significant test of the work.

In general, don't bother to add the bug number when a test is just incidentally affected by the work.

In this case, there appears to be no other change to the file, but I guess OK, you've changed to golden output file.

test/langtools/tools/doclint/html/HtmlVersionTagsAttrsTest.java line 11:

> 9:  * @run main DocLintTester -badargs -XhtmlVersion: HtmlVersionTagsAttrsTest.java
> 10:  *
> 11:  *

I'm guessing these blank lines are to maintain line numbers, right?

test/langtools/tools/doclint/html/TableTagTest.out line 22:

> 20:      *  <table summary="abc" width="50%"> <tr> <td> <tfoot> <tr> </tfoot></table>
> 21:                              ^
> 22: 7 errors

Does it work to add the final newline: various tools give warnings if files do not end with newline.

test/langtools/tools/doclint/html/TextNotAllowed.out line 30:

> 28: TextNotAllowed.java:16: error: attribute not supported in HTML5: summary
> 29:  * <table summary=description> abc </table>
> 30:           ^

The test is 'Text Not Allowed', so the test file should be valid except for text where it is not allowed.  Don't add spurious other errors. In this case, provide a `<caption>` to keep DocLint happy.

This applies throughout this test.

test/langtools/tools/doclint/tidy/InvalidName.out line 3:

> 1: InvalidName.java:17: error: invalid name for anchor: "foo()"
> 2:  * <a id="foo()">invalid</a>
> 3:       ^

This seems incorrect. In HTML5 all names are valid unless they contain whitespace.

test/langtools/tools/doclint/tidy/TextNotAllowed.out line 2:

> 1: TextNotAllowed.java:14: error: attribute not supported in HTML5: summary
> 2:  * <table summary=description> abc </table>

See previous comments about spurious error messages

test/langtools/tools/doclint/tidy/TrimmingEmptyTag.out line 5:

> 3:       ^
> 4: TrimmingEmptyTag.java:15: error: attribute not supported in HTML5: summary
> 5:  * <table summary=description></table>

ditto

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java line 148:

> 146:             return;
> 147:         } else if (useXhtmlVersion) {
> 148:             System.err.println(localize("dc.main.use.xhtmlversion"));

use `out.println`

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

> 358:             EnumSet.of(Flag.ACCEPTS_BLOCK, Flag.ACCEPTS_INLINE),
> 359:             attrs(AttrKind.OK, COLSPAN, ROWSPAN, HEADERS, SCOPE, Attr.ABBR),
> 360:             attrs(AttrKind.UNSUPPORTED, WIDTH, BGCOLOR, HEIGHT, NOWRAP, AXIS, ALIGN, CHAR, CHAROFF, VALIGN)), // Removed after JDK-8255214 fixed.

remove comment

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

> 373: 
> 374:     TR(BlockType.TABLE_ITEM, EndKind.OPTIONAL,
> 375:             attrs(AttrKind.UNSUPPORTED, ALIGN, CHAR, CHAROFF, BGCOLOR, VALIGN)) { // Removed after JDK-8255215 fixed

remove comment

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 91:

> 89: dc.main.ioerror=IO error: {0}
> 90: dc.main.no.files.given=No files given
> 91: dc.main.use.xhtmlversion=html5 is the default and only supported version for -XhtmlVersion, and this option may be removed in a future release.

change `version` to `value` 
change `, and` to `;`

`
html5 is the default and only supported value for -XhtmlVersion; this option may be removed in a future release.
`

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

Changes requested by jjg (Reviewer).

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

From ysatowse at openjdk.java.net  Fri Dec 11 07:23:09 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 11 Dec 2020 07:23:09 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
Message-ID: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>

HTML4 is no longer supported in javadoc.

doclint needs to drop HTML4 support as well.
The changes consist of:
* Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
* Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
* Modifying test code and expected outputs to be checked in HTML5

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

Commit messages:
 - 3rd: 8247957 and 8256312
 - Merge branch 'master' into JDK-8247957_2
 - 8247957: remove doclint support for HTML 4
 - 8247957: remove doclint support for HTML 4

Changes: https://git.openjdk.java.net/jdk/pull/893/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=893&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8247957
  Stats: 1445 lines in 54 files changed: 418 ins; 744 del; 283 mod
  Patch: https://git.openjdk.java.net/jdk/pull/893.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/893/head:pull/893

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

From ysatowse at openjdk.java.net  Fri Dec 11 07:23:22 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 11 Dec 2020 07:23:22 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
In-Reply-To: <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
Message-ID: <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>

On Thu, 12 Nov 2020 02:28:51 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> HTML4 is no longer supported in javadoc.
>> 
>> doclint needs to drop HTML4 support as well.
>> The changes consist of:
>> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
>> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
>> * Modifying test code and expected outputs to be checked in HTML5
>
> Generally nice; congratulations on figuring this all out.
> 
> Some comments in files need response and/or action.

@jonathan-gibbons The new commit includes the changes for your review comments and "8256312: Valid anchor 'id' value not allowed".  Please take a look over at your convenience.

> Please make the review non-draft as well

Thanks for reviewing @jonathan-gibbons 
This request should have got changed to "non-draft".

FYI. all tests in jdk-tier1 are still green with the latest changes.
https://mach5.us.oracle.com/mdash/jobs/yoshiki-jdk-20201211-0555-16616611

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint_zh_CN.properties line 30:
> 
>> 28: dc.attr.lacks.value = \u5C5E\u6027\u7F3A\u5C11\u503C
>> 29: dc.attr.not.number = \u5C5E\u6027\u503C\u4E0D\u662F\u6570\u5B57
>> 30: dc.attr.not.supported.html4 = \u5C5E\u6027\u5728 HTML4 \u4E2D\u4E0D\u53D7\u652F\u6301: {0}
> 
> In general, we (Dev) do not edit any localized resource files. That happens "automatically" by the localization team.

I see.  Will discard all changes done in the localized resource files.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/HtmlTag.java line 410:
> 
>> 408:         OBSOLETE,
>> 409:         UNSUPPORTED
>> 410:     }
> 
> On one hand, I don't think we need this level of detail, but on the other, I see it closely matches `AttrKind`, so OK.
> 
> Is there are useful distinction between INVALID / OBSOLETE / UNSUPPORTED ?

OK: valid
OBSOLETE: obsolete, deprecated, but still supported (valid)
UNSUPPORTED: ever supported but no longer supported (invalid)
INVALID: the rest of others (invalid)

UNSUPPORTED can be used if we would like to choose a friendly message instead of saying "unknown tag" only.
OBSOLETE is not used anywhere in this commit.  Although HTML5 has some obsolete features, [JDK-8215577](https://bugs.openjdk.java.net/browse/JDK-8215577) didn't define them as valid features if my understanding is correct.  So I chose not to allow obsolete features in order to avoid inconsistency.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 692:
> 
>> 690:                                 }
>> 691:                             } catch (NumberFormatException ex) {
>> 692:                                 env.messages.error(HTML, tree, "dc.attr.img.border", attr);
> 
> It's generally better practice to use unique message keys at each call site.  This is so that if there is a downstream problem when someone reports a problem with an error message, we know the exact single place in the code where the message comes from.

Agreed.  I would like to change 675-695 as below

                    case BORDER:
                        if (currTag == HtmlTag.TABLE) {
                            String v = getAttrValue(tree);
                            try {
                                if (v == null || (!v.isEmpty() && Integer.parseInt(v) != 1)) {
                                    env.messages.error(HTML, tree, "dc.attr.table.border.not.valid", attr);
                                }
                            } catch (NumberFormatException ex) {
                                env.messages.error(HTML, tree, "dc.attr.table.border.not.number", attr);
                            }
                        } else if (currTag == HtmlTag.IMG) {
                            String v = getAttrValue(tree);
                            try {
                                if (v == null || (!v.isEmpty() && Integer.parseInt(v) != 0)) {
                                    env.messages.error(HTML, tree, "dc.attr.img.border.not.valid", attr);
                                }
                            } catch (NumberFormatException ex) {
                                env.messages.error(HTML, tree, "dc.attr.img.border.not.number", attr);
                            }
                        }
                        break;

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java line 229:
> 
>> 227:                 String argVersion = arg.substring(arg.indexOf(":") + 1);
>> 228:                 if (argVersion == null || !argVersion.equals("html5")) {
>> 229:                     throw new BadArgs("dc.bad.value.for.option", arg, argVersion);
> 
> It might be friendly to give a warning when this option is used, saying that `html5` is the default and only supported version, and that this option may be removed in a future release.

Ok

> test/langtools/tools/doclint/html/TableTagTest.out line 22:
> 
>> 20:      *  <table summary="abc" width="50%"> <tr> <td> <tfoot> <tr> </tfoot></table>
>> 21:                              ^
>> 22: 7 errors
> 
> Does it work to add the final newline: various tools give warnings if files do not end with newline.

It works though.  But I will add a blank line at the end for consistency.

> test/langtools/tools/doclint/html/TextNotAllowed.out line 30:
> 
>> 28: TextNotAllowed.java:16: error: attribute not supported in HTML5: summary
>> 29:  * <table summary=description> abc </table>
>> 30:           ^
> 
> The test is 'Text Not Allowed', so the test file should be valid except for text where it is not allowed.  Don't add spurious other errors. In this case, provide a `<caption>` to keep DocLint happy.
> 
> This applies throughout this test.

Thanks.  I was lacking of such perspective.

> test/langtools/tools/doclint/tidy/TextNotAllowed.out line 2:
> 
>> 1: TextNotAllowed.java:14: error: attribute not supported in HTML5: summary
>> 2:  * <table summary=description> abc </table>
> 
> See previous comments about spurious error messages

Ok.

> test/langtools/tools/doclint/tidy/TrimmingEmptyTag.out line 5:
> 
>> 3:       ^
>> 4: TrimmingEmptyTag.java:15: error: attribute not supported in HTML5: summary
>> 5:  * <table summary=description></table>
> 
> ditto

Ok.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/HtmlTag.java line 51:
> 
>> 49:  * public.
>> 50:  *
>> 51:  * @see <a href="http://www.w3.org/TR/REC-html40/">HTML 4.01 Specification</a>
> 
> Given the presence of UNSUPPORTED in the ensuing code, I'd recommend leaving this link, for historical purposes.

Ok.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/HtmlTag.java line 360:
> 
>> 358:             attrs(AttrKind.OK, COLSPAN, ROWSPAN, HEADERS, SCOPE, Attr.ABBR),
>> 359:             attrs(AttrKind.UNSUPPORTED, WIDTH, BGCOLOR, HEIGHT, NOWRAP, AXIS, ALIGN, CHAR, CHAROFF),
>> 360:             attrs(AttrKind.OK, VALIGN)), // Removed after JDK-8255214 fixed.
> 
> Does this need attention? JDK-8255215 has been fixed

Yes, now that this can be removed.  I will do.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java line 348:
> 
>> 346:                 String argVersion = arg.substring(arg.indexOf(":") + 1);
>> 347:                 if (argVersion == null || !argVersion.equals("html5")) {
>> 348:                     throw new IllegalArgumentException(argVersion);
> 
> These lines are only used when invoked from javac/javadoc etc, so it would be reasonable to delete them entirely, provided those tools never try and use this option.

These lines are likely to be used as long as the "--doclint-format html5" option is permitted.  For example, this option is still used in the make/common/JavaCompilation.gmk.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/HtmlTag.java line 541:
> 
>> 539:         OBSOLETE,
>> 540:         UNSUPPORTED
>> 541:     }
> 
> Is there a useful distinction between INVALID / OBSOLETE / UNSUPPORTED ?

Same distinction as mentioned for ElemKind

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 32:
> 
>> 30: dc.attr.not.supported.html5 = attribute not supported in HTML5: {0}
>> 31: dc.attr.obsolete = attribute obsolete: {0}
>> 32: dc.attr.obsolete.use.css = attribute obsolete, use CSS instead: {0}
> 
> Is this still required?

Do you mean ".html5" would be better to be removed?
If so, yes.  I just left it because the message would be friendly if it still say "attribute not supported in HTML5".

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 35:
> 
>> 33: dc.attr.repeated = repeated attribute: {0}
>> 34: dc.attr.img.border = attribute border for img only accepts "0", use CSS instead: {0}
>> 35: dc.attr.table.border = attribute border for table only accepts "" or "1", use CSS instead: {0}
> 
> I suggest quoting the attribute name "border"

Ok.

> test/langtools/tools/doclint/AccessibilityTest.out line 28:
> 
>> 26:      * <table><tr><th>head<tr><td>data</table>
>> 27:                                       ^
>> 28: AccessibilityTest.java:66: error: no summary or caption for table
> 
> summary is not a valid attribute in HTML5, so I would omit it from the message.

You are right.  I will remove "summary" from the message, and then remove two of the tests that still use "summary".

> test/langtools/tools/doclint/AnchorTest.java line 3:
> 
>> 1: /*
>> 2:  * @test /nodynamiccopyright/
>> 3:  * @bug 8004832 8247957
> 
> The bug number should only be added when the test can be considered to be a significant test of the work.
> 
> In general, don't bother to add the bug number when a test is just incidentally affected by the work.
> 
> In this case, there appears to be no other change to the file, but I guess OK, you've changed to golden output file.

Understood.  Thanks for your instruction.

> test/langtools/tools/doclint/html/HtmlVersionTagsAttrsTest.java line 11:
> 
>> 9:  * @run main DocLintTester -badargs -XhtmlVersion: HtmlVersionTagsAttrsTest.java
>> 10:  *
>> 11:  *
> 
> I'm guessing these blank lines are to maintain line numbers, right?

Right

> test/langtools/tools/doclint/tidy/InvalidName.out line 3:
> 
>> 1: InvalidName.java:17: error: invalid name for anchor: "foo()"
>> 2:  * <a id="foo()">invalid</a>
>> 3:       ^
> 
> This seems incorrect. In HTML5 all names are valid unless they contain whitespace.

Understood.  Need to file it as another DocLint bug.

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

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

From jjg at openjdk.java.net  Fri Dec 11 07:23:23 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 11 Dec 2020 07:23:23 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
In-Reply-To: <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
Message-ID: <iGSBNphHAu8InDARn6FJ76QIIZmc1bnN7gG4VqVJDsU=.37b6c36d-f2ed-406a-9fb8-7616e75da282@github.com>

On Fri, 13 Nov 2020 01:10:06 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java line 348:
>> 
>>> 346:                 String argVersion = arg.substring(arg.indexOf(":") + 1);
>>> 347:                 if (argVersion == null || !argVersion.equals("html5")) {
>>> 348:                     throw new IllegalArgumentException(argVersion);
>> 
>> These lines are only used when invoked from javac/javadoc etc, so it would be reasonable to delete them entirely, provided those tools never try and use this option.
>
> These lines are likely to be used as long as the "--doclint-format html5" option is permitted.  For example, this option is still used in the make/common/JavaCompilation.gmk.

1. we can update make/common/JavaCompilation.gmk
2. the option in javac/javadoc should be converted to a no-op so that it does not get passed down to doclint

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 32:
>> 
>>> 30: dc.attr.not.supported.html5 = attribute not supported in HTML5: {0}
>>> 31: dc.attr.obsolete = attribute obsolete: {0}
>>> 32: dc.attr.obsolete.use.css = attribute obsolete, use CSS instead: {0}
>> 
>> Is this still required?
>
> Do you mean ".html5" would be better to be removed?
> If so, yes.  I just left it because the message would be friendly if it still say "attribute not supported in HTML5".

Sorry, the comment is incorrectly focussed (and annoyingly cryptic: my apologies). 
I think I was referring to `dc.attr.obsolete.use.css`

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

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

From ysatowse at openjdk.java.net  Fri Dec 11 07:23:24 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 11 Dec 2020 07:23:24 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
In-Reply-To: <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
Message-ID: <bNGdCBxlZys-2-Pd3PHz77YC1ySn6y863sFFeuWlgKc=.d279693b-614b-4f84-81ce-595c695e3447@github.com>

On Fri, 13 Nov 2020 02:05:23 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> test/langtools/tools/doclint/tidy/InvalidName.out line 3:
>> 
>>> 1: InvalidName.java:17: error: invalid name for anchor: "foo()"
>>> 2:  * <a id="foo()">invalid</a>
>>> 3:       ^
>> 
>> This seems incorrect. In HTML5 all names are valid unless they contain whitespace.
>
> Understood.  Need to file it as another DocLint bug.

Filed as [JDK-8256312](https://bugs.openjdk.java.net/browse/JDK-8256312)

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

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

From ysatowse at openjdk.java.net  Fri Dec 11 07:23:23 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 11 Dec 2020 07:23:23 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
In-Reply-To: <mW_Qc1r_RiZySoSN9D-WeLYDALpejNnG_4Ocb2rrAcU=.22ce6aaf-5f4d-4326-8ef3-b19d42c2f6ad@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
 <iGSBNphHAu8InDARn6FJ76QIIZmc1bnN7gG4VqVJDsU=.37b6c36d-f2ed-406a-9fb8-7616e75da282@github.com>
 <mW_Qc1r_RiZySoSN9D-WeLYDALpejNnG_4Ocb2rrAcU=.22ce6aaf-5f4d-4326-8ef3-b19d42c2f6ad@github.com>
Message-ID: <z0lA35ZUYIP6kf-awNNrhKELLpclGDAe55qsuYF4tnY=.81ee9176-db0b-47f9-a3d6-27943a07c65f@github.com>

On Fri, 13 Nov 2020 01:26:30 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 1. we can update make/common/JavaCompilation.gmk
>> 2. the option in javac/javadoc should be converted to a no-op so that it does not get passed down to doclint
>
> (updating make/common/JavaCompilation.gmk should be done with a separate JBS issue, filed against the build.)

Filed as [JDK-8256313](https://bugs.openjdk.java.net/browse/JDK-8256313).

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

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

From jjg at openjdk.java.net  Fri Dec 11 07:23:23 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 11 Dec 2020 07:23:23 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
In-Reply-To: <iGSBNphHAu8InDARn6FJ76QIIZmc1bnN7gG4VqVJDsU=.37b6c36d-f2ed-406a-9fb8-7616e75da282@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
 <iGSBNphHAu8InDARn6FJ76QIIZmc1bnN7gG4VqVJDsU=.37b6c36d-f2ed-406a-9fb8-7616e75da282@github.com>
Message-ID: <mW_Qc1r_RiZySoSN9D-WeLYDALpejNnG_4Ocb2rrAcU=.22ce6aaf-5f4d-4326-8ef3-b19d42c2f6ad@github.com>

On Fri, 13 Nov 2020 01:25:44 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> These lines are likely to be used as long as the "--doclint-format html5" option is permitted.  For example, this option is still used in the make/common/JavaCompilation.gmk.
>
> 1. we can update make/common/JavaCompilation.gmk
> 2. the option in javac/javadoc should be converted to a no-op so that it does not get passed down to doclint

(updating make/common/JavaCompilation.gmk should be done with a separate JBS issue, filed against the build.)

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

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

From ysatowse at openjdk.java.net  Fri Dec 11 07:23:24 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 11 Dec 2020 07:23:24 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
In-Reply-To: <iGSBNphHAu8InDARn6FJ76QIIZmc1bnN7gG4VqVJDsU=.37b6c36d-f2ed-406a-9fb8-7616e75da282@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
 <iGSBNphHAu8InDARn6FJ76QIIZmc1bnN7gG4VqVJDsU=.37b6c36d-f2ed-406a-9fb8-7616e75da282@github.com>
Message-ID: <jxeGKX2d6p67pZZkVbEQt6eV6cmFIxp5SkOLTA1KuxU=.c998f8a6-cf1d-44d5-8a94-6afb22cf8ba2@github.com>

On Fri, 13 Nov 2020 01:32:18 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Do you mean ".html5" would be better to be removed?
>> If so, yes.  I just left it because the message would be friendly if it still say "attribute not supported in HTML5".
>
> Sorry, the comment is incorrectly focussed (and annoyingly cryptic: my apologies). 
> I think I was referring to `dc.attr.obsolete.use.css`

I got it.  Ok. Will remove it.

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

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

From jjg at openjdk.java.net  Fri Dec 11 07:23:25 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 11 Dec 2020 07:23:25 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
In-Reply-To: <z0lA35ZUYIP6kf-awNNrhKELLpclGDAe55qsuYF4tnY=.81ee9176-db0b-47f9-a3d6-27943a07c65f@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
 <iGSBNphHAu8InDARn6FJ76QIIZmc1bnN7gG4VqVJDsU=.37b6c36d-f2ed-406a-9fb8-7616e75da282@github.com>
 <mW_Qc1r_RiZySoSN9D-WeLYDALpejNnG_4Ocb2rrAcU=.22ce6aaf-5f4d-4326-8ef3-b19d42c2f6ad@github.com>
 <z0lA35ZUYIP6kf-awNNrhKELLpclGDAe55qsuYF4tnY=.81ee9176-db0b-47f9-a3d6-27943a07c65f@github.com>
Message-ID: <jDe1anz2EjUGL4guAqj9d8qGi-JbUGu_-I5JG4hPPxQ=.ef075371-bab5-4768-b1fd-92f440babe2e@github.com>

On Fri, 13 Nov 2020 02:49:40 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> (updating make/common/JavaCompilation.gmk should be done with a separate JBS issue, filed against the build.)
>
> Filed as [JDK-8256313](https://bugs.openjdk.java.net/browse/JDK-8256313).

In javac Arguments class, we should delete these lines at about 855

`
        String format = options.get(Option.DOCLINT_FORMAT);
        if (format != null) {
            doclintOpts.add(DocLint.XHTML_VERSION_PREFIX + format);
        }
`

This could be a separate JBS issue, if you prefer.

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

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

From ysatowse at openjdk.java.net  Fri Dec 11 07:23:25 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 11 Dec 2020 07:23:25 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4
In-Reply-To: <jDe1anz2EjUGL4guAqj9d8qGi-JbUGu_-I5JG4hPPxQ=.ef075371-bab5-4768-b1fd-92f440babe2e@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
 <iGSBNphHAu8InDARn6FJ76QIIZmc1bnN7gG4VqVJDsU=.37b6c36d-f2ed-406a-9fb8-7616e75da282@github.com>
 <mW_Qc1r_RiZySoSN9D-WeLYDALpejNnG_4Ocb2rrAcU=.22ce6aaf-5f4d-4326-8ef3-b19d42c2f6ad@github.com>
 <z0lA35ZUYIP6kf-awNNrhKELLpclGDAe55qsuYF4tnY=.81ee9176-db0b-47f9-a3d6-27943a07c65f@github.com>
 <jDe1anz2EjUGL4guAqj9d8qGi-JbUGu_-I5JG4hPPxQ=.ef075371-bab5-4768-b1fd-92f440babe2e@github.com>
Message-ID: <lYprDse62HD_oaqKcwxoJu05q8A9A8_87a8ffaFFaQg=.f207077e-fdfa-4cd2-9064-1232775615c7@github.com>

On Thu, 26 Nov 2020 21:25:11 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Filed as [JDK-8256313](https://bugs.openjdk.java.net/browse/JDK-8256313).
>
> In javac Arguments class, we should delete these lines at about 855
> 
> `
>         String format = options.get(Option.DOCLINT_FORMAT);
>         if (format != null) {
>             doclintOpts.add(DocLint.XHTML_VERSION_PREFIX + format);
>         }
> `
> 
> This could be a separate JBS issue, if you prefer.

Filed as [JDK-8257204](https://bugs.openjdk.java.net/browse/JDK-8257204).

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

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

From hannesw at openjdk.java.net  Fri Dec 11 10:53:57 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 11 Dec 2020 10:53:57 GMT
Subject: RFR: 8258056:
 jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java fails against
 jdk17
In-Reply-To: <r8y03m_mlpJIsQQaNiKouMre8COrejK5Aj-hSJ7BZ_0=.14a6dfd2-08c7-4716-afc5-298a5b4db416@github.com>
References: <PazMh3FhCkLfyWIyoBFRcCjmOysCmL7Q0a7gn0hPQfw=.27accea1-2be4-4249-8927-5410ba228526@github.com>
 <SEwBdluivvsqSTxPtFD-r6E34TynkDSGxcrvdYG5yq4=.5a53dfb0-5b89-4687-89f0-b543c2b01576@github.com>
 <XwuX2eSnIDnXlNrg6Sjrsl9WdeV48TNjezTbQiy3rVQ=.6b2b8566-8f93-4ff3-9051-3ffe45d1742e@github.com>
 <R7SST41sG5AhEQBQT7R1zrzdpBVXCmITyzxQHcoZLtk=.bb27f32c-4e34-4930-91fe-15c587ec3cad@github.com>
 <r8y03m_mlpJIsQQaNiKouMre8COrejK5Aj-hSJ7BZ_0=.14a6dfd2-08c7-4716-afc5-298a5b4db416@github.com>
Message-ID: <vyWh1rf9PD5k--lo8evgMgt2Uve3WqmALnCYURuHv9I=.b5a80dc1-d8e2-4177-923a-0ceef08066e9@github.com>

On Thu, 10 Dec 2020 23:44:42 GMT, Igor Ignatyev <iignatyev at openjdk.org> wrote:

>> This commit seems not to pass your workflow. 
>> https://github.com/iignatev/jdk/actions/runs/413640509
>
>> This commit seems not to pass your workflow.
>> https://github.com/iignatev/jdk/actions/runs/413640509
> 
> thanks for letting me know, the failures you linked to are b/c of [8258054](https://bugs.openjdk.java.net/browse/JDK-8258054) which got fixed by #1738

Thanks for quickly fixing this, @iignatev! 

This was a stupid mistake of mine to add a test that contains a pre-release platform documentation URL. I'll take care of fixing the root cause, which is not to generate platform documentation links in the first place. JBS issue filed here: https://bugs.openjdk.java.net/browse/JDK-8258092

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

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

From hannesw at openjdk.java.net  Fri Dec 11 11:29:02 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 11 Dec 2020 11:29:02 GMT
Subject: [jdk16] RFR: 8258092: Link to early access platform documentation in
 TestHtmlTableTags.java
Message-ID: <FZJed5kmb1EDuH7ADM-FSs0lYdsT6356x7WsLNKlPCA=.0ec46970-8fb9-44fa-be1b-437cd26a2080@github.com>

I recently added tests that expect javadoc output to contain links to early access jdk 16 platform documentation. 

This fix adds the `--no-platform-links` option to the tests in question and updates the expected output accordingly.

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

Commit messages:
 - JDK-8258092: Link to early access platform documentation in TestHtmlTableTags.java

Changes: https://git.openjdk.java.net/jdk16/pull/10/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=10&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8258092
  Stats: 14 lines in 1 file changed: 2 ins; 8 del; 4 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/10.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/10/head:pull/10

PR: https://git.openjdk.java.net/jdk16/pull/10

From jjg at openjdk.java.net  Fri Dec 11 18:49:54 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 11 Dec 2020 18:49:54 GMT
Subject: [jdk16] RFR: 8258092: Link to early access platform documentation
 in TestHtmlTableTags.java
In-Reply-To: <FZJed5kmb1EDuH7ADM-FSs0lYdsT6356x7WsLNKlPCA=.0ec46970-8fb9-44fa-be1b-437cd26a2080@github.com>
References: <FZJed5kmb1EDuH7ADM-FSs0lYdsT6356x7WsLNKlPCA=.0ec46970-8fb9-44fa-be1b-437cd26a2080@github.com>
Message-ID: <JgDtNc-GAncqaTjRwt4gR31iHVgun496IGlK5F-R4Dc=.e56f3df6-8c07-4c32-86c3-1ab08ffdec3d@github.com>

On Fri, 11 Dec 2020 11:24:15 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> I recently added tests that expect javadoc output to contain links to early access jdk 16 platform documentation. 
> 
> This fix adds the `--no-platform-links` option to the tests in question and updates the expected output accordingly.

Marked as reviewed by jjg (Reviewer).

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

PR: https://git.openjdk.java.net/jdk16/pull/10

From jjg at openjdk.java.net  Sun Dec 13 00:25:07 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Sun, 13 Dec 2020 00:25:07 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search
Message-ID: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>

This is for JDK16, as a precursor to fixing JDK-8258002.

While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.

The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.

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

Commit messages:
 - JDK-8247994: Localize javadoc search

Changes: https://git.openjdk.java.net/jdk16/pull/16/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=16&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8247994
  Stats: 122 lines in 9 files changed: 88 ins; 6 del; 28 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/16.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/16/head:pull/16

PR: https://git.openjdk.java.net/jdk16/pull/16

From jjg at openjdk.java.net  Sun Dec 13 00:25:08 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Sun, 13 Dec 2020 00:25:08 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search
In-Reply-To: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
Message-ID: <Qw4H-xSPXjuND9jttEWDaJ3q_Fs3m0ckeMwtASd9KKQ=.3e47de4c-4090-4f8c-8f6b-5e15d8f4b077@github.com>

On Sun, 13 Dec 2020 00:19:59 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This is for JDK16, as a precursor to fixing JDK-8258002.
> 
> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
> 
> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.

make/CompileInterimLangtools.gmk line 77:

> 75:           Standard.java, \
> 76:       EXTRA_FILES := $(BUILDTOOLS_OUTPUTDIR)/gensrc/$1.interim/module-info.java, \
> 77:       COPY := .gif .png .xml .css .js .js.template .txt javax.tools.JavaCompilerTool, \

Build-folk: it would be nice if this macro could use `$(jdk.javadoc_COPY)` instead of having to duplicate entries.
(Future RFE?)

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

PR: https://git.openjdk.java.net/jdk16/pull/16

From hannesw at openjdk.java.net  Mon Dec 14 08:11:54 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 14 Dec 2020 08:11:54 GMT
Subject: [jdk16] Integrated: 8258092: Link to early access platform
 documentation in TestHtmlTableTags.java
In-Reply-To: <FZJed5kmb1EDuH7ADM-FSs0lYdsT6356x7WsLNKlPCA=.0ec46970-8fb9-44fa-be1b-437cd26a2080@github.com>
References: <FZJed5kmb1EDuH7ADM-FSs0lYdsT6356x7WsLNKlPCA=.0ec46970-8fb9-44fa-be1b-437cd26a2080@github.com>
Message-ID: <sSVfHTN9kLTeNnbUprMxZyndzlUUJqS1-k0znXURBZ8=.13771118-ba53-48f3-a776-e5b5f7e0a65b@github.com>

On Fri, 11 Dec 2020 11:24:15 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> I recently added tests that expect javadoc output to contain links to early access jdk 16 platform documentation. 
> 
> This fix adds the `--no-platform-links` option to the tests in question and updates the expected output accordingly.

This pull request has now been integrated.

Changeset: 164c8a6e
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk16/commit/164c8a6e
Stats:     14 lines in 1 file changed: 2 ins; 8 del; 4 mod

8258092: Link to early access platform documentation in TestHtmlTableTags.java

Reviewed-by: jjg

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

PR: https://git.openjdk.java.net/jdk16/pull/10

From hannesw at openjdk.java.net  Mon Dec 14 09:52:59 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 14 Dec 2020 09:52:59 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search
In-Reply-To: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
Message-ID: <h4L7gwb3BEtV6LBW0MrXnCCuYsqclJw3czHLDHDzv2U=.e1a66d2b-7be5-41d7-90e5-be116ed55caf@github.com>

On Sun, 13 Dec 2020 00:19:59 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This is for JDK16, as a precursor to fixing JDK-8258002.
> 
> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
> 
> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.

Looks good in general. `<Unnamed>` shouldn't be localized as it is an internal tag (see inline comment).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/search.js.template line 40:

> 38: var MIN_RESULTS = 3;
> 39: var MAX_RESULTS = 500;
> 40: var UNNAMED = "##REPLACE:doclet.search.unnamed##";

`<Unnamed>` is not a string that is ever shown to the user, it is what is used by javadoc to denote the default package (see `toolkit.util.DocletConstants.DEFAULT_PACKAGE_NAME`). This variable shouldn't be localized as that would break behaviour for code in the default package (and show the localized string as package name, instead of no package name).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFile.java line 256:

> 254:                 sb.append(resources.getText(m.group("key")));
> 255:             } catch (MissingResourceException e) {
> 256:                 sb.append(m.group());

Shouldn't we propagate an error here, or issue a warning? If a key is missing localized properties the value from default properties should be used, so this should never happen, right?

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

Changes requested by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk16/pull/16

From hannesw at openjdk.java.net  Mon Dec 14 09:58:56 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 14 Dec 2020 09:58:56 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search
In-Reply-To: <h4L7gwb3BEtV6LBW0MrXnCCuYsqclJw3czHLDHDzv2U=.e1a66d2b-7be5-41d7-90e5-be116ed55caf@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
 <h4L7gwb3BEtV6LBW0MrXnCCuYsqclJw3czHLDHDzv2U=.e1a66d2b-7be5-41d7-90e5-be116ed55caf@github.com>
Message-ID: <KALg26trMSMSixmSapr3eujUWZE1bpeppZzzl6EzJF4=.0e009ea3-34b5-4730-a5e8-ddc99e9fb36b@github.com>

On Mon, 14 Dec 2020 09:34:31 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This is for JDK16, as a precursor to fixing JDK-8258002.
>> 
>> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
>> 
>> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFile.java line 256:
> 
>> 254:                 sb.append(resources.getText(m.group("key")));
>> 255:             } catch (MissingResourceException e) {
>> 256:                 sb.append(m.group());
> 
> Shouldn't we propagate an error here, or issue a warning? If a key is missing localized properties the value from default properties should be used, so this should never happen, right?

I see the added check for "##REPLACE:" in TestSearch.java will catch that case, so I guess it's ok.

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

PR: https://git.openjdk.java.net/jdk16/pull/16

From jwilhelm at openjdk.java.net  Tue Dec 15 03:43:15 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 15 Dec 2020 03:43:15 GMT
Subject: Integrated: Merge jdk16
In-Reply-To: <2Yx43vz64GrneweTv0nw17cuOAEzWPovF7LZ8AkDsME=.932a0aa9-2c4b-4949-bb66-c059f3942091@github.com>
References: <2Yx43vz64GrneweTv0nw17cuOAEzWPovF7LZ8AkDsME=.932a0aa9-2c4b-4949-bb66-c059f3942091@github.com>
Message-ID: <YDDhTdRzo8khlVw3vZZ6X1D0sz8g2OvS7GA8wJrT4jc=.bd8786cc-d03d-4a59-95b6-76df7f1fbfae@github.com>

On Tue, 15 Dec 2020 03:37:23 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Merge change from JDK 16

This pull request has now been integrated.

Changeset: 381021ae
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/381021ae
Stats:     875 lines in 42 files changed: 644 ins; 154 del; 77 mod

Merge

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

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

From jwilhelm at openjdk.java.net  Tue Dec 15 03:43:14 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 15 Dec 2020 03:43:14 GMT
Subject: Integrated: Merge jdk16
Message-ID: <2Yx43vz64GrneweTv0nw17cuOAEzWPovF7LZ8AkDsME=.932a0aa9-2c4b-4949-bb66-c059f3942091@github.com>

Merge change from JDK 16

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

Commit messages:
 - Merge
 - 8258094: AIX build fails after 8257602
 - 8258092: Link to early access platform documentation in TestHtmlTableTags.java
 - 8254350: CompletableFuture.get may swallow InterruptedException
 - 8258111: Problemlist compiler/blackhole tests for -Xcomp until JDK-8258101 is fixed
 - 8257596: Clarify trusted final fields for record classes
 - 8257919: [JVMCI] profiling info didn't change after reprofile
 - 8257598: Clarify what component values are used in Record::equals
 - 8258060: Update @jls tags for renamed/renumbered sections
 - 8256641: CDS VM operations do not lock the heap
 - ... and 3 more: https://git.openjdk.java.net/jdk/compare/2c3ae19a...b0ad1bcd

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

Changes: https://git.openjdk.java.net/jdk/pull/1775/files
  Stats: 875 lines in 42 files changed: 644 ins; 154 del; 77 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1775.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1775/head:pull/1775

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

From ysatowse at openjdk.java.net  Tue Dec 15 07:26:15 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Tue, 15 Dec 2020 07:26:15 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v2]
In-Reply-To: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
Message-ID: <HvlYLiUQXFTip93rpKXiNrJfbZeaFBZ-hvoqBR3OgTw=.f419490f-4206-4b52-85ee-f85d5eebd408@github.com>

> HTML4 is no longer supported in javadoc.
> 
> doclint needs to drop HTML4 support as well.
> The changes consist of:
> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
> * Modifying test code and expected outputs to be checked in HTML5

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

  8257204 and 8256313
  8257204: Remove usage of -Xhtmlversion option from javac
  8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/893/files
  - new: https://git.openjdk.java.net/jdk/pull/893/files/4b733399..294b3cce

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

  Stats: 182 lines in 9 files changed: 0 ins; 71 del; 111 mod
  Patch: https://git.openjdk.java.net/jdk/pull/893.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/893/head:pull/893

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

From ysatowse at openjdk.java.net  Tue Dec 15 07:30:59 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Tue, 15 Dec 2020 07:30:59 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v2]
In-Reply-To: <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
Message-ID: <49zhTArZTN6JEApqmuxnSz-_9Jdiuvu8WKuSOTd6fRk=.0345e583-8e0a-4589-8c89-92df7b164013@github.com>

On Fri, 11 Dec 2020 06:44:57 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> Please make the review non-draft as well
>
> Thanks for reviewing @jonathan-gibbons 
> This request should have got changed to "non-draft".
> 
> FYI. all tests in jdk-tier1 are still green with the latest changes.
> https://mach5.us.oracle.com/mdash/jobs/yoshiki-jdk-20201211-0555-16616611

This commit includes the changes for 
8257204: Remove usage of -Xhtmlversion option from javac
8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option

The changes presume the changes made by a 8247957.   And there is no need to separate them from 8247957, so I would like to pull all changes into this.

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

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

From ihse at openjdk.java.net  Tue Dec 15 09:24:01 2020
From: ihse at openjdk.java.net (Magnus Ihse Bursie)
Date: Tue, 15 Dec 2020 09:24:01 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v2]
In-Reply-To: <HvlYLiUQXFTip93rpKXiNrJfbZeaFBZ-hvoqBR3OgTw=.f419490f-4206-4b52-85ee-f85d5eebd408@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <HvlYLiUQXFTip93rpKXiNrJfbZeaFBZ-hvoqBR3OgTw=.f419490f-4206-4b52-85ee-f85d5eebd408@github.com>
Message-ID: <Yfps7QXZ65d-qGqLGp30xpflAFAwxOXt0FCSPJCBZy4=.27fbdd12-998a-4dbe-8007-9fa02281505c@github.com>

On Tue, 15 Dec 2020 07:26:15 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> HTML4 is no longer supported in javadoc.
>> 
>> doclint needs to drop HTML4 support as well.
>> The changes consist of:
>> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
>> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
>> * Modifying test code and expected outputs to be checked in HTML5
>
> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8257204 and 8256313
>   8257204: Remove usage of -Xhtmlversion option from javac
>   8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option

Build change look fine. I have not looked at the other changes.

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

Marked as reviewed by ihse (Reviewer).

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

From ihse at openjdk.java.net  Tue Dec 15 09:27:59 2020
From: ihse at openjdk.java.net (Magnus Ihse Bursie)
Date: Tue, 15 Dec 2020 09:27:59 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search
In-Reply-To: <Qw4H-xSPXjuND9jttEWDaJ3q_Fs3m0ckeMwtASd9KKQ=.3e47de4c-4090-4f8c-8f6b-5e15d8f4b077@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
 <Qw4H-xSPXjuND9jttEWDaJ3q_Fs3m0ckeMwtASd9KKQ=.3e47de4c-4090-4f8c-8f6b-5e15d8f4b077@github.com>
Message-ID: <Qa53ZO70gbtLBFhijs-2nPk-ZwMppxBjMZYBQiU4XGs=.54878d14-e980-43ea-8713-b0c27781f7a7@github.com>

On Sun, 13 Dec 2020 00:22:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This is for JDK16, as a precursor to fixing JDK-8258002.
>> 
>> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
>> 
>> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.
>
> make/CompileInterimLangtools.gmk line 77:
> 
>> 75:           Standard.java, \
>> 76:       EXTRA_FILES := $(BUILDTOOLS_OUTPUTDIR)/gensrc/$1.interim/module-info.java, \
>> 77:       COPY := .gif .png .xml .css .js .js.template .txt javax.tools.JavaCompilerTool, \
> 
> Build-folk: it would be nice if this macro could use `$(jdk.javadoc_COPY)` instead of having to duplicate entries.
> (Future RFE?)

I agree. The entire design of CompileJavaModules.gmk needs to be updated. I've been procrastinating on cleaning this up, maybe it's time to get going on it...

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

PR: https://git.openjdk.java.net/jdk16/pull/16

From ihse at openjdk.java.net  Tue Dec 15 09:27:57 2020
From: ihse at openjdk.java.net (Magnus Ihse Bursie)
Date: Tue, 15 Dec 2020 09:27:57 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search
In-Reply-To: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
Message-ID: <EPayynUeJDI3wH52uEQvXuGsoroPkiJ8KkWEqlVo9N8=.dcb277f7-d889-4568-8157-b7f8d6214153@github.com>

On Sun, 13 Dec 2020 00:19:59 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This is for JDK16, as a precursor to fixing JDK-8258002.
> 
> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
> 
> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.

Build changes look good.

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

Marked as reviewed by ihse (Reviewer).

PR: https://git.openjdk.java.net/jdk16/pull/16

From jjg at openjdk.java.net  Tue Dec 15 15:56:11 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 15 Dec 2020 15:56:11 GMT
Subject: [jdk16] RFR: JDK-8258002: Update "type" terminology in generated docs
Message-ID: <2iGo26T8BEhIoC_m49jykuUx56I8011VN3Sq6b_X2w4=.ca025625-a929-49df-8242-5924c305b7b7@github.com>

This is the bulk of the work to update javadoc to use certain terminology dependent on the source version in use. There will be a minor update when JDK-8247994 has been pushed. That will allow us to modify strings displayed by JavaScript Search.

The groups of terms being changed are:

* `Types` to `Classes and Interfaces`
* `Annotation Type` to `Annotation Interface`
* `Enum` to `Enum Class`

The new terminology will be used when the source version of the elements being documented is 16 or higher. This is the default behavior. The corollary is that the old terminology will be used when the `--source` or `--release` option is used to specify a version less than `16`.

In addition, the terminology for `Record` is being unconditionally changed to use `Record Class`. Since the feature was in preview before this release, there is no need to be able to generate the previous form.

Also, in the course of this work, it was noted that on the "Use" page for an annotation type/interface, it was incorrectly classified as a *class*, instead of *annotation interface*: that has been fixed.

Fundamentally, the change is managed at a very low level, by passing a _mapping function_ into `Resource.getText`. This allows high level code, `HtmlDoclet` in this case, to provide version-specific overrides of the resource key to be used. The avoids having to have version-specific checks at the point of use for each affected resource.

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

Commit messages:
 - remove adaptive terminology for records
 - add test
 - Remove obsolete properties and code
 - Version 2: release-specific terminology
 - JDK-8258002: Update "type" terminology in generated docs

Changes: https://git.openjdk.java.net/jdk16/pull/20/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=20&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8258002
  Stats: 561 lines in 46 files changed: 322 ins; 45 del; 194 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/20.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/20/head:pull/20

PR: https://git.openjdk.java.net/jdk16/pull/20

From jjg at openjdk.java.net  Tue Dec 15 21:24:08 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Tue, 15 Dec 2020 21:24:08 GMT
Subject: [jdk16] RFR: JDK-8258338: Support deprecated records
Message-ID: <4zfUGx0G872UH1PQDZU8mcGaae-SxeA5FGPWZDseaNU=.e0b530df-d73a-424c-98ee-df076edab7b1@github.com>

Relatively simple update to fix an oversight in the support for records. `RECORD` was not added to `DeprElementKind` with the derivative downstream updates.

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

Commit messages:
 - JDK-8258338: Support deprecated records

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

PR: https://git.openjdk.java.net/jdk16/pull/29

From ysatowse at openjdk.java.net  Wed Dec 16 02:09:00 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Wed, 16 Dec 2020 02:09:00 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v2]
In-Reply-To: <Yfps7QXZ65d-qGqLGp30xpflAFAwxOXt0FCSPJCBZy4=.27fbdd12-998a-4dbe-8007-9fa02281505c@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <HvlYLiUQXFTip93rpKXiNrJfbZeaFBZ-hvoqBR3OgTw=.f419490f-4206-4b52-85ee-f85d5eebd408@github.com>
 <Yfps7QXZ65d-qGqLGp30xpflAFAwxOXt0FCSPJCBZy4=.27fbdd12-998a-4dbe-8007-9fa02281505c@github.com>
Message-ID: <8zKt8T3B6UDl5dUP47zJZXAj9PDCuZkO3AsrK1qmfHg=.50d5af51-f1bd-42e8-9852-983ae52a2390@github.com>

On Tue, 15 Dec 2020 09:20:44 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   8257204 and 8256313
>>   8257204: Remove usage of -Xhtmlversion option from javac
>>   8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option
>
> Build change look fine. I have not looked at the other changes.

I found an issue when called from javac, so will convert to draft until the issue resolved.

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

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

From hannesw at openjdk.java.net  Wed Dec 16 09:56:59 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 16 Dec 2020 09:56:59 GMT
Subject: [jdk16] RFR: JDK-8258338: Support deprecated records
In-Reply-To: <4zfUGx0G872UH1PQDZU8mcGaae-SxeA5FGPWZDseaNU=.e0b530df-d73a-424c-98ee-df076edab7b1@github.com>
References: <4zfUGx0G872UH1PQDZU8mcGaae-SxeA5FGPWZDseaNU=.e0b530df-d73a-424c-98ee-df076edab7b1@github.com>
Message-ID: <eXme-uG37HSm7Dgw6ZRzhvyO8aFlgQg-mdosA9KjN-8=.992a8807-e59f-4825-b5c3-6a30119764f1@github.com>

On Tue, 15 Dec 2020 21:19:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Relatively simple update to fix an oversight in the support for records. `RECORD` was not added to `DeprElementKind` with the derivative downstream updates.

Looks good!

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk16/pull/29

From jjg at openjdk.java.net  Wed Dec 16 18:17:57 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 16 Dec 2020 18:17:57 GMT
Subject: RFR: 8223607: --override-methods=summary ignores some signature
 changes
In-Reply-To: <h5-58f5Q1E-u5-z14_MedqI_uzzzKDZjRVl1Hv4DC_k=.24aa42fc-ac49-476d-a504-b1ef8c740066@github.com>
References: <h5-58f5Q1E-u5-z14_MedqI_uzzzKDZjRVl1Hv4DC_k=.24aa42fc-ac49-476d-a504-b1ef8c740066@github.com>
Message-ID: <UHgKVFwyn2NQaTCgewfr7xvkZNpyFXvSsE2iRdkyE4M=.df93926d-9003-40a2-bff8-153171a11445@github.com>

On Thu, 10 Dec 2020 13:17:49 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This change causes overriding methods to be documented in the details section under some conditions even when javadoc is run with `--override-methods=summary` and the method does not have a doc comment. Previously this already happened when the overriding method had a covariant return type (JDK-8219147). The following conditions will now trigger the same behaviour:
> 
>  - method visibility changes from `protected` to `public`
>  - any change in thrown exceptions
>  - change in documented annotations anywhere in the method signature
> 
> The conditions are simple by intention as we don't want to do checks that add to much complexity (such as distinguishing between checked and unchecked exceptions) and instead want to set the bar for inclusion in the details section relatively low.

This looks good, but given the noteworthy and significant changes in `VisibleMemberTable`,
I'd like to suggest you address JDK-8258429 at this time, which has significant overlap.

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

> 605:     // Check whether the signature of an overriding method has any changes worth
> 606:     // being documented compared to the overridden method.
> 607:     private boolean overridingSignatureChanged(ExecutableElement method, ExecutableElement overriddenMethod) {

In the body of this method, can you add in:

change in abstract/non-abstract (both ways)
change in final/non-final

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

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

From jjg at openjdk.java.net  Wed Dec 16 18:29:00 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 16 Dec 2020 18:29:00 GMT
Subject: RFR: JDK-6251738: Want a top-level summary page that itemizes all
 spec documents referenced from javadocs (OEM spec) [v2]
In-Reply-To: <GEwkDW5Hm6vl7P3oQXO80jukkmydlyx4v4rXba7-f3E=.36cc3952-8017-46dc-bfd3-177bcbabe960@github.com>
References: <6T_odbmLeZsI2_G8H7bcfL8jLi8TUAxc_u6g6OvUBjU=.76eff40f-10f7-4b16-a605-718f528b3e03@github.com>
 <nj16p9kuRLdEcRSAfX6hjkiETqLFM3XJgHzSep950jg=.3b870729-a855-4cae-b510-520d0166ffb3@github.com>
 <GEwkDW5Hm6vl7P3oQXO80jukkmydlyx4v4rXba7-f3E=.36cc3952-8017-46dc-bfd3-177bcbabe960@github.com>
Message-ID: <C1yKyssMIqT_8tC1_JlpF1hMlDBpONw1FjOmPJuY6YA=.9db2227d-fccb-4cc5-8fe8-4da49c1da40c@github.com>

On Thu, 5 Nov 2020 16:16:44 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 11 commits:
>> 
>>  - Fix merge issues; review feedback
>>  - Merge with master
>>  - allow rich content in createAnchorAndSearchIndex
>>  - update Docs.gmk to stop disabling spec tag
>>  - fix TestSpecTag.testEncodedURI
>>  - fix tests
>>  - remove support to workaround legacy @spec tag
>>  - Merge remote-tracking branch 'upstream/master' into new-spec-tag
>>  - fix trailing whitespace in test
>>  - temporarily allow existing legacy usage `@spec JPMS` `@spec jsr-51`
>>  - ... and 1 more: https://git.openjdk.java.net/jdk/compare/804bd725...ed5512d9
>
> 1. Thanks for incorporating my previous offline feedback.
> 2. Since Hannes and Erik seem to have looked at everything else, I looked mostly at changes in `src/jdk.compiler/share/classes/com/sun/source/**`, which are good!
> 3. There should be a corresponding but separate change to "Documentation Comment Specification for the Standard Doclet".
> 4. Can we use this new `@since` tag to refer to the spec at `com/sun/tools/javac/parser/DocCommentParser.java:1116`?
> 5. Should we specify in `com.sun.source.doctree.SpecTree` that both `url` and `label` parts are mandatory?
> 6. `DCSpec extends DCEndPosTree`, sigh... Although that is not a public API, this design suggests we could improve that abstraction sometime later.

Closing pull request, until we better decide the contents of the spec page

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

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

From jjg at openjdk.java.net  Wed Dec 16 18:29:02 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 16 Dec 2020 18:29:02 GMT
Subject: Withdrawn: JDK-6251738: Want a top-level summary page that itemizes
 all spec documents referenced from javadocs (OEM spec)
In-Reply-To: <6T_odbmLeZsI2_G8H7bcfL8jLi8TUAxc_u6g6OvUBjU=.76eff40f-10f7-4b16-a605-718f528b3e03@github.com>
References: <6T_odbmLeZsI2_G8H7bcfL8jLi8TUAxc_u6g6OvUBjU=.76eff40f-10f7-4b16-a605-718f528b3e03@github.com>
Message-ID: <_5FMfeDyMMGcBlb5BSM-cA0LsrrJYnIcvggWuUy-yf0=.3e55f9e7-ece2-4809-93bc-6afd433c49e7@github.com>

On Thu, 22 Oct 2020 02:40:44 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This introduces support for a new `@spec` tag that can be used as either an inline tag or as a block tag. It is used to identify references to external specifications, in such a way that the references can be collected together on a new summary page, called "Other Specifications", available from either the static INDEX page or the interactive search box.
> 
> As an inline tag, the format is `{@spec url label}`, which is roughly translated to `<a href="url">label</a>` in the generated docs.
> 
> As a block tag, the format is simply
> 
>     @spec url label
> 
> which is handled in a manner analogous to
> 
>     @see <a href="url">label</a>
> 
> The tag is notable for being the first standard/supported tag that can be used as either an inline or block tag. (We have had support for bimodal non-standard/custom tags for a while, such as `{@jls}` and `{@jvms}`.) To support bimodal standard tags, some changes to `DocCommentParser` are incorporated here.
> 
> This change is only the _support_ for the new tag;  it does _not_ include any changes to API docs to _use_ the new tag.

This pull request has been closed without being integrated.

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

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

From jjg at openjdk.java.net  Wed Dec 16 22:29:56 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 16 Dec 2020 22:29:56 GMT
Subject: [jdk16] Integrated: JDK-8258338: Support deprecated records
In-Reply-To: <4zfUGx0G872UH1PQDZU8mcGaae-SxeA5FGPWZDseaNU=.e0b530df-d73a-424c-98ee-df076edab7b1@github.com>
References: <4zfUGx0G872UH1PQDZU8mcGaae-SxeA5FGPWZDseaNU=.e0b530df-d73a-424c-98ee-df076edab7b1@github.com>
Message-ID: <C9pw5diZ8CL-XApGGbl5ZzeSd_Jp0vH-vH6UHl6NZ7c=.a6d1cfd9-950d-4989-a10f-823674c8a92f@github.com>

On Tue, 15 Dec 2020 21:19:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Relatively simple update to fix an oversight in the support for records. `RECORD` was not added to `DeprElementKind` with the derivative downstream updates.

This pull request has now been integrated.

Changeset: ce0ab2dd
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk16/commit/ce0ab2dd
Stats:     84 lines in 5 files changed: 83 ins; 0 del; 1 mod

8258338: Support deprecated records

Reviewed-by: hannesw

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

PR: https://git.openjdk.java.net/jdk16/pull/29

From jjg at openjdk.java.net  Wed Dec 16 22:30:56 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 16 Dec 2020 22:30:56 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search
In-Reply-To: <h4L7gwb3BEtV6LBW0MrXnCCuYsqclJw3czHLDHDzv2U=.e1a66d2b-7be5-41d7-90e5-be116ed55caf@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
 <h4L7gwb3BEtV6LBW0MrXnCCuYsqclJw3czHLDHDzv2U=.e1a66d2b-7be5-41d7-90e5-be116ed55caf@github.com>
Message-ID: <n4TZRZAE4icwhh4C0YbnPciLYpJRyUFF8TRu5B1OrDo=.7d5d8fa5-a681-4160-9d7e-5768a5a1efad@github.com>

On Mon, 14 Dec 2020 09:11:31 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This is for JDK16, as a precursor to fixing JDK-8258002.
>> 
>> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
>> 
>> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/search.js.template line 40:
> 
>> 38: var MIN_RESULTS = 3;
>> 39: var MAX_RESULTS = 500;
>> 40: var UNNAMED = "##REPLACE:doclet.search.unnamed##";
> 
> `<Unnamed>` is not a string that is ever shown to the user, it is what is used by javadoc to denote the default package (see `toolkit.util.DocletConstants.DEFAULT_PACKAGE_NAME`). This variable shouldn't be localized as that would break behaviour for code in the default package (and show the localized string as package name, instead of no package name).

Noted, thanks

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

PR: https://git.openjdk.java.net/jdk16/pull/16

From jjg at openjdk.java.net  Wed Dec 16 23:21:11 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 16 Dec 2020 23:21:11 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search [v2]
In-Reply-To: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
Message-ID: <1GIodXJQxB1mO27Of0bxkkihV_wRhbb3EoGTnCFWG3w=.f927c17d-3653-4d58-9210-dc5b692386b8@github.com>

> This is for JDK16, as a precursor to fixing JDK-8258002.
> 
> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
> 
> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.

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

 - Merge remote-tracking branch 'upstream/master' into localize.search.js
 - JDK-8247994: Localize javadoc search

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

Changes:
  - all: https://git.openjdk.java.net/jdk16/pull/16/files
  - new: https://git.openjdk.java.net/jdk16/pull/16/files/8eb7f27b..ec111185

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

  Stats: 1532 lines in 52 files changed: 1207 ins; 121 del; 204 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/16.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/16/head:pull/16

PR: https://git.openjdk.java.net/jdk16/pull/16

From ysatowse at openjdk.java.net  Thu Dec 17 01:40:14 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Thu, 17 Dec 2020 01:40:14 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v3]
In-Reply-To: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
Message-ID: <198fmbGGxYO2VRc3gAVf89rYSoQFlnKyThNUzvuI5uk=.da1f6607-9e2e-48c2-8ab3-833f207a960c@github.com>

> HTML4 is no longer supported in javadoc.
> 
> doclint needs to drop HTML4 support as well.
> The changes consist of:
> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
> * Modifying test code and expected outputs to be checked in HTML5

Yoshiki Sato 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:

  8257204 and 8256313
  8257204: Remove usage of -Xhtmlversion option from javac
  8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/893/files
  - new: https://git.openjdk.java.net/jdk/pull/893/files/294b3cce..30db3882

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

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

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

From jwilhelm at openjdk.java.net  Thu Dec 17 02:59:10 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 17 Dec 2020 02:59:10 GMT
Subject: RFR: Merge jdk16
Message-ID: <McqAH5-R-bb_iCp28M-rz3l1FgelG-P-leUREc2C2d8=.c6cb6368-a6f4-43c1-86d7-cdad7caf236d@github.com>

Merge JDK 16 -> JDK 17

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

Commit messages:
 - Merge
 - 8258338: Support deprecated records
 - 8241353: NPE in ToolProvider.getSystemJavaCompiler
 - 8255880: UI of Swing components is not redrawn after their internal state changed
 - 8257637: Update usage of "type" terminology in java.lang.annotation
 - 8258236: Segfault in ClassListParser::resolve_indy dumping static AppCDS archive
 - 8258419: RSA cipher buffer cleanup
 - 8258380: [JVMCI] don't clear InstalledCode reference when unloading JVMCI nmethods
 - 8258427: Problem List some tests related to FileDialog for MacOS
 - 8258140: Update @jls tags in java.base for renamed/renumbered sections
 - ... and 4 more: https://git.openjdk.java.net/jdk/compare/b2f03554...951fc9c0

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

Changes: https://git.openjdk.java.net/jdk/pull/1812/files
  Stats: 882 lines in 41 files changed: 659 ins; 30 del; 193 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1812.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1812/head:pull/1812

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

From jwilhelm at openjdk.java.net  Thu Dec 17 03:08:57 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 17 Dec 2020 03:08:57 GMT
Subject: Integrated: Merge jdk16
In-Reply-To: <McqAH5-R-bb_iCp28M-rz3l1FgelG-P-leUREc2C2d8=.c6cb6368-a6f4-43c1-86d7-cdad7caf236d@github.com>
References: <McqAH5-R-bb_iCp28M-rz3l1FgelG-P-leUREc2C2d8=.c6cb6368-a6f4-43c1-86d7-cdad7caf236d@github.com>
Message-ID: <6qEv2eY0O11uVLbYwNrAVT7U4LFVK5INiyqa2hByAyQ=.5b8cb7e1-d127-487a-91fc-a1a65e4786b3@github.com>

On Thu, 17 Dec 2020 02:48:38 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Merge JDK 16 -> JDK 17

This pull request has now been integrated.

Changeset: 11bd7a81
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/11bd7a81
Stats:     882 lines in 41 files changed: 659 ins; 30 del; 193 mod

Merge

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

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

From jjg at openjdk.java.net  Thu Dec 17 05:01:03 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 17 Dec 2020 05:01:03 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v3]
In-Reply-To: <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
Message-ID: <utC2G0Ga3tAOMc2s-SPwbfinJD5P8fyxUHnM23lJOp4=.6cf5de97-58c8-40a3-8265-3a52eff785df@github.com>

On Thu, 12 Nov 2020 03:10:01 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/HtmlTag.java line 410:
>> 
>>> 408:         OBSOLETE,
>>> 409:         UNSUPPORTED
>>> 410:     }
>> 
>> On one hand, I don't think we need this level of detail, but on the other, I see it closely matches `AttrKind`, so OK.
>> 
>> Is there are useful distinction between INVALID / OBSOLETE / UNSUPPORTED ?
>
> OK: valid
> OBSOLETE: obsolete, deprecated, but still supported (valid)
> UNSUPPORTED: ever supported but no longer supported (invalid)
> INVALID: the rest of others (invalid)
> 
> UNSUPPORTED can be used if we would like to choose a friendly message instead of saying "unknown tag" only.
> OBSOLETE is not used anywhere in this commit.  Although HTML5 has some obsolete features, [JDK-8215577](https://bugs.openjdk.java.net/browse/JDK-8215577) didn't define them as valid features if my understanding is correct.  So I chose not to allow obsolete features in order to avoid inconsistency.

For both `ElemKind` and `AttrKind` there only seem to be two kinds:
* valid
* previously valid

For these two cases, `OK` is obviously reasonable for `valid`, but `OBSOLETE` seems a better fit than `UNSUPPORTED`, but you could also use `HTML4` or `OLD_HTML4` or something like that to indicate why we're keeping the name around for better messages.  Or, stay with `UNSUPPORTED` but add a doc comment explaining that it was previously supported but no longer supported

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

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

From jjg at openjdk.java.net  Thu Dec 17 05:01:03 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 17 Dec 2020 05:01:03 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v3]
In-Reply-To: <198fmbGGxYO2VRc3gAVf89rYSoQFlnKyThNUzvuI5uk=.da1f6607-9e2e-48c2-8ab3-833f207a960c@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <198fmbGGxYO2VRc3gAVf89rYSoQFlnKyThNUzvuI5uk=.da1f6607-9e2e-48c2-8ab3-833f207a960c@github.com>
Message-ID: <BLs1ScSdxGuJRpKnq8ofPhBe5NMV0oV8lb-u-bLpAg0=.9e77a827-999f-4e56-9d29-9d23dc164d50@github.com>

On Thu, 17 Dec 2020 01:40:14 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> HTML4 is no longer supported in javadoc.
>> 
>> doclint needs to drop HTML4 support as well.
>> The changes consist of:
>> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
>> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
>> * Modifying test code and expected outputs to be checked in HTML5
>
> Yoshiki Sato 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:
> 
>   8257204 and 8256313
>   8257204: Remove usage of -Xhtmlversion option from javac
>   8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option

Mostly OK; some minor suggestions

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 36:

> 34: dc.attr.img.border.not.number = attribute "border" for img is not a number
> 35: dc.attr.table.border.not.valid = attribute "border" for table only accepts "" or "1", use CSS instead: {0}
> 36: dc.attr.table.border.not.number = attribute "border" for table is not a number

suggest dropping "use CSS instead"

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

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

From jjg at openjdk.java.net  Thu Dec 17 05:01:04 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 17 Dec 2020 05:01:04 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v3]
In-Reply-To: <BLs1ScSdxGuJRpKnq8ofPhBe5NMV0oV8lb-u-bLpAg0=.9e77a827-999f-4e56-9d29-9d23dc164d50@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <198fmbGGxYO2VRc3gAVf89rYSoQFlnKyThNUzvuI5uk=.da1f6607-9e2e-48c2-8ab3-833f207a960c@github.com>
 <BLs1ScSdxGuJRpKnq8ofPhBe5NMV0oV8lb-u-bLpAg0=.9e77a827-999f-4e56-9d29-9d23dc164d50@github.com>
Message-ID: <ct3G5aCjd2l1ULLxIeslbJeu_pdn7Y9XrUo3iALSTdM=.8ca1e3d4-6fc0-4929-ba6d-b9055b5f7093@github.com>

On Thu, 17 Dec 2020 04:50:59 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Yoshiki Sato 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:
>> 
>>   8257204 and 8256313
>>   8257204: Remove usage of -Xhtmlversion option from javac
>>   8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 36:
> 
>> 34: dc.attr.img.border.not.number = attribute "border" for img is not a number
>> 35: dc.attr.table.border.not.valid = attribute "border" for table only accepts "" or "1", use CSS instead: {0}
>> 36: dc.attr.table.border.not.number = attribute "border" for table is not a number
> 
> suggest dropping "use CSS instead"

The wording of `attribute "border" for img is not a number` seems strange.
Suggest something like `invalid value for attribute "border": {0}`

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

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

From ysatowse at openjdk.java.net  Thu Dec 17 06:37:00 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Thu, 17 Dec 2020 06:37:00 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v3]
In-Reply-To: <ct3G5aCjd2l1ULLxIeslbJeu_pdn7Y9XrUo3iALSTdM=.8ca1e3d4-6fc0-4929-ba6d-b9055b5f7093@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <198fmbGGxYO2VRc3gAVf89rYSoQFlnKyThNUzvuI5uk=.da1f6607-9e2e-48c2-8ab3-833f207a960c@github.com>
 <BLs1ScSdxGuJRpKnq8ofPhBe5NMV0oV8lb-u-bLpAg0=.9e77a827-999f-4e56-9d29-9d23dc164d50@github.com>
 <ct3G5aCjd2l1ULLxIeslbJeu_pdn7Y9XrUo3iALSTdM=.8ca1e3d4-6fc0-4929-ba6d-b9055b5f7093@github.com>
Message-ID: <LaPvn9zXOCuv3dabCWRzTvMc_Qmch_-YLBUnkrS1Njw=.6f56b3b4-1382-49b5-845c-3250c591143f@github.com>

On Thu, 17 Dec 2020 04:52:48 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 36:
>> 
>>> 34: dc.attr.img.border.not.number = attribute "border" for img is not a number
>>> 35: dc.attr.table.border.not.valid = attribute "border" for table only accepts "" or "1", use CSS instead: {0}
>>> 36: dc.attr.table.border.not.number = attribute "border" for table is not a number
>> 
>> suggest dropping "use CSS instead"
>
> The wording of `attribute "border" for img is not a number` seems strange.
> Suggest something like `invalid value for attribute "border": {0}`

Ok, I will fix that.

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

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

From ysatowse at openjdk.java.net  Thu Dec 17 06:42:01 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Thu, 17 Dec 2020 06:42:01 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v3]
In-Reply-To: <utC2G0Ga3tAOMc2s-SPwbfinJD5P8fyxUHnM23lJOp4=.6cf5de97-58c8-40a3-8265-3a52eff785df@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <RAdVAZpFjoxQnDj02FVOpgugTaQuNd-LMzpKXeu4VEU=.465404f4-4737-4ec2-b7b5-1681b6471698@github.com>
 <n2ea4PoUtsEtADcdUM3AkkrO22AT2Tn4nJo2TspgK54=.3d72d7f6-3ce5-4aa3-a2aa-3f49c51b83b1@github.com>
 <utC2G0Ga3tAOMc2s-SPwbfinJD5P8fyxUHnM23lJOp4=.6cf5de97-58c8-40a3-8265-3a52eff785df@github.com>
Message-ID: <nIfzA3CWPNH4afTxI1eBE303Bsj6gINA4pYPe5dOpu8=.2d5bdda8-f220-4b47-ad76-44e83405bb35@github.com>

On Thu, 17 Dec 2020 04:48:44 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> OK: valid
>> OBSOLETE: obsolete, deprecated, but still supported (valid)
>> UNSUPPORTED: ever supported but no longer supported (invalid)
>> INVALID: the rest of others (invalid)
>> 
>> UNSUPPORTED can be used if we would like to choose a friendly message instead of saying "unknown tag" only.
>> OBSOLETE is not used anywhere in this commit.  Although HTML5 has some obsolete features, [JDK-8215577](https://bugs.openjdk.java.net/browse/JDK-8215577) didn't define them as valid features if my understanding is correct.  So I chose not to allow obsolete features in order to avoid inconsistency.
>
> For both `ElemKind` and `AttrKind` there only seem to be two kinds:
> * valid
> * previously valid
> 
> For these two cases, `OK` is obviously reasonable for `valid`, but `OBSOLETE` seems a better fit than `UNSUPPORTED`, but you could also use `HTML4` or `OLD_HTML4` or something like that to indicate why we're keeping the name around for better messages.  Or, stay with `UNSUPPORTED` but add a doc comment explaining that it was previously supported but no longer supported

Ok, I will use `HTML4`.

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

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

From jjg at openjdk.java.net  Thu Dec 17 16:39:17 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 17 Dec 2020 16:39:17 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search [v3]
In-Reply-To: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
Message-ID: <yNCZp72SmLyGtISZOHf03lrmZWaObtajWmXyeNZITqc=.caba81f4-e70b-42a2-b92c-3d93bcf5b377@github.com>

> This is for JDK16, as a precursor to fixing JDK-8258002.
> 
> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
> 
> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.

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

  Address review comment

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

Changes:
  - all: https://git.openjdk.java.net/jdk16/pull/16/files
  - new: https://git.openjdk.java.net/jdk16/pull/16/files/ec111185..1a406f35

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

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

PR: https://git.openjdk.java.net/jdk16/pull/16

From hannesw at openjdk.java.net  Thu Dec 17 17:06:00 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 17 Dec 2020 17:06:00 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search [v3]
In-Reply-To: <yNCZp72SmLyGtISZOHf03lrmZWaObtajWmXyeNZITqc=.caba81f4-e70b-42a2-b92c-3d93bcf5b377@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
 <yNCZp72SmLyGtISZOHf03lrmZWaObtajWmXyeNZITqc=.caba81f4-e70b-42a2-b92c-3d93bcf5b377@github.com>
Message-ID: <-H-OPr6wCQeLESYlsa7aQTVJjtzxeknaqJRpy0-s0L8=.af6de1b0-749d-4cf4-898b-2f4284db3ebd@github.com>

On Thu, 17 Dec 2020 16:39:17 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This is for JDK16, as a precursor to fixing JDK-8258002.
>> 
>> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
>> 
>> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Address review comment

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/search.js.template line 40:

> 38: var MIN_RESULTS = 3;
> 39: var MAX_RESULTS = 500;
> 40: var UNNAMED = "<Unnamed>>";

Oops, an additional closing angle bracket slipped there.

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

PR: https://git.openjdk.java.net/jdk16/pull/16

From jjg at openjdk.java.net  Thu Dec 17 17:13:14 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 17 Dec 2020 17:13:14 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search [v4]
In-Reply-To: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
Message-ID: <z4c0UByrdXBXCUoBX41qx9nJJVh0XOUynSgF9mAFt4Q=.70d8db98-dc89-4883-96aa-eb1f8c8770fc@github.com>

> This is for JDK16, as a precursor to fixing JDK-8258002.
> 
> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
> 
> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.

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

  Address review comment

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

Changes:
  - all: https://git.openjdk.java.net/jdk16/pull/16/files
  - new: https://git.openjdk.java.net/jdk16/pull/16/files/1a406f35..de6802c0

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

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

PR: https://git.openjdk.java.net/jdk16/pull/16

From hannesw at openjdk.java.net  Thu Dec 17 17:13:15 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 17 Dec 2020 17:13:15 GMT
Subject: [jdk16] RFR: JDK-8247994: Localize javadoc search [v4]
In-Reply-To: <z4c0UByrdXBXCUoBX41qx9nJJVh0XOUynSgF9mAFt4Q=.70d8db98-dc89-4883-96aa-eb1f8c8770fc@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
 <z4c0UByrdXBXCUoBX41qx9nJJVh0XOUynSgF9mAFt4Q=.70d8db98-dc89-4883-96aa-eb1f8c8770fc@github.com>
Message-ID: <6teL5P5Sg13pNY0zUuTF-wQc5a_rr8zrq4xNAxoGJL0=.5d6444e0-66d4-43ee-aa80-5ac2bfa9fc75@github.com>

On Thu, 17 Dec 2020 17:10:10 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This is for JDK16, as a precursor to fixing JDK-8258002.
>> 
>> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
>> 
>> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Address review comment

Marked as reviewed by hannesw (Reviewer).

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

PR: https://git.openjdk.java.net/jdk16/pull/16

From jjg at openjdk.java.net  Thu Dec 17 18:36:58 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 17 Dec 2020 18:36:58 GMT
Subject: [jdk16] Integrated: JDK-8247994: Localize javadoc search
In-Reply-To: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
References: <z3KZ-s7GOAJs559ZzG72xKfifl6AnB9raU6UvxMizt4=.c9c8dd11-5c19-4efd-a358-a8f0c0cdc196@github.com>
Message-ID: <mLgRaQMV52_N_PKjfTsigoc0sYxYeecyxktxV7i98-A=.7f258a87-60b0-4a0d-a25e-b45d4ad3a3e1@github.com>

On Sun, 13 Dec 2020 00:19:59 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This is for JDK16, as a precursor to fixing JDK-8258002.
> 
> While it is good to be using localized strings in the generated output, the significance for JDK-8258002 is that the strings are now obtained from a resource file, and not hardcoded in JavaScript file itself.
> 
> The source file `search.js` is renamed to `search.js.template`, and (unlike other template files) is copied as-is into the generated image. The values in the template are resolved when javadoc is executed, depending on the locale in use at the time. Because of the change in the file's extension, two makefiles are updated to accommodate the new extension: one is for the "interim" javadoc used to generate the API docs; the other is for the primary javadoc in the main JDK image.

This pull request has now been integrated.

Changeset: 30ca0a5d
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk16/commit/30ca0a5d
Stats:     120 lines in 9 files changed: 87 ins; 6 del; 27 mod

8247994: Localize javadoc search

Reviewed-by: hannesw, ihse

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

PR: https://git.openjdk.java.net/jdk16/pull/16

From jjg at openjdk.java.net  Thu Dec 17 19:58:10 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 17 Dec 2020 19:58:10 GMT
Subject: [jdk16] RFR: JDK-8258002: Update "type" terminology in generated
 docs [v2]
In-Reply-To: <2iGo26T8BEhIoC_m49jykuUx56I8011VN3Sq6b_X2w4=.ca025625-a929-49df-8242-5924c305b7b7@github.com>
References: <2iGo26T8BEhIoC_m49jykuUx56I8011VN3Sq6b_X2w4=.ca025625-a929-49df-8242-5924c305b7b7@github.com>
Message-ID: <mIYyYFJ0Ngx5sxWDApgZgjFQ-uuZCFRucc9bYX9gbrQ=.a209cef6-d282-4aeb-99ba-3da510d229ad@github.com>

> This is the bulk of the work to update javadoc to use certain terminology dependent on the source version in use. There will be a minor update when JDK-8247994 has been pushed. That will allow us to modify strings displayed by JavaScript Search.
> 
> The groups of terms being changed are:
> 
> * `Types` to `Classes and Interfaces`
> * `Annotation Type` to `Annotation Interface`
> * `Enum` to `Enum Class`
> 
> The new terminology will be used when the source version of the elements being documented is 16 or higher. This is the default behavior. The corollary is that the old terminology will be used when the `--source` or `--release` option is used to specify a version less than `16`.
> 
> In addition, the terminology for `Record` is being unconditionally changed to use `Record Class`. Since the feature was in preview before this release, there is no need to be able to generate the previous form.
> 
> Also, in the course of this work, it was noted that on the "Use" page for an annotation type/interface, it was incorrectly classified as a *class*, instead of *annotation interface*: that has been fixed.
> 
> Fundamentally, the change is managed at a very low level, by passing a _mapping function_ into `Resource.getText`. This allows high level code, `HtmlDoclet` in this case, to provide version-specific overrides of the resource key to be used. The avoids having to have version-specific checks at the point of use for each affected resource.

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

 - Fix failures
 - Merge with upstream/master
 - remove adaptive terminology for records
 - add test
 - Remove obsolete properties and code
 - Version 2: release-specific terminology
 - JDK-8258002: Update "type" terminology in generated docs

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

Changes: https://git.openjdk.java.net/jdk16/pull/20/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=20&range=01
  Stats: 564 lines in 45 files changed: 323 ins; 45 del; 196 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/20.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/20/head:pull/20

PR: https://git.openjdk.java.net/jdk16/pull/20

From jwilhelm at openjdk.java.net  Thu Dec 17 20:44:15 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 17 Dec 2020 20:44:15 GMT
Subject: Integrated: Merge jdk16
Message-ID: <LD8ANDgogS-bx4izFlwhL_9-MwiCI2jNn6a4Ehb2wmA=.80d8ff3d-e60b-4634-bcce-943c96d6edbd@github.com>

Forwardport JDK 16 -> JDK 17

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

Commit messages:
 - Merge
 - 8247994: Localize javadoc search
 - 8258515: javac should issue an error if an annotation is nested in a local class or interface
 - 8258225: compiler/c2/cr6340864/TestIntVect.java runs faster in interpreter
 - 8258293: tools/jpackage/share/RuntimePackageTest.java#id0 with RuntimePackageTest.testUsrInstallDir2
 - 8257621: JFR StringPool misses cached items across consecutive recordings
 - 8257999: Parallel GC crash in gc/parallel/TestDynShrinkHeap.java: new region is not in covered_region
 - 8257636: Update usage of "type" terminology in java.lang.Class and java.lang.reflect
 - 8258505: [TESTBUG] TestDivZeroWithSplitIf.java fails due to missing UnlockDiagnosticVMOptions
 - 8254023: A module declaration is not allowed to be a target of an annotation that lacks an @Target meta-annotation

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

Changes: https://git.openjdk.java.net/jdk/pull/1827/files
  Stats: 773 lines in 63 files changed: 449 ins; 124 del; 200 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1827.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1827/head:pull/1827

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

From jwilhelm at openjdk.java.net  Thu Dec 17 20:44:15 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 17 Dec 2020 20:44:15 GMT
Subject: Integrated: Merge jdk16
In-Reply-To: <LD8ANDgogS-bx4izFlwhL_9-MwiCI2jNn6a4Ehb2wmA=.80d8ff3d-e60b-4634-bcce-943c96d6edbd@github.com>
References: <LD8ANDgogS-bx4izFlwhL_9-MwiCI2jNn6a4Ehb2wmA=.80d8ff3d-e60b-4634-bcce-943c96d6edbd@github.com>
Message-ID: <Rb-Ei4T62YffDeV4VkDR96LjtERDt8U5cJKXE0Vk7kY=.67f13552-6ea7-4be4-a61d-d546c313b68f@github.com>

On Thu, 17 Dec 2020 20:38:45 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Forwardport JDK 16 -> JDK 17

This pull request has now been integrated.

Changeset: f15528eb
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/f15528eb
Stats:     773 lines in 63 files changed: 449 ins; 124 del; 200 mod

Merge

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

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

From jjg at openjdk.java.net  Fri Dec 18 01:22:02 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 18 Dec 2020 01:22:02 GMT
Subject: RFR: JDK-8258655: remove <-- NewPage --> comment from generated pages
Message-ID: <IX2kZVdTgcBtKACIyHuL3rmOwhaNImBxNu_mYb4rpsc=.bfee4f7f-3290-455b-b2a8-3f7fff38919b@github.com>

Small change to remove an unnecessary comment from the beginning of generated files.  I'm guessing the comment dates from way back when the doc pages were used to generate paper books.  For those that want to identify that point in the file, either the DOCTYPE or start of the HTML elements t should be enough.

No test: it's somewhat silly to rigorously test that the comment will always be missing.

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

Commit messages:
 - JDK-8258655: remove <-- NewPage --> comment from generated pages

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

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

From ysatowse at openjdk.java.net  Fri Dec 18 01:34:15 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 18 Dec 2020 01:34:15 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v4]
In-Reply-To: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
Message-ID: <vZkUHKS22sXksvEkZIlwencSsNSc0HTcCR-5Mp71daQ=.06eeb39b-39c4-4854-861d-432a4b95e946@github.com>

> HTML4 is no longer supported in javadoc.
> 
> doclint needs to drop HTML4 support as well.
> The changes consist of:
> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
> * Modifying test code and expected outputs to be checked in HTML5

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

  5th: 8257204 and 8256313
  8257204: Remove usage of -Xhtmlversion option from javac
  8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/893/files
  - new: https://git.openjdk.java.net/jdk/pull/893/files/30db3882..f9ae0c5f

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

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

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

From ysatowse at openjdk.java.net  Fri Dec 18 02:34:16 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 18 Dec 2020 02:34:16 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
Message-ID: <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>

> HTML4 is no longer supported in javadoc.
> 
> doclint needs to drop HTML4 support as well.
> The changes consist of:
> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
> * Modifying test code and expected outputs to be checked in HTML5

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

  5th: 8258460: Remove --doclint-format option from javac

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/893/files
  - new: https://git.openjdk.java.net/jdk/pull/893/files/f9ae0c5f..261f207a

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

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

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

From ysatowse at openjdk.java.net  Fri Dec 18 02:42:00 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 18 Dec 2020 02:42:00 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v3]
In-Reply-To: <BLs1ScSdxGuJRpKnq8ofPhBe5NMV0oV8lb-u-bLpAg0=.9e77a827-999f-4e56-9d29-9d23dc164d50@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <198fmbGGxYO2VRc3gAVf89rYSoQFlnKyThNUzvuI5uk=.da1f6607-9e2e-48c2-8ab3-833f207a960c@github.com>
 <BLs1ScSdxGuJRpKnq8ofPhBe5NMV0oV8lb-u-bLpAg0=.9e77a827-999f-4e56-9d29-9d23dc164d50@github.com>
Message-ID: <rY5rzSkeAG6Y5_HV9oA4UW_wY0957Dk7nvE6fSdY-ws=.02fe43aa-e5ae-425b-beb3-23d414423408@github.com>

On Thu, 17 Dec 2020 04:58:21 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Yoshiki Sato 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:
>> 
>>   8257204 and 8256313
>>   8257204: Remove usage of -Xhtmlversion option from javac
>>   8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option
>
> Mostly OK; some minor suggestions

Some related changes to 8258460 in closed repo is here.
https://orahub.oci.oraclecorp.com/yoshiki_sato/jdk/-/merge_requests/new?merge_request%5Bsource_branch%5D=JDK-8247957_2

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

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

From jjg at openjdk.java.net  Fri Dec 18 04:25:01 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 18 Dec 2020 04:25:01 GMT
Subject: RFR: JDK-8258659: Eliminate whitespace comments from generated pages
Message-ID: <5MNWSdLupasKzYLghGsNqzC784_BE0Ph4pJg5UvxL0U=.7172efb2-b80c-4c97-abe8-6ecf389f0400@github.com>

Empty comments were being used to stop empty nodes being optimized away in `HtmlTree.add`, but the empty comments caused annoying noise in the generated docs.  A better solution is to use `HtmlTree.EMPTY`, which had the right effect, without the unwanted side-effects.

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

Commit messages:
 - JDK-8258659: Eliminate whitespace comments from generated pages

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

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

From hannesw at openjdk.java.net  Fri Dec 18 14:31:38 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 18 Dec 2020 14:31:38 GMT
Subject: [jdk16] RFR: 8223607: --override-methods=summary ignores some
 signature changes
Message-ID: <R831Ww4fvhtFT3FEjl0b3a-G6uqEEU4HX6o5BHF7gzE=.69628a72-1287-495f-a1f3-38e3d098e5c6@github.com>

Jon, 

I created a new pull request for this on the jdk16 repository because the original one was created on the mainline jdk repo. The first commit in this PR is identical to the one you already reviewed in the old PR. The second commit adds checks and tests for changes from non-final to final and changes in abstractness of overriding methods. Thus the full list of conditions under which a simple overriding method is included in the details section of the overriding class is now:


    - method access changes from protected to public
    - method is overridden as final
    - method overridden with different abstractness
    - any change in thrown exceptions
    - change in documented annotations anywhere in the method signature

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

Commit messages:
 - Include conditions listed in JDK-8258429
 - JDK-8223607: --override-methods=summary ignores some signature changes

Changes: https://git.openjdk.java.net/jdk16/pull/52/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=52&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8223607
  Stats: 472 lines in 7 files changed: 443 ins; 15 del; 14 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/52.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/52/head:pull/52

PR: https://git.openjdk.java.net/jdk16/pull/52

From hannesw at openjdk.java.net  Fri Dec 18 14:32:25 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 18 Dec 2020 14:32:25 GMT
Subject: RFR: 8223607: --override-methods=summary ignores some signature
 changes
In-Reply-To: <UHgKVFwyn2NQaTCgewfr7xvkZNpyFXvSsE2iRdkyE4M=.df93926d-9003-40a2-bff8-153171a11445@github.com>
References: <h5-58f5Q1E-u5-z14_MedqI_uzzzKDZjRVl1Hv4DC_k=.24aa42fc-ac49-476d-a504-b1ef8c740066@github.com>
 <UHgKVFwyn2NQaTCgewfr7xvkZNpyFXvSsE2iRdkyE4M=.df93926d-9003-40a2-bff8-153171a11445@github.com>
Message-ID: <Qd_7Eh-g-4vG1ojxJl3D7uZ94s93e_uIpCCjEZXBbjM=.6dbfc162-5f75-41db-ab17-3ded3c215c03@github.com>

On Wed, 16 Dec 2020 18:15:27 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This change causes overriding methods to be documented in the details section under some conditions even when javadoc is run with `--override-methods=summary` and the method does not have a doc comment. Previously this already happened when the overriding method had a covariant return type (JDK-8219147). The following conditions will now trigger the same behaviour:
>> 
>>  - method visibility changes from `protected` to `public`
>>  - any change in thrown exceptions
>>  - change in documented annotations anywhere in the method signature
>> 
>> The conditions are simple by intention as we don't want to do checks that add to much complexity (such as distinguishing between checked and unchecked exceptions) and instead want to set the bar for inclusion in the details section relatively low.
>
> This looks good, but given the noteworthy and significant changes in `VisibleMemberTable`,
> I'd like to suggest you address JDK-8258429 at this time, which has significant overlap.

New PR created for jdk16 repository, closing this one.

https://github.com/openjdk/jdk16/pull/52

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

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

From hannesw at openjdk.java.net  Fri Dec 18 14:32:26 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 18 Dec 2020 14:32:26 GMT
Subject: Withdrawn: 8223607: --override-methods=summary ignores some signature
 changes
In-Reply-To: <h5-58f5Q1E-u5-z14_MedqI_uzzzKDZjRVl1Hv4DC_k=.24aa42fc-ac49-476d-a504-b1ef8c740066@github.com>
References: <h5-58f5Q1E-u5-z14_MedqI_uzzzKDZjRVl1Hv4DC_k=.24aa42fc-ac49-476d-a504-b1ef8c740066@github.com>
Message-ID: <sdl5sgs4CqapCzFGkSJ0mLA9S-wc4bRLYL9fhurKI0k=.b7145cff-7b24-4aee-9981-66b502497c1f@github.com>

On Thu, 10 Dec 2020 13:17:49 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This change causes overriding methods to be documented in the details section under some conditions even when javadoc is run with `--override-methods=summary` and the method does not have a doc comment. Previously this already happened when the overriding method had a covariant return type (JDK-8219147). The following conditions will now trigger the same behaviour:
> 
>  - method visibility changes from `protected` to `public`
>  - any change in thrown exceptions
>  - change in documented annotations anywhere in the method signature
> 
> The conditions are simple by intention as we don't want to do checks that add to much complexity (such as distinguishing between checked and unchecked exceptions) and instead want to set the bar for inclusion in the details section relatively low.

This pull request has been closed without being integrated.

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

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

From hannesw at openjdk.java.net  Fri Dec 18 14:40:44 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 18 Dec 2020 14:40:44 GMT
Subject: [jdk16] RFR: 8223607: --override-methods=summary ignores some
 signature changes [v2]
In-Reply-To: <R831Ww4fvhtFT3FEjl0b3a-G6uqEEU4HX6o5BHF7gzE=.69628a72-1287-495f-a1f3-38e3d098e5c6@github.com>
References: <R831Ww4fvhtFT3FEjl0b3a-G6uqEEU4HX6o5BHF7gzE=.69628a72-1287-495f-a1f3-38e3d098e5c6@github.com>
Message-ID: <3OtDHcxq5DeiZBOTrsMw4fiPT3ZtYWAaNP6OQJgV_iw=.ef60099a-4a52-4010-9eff-c15a1b3144c2@github.com>

> Jon, 
> 
> I created a new pull request for this on the jdk16 repository because the original one was created on the mainline jdk repo. The first commit in this PR is identical to the one you already reviewed in the old PR. The second commit adds checks and tests for changes from non-final to final and changes in abstractness of overriding methods. Thus the full list of conditions under which a simple overriding method is included in the details section of the overriding class is now:
> 
> 
>     - method access changes from protected to public
>     - method is overridden as final
>     - method overridden with different abstractness
>     - any change in thrown exceptions
>     - change in documented annotations anywhere in the method signature

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

  Minor fix in test comment

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

Changes:
  - all: https://git.openjdk.java.net/jdk16/pull/52/files
  - new: https://git.openjdk.java.net/jdk16/pull/52/files/f3b88db9..c7e46912

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

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

PR: https://git.openjdk.java.net/jdk16/pull/52

From jjg at openjdk.java.net  Fri Dec 18 15:36:36 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 18 Dec 2020 15:36:36 GMT
Subject: [jdk16] RFR: 8223607: --override-methods=summary ignores some
 signature changes [v2]
In-Reply-To: <3OtDHcxq5DeiZBOTrsMw4fiPT3ZtYWAaNP6OQJgV_iw=.ef60099a-4a52-4010-9eff-c15a1b3144c2@github.com>
References: <R831Ww4fvhtFT3FEjl0b3a-G6uqEEU4HX6o5BHF7gzE=.69628a72-1287-495f-a1f3-38e3d098e5c6@github.com>
 <3OtDHcxq5DeiZBOTrsMw4fiPT3ZtYWAaNP6OQJgV_iw=.ef60099a-4a52-4010-9eff-c15a1b3144c2@github.com>
Message-ID: <qZbfbLmsU2U1dMs50VsJcy5_8fISqhJXDjPKe__T5pE=.d6887457-b2be-4982-a566-726d9815a0a0@github.com>

On Fri, 18 Dec 2020 14:40:44 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Jon, 
>> 
>> I created a new pull request for this on the jdk16 repository because the original one was created on the mainline jdk repo. The first commit in this PR is identical to the one you already reviewed in the old PR. The second commit adds checks and tests for changes from non-final to final and changes in abstractness of overriding methods. Thus the full list of conditions under which a simple overriding method is included in the details section of the overriding class is now:
>> 
>> 
>>     - method access changes from protected to public
>>     - method is overridden as final
>>     - method overridden with different abstractness
>>     - any change in thrown exceptions
>>     - change in documented annotations anywhere in the method signature
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Minor fix in test comment

Nice.

Marked as reviewed by jjg (Reviewer).

Marked as reviewed by jjg (Reviewer).

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

Marked as reviewed by jjg (Reviewer).

PR: https://git.openjdk.java.net/jdk16/pull/52

From hannesw at openjdk.java.net  Fri Dec 18 15:50:00 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 18 Dec 2020 15:50:00 GMT
Subject: [jdk16] Integrated: 8223607: --override-methods=summary ignores some
 signature changes
In-Reply-To: <R831Ww4fvhtFT3FEjl0b3a-G6uqEEU4HX6o5BHF7gzE=.69628a72-1287-495f-a1f3-38e3d098e5c6@github.com>
References: <R831Ww4fvhtFT3FEjl0b3a-G6uqEEU4HX6o5BHF7gzE=.69628a72-1287-495f-a1f3-38e3d098e5c6@github.com>
Message-ID: <EiCzPW19h-Z0XgsFRVNnBd4YFIeTxrmMeiuPICmPFCs=.707defbe-5d28-44d7-8e33-e06a8d49ee08@github.com>

On Fri, 18 Dec 2020 14:26:32 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Jon, 
> 
> I created a new pull request for this on the jdk16 repository because the original one was created on the mainline jdk repo. The first commit in this PR is identical to the one you already reviewed in the old PR. The second commit adds checks and tests for changes from non-final to final and changes in abstractness of overriding methods. Thus the full list of conditions under which a simple overriding method is included in the details section of the overriding class is now:
> 
> 
>     - method access changes from protected to public
>     - method is overridden as final
>     - method overridden with different abstractness
>     - any change in thrown exceptions
>     - change in documented annotations anywhere in the method signature

This pull request has now been integrated.

Changeset: 45bd3b9e
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.java.net/jdk16/commit/45bd3b9e
Stats:     472 lines in 7 files changed: 443 ins; 15 del; 14 mod

8223607: --override-methods=summary ignores some signature changes

Reviewed-by: jjg

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

PR: https://git.openjdk.java.net/jdk16/pull/52

From hannesw at openjdk.java.net  Fri Dec 18 17:26:03 2020
From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 18 Dec 2020 17:26:03 GMT
Subject: [jdk16] RFR: JDK-8258002: Update "type" terminology in generated
 docs [v2]
In-Reply-To: <mIYyYFJ0Ngx5sxWDApgZgjFQ-uuZCFRucc9bYX9gbrQ=.a209cef6-d282-4aeb-99ba-3da510d229ad@github.com>
References: <2iGo26T8BEhIoC_m49jykuUx56I8011VN3Sq6b_X2w4=.ca025625-a929-49df-8242-5924c305b7b7@github.com>
 <mIYyYFJ0Ngx5sxWDApgZgjFQ-uuZCFRucc9bYX9gbrQ=.a209cef6-d282-4aeb-99ba-3da510d229ad@github.com>
Message-ID: <p3tQQS6182YUqukrV5VvAs9WM1d_EytZ-9W1TVS3kR4=.46189e23-74a0-4fbf-b2d6-ee08932fc99d@github.com>

On Thu, 17 Dec 2020 19:58:10 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This is the work to update javadoc to use certain terminology dependent on the source version in use.
>> 
>> The groups of terms being changed are:
>> 
>> * `Types` to `Classes and Interfaces`
>> * `Annotation Type` to `Annotation Interface`
>> * `Enum` to `Enum Class`
>> 
>> The new terminology will be used when the source version of the elements being documented is 16 or higher. This is the default behavior. The corollary is that the old terminology will be used when the `--source` or `--release` option is used to specify a version less than `16`.
>> 
>> In addition, the terminology for `Record` is being unconditionally changed to use `Record Class`. Since the feature was in preview before this release, there is no need to be able to generate the previous form.
>> 
>> Also, in the course of this work, it was noted that on the "Use" page for an annotation type/interface, it was incorrectly classified as a *class*, instead of *annotation interface*: that has been fixed.
>> 
>> Fundamentally, the change is managed at a very low level, by passing a _mapping function_ into `Resource.getText`. This allows high level code, `HtmlDoclet` in this case, to provide version-specific overrides of the resource key to be used. The avoids having to have version-specific checks at the point of use for each affected resource.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains seven commits:
> 
>  - Fix failures
>  - Merge with upstream/master
>  - remove adaptive terminology for records
>  - add test
>  - Remove obsolete properties and code
>  - Version 2: release-specific terminology
>  - JDK-8258002: Update "type" terminology in generated docs

Looks good, Jon.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeOptionalMemberWriterImpl.java line 28:

> 26: package jdk.javadoc.internal.doclets.formats.html;
> 27: 
> 28: import javax.lang.model.SourceVersion;

Unused import

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

> 184: 
> 185:         messages = new Messages(this, msgResources);
> 186:         //contents = new Contents(this);

Should be removed instead of commented out

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

> 202:         super.initConfiguration(docEnv, resourceKeyMapper);
> 203:         contents = new Contents(this);
> 204:     }

I wish initialization of the configuration instance was not that complex... I guess the reason we must do it this way is that used SourceVersion is not known earlier.

test/langtools/jdk/javadoc/doclet/testTerminology/TestTerminology.java line 153:

> 151: //                        var catTypes = "Classes and Interfaces";"""
> 152: //        );
> 153: // awaits JDK-8247994: localize JavaScript search

Should be working now :)

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk16/pull/20

From jjg at openjdk.java.net  Fri Dec 18 17:39:59 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 18 Dec 2020 17:39:59 GMT
Subject: [jdk16] RFR: JDK-8258002: Update "type" terminology in generated
 docs [v2]
In-Reply-To: <p3tQQS6182YUqukrV5VvAs9WM1d_EytZ-9W1TVS3kR4=.46189e23-74a0-4fbf-b2d6-ee08932fc99d@github.com>
References: <2iGo26T8BEhIoC_m49jykuUx56I8011VN3Sq6b_X2w4=.ca025625-a929-49df-8242-5924c305b7b7@github.com>
 <mIYyYFJ0Ngx5sxWDApgZgjFQ-uuZCFRucc9bYX9gbrQ=.a209cef6-d282-4aeb-99ba-3da510d229ad@github.com>
 <p3tQQS6182YUqukrV5VvAs9WM1d_EytZ-9W1TVS3kR4=.46189e23-74a0-4fbf-b2d6-ee08932fc99d@github.com>
Message-ID: <xJzrm8_iGy4GjFX9En-heo6l_SSdivPma4wkDiKFMGY=.2866404e-f2dd-47b1-81e6-706aff54a023@github.com>

On Fri, 18 Dec 2020 17:09:36 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains seven commits:
>> 
>>  - Fix failures
>>  - Merge with upstream/master
>>  - remove adaptive terminology for records
>>  - add test
>>  - Remove obsolete properties and code
>>  - Version 2: release-specific terminology
>>  - JDK-8258002: Update "type" terminology in generated docs
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java line 204:
> 
>> 202:         super.initConfiguration(docEnv, resourceKeyMapper);
>> 203:         contents = new Contents(this);
>> 204:     }
> 
> I wish initialization of the configuration instance was not that complex... I guess the reason we must do it this way is that used SourceVersion is not known earlier.

Agreed that initializing the configuration is overly complex. At least in part, it's because of an earlier desire to use final fields where possible, when using direct access.   And yes, the problem here is that the `SourceVersion` is not known until `init` is called.

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

PR: https://git.openjdk.java.net/jdk16/pull/20

From jjg at openjdk.java.net  Fri Dec 18 18:31:09 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 18 Dec 2020 18:31:09 GMT
Subject: [jdk16] RFR: JDK-8258002: Update "type" terminology in generated
 docs [v3]
In-Reply-To: <2iGo26T8BEhIoC_m49jykuUx56I8011VN3Sq6b_X2w4=.ca025625-a929-49df-8242-5924c305b7b7@github.com>
References: <2iGo26T8BEhIoC_m49jykuUx56I8011VN3Sq6b_X2w4=.ca025625-a929-49df-8242-5924c305b7b7@github.com>
Message-ID: <_m-AwhQxlRj97BEN58GrcRHYhRvFPj8JkZyIB3MJsew=.aed1da4d-a4d8-4480-a7e9-f00dc60e65af@github.com>

> This is the work to update javadoc to use certain terminology dependent on the source version in use.
> 
> The groups of terms being changed are:
> 
> * `Types` to `Classes and Interfaces`
> * `Annotation Type` to `Annotation Interface`
> * `Enum` to `Enum Class`
> 
> The new terminology will be used when the source version of the elements being documented is 16 or higher. This is the default behavior. The corollary is that the old terminology will be used when the `--source` or `--release` option is used to specify a version less than `16`.
> 
> In addition, the terminology for `Record` is being unconditionally changed to use `Record Class`. Since the feature was in preview before this release, there is no need to be able to generate the previous form.
> 
> Also, in the course of this work, it was noted that on the "Use" page for an annotation type/interface, it was incorrectly classified as a *class*, instead of *annotation interface*: that has been fixed.
> 
> Fundamentally, the change is managed at a very low level, by passing a _mapping function_ into `Resource.getText`. This allows high level code, `HtmlDoclet` in this case, to provide version-specific overrides of the resource key to be used. The avoids having to have version-specific checks at the point of use for each affected resource.

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

 - Review comments; update new test
 - Merge remote-tracking branch 'upstream/master' into update-javadoc
 - Fix failures
 - Merge with upstream/master
 - remove adaptive terminology for records
 - add test
 - Remove obsolete properties and code
 - Version 2: release-specific terminology
 - JDK-8258002: Update "type" terminology in generated docs

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

Changes: https://git.openjdk.java.net/jdk16/pull/20/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=20&range=02
  Stats: 557 lines in 45 files changed: 317 ins; 46 del; 194 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/20.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/20/head:pull/20

PR: https://git.openjdk.java.net/jdk16/pull/20

From jjg at openjdk.java.net  Fri Dec 18 18:39:00 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 18 Dec 2020 18:39:00 GMT
Subject: [jdk16] Integrated: JDK-8258002: Update "type" terminology in
 generated docs
In-Reply-To: <2iGo26T8BEhIoC_m49jykuUx56I8011VN3Sq6b_X2w4=.ca025625-a929-49df-8242-5924c305b7b7@github.com>
References: <2iGo26T8BEhIoC_m49jykuUx56I8011VN3Sq6b_X2w4=.ca025625-a929-49df-8242-5924c305b7b7@github.com>
Message-ID: <Y5REGrCxekHYZ09Z0aNrlSYoJPbS9LwEvi3qqjPQPxo=.473f33a5-a888-4edd-8293-d49c11b89ae0@github.com>

On Tue, 15 Dec 2020 01:42:30 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This is the work to update javadoc to use certain terminology dependent on the source version in use.
> 
> The groups of terms being changed are:
> 
> * `Types` to `Classes and Interfaces`
> * `Annotation Type` to `Annotation Interface`
> * `Enum` to `Enum Class`
> 
> The new terminology will be used when the source version of the elements being documented is 16 or higher. This is the default behavior. The corollary is that the old terminology will be used when the `--source` or `--release` option is used to specify a version less than `16`.
> 
> In addition, the terminology for `Record` is being unconditionally changed to use `Record Class`. Since the feature was in preview before this release, there is no need to be able to generate the previous form.
> 
> Also, in the course of this work, it was noted that on the "Use" page for an annotation type/interface, it was incorrectly classified as a *class*, instead of *annotation interface*: that has been fixed.
> 
> Fundamentally, the change is managed at a very low level, by passing a _mapping function_ into `Resource.getText`. This allows high level code, `HtmlDoclet` in this case, to provide version-specific overrides of the resource key to be used. The avoids having to have version-specific checks at the point of use for each affected resource.

This pull request has now been integrated.

Changeset: c04c7e1f
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk16/commit/c04c7e1f
Stats:     557 lines in 45 files changed: 317 ins; 46 del; 194 mod

8258002: Update "type" terminology in generated docs

Reviewed-by: hannesw

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

PR: https://git.openjdk.java.net/jdk16/pull/20

From jjg at openjdk.java.net  Sat Dec 19 01:14:00 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Sat, 19 Dec 2020 01:14:00 GMT
Subject: [jdk16] RFR: JDK-8258443: doclint should be service-loaded with
 system class loader
Message-ID: <Mvlw9FnB-ia4ub0bid0tgiYcCCevRZ-LJBZhwWRa1i8=.93855ab3-6d56-4269-919e-26858a851249@github.com>

Trivial fix to use the system class loader when loading doclint for javac

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

Commit messages:
 - JDK-8258443: doclint should be service-loaded with system class loader

Changes: https://git.openjdk.java.net/jdk16/pull/54/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=54&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8258443
  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/54.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/54/head:pull/54

PR: https://git.openjdk.java.net/jdk16/pull/54

From alanb at openjdk.java.net  Mon Dec 21 08:59:59 2020
From: alanb at openjdk.java.net (Alan Bateman)
Date: Mon, 21 Dec 2020 08:59:59 GMT
Subject: [jdk16] RFR: JDK-8258443: doclint should be service-loaded with
 system class loader
In-Reply-To: <Mvlw9FnB-ia4ub0bid0tgiYcCCevRZ-LJBZhwWRa1i8=.93855ab3-6d56-4269-919e-26858a851249@github.com>
References: <Mvlw9FnB-ia4ub0bid0tgiYcCCevRZ-LJBZhwWRa1i8=.93855ab3-6d56-4269-919e-26858a851249@github.com>
Message-ID: <YpOMFuDOqegtFpBBCovd-x76dYHhfjrcSYhwPv43mQQ=.ea10b809-32ca-4c58-9f7c-8031f9d7f3c9@github.com>

On Sat, 19 Dec 2020 01:08:36 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Trivial fix to use the system class loader when loading doclint for javac

Looks good, should allow JDK-8253996 to be closed too.

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

Marked as reviewed by alanb (Reviewer).

PR: https://git.openjdk.java.net/jdk16/pull/54

From jwilhelm at openjdk.java.net  Mon Dec 21 09:14:13 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Mon, 21 Dec 2020 09:14:13 GMT
Subject: Integrated: Merge jdk16
In-Reply-To: <fOSLTd2YbDw4YmfxNl8K1AxPTOHMdt2Dj5eLmRLomyk=.95727f9e-a051-4a82-900f-de79202c61aa@github.com>
References: <fOSLTd2YbDw4YmfxNl8K1AxPTOHMdt2Dj5eLmRLomyk=.95727f9e-a051-4a82-900f-de79202c61aa@github.com>
Message-ID: <IQLHzfcTQzSfHuuC7bBMAFUa68yFDXDB1SOri7leFBs=.27787a7c-5132-47e5-8919-3e7dcc3d1886@github.com>

On Mon, 21 Dec 2020 09:05:48 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Forwardport JDK 16 -> JDK 17

This pull request has now been integrated.

Changeset: d2343880
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/d2343880
Stats:     1822 lines in 76 files changed: 1281 ins; 263 del; 278 mod

Merge

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

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

From jwilhelm at openjdk.java.net  Mon Dec 21 09:14:12 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Mon, 21 Dec 2020 09:14:12 GMT
Subject: Integrated: Merge jdk16
Message-ID: <fOSLTd2YbDw4YmfxNl8K1AxPTOHMdt2Dj5eLmRLomyk=.95727f9e-a051-4a82-900f-de79202c61aa@github.com>

Forwardport JDK 16 -> JDK 17

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

Commit messages:
 - Merge
 - 8258007: Add instrumentation to NativeLibraryTest
 - 8258002: Update "type" terminology in generated docs
 - 8223607: --override-methods=summary ignores some signature changes
 - 8258687: Build broken on Windows after fix for JDK-8258134
 - 8256693: getAnnotatedReceiverType parameterizes types too eagerly
 - 8256843: [PPC64] runtime/logging/RedefineClasses.java fails with assert: registers not saved on stack
 - 8258134: assert(size == calc_size) failed: incorrect size calculation on x86_32 with AVX512 machines
 - 8257974: Regression 21% in DaCapo-lusearch-large after JDK-8236926
 - 8258373: Update the text handling in the JPasswordField
 - ... and 3 more: https://git.openjdk.java.net/jdk/compare/d4c7db50...67de4667

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

Changes: https://git.openjdk.java.net/jdk/pull/1857/files
  Stats: 1822 lines in 76 files changed: 1281 ins; 263 del; 278 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1857.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1857/head:pull/1857

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

From jjg at openjdk.java.net  Mon Dec 21 17:08:57 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 21 Dec 2020 17:08:57 GMT
Subject: [jdk16] RFR: JDK-8258443: doclint should be service-loaded with
 system class loader
In-Reply-To: <YpOMFuDOqegtFpBBCovd-x76dYHhfjrcSYhwPv43mQQ=.ea10b809-32ca-4c58-9f7c-8031f9d7f3c9@github.com>
References: <Mvlw9FnB-ia4ub0bid0tgiYcCCevRZ-LJBZhwWRa1i8=.93855ab3-6d56-4269-919e-26858a851249@github.com>
 <YpOMFuDOqegtFpBBCovd-x76dYHhfjrcSYhwPv43mQQ=.ea10b809-32ca-4c58-9f7c-8031f9d7f3c9@github.com>
Message-ID: <uq-6YkUWcC8QpN2yRlBzKVy6Tq5Zmt_IlFcMD-zMfOE=.33166525-579b-4ee0-a95b-0f4742778f92@github.com>

On Mon, 21 Dec 2020 08:57:37 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Trivial fix to use the system class loader when loading doclint for javac
>
> Looks good, should allow JDK-8253996 to be closed too.

@AlanBateman JDK-8253996 is slightly different; my intent is that javac/doclint should give a more friendly message when doclint is _really_ not available, such as in a minimal jlink-ed image.

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

PR: https://git.openjdk.java.net/jdk16/pull/54

From jjg at openjdk.java.net  Mon Dec 21 17:08:58 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Mon, 21 Dec 2020 17:08:58 GMT
Subject: [jdk16] Integrated: JDK-8258443: doclint should be service-loaded
 with system class loader
In-Reply-To: <Mvlw9FnB-ia4ub0bid0tgiYcCCevRZ-LJBZhwWRa1i8=.93855ab3-6d56-4269-919e-26858a851249@github.com>
References: <Mvlw9FnB-ia4ub0bid0tgiYcCCevRZ-LJBZhwWRa1i8=.93855ab3-6d56-4269-919e-26858a851249@github.com>
Message-ID: <9z1UNb6M-kx5yQvlPcIehuvWPvNsk5BwAuLUDV578Y4=.c8dd3b11-aafc-48cc-ad8b-4defc3041580@github.com>

On Sat, 19 Dec 2020 01:08:36 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Trivial fix to use the system class loader when loading doclint for javac

This pull request has now been integrated.

Changeset: 8da7c580
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk16/commit/8da7c580
Stats:     1 line in 1 file changed: 0 ins; 0 del; 1 mod

8258443: doclint should be service-loaded with system class loader

Reviewed-by: alanb

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

PR: https://git.openjdk.java.net/jdk16/pull/54

From jwilhelm at openjdk.java.net  Tue Dec 22 20:51:15 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 22 Dec 2020 20:51:15 GMT
Subject: RFR: Merge jdk16
Message-ID: <XRu1N9J7tPt3MhgjrOU3JdF0uE0eTZ9g6jvhY_EaO7I=.bbdca574-58a7-4251-bf49-08e2606d6798@github.com>

Forwardport JDK 16 -> JDK 17

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

Commit messages:
 - Merge
 - 8258832: ProblemList com/sun/jdi/AfterThreadDeathTest.java on Linux-X64
 - 8258827: ProblemList Naming/DefaultRegistryPort.java and Naming/legalRegistryNames/LegalRegistryNames.java on Windows
 - 8258802: ProblemList TestJstatdDefaults.java, TestJstatdRmiPort.java, and TestJstatdServer.java
 - 8258790: C2: Crash on empty macro node list
 - 8258443: doclint should be service-loaded with system class loader
 - 8255763: C2: OSR miscompilation caused by invalid memory instruction placement
 - 8258714: Shenandoah: Process references before evacuation during degen

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

Changes: https://git.openjdk.java.net/jdk/pull/1870/files
  Stats: 203 lines in 12 files changed: 181 ins; 13 del; 9 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1870.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1870/head:pull/1870

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

From jwilhelm at openjdk.java.net  Tue Dec 22 21:19:59 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 22 Dec 2020 21:19:59 GMT
Subject: Integrated: Merge jdk16
In-Reply-To: <XRu1N9J7tPt3MhgjrOU3JdF0uE0eTZ9g6jvhY_EaO7I=.bbdca574-58a7-4251-bf49-08e2606d6798@github.com>
References: <XRu1N9J7tPt3MhgjrOU3JdF0uE0eTZ9g6jvhY_EaO7I=.bbdca574-58a7-4251-bf49-08e2606d6798@github.com>
Message-ID: <QSju_jtRwOvAVt9uAlcNO9RwjIh_K9rXyZFuJ6YkgEY=.28295f59-1061-4947-8ca0-ca050e136daa@github.com>

On Tue, 22 Dec 2020 20:45:38 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Forwardport JDK 16 -> JDK 17

This pull request has now been integrated.

Changeset: f2bad3a0
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/f2bad3a0
Stats:     203 lines in 12 files changed: 181 ins; 13 del; 9 mod

Merge

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

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

From jjg at openjdk.java.net  Wed Dec 23 00:06:13 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 00:06:13 GMT
Subject: [jdk16] RFR: JDK-8253996: Javac error on jdk16 build 18: invalid
 flag: -Xdoclint:-missing
Message-ID: <1BH8xqCUnkEyAVYD50BvewKIb_AxutBS8k0TEkK7tXM=.7e865ca1-cd5c-4b29-b8e1-a3e2dedee93f@github.com>

This PR improves the diagnostic when javac is run in an image that does not provide a service provider for DocLint.

Instead of reporting messages about unsupported options, the following warning will be generated:

`
Warning: No service provider for doclint is available
`

In addition, as a minor cleanup, in the `jdk.javadoc` module, javadoc b bypasses the service loader to access `doclint` directly.

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

Commit messages:
 - JDK-8253996: Javac error on jdk16 build 18: invalid flag: -Xdoclint:-missing

Changes: https://git.openjdk.java.net/jdk16/pull/60/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=60&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8253996
  Stats: 96 lines in 6 files changed: 88 ins; 1 del; 7 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/60.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/60/head:pull/60

PR: https://git.openjdk.java.net/jdk16/pull/60

From jjg at openjdk.java.net  Wed Dec 23 01:35:07 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 01:35:07 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v4]
In-Reply-To: <vZkUHKS22sXksvEkZIlwencSsNSc0HTcCR-5Mp71daQ=.06eeb39b-39c4-4854-861d-432a4b95e946@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <vZkUHKS22sXksvEkZIlwencSsNSc0HTcCR-5Mp71daQ=.06eeb39b-39c4-4854-861d-432a4b95e946@github.com>
Message-ID: <XKTvz2-x2vrvW523LJlGWOkDOqJP27e2n5OiqmmVjZY=.abce90e3-4e29-4a89-aa99-1f74a8bf95ea@github.com>

On Fri, 18 Dec 2020 01:34:15 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> HTML4 is no longer supported in javadoc.
>> 
>> doclint needs to drop HTML4 support as well.
>> The changes consist of:
>> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
>> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
>> * Modifying test code and expected outputs to be checked in HTML5
>
> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
> 
>   5th: 8257204 and 8256313
>   8257204: Remove usage of -Xhtmlversion option from javac
>   8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option

src/jdk.compiler/share/man/javac.1 line 638:

> 636: .RS
> 637: .RE
> 638: .TP

In general, you should not edit files like this; these files are generated from upstream Markdown files.

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

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

From jjg at openjdk.java.net  Wed Dec 23 01:35:05 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 01:35:05 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
Message-ID: <g106P5efLYq8H9ekh04enafDvGW0IRB4Z4NyFN6j_8E=.9399c3bb-bb9e-46a5-83f2-a5e7c68dcddf@github.com>

On Fri, 18 Dec 2020 02:34:16 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> HTML4 is no longer supported in javadoc.
>> 
>> doclint needs to drop HTML4 support as well.
>> The changes consist of:
>> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
>> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
>> * Modifying test code and expected outputs to be checked in HTML5
>
> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
> 
>   5th: 8258460: Remove --doclint-format option from javac

Looks good.
I'll pull down a copy, for review in an IDE and to build and run tests, and if that goes OK, I will approve it.

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

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

From ysatowse at openjdk.java.net  Wed Dec 23 02:25:01 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Wed, 23 Dec 2020 02:25:01 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <g106P5efLYq8H9ekh04enafDvGW0IRB4Z4NyFN6j_8E=.9399c3bb-bb9e-46a5-83f2-a5e7c68dcddf@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
 <g106P5efLYq8H9ekh04enafDvGW0IRB4Z4NyFN6j_8E=.9399c3bb-bb9e-46a5-83f2-a5e7c68dcddf@github.com>
Message-ID: <6eJV9qXpBqWxbpH2x-RbDWpL9uOTjsCjIu5jhbQ-wSI=.c14cb5c3-266c-423f-924a-6159aa9dd502@github.com>

On Wed, 23 Dec 2020 01:32:29 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   5th: 8258460: Remove --doclint-format option from javac
>
> Looks good.
> I'll pull down a copy, for review in an IDE and to build and run tests, and if that goes OK, I will approve it.

test comment

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

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

From ysatowse at openjdk.java.net  Wed Dec 23 05:05:05 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Wed, 23 Dec 2020 05:05:05 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v4]
In-Reply-To: <XKTvz2-x2vrvW523LJlGWOkDOqJP27e2n5OiqmmVjZY=.abce90e3-4e29-4a89-aa99-1f74a8bf95ea@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <vZkUHKS22sXksvEkZIlwencSsNSc0HTcCR-5Mp71daQ=.06eeb39b-39c4-4854-861d-432a4b95e946@github.com>
 <XKTvz2-x2vrvW523LJlGWOkDOqJP27e2n5OiqmmVjZY=.abce90e3-4e29-4a89-aa99-1f74a8bf95ea@github.com>
Message-ID: <7_wU3eWhv3jNcD6RLyg4Z9V0uM7PHklBQJqfeJmycZI=.e5251839-6fe9-4e79-9877-539af1098ad5@github.com>

On Wed, 23 Dec 2020 01:27:30 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   5th: 8257204 and 8256313
>>   8257204: Remove usage of -Xhtmlversion option from javac
>>   8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option
>
> src/jdk.compiler/share/man/javac.1 line 638:
> 
>> 636: .RS
>> 637: .RE
>> 638: .TP
> 
> In general, you should not edit files like this; these files are generated from upstream Markdown files.

Ok.  I will revert this with the next commit.

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

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

From jjg at openjdk.java.net  Wed Dec 23 05:13:04 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 05:13:04 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
Message-ID: <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>

On Fri, 18 Dec 2020 02:34:16 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> HTML4 is no longer supported in javadoc.
>> 
>> doclint needs to drop HTML4 support as well.
>> The changes consist of:
>> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
>> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
>> * Modifying test code and expected outputs to be checked in HTML5
>
> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
> 
>   5th: 8258460: Remove --doclint-format option from javac

One must-fix item (bad pattern constant.)

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

> 734: 
> 735:     // https://html.spec.whatwg.org/#the-id-attribute
> 736:     private static final Pattern validId = Pattern.compile("[^\s]+");

The regular expression is invalid and needs to be fixed. It should be `Pattern.compile("[^\\s]+")`
Note the extra `` character. This is because you need to escape the `` character in the string constant, so that the `` is seen in the pattern as part of `\s`.

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

> 708: 
> 709: 
> 710:     private boolean checkAnchor(String name) {

I was going to let it slide for this round of cleanup, but if you're editing this file again (see comment on line 736) it might be worth changing the use of `anchor` to `id`.  `anchor` is a term that was more appropriate in the days before the `id` attribute, when we used `<a name="...">`.  This is an optional suggestion.  It might equally be worth focussing on the must-fix items, and postpone this cleanup for later.

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

Changes requested by jjg (Reviewer).

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

From ysatowse at openjdk.java.net  Wed Dec 23 05:41:02 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Wed, 23 Dec 2020 05:41:02 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
 <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
Message-ID: <K-lT5fBVeSNjXs6FNgsFaLRrhQWu-kclfX3TZf7FBXw=.55005f37-8658-4596-bb78-1b719af0f8e8@github.com>

On Wed, 23 Dec 2020 05:01:44 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   5th: 8258460: Remove --doclint-format option from javac
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 736:
> 
>> 734: 
>> 735:     // https://html.spec.whatwg.org/#the-id-attribute
>> 736:     private static final Pattern validId = Pattern.compile("[^\s]+");
> 
> The regular expression is invalid and needs to be fixed. It should be `Pattern.compile("[^\\s]+")`
> Note the extra `` character. This is because you need to escape the `` character in the string constant, so that the `` is seen in the pattern as part of `\s`.

Correct.  Thanks a lot for finding this error.  
Now that I have doubts why this line could have been compiled without error.  This line should cause a compiler error.

Let me review all anchor tests again because the logic should be checked there.

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

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

From ysatowse at openjdk.java.net  Wed Dec 23 06:45:01 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Wed, 23 Dec 2020 06:45:01 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
 <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
Message-ID: <SaZ-FbYfWjRxEVFDxnDM8nP_ljpFw-nj4Pe-mzl759s=.cf773bed-11dc-4017-bf0c-8aefd0c9873b@github.com>

On Wed, 23 Dec 2020 05:08:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   5th: 8258460: Remove --doclint-format option from javac
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 710:
> 
>> 708: 
>> 709: 
>> 710:     private boolean checkAnchor(String name) {
> 
> I was going to let it slide for this round of cleanup, but if you're editing this file again (see comment on line 736) it might be worth changing the use of `anchor` to `id`.  `anchor` is a term that was more appropriate in the days before the `id` attribute, when we used `<a name="...">`.  This is an optional suggestion.  It might equally be worth focussing on the must-fix items, and postpone this cleanup for later.

I understand.  But is it really no problem to be done in part of the cleanup of doclint?  
Looking at the classes in jdk/javadoc/internal/doclint,  the term `(anchor|Anchor)` looks like only used in Checker.java and resource files.  But a lot of other files, for instance in jdk/javadoc/internal/doclets, use this term to refer to the `id` or `name` attribute.  I would be fine if it is supposed to be done in each cleanup in the future.

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

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

From ysatowse at openjdk.java.net  Wed Dec 23 07:54:02 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Wed, 23 Dec 2020 07:54:02 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <K-lT5fBVeSNjXs6FNgsFaLRrhQWu-kclfX3TZf7FBXw=.55005f37-8658-4596-bb78-1b719af0f8e8@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
 <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
 <K-lT5fBVeSNjXs6FNgsFaLRrhQWu-kclfX3TZf7FBXw=.55005f37-8658-4596-bb78-1b719af0f8e8@github.com>
Message-ID: <7A3J6XuVSinC1anOYqPp1FkPmq7D25z6Ed8x-dXUJsA=.3c9a56cd-cc38-4ab4-8f88-f991fd7709dd@github.com>

On Wed, 23 Dec 2020 05:38:36 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 736:
>> 
>>> 734: 
>>> 735:     // https://html.spec.whatwg.org/#the-id-attribute
>>> 736:     private static final Pattern validId = Pattern.compile("[^\s]+");
>> 
>> The regular expression is invalid and needs to be fixed. It should be `Pattern.compile("[^\\s]+")`
>> Note the extra `` character. This is because you need to escape the `` character in the string constant, so that the `` is seen in the pattern as part of `\s`.
>
> Correct.  Thanks a lot for finding this error.  
> Now that I have doubts why this line could have been compiled without error.  This line should cause a compiler error.
> 
> Let me review all anchor tests again because the logic should be checked there.

For some reason, `"[^\s]+"` might have been dealt with as a text block, thus `\s` was regarded as a whitespace...
I believe a text block is defined with triple double quotes, but javac seems to accept `"[^\s]+"` as a text block.

That aside, all anchor tests look fine.  This is because there is no specific test to use whitespace characters such as `\n`, `\t`, `\r` and `\f` in an anchor name.  Also I confirmed the discrepancy of the results for `"[^\s]+"` and `"[^\\s]+"`.  It shows that the former is not exactly what we want to do.

$ jshell -J-Duser.language=en -J--show-version
java 15 2020-09-15
Java(TM) SE Runtime Environment (build 15+36-1562)
Java HotSpot(TM) 64-Bit Server VM (build 15+36-1562, mixed mode, sharing)
|  Welcome to JShell -- Version 15
|  For an introduction type: /help intro

jshell> Pattern validId1 = Pattern.compile("[^\s]+")
validId1 ==> [^ ]+

jshell> Pattern validId2 = Pattern.compile("[^\\s]+")
validId2 ==> [^\s]+

jshell> validId1.matcher("aaa").matches()
$3 ==> true

jshell> validId1.matcher("aaa ").matches()
$4 ==> false

jshell> validId1.matcher("aaa\n").matches()
$5 ==> true

jshell> validId2.matcher("aaa").matches()
$6 ==> true

jshell> validId2.matcher("aaa ").matches()
$7 ==> false

jshell> validId2.matcher("aaa\n").matches()
$8 ==> false

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

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

From ysatowse at openjdk.java.net  Wed Dec 23 08:18:01 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Wed, 23 Dec 2020 08:18:01 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <SaZ-FbYfWjRxEVFDxnDM8nP_ljpFw-nj4Pe-mzl759s=.cf773bed-11dc-4017-bf0c-8aefd0c9873b@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
 <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
 <SaZ-FbYfWjRxEVFDxnDM8nP_ljpFw-nj4Pe-mzl759s=.cf773bed-11dc-4017-bf0c-8aefd0c9873b@github.com>
Message-ID: <hEsFMq6xyUUyDmTATPckbAPUprE9p2Ycqqzk2GXUlJM=.6308c33d-0ba2-4de7-9c63-b26b9783a138@github.com>

On Wed, 23 Dec 2020 06:42:21 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 710:
>> 
>>> 708: 
>>> 709: 
>>> 710:     private boolean checkAnchor(String name) {
>> 
>> I was going to let it slide for this round of cleanup, but if you're editing this file again (see comment on line 736) it might be worth changing the use of `anchor` to `id`.  `anchor` is a term that was more appropriate in the days before the `id` attribute, when we used `<a name="...">`.  This is an optional suggestion.  It might equally be worth focussing on the must-fix items, and postpone this cleanup for later.
>
> I understand.  But is it really no problem to be done in part of the cleanup of doclint?  
> Looking at the classes in jdk/javadoc/internal/doclint,  the term `(anchor|Anchor)` looks like only used in Checker.java and resource files.  But a lot of other files, for instance in jdk/javadoc/internal/doclets, use this term to refer to the `id` or `name` attribute.  I would be fine if it is supposed to be done in each cleanup in the future.

If we would apply similar changing to doclint.properties, what you are thinking is like below right?

-dc.anchor.already.defined = anchor already defined: "{0}"
-dc.anchor.value.missing = no value given for anchor
+dc.id.already.defined = attribute "id" already defined: "{0}"
+dc.id.value.missing = no value given for attribute "id"

-dc.invalid.anchor = invalid name for anchor: "{0}"
-dc.invalid.id = invalid name for attribute "id": "{0}"

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

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

From jjg at openjdk.java.net  Wed Dec 23 15:56:01 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 15:56:01 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
 <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
Message-ID: <Jhwh9hnH9R7CiGsV4S7zgAu2nXrfXURb3KX7D-f3Jkg=.66a19e92-54db-4530-9360-47072587f180@github.com>

On Wed, 23 Dec 2020 05:10:31 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   5th: 8258460: Remove --doclint-format option from javac
>
> One must-fix item (bad pattern constant.)

\s was introduced as a valid escape character in JDK 15 as part of the 
support for Text Blocks.

https://docs.oracle.com/javase/specs/jls/se15/html/jls-3.html#jls-EscapeSequence
https://docs.oracle.com/javase/specs/jls/se14/preview/specs/text-blocks-jls.html#jls-3.10.7

FWIW, the escape sequence showed up with red squiggly lines in my IDE.

-- Jon

On 12/22/20 9:38 PM, Yoshiki SATO wrote:
>
> *@satoyoshiki* commented on this pull request.
>
> ------------------------------------------------------------------------
>
> In 
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java 
> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547668049__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZiYojsWrqg$>:
>
> > @@ -765,8 +732,8 @@ private Element getEnclosingPackageOrClass(Element e) {
>           return e;
>       }
>   
> -    //http://www.w3.org/TR/html401/types.html#type-name  <https://urldefense.com/v3/__http://www.w3.org/TR/html401/types.html*type-name__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZibVYnjqnQ$>
> -    private static final Pattern validName = Pattern.compile("[A-Za-z][A-Za-z0-9-_:.]*");
> +    //https://html.spec.whatwg.org/#the-id-attribute  <https://urldefense.com/v3/__https://html.spec.whatwg.org/*the-id-attribute__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZib5vw0eRg$>
> +    private static final Pattern validId = Pattern.compile("[^\s]+");
>
> Correct. Thanks a lot for finding this error.
> Now that I have doubts why this line could have been compiled without 
> error. This line should cause a compiler error.
>
> Let me review all anchor tests again because the logic should be 
> checked there.
>
> ?
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub 
> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547668049__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZiYojsWrqg$>, 
> or unsubscribe 
> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRXCJBCNZR4ZUBZCEBTSWF66TANCNFSM4TBXTH2Q__;!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZia6kQL08w$>.
>

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

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

From jjg at openjdk.java.net  Wed Dec 23 17:12:03 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 17:12:03 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <Jhwh9hnH9R7CiGsV4S7zgAu2nXrfXURb3KX7D-f3Jkg=.66a19e92-54db-4530-9360-47072587f180@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
 <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
 <Jhwh9hnH9R7CiGsV4S7zgAu2nXrfXURb3KX7D-f3Jkg=.66a19e92-54db-4530-9360-47072587f180@github.com>
Message-ID: <xZxi9rbJ9VUlAsG3ZJrHI8dfziWoH1Gt0ti6IKe4wwI=.c8f0f568-b94e-4ba3-9451-e2ef361a6f11@github.com>

On Wed, 23 Dec 2020 15:53:00 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> One must-fix item (bad pattern constant.)
>
> \s was introduced as a valid escape character in JDK 15 as part of the 
> support for Text Blocks.
> 
> https://docs.oracle.com/javase/specs/jls/se15/html/jls-3.html#jls-EscapeSequence
> https://docs.oracle.com/javase/specs/jls/se14/preview/specs/text-blocks-jls.html#jls-3.10.7
> 
> FWIW, the escape sequence showed up with red squiggly lines in my IDE.
> 
> -- Jon
> 
> On 12/22/20 9:38 PM, Yoshiki SATO wrote:
>>
>> *@satoyoshiki* commented on this pull request.
>>
>> ------------------------------------------------------------------------
>>
>> In 
>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java 
>> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547668049__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZiYojsWrqg$>:
>>
>> > @@ -765,8 +732,8 @@ private Element getEnclosingPackageOrClass(Element e) {
>>           return e;
>>       }
>>   
>> -    //http://www.w3.org/TR/html401/types.html#type-name  <https://urldefense.com/v3/__http://www.w3.org/TR/html401/types.html*type-name__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZibVYnjqnQ$>
>> -    private static final Pattern validName = Pattern.compile("[A-Za-z][A-Za-z0-9-_:.]*");
>> +    //https://html.spec.whatwg.org/#the-id-attribute  <https://urldefense.com/v3/__https://html.spec.whatwg.org/*the-id-attribute__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZib5vw0eRg$>
>> +    private static final Pattern validId = Pattern.compile("[^\s]+");
>>
>> Correct. Thanks a lot for finding this error.
>> Now that I have doubts why this line could have been compiled without 
>> error. This line should cause a compiler error.
>>
>> Let me review all anchor tests again because the logic should be 
>> checked there.
>>
>> ?
>> You are receiving this because you were mentioned.
>> Reply to this email directly, view it on GitHub 
>> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547668049__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZiYojsWrqg$>, 
>> or unsubscribe 
>> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRXCJBCNZR4ZUBZCEBTSWF66TANCNFSM4TBXTH2Q__;!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZia6kQL08w$>.
>>

On 12/22/20 10:42 PM, Yoshiki SATO wrote:
>
> *@satoyoshiki* commented on this pull request.
>
> ------------------------------------------------------------------------
>
> In 
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java 
> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547716025__;Iw!!GqivPVa7Brio!Oae1uD8yALBU6ReCJTwKccZjdEsGyXddDLOOeF2SJLi8x7SoU5jr-Jr0KVl2EVajBRHM-g$>:
>
> > -    }
> -
> -    private void validateHtml5Attrs(AttributeTree tree, Name name, AttrKind k) {
> -        switch (k) {
> -            case ALL:
> -            case HTML5:
> -                break;
> -
> -            case INVALID:
> -            case OBSOLETE:
> -            case USE_CSS:
> -            case HTML4:
> -                env.messages.error(HTML, tree, "dc.attr.not.supported.html5", name);
> -                break;
> -        }
> -    }
>   
>       private boolean checkAnchor(String name) {
>
> I understand. But is it really no problem to be done in part of the 
> cleanup of doclint?
> Looking at the classes in jdk/javadoc/internal/doclint, the term 
> |(anchor|Anchor)| looks like only used in Checker.java and resource 
> files. But a lot of other files, for instance in 
> jdk/javadoc/internal/doclets, use this term to refer to the |id| or 
> |name| attribute. I would be fine if it is supposed to be done in each 
> cleanup in the future.
>
> ?
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub 
> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547716025__;Iw!!GqivPVa7Brio!Oae1uD8yALBU6ReCJTwKccZjdEsGyXddDLOOeF2SJLi8x7SoU5jr-Jr0KVl2EVajBRHM-g$>, 
> or unsubscribe 
> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRQS4FULCERHKMAZ5OLSWGGNVANCNFSM4TBXTH2Q__;!!GqivPVa7Brio!Oae1uD8yALBU6ReCJTwKccZjdEsGyXddDLOOeF2SJLi8x7SoU5jr-Jr0KVl2EVYEkdTG2A$>.
>

If you were to cleanup the "anchor" terminology, it should only be done 
in doclint, meaning Checker.java and resource files. Cleaning up 
terminology in the rest of javadoc is another project for another day. 
But, it's OK to skip this terminology cleanup in doclint at this time, 
since it is only peripherally related to the primary goal to remove 
HTML4 support.

-- Jon

>

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

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

From jjg at openjdk.java.net  Wed Dec 23 17:15:01 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 17:15:01 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <xZxi9rbJ9VUlAsG3ZJrHI8dfziWoH1Gt0ti6IKe4wwI=.c8f0f568-b94e-4ba3-9451-e2ef361a6f11@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
 <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
 <Jhwh9hnH9R7CiGsV4S7zgAu2nXrfXURb3KX7D-f3Jkg=.66a19e92-54db-4530-9360-47072587f180@github.com>
 <xZxi9rbJ9VUlAsG3ZJrHI8dfziWoH1Gt0ti6IKe4wwI=.c8f0f568-b94e-4ba3-9451-e2ef361a6f11@github.com>
Message-ID: <RnaZOYLCduGjwzYR_Kq6vul_nmOFpjFDXfuYZ4Dt0Zo=.a22a9652-2e6d-49ac-a4cb-cc0b7d945b11@github.com>

On Wed, 23 Dec 2020 17:08:55 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> \s was introduced as a valid escape character in JDK 15 as part of the 
>> support for Text Blocks.
>> 
>> https://docs.oracle.com/javase/specs/jls/se15/html/jls-3.html#jls-EscapeSequence
>> https://docs.oracle.com/javase/specs/jls/se14/preview/specs/text-blocks-jls.html#jls-3.10.7
>> 
>> FWIW, the escape sequence showed up with red squiggly lines in my IDE.
>> 
>> -- Jon
>> 
>> On 12/22/20 9:38 PM, Yoshiki SATO wrote:
>>>
>>> *@satoyoshiki* commented on this pull request.
>>>
>>> ------------------------------------------------------------------------
>>>
>>> In 
>>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java 
>>> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547668049__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZiYojsWrqg$>:
>>>
>>> > @@ -765,8 +732,8 @@ private Element getEnclosingPackageOrClass(Element e) {
>>>           return e;
>>>       }
>>>   
>>> -    //http://www.w3.org/TR/html401/types.html#type-name  <https://urldefense.com/v3/__http://www.w3.org/TR/html401/types.html*type-name__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZibVYnjqnQ$>
>>> -    private static final Pattern validName = Pattern.compile("[A-Za-z][A-Za-z0-9-_:.]*");
>>> +    //https://html.spec.whatwg.org/#the-id-attribute  <https://urldefense.com/v3/__https://html.spec.whatwg.org/*the-id-attribute__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZib5vw0eRg$>
>>> +    private static final Pattern validId = Pattern.compile("[^\s]+");
>>>
>>> Correct. Thanks a lot for finding this error.
>>> Now that I have doubts why this line could have been compiled without 
>>> error. This line should cause a compiler error.
>>>
>>> Let me review all anchor tests again because the logic should be 
>>> checked there.
>>>
>>> ?
>>> You are receiving this because you were mentioned.
>>> Reply to this email directly, view it on GitHub 
>>> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547668049__;Iw!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZiYojsWrqg$>, 
>>> or unsubscribe 
>>> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRXCJBCNZR4ZUBZCEBTSWF66TANCNFSM4TBXTH2Q__;!!GqivPVa7Brio!OUEFldgNdIV8aqoReM0lNXfIYO3IoXGR1RUbcYmVdEHRRdA3oy1Zaa3h2DevZia6kQL08w$>.
>>>
>
> On 12/22/20 10:42 PM, Yoshiki SATO wrote:
>>
>> *@satoyoshiki* commented on this pull request.
>>
>> ------------------------------------------------------------------------
>>
>> In 
>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java 
>> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547716025__;Iw!!GqivPVa7Brio!Oae1uD8yALBU6ReCJTwKccZjdEsGyXddDLOOeF2SJLi8x7SoU5jr-Jr0KVl2EVajBRHM-g$>:
>>
>> > -    }
>> -
>> -    private void validateHtml5Attrs(AttributeTree tree, Name name, AttrKind k) {
>> -        switch (k) {
>> -            case ALL:
>> -            case HTML5:
>> -                break;
>> -
>> -            case INVALID:
>> -            case OBSOLETE:
>> -            case USE_CSS:
>> -            case HTML4:
>> -                env.messages.error(HTML, tree, "dc.attr.not.supported.html5", name);
>> -                break;
>> -        }
>> -    }
>>   
>>       private boolean checkAnchor(String name) {
>>
>> I understand. But is it really no problem to be done in part of the 
>> cleanup of doclint?
>> Looking at the classes in jdk/javadoc/internal/doclint, the term 
>> |(anchor|Anchor)| looks like only used in Checker.java and resource 
>> files. But a lot of other files, for instance in 
>> jdk/javadoc/internal/doclets, use this term to refer to the |id| or 
>> |name| attribute. I would be fine if it is supposed to be done in each 
>> cleanup in the future.
>>
>> ?
>> You are receiving this because you were mentioned.
>> Reply to this email directly, view it on GitHub 
>> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547716025__;Iw!!GqivPVa7Brio!Oae1uD8yALBU6ReCJTwKccZjdEsGyXddDLOOeF2SJLi8x7SoU5jr-Jr0KVl2EVajBRHM-g$>, 
>> or unsubscribe 
>> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRQS4FULCERHKMAZ5OLSWGGNVANCNFSM4TBXTH2Q__;!!GqivPVa7Brio!Oae1uD8yALBU6ReCJTwKccZjdEsGyXddDLOOeF2SJLi8x7SoU5jr-Jr0KVl2EVYEkdTG2A$>.
>>
> 
> If you were to cleanup the "anchor" terminology, it should only be done 
> in doclint, meaning Checker.java and resource files. Cleaning up 
> terminology in the rest of javadoc is another project for another day. 
> But, it's OK to skip this terminology cleanup in doclint at this time, 
> since it is only peripherally related to the primary goal to remove 
> HTML4 support.
> 
> -- Jon
> 
>>

Although `\s` was introduced as part of the work for text blocks, it was 
added to the set of escape characters accepted in string and character 
literals. So, no, that constant is not being treated as a text block, 
because text blocks only begin and end with triple-quotes: `"""`

See the JLS links I gave in my previous response.

-- Jon

On 12/22/20 11:50 PM, Yoshiki SATO wrote:
>
> *@satoyoshiki* commented on this pull request.
>
> ------------------------------------------------------------------------
>
> In 
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java 
> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547768833__;Iw!!GqivPVa7Brio!JzRqq_cZpzUEFer1m5NX92ABR7tcna9povirJpPwfSxuO4EFI0tRAmRLw80UwpJdsJ1BgQ$>:
>
> > @@ -765,8 +732,8 @@ private Element getEnclosingPackageOrClass(Element e) {
>           return e;
>       }
>   
> -    //http://www.w3.org/TR/html401/types.html#type-name  <https://urldefense.com/v3/__http://www.w3.org/TR/html401/types.html*type-name__;Iw!!GqivPVa7Brio!JzRqq_cZpzUEFer1m5NX92ABR7tcna9povirJpPwfSxuO4EFI0tRAmRLw80UwpJRSKFcFA$>
> -    private static final Pattern validName = Pattern.compile("[A-Za-z][A-Za-z0-9-_:.]*");
> +    //https://html.spec.whatwg.org/#the-id-attribute  <https://urldefense.com/v3/__https://html.spec.whatwg.org/*the-id-attribute__;Iw!!GqivPVa7Brio!JzRqq_cZpzUEFer1m5NX92ABR7tcna9povirJpPwfSxuO4EFI0tRAmRLw80UwpLwqIk5gQ$>
> +    private static final Pattern validId = Pattern.compile("[^\s]+");
>
> For some reason, |"[^\s]+"| might have been dealt with as a text 
> block, thus |\s| was regarded as a whitespace...
> I believe a text block is defined with triple double quotes, but javac 
> seems to accept |"[^\s]+"| as a text block.
>
> That aside, all anchor tests look fine. This is because there is no 
> specific test to use whitespace characters such as |\n|, |\t|, |\r| 
> and |\f| in an anchor name. Also I confirmed the discrepancy of the 
> results for |"[^\s]+"| and |"[^\\s]+"|. It shows that the former is 
> not exactly what we want to do.
>
> /var/tmp/jib-yoshiki/install/jdk/15/36/bundles/osx-x64/jdk-15_osx-x64_bin.tar.gz/jdk-15.jdk/Contents/Home/bin/jshell 
> -J-Duser.language=en -J--show-version
> java 15 2020-09-15
> Java(TM) SE Runtime Environment (build 15+36-1562)
> Java HotSpot(TM) 64-Bit Server VM (build 15+36-1562, mixed mode, sharing)
> | Welcome to JShell -- Version 15
> | For an introduction type: /help intro
>
> jshell> Pattern validId1 = Pattern.compile("[^\s]+")
> validId1 ==> [^ ]+
>
> jshell> Pattern validId2 = Pattern.compile("[^\s]+")
> validId2 ==> [^\s]+
>
> jshell> validId1.matcher("aaa").matches()
> $3 ==> true
>
> jshell> validId1.matcher("aaa ").matches()
> $4 ==> false
>
> jshell> validId1.matcher("aaa\n").matches()
> $5 ==> true
>
> jshell> validId2.matcher("aaa").matches()
> $6 ==> true
>
> jshell> validId2.matcher("aaa ").matches()
> $7 ==> false
>
> jshell> validId2.matcher("aaa\n").matches()
> $8 ==> false
>
> ?
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub 
> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/893*discussion_r547768833__;Iw!!GqivPVa7Brio!JzRqq_cZpzUEFer1m5NX92ABR7tcna9povirJpPwfSxuO4EFI0tRAmRLw80UwpJdsJ1BgQ$>, 
> or unsubscribe 
> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRQZVY3MLTBJ7SZR7ETSWGONXANCNFSM4TBXTH2Q__;!!GqivPVa7Brio!JzRqq_cZpzUEFer1m5NX92ABR7tcna9povirJpPwfSxuO4EFI0tRAmRLw80UwpK72GWUdA$>.
>

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

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

From dawid.weiss at gmail.com  Wed Dec 23 10:39:05 2020
From: dawid.weiss at gmail.com (Dawid Weiss)
Date: Wed, 23 Dec 2020 11:39:05 +0100
Subject: javac reports broken HTML on multiline mailto links
Message-ID: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>

Hello and Merry Christmas,

I discovered this odd javac behavior with jdk8 up to jdk15 (didn't
check the latest head). This source file (note the anchor tag over
multiple lines):

/**
 * Lucene internals or asking for help on <a
 * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
  */
public class Breaks {}

When compiled with

javac -Xdoclint:all/protected Breaks.java

generates this:

Breaks.java:2: error: malformed HTML
 * Lucene internals or asking for help on <a
                                          ^
Breaks.java:3: error: bad use of '>'
 * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
                                            ^
Breaks.java:3: error: unexpected end tag: </a>
 * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
                                                                        ^
What's interesting is that the following two alternatives compile just fine:

/**
 * Lucene internals or asking for help on <a
 * href="http://lucene.apache.org">java-user at lucene.apache.org</a>
  */
public class Passes {}

/**
 * Lucene internals or asking for help on <a
href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
to figure out why.
  */
public class Passes2 {}

Is it just me or all these should compile just fine?...

Dawid

[1] Just in case mail clients attempt to reformat the pasted examples,
here's a gist with
the sources:
https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472

From jonathan.gibbons at oracle.com  Wed Dec 23 17:47:41 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 09:47:41 -0800
Subject: javac reports broken HTML on multiline mailto links
In-Reply-To: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
References: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
Message-ID: <b0b618f0-29c5-ea22-5c8a-f5b73b0452c4@oracle.com>

Wow. And Merry Christmas to you too.

I confirm your results for all your files.

Further experimentation reveals it is strongly related to the `@` 
character in the mailto: link.? Change that character in `Breaks.java` 
and it passes.

Do you want to file the bug, or would you like me to?

-- Jon

On 12/23/20 2:39 AM, Dawid Weiss wrote:
> Hello and Merry Christmas,
>
> I discovered this odd javac behavior with jdk8 up to jdk15 (didn't
> check the latest head). This source file (note the anchor tag over
> multiple lines):
>
> /**
>   * Lucene internals or asking for help on <a
>   * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>    */
> public class Breaks {}
>
> When compiled with
>
> javac -Xdoclint:all/protected Breaks.java
>
> generates this:
>
> Breaks.java:2: error: malformed HTML
>   * Lucene internals or asking for help on <a
>                                            ^
> Breaks.java:3: error: bad use of '>'
>   * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>                                              ^
> Breaks.java:3: error: unexpected end tag: </a>
>   * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>                                                                          ^
> What's interesting is that the following two alternatives compile just fine:
>
> /**
>   * Lucene internals or asking for help on <a
>   * href="http://lucene.apache.org">java-user at lucene.apache.org</a>
>    */
> public class Passes {}
>
> /**
>   * Lucene internals or asking for help on <a
> href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
> to figure out why.
>    */
> public class Passes2 {}
>
> Is it just me or all these should compile just fine?...
>
> Dawid
>
> [1] Just in case mail clients attempt to reformat the pasted examples,
> here's a gist with
> the sources:
> https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472

From uschindler at apache.org  Wed Dec 23 18:38:36 2020
From: uschindler at apache.org (Uwe Schindler)
Date: Wed, 23 Dec 2020 18:38:36 +0000
Subject: javac reports broken HTML on multiline mailto links
In-Reply-To: <b0b618f0-29c5-ea22-5c8a-f5b73b0452c4@oracle.com>
References: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
 <b0b618f0-29c5-ea22-5c8a-f5b73b0452c4@oracle.com>
Message-ID: <D7701F99-8E63-4D21-8636-970756F09CFC@apache.org>

I may open a bug on behalf of Dawid and Apache Lucene, if you haven't done already.

Uwe

Am December 23, 2020 5:47:41 PM UTC schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>Wow. And Merry Christmas to you too.
>
>I confirm your results for all your files.
>
>Further experimentation reveals it is strongly related to the `@` 
>character in the mailto: link.? Change that character in `Breaks.java` 
>and it passes.
>
>Do you want to file the bug, or would you like me to?
>
>-- Jon
>
>On 12/23/20 2:39 AM, Dawid Weiss wrote:
>> Hello and Merry Christmas,
>>
>> I discovered this odd javac behavior with jdk8 up to jdk15 (didn't
>> check the latest head). This source file (note the anchor tag over
>> multiple lines):
>>
>> /**
>>   * Lucene internals or asking for help on <a
>>   *
>href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>    */
>> public class Breaks {}
>>
>> When compiled with
>>
>> javac -Xdoclint:all/protected Breaks.java
>>
>> generates this:
>>
>> Breaks.java:2: error: malformed HTML
>>   * Lucene internals or asking for help on <a
>>                                            ^
>> Breaks.java:3: error: bad use of '>'
>>   *
>href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>                                              ^
>> Breaks.java:3: error: unexpected end tag: </a>
>>   *
>href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>                                                                      
>   ^
>> What's interesting is that the following two alternatives compile
>just fine:
>>
>> /**
>>   * Lucene internals or asking for help on <a
>>   * href="http://lucene.apache.org">java-user at lucene.apache.org</a>
>>    */
>> public class Passes {}
>>
>> /**
>>   * Lucene internals or asking for help on <a
>>
>href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>> to figure out why.
>>    */
>> public class Passes2 {}
>>
>> Is it just me or all these should compile just fine?...
>>
>> Dawid
>>
>> [1] Just in case mail clients attempt to reformat the pasted
>examples,
>> here's a gist with
>> the sources:
>> https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20201223/fde83891/attachment.htm>

From jonathan.gibbons at oracle.com  Wed Dec 23 19:32:10 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 11:32:10 -0800
Subject: javac reports broken HTML on multiline mailto links
In-Reply-To: <D7701F99-8E63-4D21-8636-970756F09CFC@apache.org>
References: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
 <b0b618f0-29c5-ea22-5c8a-f5b73b0452c4@oracle.com>
 <D7701F99-8E63-4D21-8636-970756F09CFC@apache.org>
Message-ID: <54d06513-4ae2-0eef-620c-b710c0a5e1c6@oracle.com>

I'll open a bug later today, if you don't do it first. Mostly, it's just 
a matter of who gets to be recorded as the "reporter"

-- Jon

On 12/23/20 10:38 AM, Uwe Schindler wrote:
> I may open a bug on behalf of Dawid and Apache Lucene, if you haven't 
> done already.
>
> Uwe
>
> Am December 23, 2020 5:47:41 PM UTC schrieb Jonathan Gibbons 
> <jonathan.gibbons at oracle.com>:
>
>     Wow. And Merry Christmas to you too.
>
>     I confirm your results for all your files.
>
>     Further experimentation reveals it is strongly related to the `@`
>     character in the mailto: link.? Change that character in `Breaks.java`
>     and it passes.
>
>     Do you want to file the bug, or would you like me to?
>
>     -- Jon
>
>     On 12/23/20 2:39 AM, Dawid Weiss wrote:
>
>         Hello and Merry Christmas, I discovered this odd javac
>         behavior with jdk8 up to jdk15 (didn't check the latest head).
>         This source file (note the anchor tag over multiple lines):
>         /** * Lucene internals or asking for help on <a *
>         href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>         */ public class Breaks {} When compiled with javac
>         -Xdoclint:all/protected Breaks.java generates this:
>         Breaks.java:2: error: malformed HTML * Lucene internals or
>         asking for help on <a ^ Breaks.java:3: error: bad use of '>' *
>         href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>         ^ Breaks.java:3: error: unexpected end tag: </a> *
>         href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>         ^ What's interesting is that the following two alternatives
>         compile just fine: /** * Lucene internals or asking for help
>         on <a *
>         href="http://lucene.apache.org">java-user at lucene.apache.org</a>
>         */ public class Passes {} /** * Lucene internals or asking for
>         help on <a
>         href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>         to figure out why. */ public class Passes2 {} Is it just me or
>         all these should compile just fine?... Dawid [1] Just in case
>         mail clients attempt to reformat the pasted examples, here's a
>         gist with the sources:
>         https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472
>         <https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472> 
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20201223/39a08b4e/attachment.htm>

From jonathan.gibbons at oracle.com  Wed Dec 23 23:24:18 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 15:24:18 -0800
Subject: javac reports broken HTML on multiline mailto links
In-Reply-To: <CAM21Rt_3ig2gsZakmKWC63z4V71WJagba9wY8TP+9=kPWbtEKA@mail.gmail.com>
References: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
 <b0b618f0-29c5-ea22-5c8a-f5b73b0452c4@oracle.com>
 <D7701F99-8E63-4D21-8636-970756F09CFC@apache.org>
 <54d06513-4ae2-0eef-620c-b710c0a5e1c6@oracle.com>
 <CAM21Rt_3ig2gsZakmKWC63z4V71WJagba9wY8TP+9=kPWbtEKA@mail.gmail.com>
Message-ID: <119fd121-30f3-4de2-b307-47ac1eb15a9c@oracle.com>

Dawid,

I'm 99.99% sure I know the cause. The difference between Breaks and 
Passes2 is the newline character. There's a bug in the code that tries 
to detect malformed attributes by looking for `@` after a newline.? The 
flag for the newline should have been reset by the intervening non-white 
characters, but was not.

-- Jon

On 12/23/20 2:40 PM, Dawid Weiss wrote:
> Hi Jon,
>
> Please file a bug (or Uwe do it, if you can) - I don't have access to
> Jira. I also don't care much who gets credited for reporting - can
> be Apache Lucene or my name, does not matter.
>
>> Further experimentation reveals it is strongly related to the `@` character in the mailto: link.  Change that character in `Breaks.java` and it passes.
> ...but Passes2 is literally identical content as Breaks (it has an
> '@'), yet it's somehow treated differently... Odd, huh?! ;)
>
> Dawid
>
> On Wed, Dec 23, 2020 at 8:32 PM Jonathan Gibbons
> <jonathan.gibbons at oracle.com> wrote:
>> I'll open a bug later today, if you don't do it first. Mostly, it's just a matter of who gets to be recorded as the "reporter"
>>
>> -- Jon
>>
>> On 12/23/20 10:38 AM, Uwe Schindler wrote:
>>
>> I may open a bug on behalf of Dawid and Apache Lucene, if you haven't done already.
>>
>> Uwe
>>
>> Am December 23, 2020 5:47:41 PM UTC schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>>> Wow. And Merry Christmas to you too.
>>>
>>> I confirm your results for all your files.
>>>
>>> Further experimentation reveals it is strongly related to the `@`
>>> character in the mailto: link.  Change that character in `Breaks.java`
>>> and it passes.
>>>
>>> Do you want to file the bug, or would you like me to?
>>>
>>> -- Jon
>>>
>>> On 12/23/20 2:39 AM, Dawid Weiss wrote:
>>>>   Hello and Merry Christmas,
>>>>
>>>>   I discovered this odd javac behavior with jdk8 up to jdk15 (didn't
>>>>   check the latest head). This source file (note the anchor tag over
>>>>   multiple lines):
>>>>
>>>>   /**
>>>>     * Lucene internals or asking for help on <a
>>>>     * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>>      */
>>>>   public class Breaks {}
>>>>
>>>>   When compiled with
>>>>
>>>>   javac -Xdoclint:all/protected Breaks.java
>>>>
>>>>   generates this:
>>>>
>>>>   Breaks.java:2: error: malformed HTML
>>>>     * Lucene internals or asking for help on <a
>>>>                                              ^
>>>>   Breaks.java:3: error: bad use of '>'
>>>>     * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>>                                                ^
>>>>   Breaks.java:3: error: unexpected end tag: </a>
>>>>     * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>>                                                                            ^
>>>>   What's interesting is that the following two alternatives compile just fine:
>>>>
>>>>   /**
>>>>     * Lucene internals or asking for help on <a
>>>>     * href="https://urldefense.com/v3/__http://lucene.apache.org__;!!GqivPVa7Brio!LYiyQ3Jp-pVSiKh764B-LZwZPOUiSzf1J_0YDAoCBN9rqPLyxJpgOHVsWHxqUGpBWMrxRA$ ">java-user at lucene.apache.org</a>
>>>>      */
>>>>   public class Passes {}
>>>>
>>>>   /**
>>>>     * Lucene internals or asking for help on <a
>>>>   href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>>   to figure out why.
>>>>      */
>>>>   public class Passes2 {}
>>>>
>>>>   Is it just me or all these should compile just fine?...
>>>>
>>>>   Dawid
>>>>
>>>>   [1] Just in case mail clients attempt to reformat the pasted examples,
>>>>   here's a gist with
>>>>   the sources:
>>>>   https://urldefense.com/v3/__https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472__;!!GqivPVa7Brio!LYiyQ3Jp-pVSiKh764B-LZwZPOUiSzf1J_0YDAoCBN9rqPLyxJpgOHVsWHxqUGr0CPKrkA$

From jonathan.gibbons at oracle.com  Wed Dec 23 23:33:13 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 15:33:13 -0800
Subject: javac reports broken HTML on multiline mailto links
In-Reply-To: <CAM21Rt_3ig2gsZakmKWC63z4V71WJagba9wY8TP+9=kPWbtEKA@mail.gmail.com>
References: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
 <b0b618f0-29c5-ea22-5c8a-f5b73b0452c4@oracle.com>
 <D7701F99-8E63-4D21-8636-970756F09CFC@apache.org>
 <54d06513-4ae2-0eef-620c-b710c0a5e1c6@oracle.com>
 <CAM21Rt_3ig2gsZakmKWC63z4V71WJagba9wY8TP+9=kPWbtEKA@mail.gmail.com>
Message-ID: <5c2f7d86-264c-b06a-f28a-18c6895b3d8a@oracle.com>

https://bugs.openjdk.java.net/browse/JDK-8258916

-- Jon


On 12/23/20 2:40 PM, Dawid Weiss wrote:
> Hi Jon,
>
> Please file a bug (or Uwe do it, if you can) - I don't have access to
> Jira. I also don't care much who gets credited for reporting - can
> be Apache Lucene or my name, does not matter.
>
>> Further experimentation reveals it is strongly related to the `@` character in the mailto: link.  Change that character in `Breaks.java` and it passes.
> ...but Passes2 is literally identical content as Breaks (it has an
> '@'), yet it's somehow treated differently... Odd, huh?! ;)
>
> Dawid
>
> On Wed, Dec 23, 2020 at 8:32 PM Jonathan Gibbons
> <jonathan.gibbons at oracle.com> wrote:
>> I'll open a bug later today, if you don't do it first. Mostly, it's just a matter of who gets to be recorded as the "reporter"
>>
>> -- Jon
>>
>> On 12/23/20 10:38 AM, Uwe Schindler wrote:
>>
>> I may open a bug on behalf of Dawid and Apache Lucene, if you haven't done already.
>>
>> Uwe
>>
>> Am December 23, 2020 5:47:41 PM UTC schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>>> Wow. And Merry Christmas to you too.
>>>
>>> I confirm your results for all your files.
>>>
>>> Further experimentation reveals it is strongly related to the `@`
>>> character in the mailto: link.  Change that character in `Breaks.java`
>>> and it passes.
>>>
>>> Do you want to file the bug, or would you like me to?
>>>
>>> -- Jon
>>>
>>> On 12/23/20 2:39 AM, Dawid Weiss wrote:
>>>>   Hello and Merry Christmas,
>>>>
>>>>   I discovered this odd javac behavior with jdk8 up to jdk15 (didn't
>>>>   check the latest head). This source file (note the anchor tag over
>>>>   multiple lines):
>>>>
>>>>   /**
>>>>     * Lucene internals or asking for help on <a
>>>>     * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>>      */
>>>>   public class Breaks {}
>>>>
>>>>   When compiled with
>>>>
>>>>   javac -Xdoclint:all/protected Breaks.java
>>>>
>>>>   generates this:
>>>>
>>>>   Breaks.java:2: error: malformed HTML
>>>>     * Lucene internals or asking for help on <a
>>>>                                              ^
>>>>   Breaks.java:3: error: bad use of '>'
>>>>     * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>>                                                ^
>>>>   Breaks.java:3: error: unexpected end tag: </a>
>>>>     * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>>                                                                            ^
>>>>   What's interesting is that the following two alternatives compile just fine:
>>>>
>>>>   /**
>>>>     * Lucene internals or asking for help on <a
>>>>     * href="https://urldefense.com/v3/__http://lucene.apache.org__;!!GqivPVa7Brio!LYiyQ3Jp-pVSiKh764B-LZwZPOUiSzf1J_0YDAoCBN9rqPLyxJpgOHVsWHxqUGpBWMrxRA$ ">java-user at lucene.apache.org</a>
>>>>      */
>>>>   public class Passes {}
>>>>
>>>>   /**
>>>>     * Lucene internals or asking for help on <a
>>>>   href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>>   to figure out why.
>>>>      */
>>>>   public class Passes2 {}
>>>>
>>>>   Is it just me or all these should compile just fine?...
>>>>
>>>>   Dawid
>>>>
>>>>   [1] Just in case mail clients attempt to reformat the pasted examples,
>>>>   here's a gist with
>>>>   the sources:
>>>>   https://urldefense.com/v3/__https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472__;!!GqivPVa7Brio!LYiyQ3Jp-pVSiKh764B-LZwZPOUiSzf1J_0YDAoCBN9rqPLyxJpgOHVsWHxqUGr0CPKrkA$

From dawid.weiss at gmail.com  Wed Dec 23 22:40:15 2020
From: dawid.weiss at gmail.com (Dawid Weiss)
Date: Wed, 23 Dec 2020 23:40:15 +0100
Subject: javac reports broken HTML on multiline mailto links
In-Reply-To: <54d06513-4ae2-0eef-620c-b710c0a5e1c6@oracle.com>
References: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
 <b0b618f0-29c5-ea22-5c8a-f5b73b0452c4@oracle.com>
 <D7701F99-8E63-4D21-8636-970756F09CFC@apache.org>
 <54d06513-4ae2-0eef-620c-b710c0a5e1c6@oracle.com>
Message-ID: <CAM21Rt_3ig2gsZakmKWC63z4V71WJagba9wY8TP+9=kPWbtEKA@mail.gmail.com>

Hi Jon,

Please file a bug (or Uwe do it, if you can) - I don't have access to
Jira. I also don't care much who gets credited for reporting - can
be Apache Lucene or my name, does not matter.

> Further experimentation reveals it is strongly related to the `@` character in the mailto: link.  Change that character in `Breaks.java` and it passes.

...but Passes2 is literally identical content as Breaks (it has an
'@'), yet it's somehow treated differently... Odd, huh?! ;)

Dawid

On Wed, Dec 23, 2020 at 8:32 PM Jonathan Gibbons
<jonathan.gibbons at oracle.com> wrote:
>
> I'll open a bug later today, if you don't do it first. Mostly, it's just a matter of who gets to be recorded as the "reporter"
>
> -- Jon
>
> On 12/23/20 10:38 AM, Uwe Schindler wrote:
>
> I may open a bug on behalf of Dawid and Apache Lucene, if you haven't done already.
>
> Uwe
>
> Am December 23, 2020 5:47:41 PM UTC schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>>
>> Wow. And Merry Christmas to you too.
>>
>> I confirm your results for all your files.
>>
>> Further experimentation reveals it is strongly related to the `@`
>> character in the mailto: link.  Change that character in `Breaks.java`
>> and it passes.
>>
>> Do you want to file the bug, or would you like me to?
>>
>> -- Jon
>>
>> On 12/23/20 2:39 AM, Dawid Weiss wrote:
>>>
>>>  Hello and Merry Christmas,
>>>
>>>  I discovered this odd javac behavior with jdk8 up to jdk15 (didn't
>>>  check the latest head). This source file (note the anchor tag over
>>>  multiple lines):
>>>
>>>  /**
>>>    * Lucene internals or asking for help on <a
>>>    * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>     */
>>>  public class Breaks {}
>>>
>>>  When compiled with
>>>
>>>  javac -Xdoclint:all/protected Breaks.java
>>>
>>>  generates this:
>>>
>>>  Breaks.java:2: error: malformed HTML
>>>    * Lucene internals or asking for help on <a
>>>                                             ^
>>>  Breaks.java:3: error: bad use of '>'
>>>    * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>                                               ^
>>>  Breaks.java:3: error: unexpected end tag: </a>
>>>    * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>                                                                           ^
>>>  What's interesting is that the following two alternatives compile just fine:
>>>
>>>  /**
>>>    * Lucene internals or asking for help on <a
>>>    * href="http://lucene.apache.org">java-user at lucene.apache.org</a>
>>>     */
>>>  public class Passes {}
>>>
>>>  /**
>>>    * Lucene internals or asking for help on <a
>>>  href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
>>>  to figure out why.
>>>     */
>>>  public class Passes2 {}
>>>
>>>  Is it just me or all these should compile just fine?...
>>>
>>>  Dawid
>>>
>>>  [1] Just in case mail clients attempt to reformat the pasted examples,
>>>  here's a gist with
>>>  the sources:
>>>  https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472

From msokolov at gmail.com  Wed Dec 23 23:25:13 2020
From: msokolov at gmail.com (Michael Sokolov)
Date: Wed, 23 Dec 2020 18:25:13 -0500
Subject: javac reports broken HTML on multiline mailto links
In-Reply-To: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
References: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
Message-ID: <CAGUSZHCOZNVDrbqHWtUtxVzQ+ZzTsfv3PL4czD=Baw06dsZxjg@mail.gmail.com>

Ugh the mailto: breaks it? Seems like a bug to me. Maybe the javadoc parser
tries to validate the content of an href attribute?

On Wed, Dec 23, 2020, 5:39 AM Dawid Weiss <dawid.weiss at gmail.com> wrote:

> Hello and Merry Christmas,
>
> I discovered this odd javac behavior with jdk8 up to jdk15 (didn't
> check the latest head). This source file (note the anchor tag over
> multiple lines):
>
> /**
>  * Lucene internals or asking for help on <a
>  * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org
> </a>
>   */
> public class Breaks {}
>
> When compiled with
>
> javac -Xdoclint:all/protected Breaks.java
>
> generates this:
>
> Breaks.java:2: error: malformed HTML
>  * Lucene internals or asking for help on <a
>                                           ^
> Breaks.java:3: error: bad use of '>'
>  * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org
> </a>
>                                             ^
> Breaks.java:3: error: unexpected end tag: </a>
>  * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org
> </a>
>                                                                         ^
> What's interesting is that the following two alternatives compile just
> fine:
>
> /**
>  * Lucene internals or asking for help on <a
>  * href="http://lucene.apache.org">java-user at lucene.apache.org</a>
>   */
> public class Passes {}
>
> /**
>  * Lucene internals or asking for help on <a
> href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
> to figure out why.
>   */
> public class Passes2 {}
>
> Is it just me or all these should compile just fine?...
>
> Dawid
>
> [1] Just in case mail clients attempt to reformat the pasted examples,
> here's a gist with
> the sources:
> https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe at lucene.apache.org
> For additional commands, e-mail: dev-help at lucene.apache.org
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20201223/580b51d4/attachment.htm>

From jonathan.gibbons at oracle.com  Wed Dec 23 23:38:21 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 23 Dec 2020 15:38:21 -0800
Subject: javac reports broken HTML on multiline mailto links
In-Reply-To: <CAGUSZHCOZNVDrbqHWtUtxVzQ+ZzTsfv3PL4czD=Baw06dsZxjg@mail.gmail.com>
References: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
 <CAGUSZHCOZNVDrbqHWtUtxVzQ+ZzTsfv3PL4czD=Baw06dsZxjg@mail.gmail.com>
Message-ID: <d24db8bd-943e-48ab-86d9-595cacaf201c@oracle.com>

Michael,

The error is more subtle than that. There will be a fix in due course.

-- Jon

On 12/23/20 3:25 PM, Michael Sokolov wrote:
> Ugh the mailto: breaks it? Seems like a bug to me. Maybe the javadoc 
> parser tries to validate the content of an href attribute?
>
> On Wed, Dec 23, 2020, 5:39 AM Dawid Weiss <dawid.weiss at gmail.com 
> <mailto:dawid.weiss at gmail.com>> wrote:
>
>     Hello and Merry Christmas,
>
>     I discovered this odd javac behavior with jdk8 up to jdk15 (didn't
>     check the latest head). This source file (note the anchor tag over
>     multiple lines):
>
>     /**
>     ?* Lucene internals or asking for help on <a
>     ?* href="mailto:java-user at lucene.apache.org
>     <mailto:java-user at lucene.apache.org>">java-user at lucene.apache.org
>     <mailto:java-user at lucene.apache.org></a>
>     ? */
>     public class Breaks {}
>
>     When compiled with
>
>     javac -Xdoclint:all/protected Breaks.java
>
>     generates this:
>
>     Breaks.java:2: error: malformed HTML
>     ?* Lucene internals or asking for help on <a
>     ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ^
>     Breaks.java:3: error: bad use of '>'
>     ?* href="mailto:java-user at lucene.apache.org
>     <mailto:java-user at lucene.apache.org>">java-user at lucene.apache.org
>     <mailto:java-user at lucene.apache.org></a>
>     ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ^
>     Breaks.java:3: error: unexpected end tag: </a>
>     ?* href="mailto:java-user at lucene.apache.org
>     <mailto:java-user at lucene.apache.org>">java-user at lucene.apache.org
>     <mailto:java-user at lucene.apache.org></a>
>     ? ? ? ? ? ^
>     What's interesting is that the following two alternatives compile
>     just fine:
>
>     /**
>     ?* Lucene internals or asking for help on <a
>     ?* href="http://lucene.apache.org
>     <http://lucene.apache.org>">java-user at lucene.apache.org
>     <mailto:java-user at lucene.apache.org></a>
>     ? */
>     public class Passes {}
>
>     /**
>     ?* Lucene internals or asking for help on <a
>     href="mailto:java-user at lucene.apache.org
>     <mailto:java-user at lucene.apache.org>">java-user at lucene.apache.org
>     <mailto:java-user at lucene.apache.org></a>
>     to figure out why.
>     ? */
>     public class Passes2 {}
>
>     Is it just me or all these should compile just fine?...
>
>     Dawid
>
>     [1] Just in case mail clients attempt to reformat the pasted examples,
>     here's a gist with
>     the sources:
>     https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472
>     <https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472>
>
>     ---------------------------------------------------------------------
>     To unsubscribe, e-mail: dev-unsubscribe at lucene.apache.org
>     <mailto:dev-unsubscribe at lucene.apache.org>
>     For additional commands, e-mail: dev-help at lucene.apache.org
>     <mailto:dev-help at lucene.apache.org>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20201223/4e045d88/attachment-0001.htm>

From ysatowse at openjdk.java.net  Thu Dec 24 01:17:00 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Thu, 24 Dec 2020 01:17:00 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v5]
In-Reply-To: <Jhwh9hnH9R7CiGsV4S7zgAu2nXrfXURb3KX7D-f3Jkg=.66a19e92-54db-4530-9360-47072587f180@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <qLWbJ9PDN8m4Lx7CG3JB_B8YFeAL3MiXfnmjgVYgZ8w=.c9276710-9637-4b25-a275-13ca336e988c@github.com>
 <oYLJ4H1-8m_-vudrpTG9HFAauozvrmWj8VGixyZ9L8g=.90efff73-4552-4fcc-8689-f71b742e8ccc@github.com>
 <Jhwh9hnH9R7CiGsV4S7zgAu2nXrfXURb3KX7D-f3Jkg=.66a19e92-54db-4530-9360-47072587f180@github.com>
Message-ID: <VDi3Ijs-MdtHTAXBk6LNoIDeCxdgIEuWWteMuyyeveI=.c1ac5846-7028-4247-92a6-be63a6ce935b@github.com>

On Wed, 23 Dec 2020 15:53:00 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> \s was introduced as a valid escape character in JDK 15 as part of the support for Text Blocks. https://docs.oracle.com/javase/specs/jls/se15/html/jls-3.html#jls-EscapeSequence https://docs.oracle.com/javase/specs/jls/se14/preview/specs/text-blocks-jls.html#jls-3.10.7 FWIW, the escape sequence showed up with red squiggly lines in my IDE.
> [?](#)

Ok.  I didn't know that.  When I change my project SDK to 14, the escape sequence showed up with red squiggly.

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

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

From jjg at openjdk.java.net  Thu Dec 24 02:09:05 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 24 Dec 2020 02:09:05 GMT
Subject: [jdk16] RFR: JDK-8258916: javac/doclint reports broken HTML on
 multiline mailto links
Message-ID: <8D7rBvR2PWIrPXSnfv1wxmUoilT3MOVUgvqFcHHYnVQ=.21b6765e-1368-46f8-a2e9-7c41d6d121ea@github.com>

Please review a trivial fix to correctly handle '@' inside the value of an HTML attribute. 
The fix is simply to cancel the `newline` flag that is set when a newline has been read.

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

Commit messages:
 - JDK-8258916: javac reports broken HTML on multiline mailto links

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

PR: https://git.openjdk.java.net/jdk16/pull/68

From ysatowse at openjdk.java.net  Thu Dec 24 02:54:17 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Thu, 24 Dec 2020 02:54:17 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v6]
In-Reply-To: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
Message-ID: <iAxu3KnauDOTBgSQCyVQoI8PZXWJC96g-CTZQCD8dU8=.be3b7775-1a43-42ed-87cc-6471ff5baa13@github.com>

> HTML4 is no longer supported in javadoc.
> 
> doclint needs to drop HTML4 support as well.
> The changes consist of:
> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
> * Modifying test code and expected outputs to be checked in HTML5

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

  7th: Some fixes and additional changes for 8247957

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/893/files
  - new: https://git.openjdk.java.net/jdk/pull/893/files/261f207a..8a0e1193

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

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

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

From jlaskey at openjdk.java.net  Thu Dec 24 03:08:01 2020
From: jlaskey at openjdk.java.net (Jim Laskey)
Date: Thu, 24 Dec 2020 03:08:01 GMT
Subject: [jdk16] RFR: JDK-8258916: javac/doclint reports broken HTML on
 multiline mailto links
In-Reply-To: <8D7rBvR2PWIrPXSnfv1wxmUoilT3MOVUgvqFcHHYnVQ=.21b6765e-1368-46f8-a2e9-7c41d6d121ea@github.com>
References: <8D7rBvR2PWIrPXSnfv1wxmUoilT3MOVUgvqFcHHYnVQ=.21b6765e-1368-46f8-a2e9-7c41d6d121ea@github.com>
Message-ID: <o361GH3BXj8lXnhEoq5OZh8eyYcZaRu9zK27CSOiOYA=.129835fc-73d1-4da5-a549-261718707c0c@github.com>

On Thu, 24 Dec 2020 02:04:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a trivial fix to correctly handle '@' inside the value of an HTML attribute. 
> The fix is simply to cancel the `newline` flag that is set when a newline has been read.

Marked as reviewed by jlaskey (Reviewer).

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

PR: https://git.openjdk.java.net/jdk16/pull/68

From iris at openjdk.java.net  Thu Dec 24 03:16:59 2020
From: iris at openjdk.java.net (Iris Clark)
Date: Thu, 24 Dec 2020 03:16:59 GMT
Subject: [jdk16] RFR: JDK-8258916: javac/doclint reports broken HTML on
 multiline mailto links
In-Reply-To: <8D7rBvR2PWIrPXSnfv1wxmUoilT3MOVUgvqFcHHYnVQ=.21b6765e-1368-46f8-a2e9-7c41d6d121ea@github.com>
References: <8D7rBvR2PWIrPXSnfv1wxmUoilT3MOVUgvqFcHHYnVQ=.21b6765e-1368-46f8-a2e9-7c41d6d121ea@github.com>
Message-ID: <m07Dt6o8Kxxg8LjWWo0fp4q63sJ3CbxX-CQvVtQALrs=.cc3a1144-6339-45c3-a022-2322533dfc75@github.com>

On Thu, 24 Dec 2020 02:04:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a trivial fix to correctly handle '@' inside the value of an HTML attribute. 
> The fix is simply to cancel the `newline` flag that is set when a newline has been read.

Marked as reviewed by iris (Reviewer).

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

PR: https://git.openjdk.java.net/jdk16/pull/68

From jjg at openjdk.java.net  Thu Dec 24 04:53:02 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 24 Dec 2020 04:53:02 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v6]
In-Reply-To: <iAxu3KnauDOTBgSQCyVQoI8PZXWJC96g-CTZQCD8dU8=.be3b7775-1a43-42ed-87cc-6471ff5baa13@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <iAxu3KnauDOTBgSQCyVQoI8PZXWJC96g-CTZQCD8dU8=.be3b7775-1a43-42ed-87cc-6471ff5baa13@github.com>
Message-ID: <5hMtvUeQgEc5mk5_Fcb3vahTxPIviTG5pbDD_J0f1ec=.5fbd685c-606e-44e4-843d-449418c1a950@github.com>

On Thu, 24 Dec 2020 02:54:17 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> HTML4 is no longer supported in javadoc.
>> 
>> doclint needs to drop HTML4 support as well.
>> The changes consist of:
>> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
>> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
>> * Modifying test code and expected outputs to be checked in HTML5
>
> Yoshiki Sato has updated the pull request incrementally with one additional commit since the last revision:
> 
>   7th: Some fixes and additional changes for 8247957

Marked as reviewed by jjg (Reviewer).

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

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

From jjg at openjdk.java.net  Thu Dec 24 04:55:59 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 24 Dec 2020 04:55:59 GMT
Subject: [jdk16] Integrated: JDK-8258916: javac/doclint reports broken HTML on
 multiline mailto links
In-Reply-To: <8D7rBvR2PWIrPXSnfv1wxmUoilT3MOVUgvqFcHHYnVQ=.21b6765e-1368-46f8-a2e9-7c41d6d121ea@github.com>
References: <8D7rBvR2PWIrPXSnfv1wxmUoilT3MOVUgvqFcHHYnVQ=.21b6765e-1368-46f8-a2e9-7c41d6d121ea@github.com>
Message-ID: <uY-9392fMGz1hqhmc-m3jtKLaIGbyG-Mvwony4QyKBg=.83c2dbd9-38bc-4289-b7d0-a0ca9d2a7271@github.com>

On Thu, 24 Dec 2020 02:04:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a trivial fix to correctly handle '@' inside the value of an HTML attribute. 
> The fix is simply to cancel the `newline` flag that is set when a newline has been read.

This pull request has now been integrated.

Changeset: c398a828
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.java.net/jdk16/commit/c398a828
Stats:     8 lines in 2 files changed: 7 ins; 0 del; 1 mod

8258916: javac/doclint reports broken HTML on multiline mailto links

Reviewed-by: jlaskey, iris

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

PR: https://git.openjdk.java.net/jdk16/pull/68

From jwilhelm at openjdk.java.net  Thu Dec 24 07:28:59 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 24 Dec 2020 07:28:59 GMT
Subject: RFR: Merge jdk16
Message-ID: <wQSFlx_IyhencApL5ww2nZ2agMkrsK6uGcvb_HG-L6Q=.c051fae7-49c9-4152-9ed0-b08e595140fa@github.com>

Forwardport JDK 16 -> JDK 17

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

Commit messages:
 - Merge
 - 8258916: javac/doclint reports broken HTML on multiline mailto links
 - 8253954: javac crash when compiling code with enhanced switch expressions with option -Xjcov
 - 8257468: runtime/whitebox/TestWBDeflateIdleMonitors.java fails with Monitor should be deflated.: expected true to equal false
 - 8257521: runtime/logging/MonitorInflationTest.java crashed in MonitorList::unlink_deflated

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

Changes: https://git.openjdk.java.net/jdk/pull/1887/files
  Stats: 74 lines in 6 files changed: 68 ins; 0 del; 6 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1887.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1887/head:pull/1887

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

From jwilhelm at openjdk.java.net  Thu Dec 24 08:32:43 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 24 Dec 2020 08:32:43 GMT
Subject: RFR: Merge jdk16 [v2]
In-Reply-To: <wQSFlx_IyhencApL5ww2nZ2agMkrsK6uGcvb_HG-L6Q=.c051fae7-49c9-4152-9ed0-b08e595140fa@github.com>
References: <wQSFlx_IyhencApL5ww2nZ2agMkrsK6uGcvb_HG-L6Q=.c051fae7-49c9-4152-9ed0-b08e595140fa@github.com>
Message-ID: <IMm6CSwqmNfAdSoHS8Nl-ZRAc8FKox4njPwLtkLvJj4=.f49d028e-21bf-4c74-a560-9d85c9a3b97e@github.com>

> Forwardport JDK 16 -> JDK 17

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

 - Merge
 - 8258913: ProblemList javax/swing/JComboBox/6559152/bug6559152.java on Linux-X64
   
   Reviewed-by: prr
 - 8258856: VM build without C1/C2 fails after JDK-8243205
   
   Reviewed-by: jiefu, kvn
 - 8258851: Mismatch in SunPKCS11 provider registration properties and actual implementation
   
   Reviewed-by: weijun
 - 8258839: Remove JVM option ExitVMOnVerifyError
   
   Reviewed-by: iignatyev, dcubed, coleenp
 - 8258186: Replace use of JNI_COMMIT mode with mode 0
   
   Reviewed-by: xuelei, alanb
 - 8258911: ProblemList serviceability/attach/RemovingUnixDomainSocketTest.java on Linux-X64
   
   Reviewed-by: amenkov
 - 8258557: Deproblemlist fixed problemlisted test
   
   Reviewed-by: trebari, serb
 - 8258837: Remove JVM option DisableStartThread
   
   Reviewed-by: kbarrett, dcubed
 - 8253368: TLS connection always receives close_notify exception
   
   Reviewed-by: xuelei
 - ... and 113 more: https://git.openjdk.java.net/jdk/compare/c398a828...f32ccfaa

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

Changes: https://git.openjdk.java.net/jdk/pull/1887/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=1887&range=01
  Stats: 23854 lines in 636 files changed: 18445 ins; 3271 del; 2138 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1887.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1887/head:pull/1887

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

From jwilhelm at openjdk.java.net  Thu Dec 24 08:32:44 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 24 Dec 2020 08:32:44 GMT
Subject: Integrated: Merge jdk16
In-Reply-To: <wQSFlx_IyhencApL5ww2nZ2agMkrsK6uGcvb_HG-L6Q=.c051fae7-49c9-4152-9ed0-b08e595140fa@github.com>
References: <wQSFlx_IyhencApL5ww2nZ2agMkrsK6uGcvb_HG-L6Q=.c051fae7-49c9-4152-9ed0-b08e595140fa@github.com>
Message-ID: <eNUUbu2_78dpB_izL6f5sxGpERcVpUa54Q1T0OTxfjE=.4594ede1-60b2-40f3-a48a-517fbdb3989e@github.com>

On Thu, 24 Dec 2020 07:23:41 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Forwardport JDK 16 -> JDK 17

This pull request has now been integrated.

Changeset: 57217b58
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/jdk/commit/57217b58
Stats:     74 lines in 6 files changed: 68 ins; 0 del; 6 mod

Merge

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

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

From dawid.weiss at gmail.com  Thu Dec 24 12:55:15 2020
From: dawid.weiss at gmail.com (Dawid Weiss)
Date: Thu, 24 Dec 2020 13:55:15 +0100
Subject: javac reports broken HTML on multiline mailto links
In-Reply-To: <119fd121-30f3-4de2-b307-47ac1eb15a9c@oracle.com>
References: <CAM21Rt9eOgXWA8dq6HUwJPW7nFpnPp7YcdQKHYRMaMmMGyEmpA@mail.gmail.com>
 <b0b618f0-29c5-ea22-5c8a-f5b73b0452c4@oracle.com>
 <D7701F99-8E63-4D21-8636-970756F09CFC@apache.org>
 <54d06513-4ae2-0eef-620c-b710c0a5e1c6@oracle.com>
 <CAM21Rt_3ig2gsZakmKWC63z4V71WJagba9wY8TP+9=kPWbtEKA@mail.gmail.com>
 <119fd121-30f3-4de2-b307-47ac1eb15a9c@oracle.com>
Message-ID: <CAM21Rt9z_PwJVU0Buw+uNCRucH7-u59NV8HLUqpUEndNk6fd1w@mail.gmail.com>

Thanks Jon. I appreciate the quick fix too!

Merry Christmas again. Fewer software bugs and more sunshine enjoyed
without a face mask in 2021.
Dawid

On Thu, Dec 24, 2020 at 12:26 AM Jonathan Gibbons
<jonathan.gibbons at oracle.com> wrote:
>
> Dawid,
>
> I'm 99.99% sure I know the cause. The difference between Breaks and
> Passes2 is the newline character. There's a bug in the code that tries
> to detect malformed attributes by looking for `@` after a newline.  The
> flag for the newline should have been reset by the intervening non-white
> characters, but was not.
>
> -- Jon
>
> On 12/23/20 2:40 PM, Dawid Weiss wrote:
> > Hi Jon,
> >
> > Please file a bug (or Uwe do it, if you can) - I don't have access to
> > Jira. I also don't care much who gets credited for reporting - can
> > be Apache Lucene or my name, does not matter.
> >
> >> Further experimentation reveals it is strongly related to the `@` character in the mailto: link.  Change that character in `Breaks.java` and it passes.
> > ...but Passes2 is literally identical content as Breaks (it has an
> > '@'), yet it's somehow treated differently... Odd, huh?! ;)
> >
> > Dawid
> >
> > On Wed, Dec 23, 2020 at 8:32 PM Jonathan Gibbons
> > <jonathan.gibbons at oracle.com> wrote:
> >> I'll open a bug later today, if you don't do it first. Mostly, it's just a matter of who gets to be recorded as the "reporter"
> >>
> >> -- Jon
> >>
> >> On 12/23/20 10:38 AM, Uwe Schindler wrote:
> >>
> >> I may open a bug on behalf of Dawid and Apache Lucene, if you haven't done already.
> >>
> >> Uwe
> >>
> >> Am December 23, 2020 5:47:41 PM UTC schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
> >>> Wow. And Merry Christmas to you too.
> >>>
> >>> I confirm your results for all your files.
> >>>
> >>> Further experimentation reveals it is strongly related to the `@`
> >>> character in the mailto: link.  Change that character in `Breaks.java`
> >>> and it passes.
> >>>
> >>> Do you want to file the bug, or would you like me to?
> >>>
> >>> -- Jon
> >>>
> >>> On 12/23/20 2:39 AM, Dawid Weiss wrote:
> >>>>   Hello and Merry Christmas,
> >>>>
> >>>>   I discovered this odd javac behavior with jdk8 up to jdk15 (didn't
> >>>>   check the latest head). This source file (note the anchor tag over
> >>>>   multiple lines):
> >>>>
> >>>>   /**
> >>>>     * Lucene internals or asking for help on <a
> >>>>     * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
> >>>>      */
> >>>>   public class Breaks {}
> >>>>
> >>>>   When compiled with
> >>>>
> >>>>   javac -Xdoclint:all/protected Breaks.java
> >>>>
> >>>>   generates this:
> >>>>
> >>>>   Breaks.java:2: error: malformed HTML
> >>>>     * Lucene internals or asking for help on <a
> >>>>                                              ^
> >>>>   Breaks.java:3: error: bad use of '>'
> >>>>     * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
> >>>>                                                ^
> >>>>   Breaks.java:3: error: unexpected end tag: </a>
> >>>>     * href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
> >>>>                                                                            ^
> >>>>   What's interesting is that the following two alternatives compile just fine:
> >>>>
> >>>>   /**
> >>>>     * Lucene internals or asking for help on <a
> >>>>     * href="https://urldefense.com/v3/__http://lucene.apache.org__;!!GqivPVa7Brio!LYiyQ3Jp-pVSiKh764B-LZwZPOUiSzf1J_0YDAoCBN9rqPLyxJpgOHVsWHxqUGpBWMrxRA$ ">java-user at lucene.apache.org</a>
> >>>>      */
> >>>>   public class Passes {}
> >>>>
> >>>>   /**
> >>>>     * Lucene internals or asking for help on <a
> >>>>   href="mailto:java-user at lucene.apache.org">java-user at lucene.apache.org</a>
> >>>>   to figure out why.
> >>>>      */
> >>>>   public class Passes2 {}
> >>>>
> >>>>   Is it just me or all these should compile just fine?...
> >>>>
> >>>>   Dawid
> >>>>
> >>>>   [1] Just in case mail clients attempt to reformat the pasted examples,
> >>>>   here's a gist with
> >>>>   the sources:
> >>>>   https://urldefense.com/v3/__https://gist.github.com/dweiss/c1c9f218c6a8e5d2f253193806a9f472__;!!GqivPVa7Brio!LYiyQ3Jp-pVSiKh764B-LZwZPOUiSzf1J_0YDAoCBN9rqPLyxJpgOHVsWHxqUGr0CPKrkA$

From jjg at openjdk.java.net  Thu Dec 24 21:21:09 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Thu, 24 Dec 2020 21:21:09 GMT
Subject: [jdk16] RFR: JDK-8251200: False positive messages about missing
 comments for serialization
Message-ID: <DZGU669kvbvO3JZPkpnhbEKz9g6zEURcyGwEeeVwvAs=.fa702781-1ef8-4913-b800-f333ce4cb3a0@github.com>

Using the `@serial` tag, a class can explicitly opt-in to being documented on the serialized form page.  However, a class that does not want to opt-in should not be required to have a doc comment, and should not trigger the "missing comment" warning if there is no comment.

The fix is to check for the presence of the comment on a class before analyzing it to see if it contains `@serial` tags.

The code in `Utils.getDocCommentTree0` is slightly refactored to allow a new predicate `hasDocCommentTree` to be added.

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

Commit messages:
 - JDK-8251200: False positive messages about missing comments for serialization

Changes: https://git.openjdk.java.net/jdk16/pull/70/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=70&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8251200
  Stats: 138 lines in 3 files changed: 115 ins; 21 del; 2 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/70.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/70/head:pull/70

PR: https://git.openjdk.java.net/jdk16/pull/70

From ysatowse at openjdk.java.net  Fri Dec 25 02:17:16 2020
From: ysatowse at openjdk.java.net (Yoshiki Sato)
Date: Fri, 25 Dec 2020 02:17:16 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v7]
In-Reply-To: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
Message-ID: <LzK41S5KU-_RAey_VEUY36M38mCNpTaUyTyAQGFyy_k=.bd57bd4b-edf0-465e-987a-bc8b96b5bf5f@github.com>

> HTML4 is no longer supported in javadoc.
> 
> doclint needs to drop HTML4 support as well.
> The changes consist of:
> * Removing -Xhtmlversion option from doclint and --doclint-format from javac.
> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
> * Updating makefile not to use removed option.
> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
> * Fixing incorrect value checks for the id attribute.
> * Modifying test code and expected outputs to be checked in HTML5

Yoshiki Sato has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains ten commits:

 - Merge master
 - 7th: Some fixes and additional changes for 8247957
 - 5th: 8258460: Remove --doclint-format option from javac
 - 5th: 8257204 and 8256313
   8257204: Remove usage of -Xhtmlversion option from javac
   8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option
 - 8257204 and 8256313
   8257204: Remove usage of -Xhtmlversion option from javac
   8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option
 - 3rd: 8247957 and 8256312
 - Merge branch 'master' into JDK-8247957_2
 - 8247957: remove doclint support for HTML 4
   8256312: Valid anchor 'id' value not allowed
 - 8247957: remove doclint support for HTML 4

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

Changes: https://git.openjdk.java.net/jdk/pull/893/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=893&range=06
  Stats: 1499 lines in 60 files changed: 411 ins; 808 del; 280 mod
  Patch: https://git.openjdk.java.net/jdk/pull/893.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/893/head:pull/893

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

From jjg at openjdk.java.net  Fri Dec 25 02:21:03 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 25 Dec 2020 02:21:03 GMT
Subject: [jdk16] RFR: JDK-8249633: doclint reports missing javadoc for JavaFX
 property methods that have a property description
Message-ID: <_RXuS8PE5hG6q-4UljOBrv-GkWPbeVyLCtP3FWborfs=.f78e2972-9e58-4c02-bb6b-9df3b76f9fd6@github.com>

There are two parts to the fix:

1. Similar to that of JDK-8251200:  predicate methods in `Utils` used to check if an element has certain tags in its doc comment may trigger the missing comment check even when there does not need to be a comment.

2. When synthesizing comments for the property-related methods, the code checks for the existence of explicit comments, in case they exist; that could also trigger the "missing comment" check.

The fix shares some changes with JDK-8251200; whichever does not go first will need a merge commit.

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

Commit messages:
 - fix whitespace
 - JDK-8249633: doclint reports missing javadoc for JavaFX property methods that have a property description

Changes: https://git.openjdk.java.net/jdk16/pull/71/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk16&pr=71&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8249633
  Stats: 131 lines in 3 files changed: 99 ins; 21 del; 11 mod
  Patch: https://git.openjdk.java.net/jdk16/pull/71.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk16 pull/71/head:pull/71

PR: https://git.openjdk.java.net/jdk16/pull/71

From jjg at openjdk.java.net  Fri Dec 25 02:24:03 2020
From: jjg at openjdk.java.net (Jonathan Gibbons)
Date: Fri, 25 Dec 2020 02:24:03 GMT
Subject: RFR: 8247957: remove doclint support for HTML 4 [v7]
In-Reply-To: <LzK41S5KU-_RAey_VEUY36M38mCNpTaUyTyAQGFyy_k=.bd57bd4b-edf0-465e-987a-bc8b96b5bf5f@github.com>
References: <vlbJ-zrZsNQGcUxAM9Z76lcpLj2QeNnlyZnjBQJTF3U=.82e5e47e-5db1-4a4f-8ca0-48009fbda71d@github.com>
 <LzK41S5KU-_RAey_VEUY36M38mCNpTaUyTyAQGFyy_k=.bd57bd4b-edf0-465e-987a-bc8b96b5bf5f@github.com>
Message-ID: <qaq5n4TG873EONYE468-sVM_oq8AibEpWT1haNhmIOM=.cf3d7c3b-2510-4c67-8fbf-3d90031b54cc@github.com>

On Fri, 25 Dec 2020 02:17:16 GMT, Yoshiki Sato <ysatowse at openjdk.org> wrote:

>> HTML4 is no longer supported in javadoc.
>> 
>> doclint needs to drop HTML4 support as well.
>> The changes consist of:
>> * Removing -Xhtmlversion option from doclint and --doclint-format from javac.
>> * Removing jdk.javadoc.internal.doclint.HtmlVersion and its references.
>> * Updating makefile not to use removed option.
>> * Sorting out supported tags and attributes in HTML5 (including fix incorrect permission of valign in TH, TR, TD, THEAD and TBODY)
>> * Fixing incorrect value checks for the id attribute.
>> * Modifying test code and expected outputs to be checked in HTML5
>
> Yoshiki Sato has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains ten commits:
> 
>  - Merge master
>  - 7th: Some fixes and additional changes for 8247957
>  - 5th: 8258460: Remove --doclint-format option from javac
>  - 5th: 8257204 and 8256313
>    8257204: Remove usage of -Xhtmlversion option from javac
>    8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option
>  - 8257204 and 8256313
>    8257204: Remove usage of -Xhtmlversion option from javac
>    8256313: JavaCompilation.gmk needs to be updated not to use --doclint-format html5 option
>  - 3rd: 8247957 and 8256312
>  - Merge branch 'master' into JDK-8247957_2
>  - 8247957: remove doclint support for HTML 4
>    8256312: Valid anchor 'id' value not allowed
>  - 8247957: remove doclint support for HTML 4

Marked as reviewed by jjg (Reviewer).

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

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