From HANNES.WALLNOEFER at ORACLE.COM Mon Aug 3 09:55:51 2020 From: HANNES.WALLNOEFER at ORACLE.COM (Hannes Wallnoefer) Date: Mon, 3 Aug 2020 11:55:51 +0200 Subject: RFR: 8250954: Avoid multiple warnings for external docs with mismatching modularity Message-ID: <0E52EC4E-9C4B-41C5-9F27-00B41FDA84F7@ORACLE.COM> Please review: JBS: https://bugs.openjdk.java.net/browse/JDK-8250954 Webrev: http://cr.openjdk.java.net/~hannesw/8250954/webrev.00/ This is a trivial fix to print only one warning per external documentation bundle in case of mismatching modularity, instead of printing one for each contained package. Thanks, Hannes From fw at deneb.enyo.de Tue Aug 4 18:20:31 2020 From: fw at deneb.enyo.de (Florian Weimer) Date: Tue, 04 Aug 2020 20:20:31 +0200 Subject: "no comment" warnings for non-public entities related to serialization Message-ID: <87lfiue0i8.fsf@mid.deneb.enyo.de> I'm not sure how recent this change is, but I noticed that "no comment" warnings are now printed for entities that are related to serialization: non-public classes which implement Serializable, and private non-transient fields in serializable classes, and named private serialization-related methods. I think it might make sense to add a few words to the warning that it's about serialization compatibility. It took me a moment to realize why javadoc was warning about these constructs. From jonathan.gibbons at oracle.com Tue Aug 4 18:33:24 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 4 Aug 2020 11:33:24 -0700 Subject: "no comment" warnings for non-public entities related to serialization In-Reply-To: <87lfiue0i8.fsf@mid.deneb.enyo.de> References: <87lfiue0i8.fsf@mid.deneb.enyo.de> Message-ID: On 8/4/20 11:20 AM, Florian Weimer wrote: > I'm not sure how recent this change is, but I noticed that "no > comment" warnings are now printed for entities that are related to > serialization: non-public classes which implement Serializable, and > private non-transient fields in serializable classes, and named > private serialization-related methods. > > I think it might make sense to add a few words to the warning that > it's about serialization compatibility. It took me a moment to > realize why javadoc was warning about these constructs. Hi Florian, Thanks for the suggestion.? This is a side-effect of a recent bug fix, that missing comments were never being detected by doclint in javadoc. This was true for all missing comments, not just for declarations and comments related to serialization. I'd be curious if you have seen the warning generated inappropriately. For example, you write: `non-public classes which implement Serializable` If the class is not being documented, you shouldn't see any warnings about anything related to the doc comments for the class. Given that this is a general message about any missing comments, it may be tricky to add additional info when the comment is related to serialization. -- Jon From jonathan.gibbons at oracle.com Tue Aug 4 19:26:12 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 4 Aug 2020 12:26:12 -0700 Subject: "no comment" warnings for non-public entities related to serialization In-Reply-To: <878seudxue.fsf@mid.deneb.enyo.de> References: <87lfiue0i8.fsf@mid.deneb.enyo.de> <878seudxue.fsf@mid.deneb.enyo.de> Message-ID: <1550490e-421b-7201-809a-43c47975d30b@oracle.com> On 8/4/20 12:18 PM, Florian Weimer wrote: > * Jonathan Gibbons: > >> On 8/4/20 11:20 AM, Florian Weimer wrote: >>> I'm not sure how recent this change is, but I noticed that "no >>> comment" warnings are now printed for entities that are related to >>> serialization: non-public classes which implement Serializable, and >>> private non-transient fields in serializable classes, and named >>> private serialization-related methods. >>> >>> I think it might make sense to add a few words to the warning that >>> it's about serialization compatibility. It took me a moment to >>> realize why javadoc was warning about these constructs. >> Hi Florian, >> >> Thanks for the suggestion.? This is a side-effect of a recent bug fix, >> that missing comments were never being detected by doclint in javadoc. >> This was true for all missing comments, not just for declarations and >> comments related to serialization. > Hah. I had not realized that. I guess my public methods have already > been documented, just not the things related to serialization. > >> I'd be curious if you have seen the warning generated inappropriately. >> For example, you write: `non-public classes which implement Serializable` >> If the class is not being documented, you shouldn't see any warnings >> about anything related to the doc comments for the class. > In certain contexts, I get a doclint warning for: > > package enyo.util; > > class E extends Exception { > } > > src/enyo.core/enyo/util/E.java:3: warning: no comment > class E extends Exception { > ^ > > I expect no warning is expected here? > > There's more to it, for a standalone example, I do not get a warning. > I see it with a modular build, where enyo.util is an exported package. > The source file is called E.java and it's on the module source path, > and contains just those four quoted lines. It would be surprising (bug?) to see a warning being generated for a class that is not being documented.? I assume you have not given command-line options to include that class in the documentation.? I'm also guessing that this is while using javadoc, where the recent change occurred; not javac. I can also try and recreate the issue, based on what you have said so far. -- Jon From fw at deneb.enyo.de Tue Aug 4 19:18:01 2020 From: fw at deneb.enyo.de (Florian Weimer) Date: Tue, 04 Aug 2020 21:18:01 +0200 Subject: "no comment" warnings for non-public entities related to serialization In-Reply-To: (Jonathan Gibbons's message of "Tue, 4 Aug 2020 11:33:24 -0700") References: <87lfiue0i8.fsf@mid.deneb.enyo.de> Message-ID: <878seudxue.fsf@mid.deneb.enyo.de> * Jonathan Gibbons: > On 8/4/20 11:20 AM, Florian Weimer wrote: >> I'm not sure how recent this change is, but I noticed that "no >> comment" warnings are now printed for entities that are related to >> serialization: non-public classes which implement Serializable, and >> private non-transient fields in serializable classes, and named >> private serialization-related methods. >> >> I think it might make sense to add a few words to the warning that >> it's about serialization compatibility. It took me a moment to >> realize why javadoc was warning about these constructs. > > Hi Florian, > > Thanks for the suggestion.? This is a side-effect of a recent bug fix, > that missing comments were never being detected by doclint in javadoc. > This was true for all missing comments, not just for declarations and > comments related to serialization. Hah. I had not realized that. I guess my public methods have already been documented, just not the things related to serialization. > I'd be curious if you have seen the warning generated inappropriately. > For example, you write: `non-public classes which implement Serializable` > If the class is not being documented, you shouldn't see any warnings > about anything related to the doc comments for the class. In certain contexts, I get a doclint warning for: package enyo.util; class E extends Exception { } src/enyo.core/enyo/util/E.java:3: warning: no comment class E extends Exception { ^ I expect no warning is expected here? There's more to it, for a standalone example, I do not get a warning. I see it with a modular build, where enyo.util is an exported package. The source file is called E.java and it's on the module source path, and contains just those four quoted lines. From fw at deneb.enyo.de Tue Aug 4 19:49:33 2020 From: fw at deneb.enyo.de (Florian Weimer) Date: Tue, 04 Aug 2020 21:49:33 +0200 Subject: "no comment" warnings for non-public entities related to serialization In-Reply-To: <1550490e-421b-7201-809a-43c47975d30b@oracle.com> (Jonathan Gibbons's message of "Tue, 4 Aug 2020 12:26:12 -0700") References: <87lfiue0i8.fsf@mid.deneb.enyo.de> <878seudxue.fsf@mid.deneb.enyo.de> <1550490e-421b-7201-809a-43c47975d30b@oracle.com> Message-ID: <87zh7achte.fsf@mid.deneb.enyo.de> * Jonathan Gibbons: > It would be surprising (bug?) to see a warning being generated for a > class that > is not being documented.? I assume you have not given command-line options > to include that class in the documentation.? I'm also guessing that this is > while using javadoc, where the recent change occurred; not javac. > > I can also try and recreate the issue, based on what you have said so far. I can reproduce the issue outside of my strange build environment, so it should be easy enough to produce a small reproducer. I'll see if I can get something to you by the end of the week. From fw at deneb.enyo.de Wed Aug 5 17:02:02 2020 From: fw at deneb.enyo.de (Florian Weimer) Date: Wed, 05 Aug 2020 19:02:02 +0200 Subject: "no comment" warning for non-public exception (was: Re: "no comment" warnings for non-public entities related to serialization) In-Reply-To: <87zh7achte.fsf@mid.deneb.enyo.de> (Florian Weimer's message of "Tue, 04 Aug 2020 21:49:33 +0200") References: <87lfiue0i8.fsf@mid.deneb.enyo.de> <878seudxue.fsf@mid.deneb.enyo.de> <1550490e-421b-7201-809a-43c47975d30b@oracle.com> <87zh7achte.fsf@mid.deneb.enyo.de> Message-ID: <87k0ydauwl.fsf_-_@mid.deneb.enyo.de> * Florian Weimer: > * Jonathan Gibbons: > >> It would be surprising (bug?) to see a warning being generated for a >> class that >> is not being documented.? I assume you have not given command-line options >> to include that class in the documentation.? I'm also guessing that this is >> while using javadoc, where the recent change occurred; not javac. >> >> I can also try and recreate the issue, based on what you have said so far. > > I can reproduce the issue outside of my strange build environment, so > it should be easy enough to produce a small reproducer. I'll see if I > can get something to you by the end of the week. I was able to reproduce it. Three files are needed: # src/enyo.core/module-info.java /** * Documented. */ module enyo.core { exports enyo.util; } # src/enyo.core/enyo/util/E.java package enyo.util; class E extends Exception { } # src/enyo.core/enyo/util/F.java package enyo.util; /** * Documented. */ public class F extends Exception { } Then: $ javadoc -quiet -d doc --module-source-path src --module enyo.core src/enyo.core/enyo/util/E.java:3: warning: no comment class E extends Exception { ^ 1 warning This is with a fairly current OpenJDK 16 build (60417:c13af6e1d11f, I think). From jonathan.gibbons at oracle.com Wed Aug 5 18:16:46 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 5 Aug 2020 11:16:46 -0700 Subject: "no comment" warning for non-public exception In-Reply-To: <87k0ydauwl.fsf_-_@mid.deneb.enyo.de> References: <87lfiue0i8.fsf@mid.deneb.enyo.de> <878seudxue.fsf@mid.deneb.enyo.de> <1550490e-421b-7201-809a-43c47975d30b@oracle.com> <87zh7achte.fsf@mid.deneb.enyo.de> <87k0ydauwl.fsf_-_@mid.deneb.enyo.de> Message-ID: <2640c1fa-c85f-3d1e-47fc-a8ff5664ff92@oracle.com> On 8/5/20 10:02 AM, Florian Weimer wrote: > * Florian Weimer: > >> * Jonathan Gibbons: >> >>> It would be surprising (bug?) to see a warning being generated for a >>> class that >>> is not being documented.? I assume you have not given command-line options >>> to include that class in the documentation.? I'm also guessing that this is >>> while using javadoc, where the recent change occurred; not javac. >>> >>> I can also try and recreate the issue, based on what you have said so far. >> I can reproduce the issue outside of my strange build environment, so >> it should be easy enough to produce a small reproducer. I'll see if I >> can get something to you by the end of the week. > I was able to reproduce it. Three files are needed: > > # src/enyo.core/module-info.java > > /** > * Documented. > */ > module enyo.core { > exports enyo.util; > } > > # src/enyo.core/enyo/util/E.java > > package enyo.util; > > class E extends Exception { > } > > # src/enyo.core/enyo/util/F.java > > package enyo.util; > > /** > * Documented. > */ > public class F extends Exception { > } > > > Then: > > $ javadoc -quiet -d doc --module-source-path src --module enyo.core > src/enyo.core/enyo/util/E.java:3: warning: no comment > class E extends Exception { > ^ > 1 warning > > This is with a fairly current OpenJDK 16 build (60417:c13af6e1d11f, I think). Hmmm. thanks for the report. That certainly seems like a bug that needs to be investigated. -- Jon From jonathan.gibbons at oracle.com Wed Aug 5 18:36:12 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 5 Aug 2020 11:36:12 -0700 Subject: "no comment" warning for non-public exception In-Reply-To: <2640c1fa-c85f-3d1e-47fc-a8ff5664ff92@oracle.com> References: <87lfiue0i8.fsf@mid.deneb.enyo.de> <878seudxue.fsf@mid.deneb.enyo.de> <1550490e-421b-7201-809a-43c47975d30b@oracle.com> <87zh7achte.fsf@mid.deneb.enyo.de> <87k0ydauwl.fsf_-_@mid.deneb.enyo.de> <2640c1fa-c85f-3d1e-47fc-a8ff5664ff92@oracle.com> Message-ID: <51e7f30c-90d6-bf92-2e96-2ea1ab0ac9a4@oracle.com> On 8/5/20 11:16 AM, Jonathan Gibbons wrote: > > On 8/5/20 10:02 AM, Florian Weimer wrote: >> * Florian Weimer: >> >>> * Jonathan Gibbons: >>> >>>> It would be surprising (bug?) to see a warning being generated for a >>>> class that >>>> is not being documented.? I assume you have not given command-line >>>> options >>>> to include that class in the documentation.? I'm also guessing that >>>> this is >>>> while using javadoc, where the recent change occurred; not javac. >>>> >>>> I can also try and recreate the issue, based on what you have said >>>> so far. >>> I can reproduce the issue outside of my strange build environment, so >>> it should be easy enough to produce a small reproducer.? I'll see if I >>> can get something to you by the end of the week. >> I was able to reproduce it.? Three files are needed: >> >> # src/enyo.core/module-info.java >> >> /** >> ? * Documented. >> ? */ >> module enyo.core { >> ???? exports enyo.util; >> } >> >> # src/enyo.core/enyo/util/E.java >> >> package enyo.util; >> >> class E extends Exception { >> } >> >> # src/enyo.core/enyo/util/F.java >> >> package enyo.util; >> >> /** >> ? * Documented. >> ? */ >> public class F extends Exception { >> } >> >> >> Then: >> >> $ javadoc -quiet -d doc --module-source-path src --module enyo.core >> src/enyo.core/enyo/util/E.java:3: warning: no comment >> class E extends Exception { >> ^ >> 1 warning >> >> This is with a fairly current OpenJDK 16 build (60417:c13af6e1d11f, I >> think). > > Hmmm. thanks for the report. That certainly seems like a bug that > needs to be investigated. > > -- Jon > > Tracked as https://bugs.openjdk.java.net/browse/JDK-8251200 -- Jon From jonathan.gibbons at oracle.com Mon Aug 10 15:23:56 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 10 Aug 2020 08:23:56 -0700 Subject: RFR: 8250954: Avoid multiple warnings for external docs with mismatching modularity In-Reply-To: <0E52EC4E-9C4B-41C5-9F27-00B41FDA84F7@ORACLE.COM> References: <0E52EC4E-9C4B-41C5-9F27-00B41FDA84F7@ORACLE.COM> Message-ID: <536a354a-eb30-d645-723a-d5f34d00ded9@oracle.com> +1 -- Jon On 8/3/20 2:55 AM, Hannes Wallnoefer wrote: > Please review: > > JBS: https://bugs.openjdk.java.net/browse/JDK-8250954 > Webrev: http://cr.openjdk.java.net/~hannesw/8250954/webrev.00/ > > This is a trivial fix to print only one warning per external documentation bundle in case of mismatching modularity, instead of printing one for each contained package. > > Thanks, > Hannes From pavel.rappo at oracle.com Thu Aug 13 18:48:19 2020 From: pavel.rappo at oracle.com (Pavel Rappo) Date: Thu, 13 Aug 2020 19:48:19 +0100 Subject: RFR [16] 8251550: Clean up jdk.javadoc and the related parts of jdk.compiler Message-ID: <680444AC-6DD8-49CF-9B3D-D71A2AD6B4C1@oracle.com> Hello, Please review the below change for https://bugs.openjdk.java.net/browse/JDK-8251550 http://cr.openjdk.java.net/~prappo/8251550/webrev.00/ This represents squashed commits that have accumulated in my git branch. Since the changeset has started to look dangerously big, I decided not to wait until we finish the migration to Git and GitHub, and push it sooner. The less the others have to merge, the better. -Pavel From jonathan.gibbons at oracle.com Fri Aug 14 16:49:09 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 14 Aug 2020 09:49:09 -0700 Subject: RFR [16] 8251550: Clean up jdk.javadoc and the related parts of jdk.compiler In-Reply-To: <680444AC-6DD8-49CF-9B3D-D71A2AD6B4C1@oracle.com> References: <680444AC-6DD8-49CF-9B3D-D71A2AD6B4C1@oracle.com> Message-ID: Good cleanup. Some systemic changes needed. Details below. -- Jon On 8/13/20 11:48 AM, Pavel Rappo wrote: > Hello, > > Please review the below change for https://bugs.openjdk.java.net/browse/JDK-8251550 > > http://cr.openjdk.java.net/~prappo/8251550/webrev.00/ > > This represents squashed commits that have accumulated in my git branch. Since the changeset has started to look dangerously big, I decided not to wait until we finish the migration to Git and GitHub, and push it sooner. The less the others have to merge, the better. > > -Pavel > Some of the doctree changes contain this sequence: ???

??? 


That will trigger a doccheck warning for a redundant 
 tag.

Since you're improving the doc comments for the DocTree nodes, it would 
be nice to use ... or (better) ,,, around the 
variables in the templates. For example:

34 * 
35 * @author name-text
36 * 

   37  *

DocRootTree:

I think you need {@literal ...} on line 33.

DocTypeTree:
As an enhancement, given that the tools only support HTML 5 these days, 
It might be helpful to give the specific text for an HTML 5 document

32 * 
   33  *    <!doctype text>
34 * 


 ??? + * For HTML5 documents, the correct form is? {@code }.

EntityTree:
Maybe remove the "misleading" spaces in the examples?

General:

Thinking aloud, for a future update when we have the `{@spec}` tag. In 
the introductory sentence for each tag, replace the use of `{@code}` by 
`{@spec}` linking to the right place in the doc-comment tag 
specification. I guess for many, it's not necessary, but the idea came 
to mind reading IndexTree, where more information may be helpful. That 
being said, additional info belongs in the tag spec, not the tree node spec.

DocSourcePositions:57,89
replace `CompilationUnit` with `compilation unit`

DocTreeFactory:112
We are inconsistent about whether to use `{..}` for inline tags, which 
will be worse when we add our first bimodal standard tag, `@return`, but 
using `{...}` for `{@deprecated}` is definitely wrong

General: (question)
Does a trailing space inside `{@code something }` cause extra whitespace 
in the rendered HTML?

DocTreePath:37,96,98,99
More un-code-d type names. Follow existing conventions for either using 
`{@code...}` or the descriptive equivalent (e.g. "tree path")

Trees:239,240
replace "The" by "the"
remove package name from TypeMirror, and use @code for that and ErrorType

DocCommentParser:
avoid Latin abbreviations; use "for example, such as"
1103: another candidate for `{@spec}` !!

Pretty: removing import
In general, this is a dangerous edit; throughout javac, you will see 
imports of javac.util.List in preference to java.util.List. I assume you 
have compiled and run the tests, to validate this change.

WriterFactory:135
Trailing period.

BaseTaglet
Yay for removing redundant doc comments from overridden methods!

toolkit/taglets/Taglet.java
41,143:
If you think "tag" refers to instances in doc comments, the original was 
correct
If you think "tag" refers to the class of the instances, the new text 
should use "the block tag"
142: consider remove "all" from end of line

-- Jon

-------------- next part --------------
An HTML attachment was scrubbed...
URL: 

From pavel.rappo at oracle.com  Mon Aug 17 12:30:47 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Mon, 17 Aug 2020 13:30:47 +0100
Subject: RFR [16] 8251550: Clean up jdk.javadoc and the related parts of
 jdk.compiler
In-Reply-To: 
References: <680444AC-6DD8-49CF-9B3D-D71A2AD6B4C1@oracle.com>
 
Message-ID: <006C3BFB-A553-45B8-828E-190F1A39D46F@oracle.com>

Thanks for having a good look at it, Jon. My replies are inline.

> On 14 Aug 2020, at 17:49, Jonathan Gibbons  wrote:
> 
> Good cleanup.
> 
> Some systemic changes needed. Details below.
> 
> -- Jon
> 
> On 8/13/20 11:48 AM, Pavel Rappo wrote:
>> Hello,
>> 
>> Please review the below change for 
>> https://bugs.openjdk.java.net/browse/JDK-8251550
>> 
>> 
>>   
>> http://cr.openjdk.java.net/~prappo/8251550/webrev.00/
>> 
>> 
>> This represents squashed commits that have accumulated in my git branch. Since the changeset has started to look dangerously big, I decided not to wait until we finish the migration to Git and GitHub, and push it sooner. The less the others have to merge, the better.
>> 
>> -Pavel
>> 
>> 
> 
> 
> Some of the doctree changes contain this sequence:
> 
>     

>     
> 
> That will trigger a doccheck warning for a redundant 
 tag.

Fixed.

> Since you're improving the doc comments for the DocTree nodes, it would be nice to use ... or (better) ,,, around the variables in the templates.  For example:
> 
>   34  * 
>   35  *    @author name-text
>   36  * 

> 
>   37  *

Understood. However, for now I would prefer consistency (with the interfaces of the com.sun.source.tree package) over further improvement.

> DocRootTree:
> 
> I think you need {@literal ...} on line 33.

Why? The doc comment uses an HTML entity, not a naked "@" symbol:

    * 

    * 
    *    {@docroot}
    * 


Are you looking at the actual *diff* rather than at a *view* of the webrev? Webrev is infamous for producing a certain type of illusions.

> DocTypeTree:
> As an enhancement, given that the tools only support HTML 5 these days, It might be helpful to give the specific text for an HTML 5 document
> 
>   32  * 
> 
>   33  *    <!doctype text>
> 
>   34  * 

>     + * For HTML5 documents, the correct form is  {@code }.

Added the proposed line.

> EntityTree:
> Maybe remove the "misleading" spaces in the examples?

Removed the spaces.

> General:
> 
> Thinking aloud, for a future update when we have the `{@spec}` tag. In the introductory sentence for each tag, replace the use of `{@code}` by `{@spec}` linking to the right place in the doc-comment tag specification. I guess for many, it's not necessary, but the idea came to mind reading IndexTree, where more information may be helpful. That being said, additional info belongs in the tag spec, not the tree node spec.

Agreed.

> DocSourcePositions:57,89
> replace `CompilationUnit` with `compilation unit`

Replaced.

> DocTreeFactory:112
> We are inconsistent about whether to use `{..}` for inline tags, which will be worse when we add our first bimodal standard tag, `@return`, but using `{...}` for `{@deprecated}` is definitely wrong

Yes, I have that thought too. I fixed "@deprecated" along with other block tags in DocTreeFactory.java. On the other hand, I added missing curly braces around "@summary".

> General: (question)
> Does a trailing space inside `{@code something }` cause extra whitespace in the rendered HTML?

Yes, it does. I removed those *outer* trailing whitespace characters.

> DocTreePath:37,96,98,99
> More un-code-d type names. Follow existing conventions for either using `{@code...}` or the descriptive equivalent (e.g. "tree path")

@code-d those and some others.

> Trees:239,240
> replace "The" by "the"

Replaced there and in one other place.

> remove package name from TypeMirror, and use @code for that and ErrorType

Removed the package, but will NOT do the rest: it would be completely inconsistent with everything else in that file.

> DocCommentParser:
> avoid Latin abbreviations; use "for example, such as"

Fixed. Although, I don't get the rationale behind this piece of advice. One reason not to use any abbreviations would be the period characters: periods interfere with detecting first sentences in doc comments.

> 1103: another candidate for `{@spec}` !!

Yes. I just felt I have to provide something more fresh and immediately accessible.

> Pretty: removing import
> In general, this is a dangerous edit; throughout javac, you will see imports of javac.util.List in preference to java.util.List. I assume you have compiled and run the tests, to validate this change.

Correct, before posting the initial webrev I ran the tiers 1 through 3 in our CI. It was fine.

> WriterFactory:135
> Trailing period.

Removed there and in some other places.

> BaseTaglet
> Yay for removing redundant doc comments from overridden methods!
> 
> toolkit/taglets/Taglet.java
> 41,143: 
> If you think "tag" refers to instances in doc comments, the original was correct
> If you think "tag" refers to the class of the instances, the new text should use "the block tag"

Those terms have to be better defined in the spec.

> 142: consider remove "all" from end of line

Removed.

-Pavel

> -- Jon
> 


From pavel.rappo at oracle.com  Mon Aug 17 13:01:23 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Mon, 17 Aug 2020 14:01:23 +0100
Subject: RFR [16] 8251550: Clean up jdk.javadoc and the related parts of
 jdk.compiler
In-Reply-To: <006C3BFB-A553-45B8-828E-190F1A39D46F@oracle.com>
References: <680444AC-6DD8-49CF-9B3D-D71A2AD6B4C1@oracle.com>
 
 <006C3BFB-A553-45B8-828E-190F1A39D46F@oracle.com>
Message-ID: <93487E20-58B5-4487-89B6-4D76975156A5@oracle.com>

I forgot to add the link to the new webrev. Here it is:

    http://cr.openjdk.java.net/~prappo/8251550/webrev.01/

> On 17 Aug 2020, at 13:30, Pavel Rappo  wrote:
> 
> Thanks for having a good look at it, Jon. My replies are inline.
> 
>> On 14 Aug 2020, at 17:49, Jonathan Gibbons  wrote:
>> 
>> Good cleanup.
>> 
>> Some systemic changes needed. Details below.
>> 
>> -- Jon
>> 
>> On 8/13/20 11:48 AM, Pavel Rappo wrote:
>>> Hello,
>>> 
>>> Please review the below change for 
>>> https://bugs.openjdk.java.net/browse/JDK-8251550
>>> 
>>> 
>>> 
>>> http://cr.openjdk.java.net/~prappo/8251550/webrev.00/
>>> 
>>> 
>>> This represents squashed commits that have accumulated in my git branch. Since the changeset has started to look dangerously big, I decided not to wait until we finish the migration to Git and GitHub, and push it sooner. The less the others have to merge, the better.
>>> 
>>> -Pavel
>>> 
>>> 
>> 
>> 
>> Some of the doctree changes contain this sequence:
>> 
>>    

>>    
>> 
>> That will trigger a doccheck warning for a redundant 
 tag.
> 
> Fixed.
> 
>> Since you're improving the doc comments for the DocTree nodes, it would be nice to use ... or (better) ,,, around the variables in the templates.  For example:
>> 
>>  34  * 
>>  35  *    @author name-text
>>  36  * 

>> 
>>  37  *
> 
> Understood. However, for now I would prefer consistency (with the interfaces of the com.sun.source.tree package) over further improvement.
> 
>> DocRootTree:
>> 
>> I think you need {@literal ...} on line 33.
> 
> Why? The doc comment uses an HTML entity, not a naked "@" symbol:
> 
>    * 

>    * 
>    *    {@docroot}
>    * 

> 
> Are you looking at the actual *diff* rather than at a *view* of the webrev? Webrev is infamous for producing a certain type of illusions.
> 
>> DocTypeTree:
>> As an enhancement, given that the tools only support HTML 5 these days, It might be helpful to give the specific text for an HTML 5 document
>> 
>>  32  * 
>> 
>>  33  *    <!doctype text>
>> 
>>  34  * 

>>    + * For HTML5 documents, the correct form is  {@code }.
> 
> Added the proposed line.
> 
>> EntityTree:
>> Maybe remove the "misleading" spaces in the examples?
> 
> Removed the spaces.
> 
>> General:
>> 
>> Thinking aloud, for a future update when we have the `{@spec}` tag. In the introductory sentence for each tag, replace the use of `{@code}` by `{@spec}` linking to the right place in the doc-comment tag specification. I guess for many, it's not necessary, but the idea came to mind reading IndexTree, where more information may be helpful. That being said, additional info belongs in the tag spec, not the tree node spec.
> 
> Agreed.
> 
>> DocSourcePositions:57,89
>> replace `CompilationUnit` with `compilation unit`
> 
> Replaced.
> 
>> DocTreeFactory:112
>> We are inconsistent about whether to use `{..}` for inline tags, which will be worse when we add our first bimodal standard tag, `@return`, but using `{...}` for `{@deprecated}` is definitely wrong
> 
> Yes, I have that thought too. I fixed "@deprecated" along with other block tags in DocTreeFactory.java. On the other hand, I added missing curly braces around "@summary".
> 
>> General: (question)
>> Does a trailing space inside `{@code something }` cause extra whitespace in the rendered HTML?
> 
> Yes, it does. I removed those *outer* trailing whitespace characters.
> 
>> DocTreePath:37,96,98,99
>> More un-code-d type names. Follow existing conventions for either using `{@code...}` or the descriptive equivalent (e.g. "tree path")
> 
> @code-d those and some others.
> 
>> Trees:239,240
>> replace "The" by "the"
> 
> Replaced there and in one other place.
> 
>> remove package name from TypeMirror, and use @code for that and ErrorType
> 
> Removed the package, but will NOT do the rest: it would be completely inconsistent with everything else in that file.
> 
>> DocCommentParser:
>> avoid Latin abbreviations; use "for example, such as"
> 
> Fixed. Although, I don't get the rationale behind this piece of advice. One reason not to use any abbreviations would be the period characters: periods interfere with detecting first sentences in doc comments.
> 
>> 1103: another candidate for `{@spec}` !!
> 
> Yes. I just felt I have to provide something more fresh and immediately accessible.
> 
>> Pretty: removing import
>> In general, this is a dangerous edit; throughout javac, you will see imports of javac.util.List in preference to java.util.List. I assume you have compiled and run the tests, to validate this change.
> 
> Correct, before posting the initial webrev I ran the tiers 1 through 3 in our CI. It was fine.
> 
>> WriterFactory:135
>> Trailing period.
> 
> Removed there and in some other places.
> 
>> BaseTaglet
>> Yay for removing redundant doc comments from overridden methods!
>> 
>> toolkit/taglets/Taglet.java
>> 41,143: 
>> If you think "tag" refers to instances in doc comments, the original was correct
>> If you think "tag" refers to the class of the instances, the new text should use "the block tag"
> 
> Those terms have to be better defined in the spec.
> 
>> 142: consider remove "all" from end of line
> 
> Removed.
> 
> -Pavel
> 
>> -- Jon


From jonathan.gibbons at oracle.com  Mon Aug 17 14:28:00 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 17 Aug 2020 07:28:00 -0700
Subject: RFR [16] 8251550: Clean up jdk.javadoc and the related parts of
 jdk.compiler
In-Reply-To: <006C3BFB-A553-45B8-828E-190F1A39D46F@oracle.com>
References: <680444AC-6DD8-49CF-9B3D-D71A2AD6B4C1@oracle.com>
 
 <006C3BFB-A553-45B8-828E-190F1A39D46F@oracle.com>
Message-ID: <0d4fde30-28c2-5897-9d73-26be31f99bdb@oracle.com>

I've read your responses, which all look OK.

I'll give the webrev a look as well.

-- Jon

On 8/17/20 5:30 AM, Pavel Rappo wrote:
> Thanks for having a good look at it, Jon. My replies are inline.
>
>> On 14 Aug 2020, at 17:49, Jonathan Gibbons  wrote:
>>
>> Good cleanup.
>>
>> Some systemic changes needed. Details below.
>>
>> -- Jon
>>
>> On 8/13/20 11:48 AM, Pavel Rappo wrote:
>>> Hello,
>>>
>>> Please review the below change for
>>> https://bugs.openjdk.java.net/browse/JDK-8251550
>>>
>>>
>>>    
>>> http://cr.openjdk.java.net/~prappo/8251550/webrev.00/
>>>
>>>
>>> This represents squashed commits that have accumulated in my git branch. Since the changeset has started to look dangerously big, I decided not to wait until we finish the migration to Git and GitHub, and push it sooner. The less the others have to merge, the better.
>>>
>>> -Pavel
>>>
>>>
>>
>> Some of the doctree changes contain this sequence:
>>
>>      

>>      
>>
>> That will trigger a doccheck warning for a redundant 
 tag.
> Fixed.
>
>> Since you're improving the doc comments for the DocTree nodes, it would be nice to use ... or (better) ,,, around the variables in the templates.  For example:
>>
>>    34  * 
>>    35  *    @author name-text
>>    36  * 

>>
>>    37  *
> Understood. However, for now I would prefer consistency (with the interfaces of the com.sun.source.tree package) over further improvement.
>
>> DocRootTree:
>>
>> I think you need {@literal ...} on line 33.
> Why? The doc comment uses an HTML entity, not a naked "@" symbol:
>
>      * 

>      * 
>      *    {@docroot}
>      * 

>
> Are you looking at the actual *diff* rather than at a *view* of the webrev? Webrev is infamous for producing a certain type of illusions.
>
>> DocTypeTree:
>> As an enhancement, given that the tools only support HTML 5 these days, It might be helpful to give the specific text for an HTML 5 document
>>
>>    32  * 
>>
>>    33  *    <!doctype text>
>>
>>    34  * 

>>      + * For HTML5 documents, the correct form is  {@code }.
> Added the proposed line.
>
>> EntityTree:
>> Maybe remove the "misleading" spaces in the examples?
> Removed the spaces.
>
>> General:
>>
>> Thinking aloud, for a future update when we have the `{@spec}` tag. In the introductory sentence for each tag, replace the use of `{@code}` by `{@spec}` linking to the right place in the doc-comment tag specification. I guess for many, it's not necessary, but the idea came to mind reading IndexTree, where more information may be helpful. That being said, additional info belongs in the tag spec, not the tree node spec.
> Agreed.
>
>> DocSourcePositions:57,89
>> replace `CompilationUnit` with `compilation unit`
> Replaced.
>
>> DocTreeFactory:112
>> We are inconsistent about whether to use `{..}` for inline tags, which will be worse when we add our first bimodal standard tag, `@return`, but using `{...}` for `{@deprecated}` is definitely wrong
> Yes, I have that thought too. I fixed "@deprecated" along with other block tags in DocTreeFactory.java. On the other hand, I added missing curly braces around "@summary".
>
>> General: (question)
>> Does a trailing space inside `{@code something }` cause extra whitespace in the rendered HTML?
> Yes, it does. I removed those *outer* trailing whitespace characters.
>
>> DocTreePath:37,96,98,99
>> More un-code-d type names. Follow existing conventions for either using `{@code...}` or the descriptive equivalent (e.g. "tree path")
> @code-d those and some others.
>
>> Trees:239,240
>> replace "The" by "the"
> Replaced there and in one other place.
>
>> remove package name from TypeMirror, and use @code for that and ErrorType
> Removed the package, but will NOT do the rest: it would be completely inconsistent with everything else in that file.
>
>> DocCommentParser:
>> avoid Latin abbreviations; use "for example, such as"
> Fixed. Although, I don't get the rationale behind this piece of advice. One reason not to use any abbreviations would be the period characters: periods interfere with detecting first sentences in doc comments.
>
>> 1103: another candidate for `{@spec}` !!
> Yes. I just felt I have to provide something more fresh and immediately accessible.
>
>> Pretty: removing import
>> In general, this is a dangerous edit; throughout javac, you will see imports of javac.util.List in preference to java.util.List. I assume you have compiled and run the tests, to validate this change.
> Correct, before posting the initial webrev I ran the tiers 1 through 3 in our CI. It was fine.
>
>> WriterFactory:135
>> Trailing period.
> Removed there and in some other places.
>
>> BaseTaglet
>> Yay for removing redundant doc comments from overridden methods!
>>
>> toolkit/taglets/Taglet.java
>> 41,143:
>> If you think "tag" refers to instances in doc comments, the original was correct
>> If you think "tag" refers to the class of the instances, the new text should use "the block tag"
> Those terms have to be better defined in the spec.
>
>> 142: consider remove "all" from end of line
> Removed.
>
> -Pavel
>
>> -- Jon
>>

From pavel.rappo at oracle.com  Mon Aug 17 15:17:10 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Mon, 17 Aug 2020 16:17:10 +0100
Subject: RFR [16] 8251550: Clean up jdk.javadoc and the related parts of
 jdk.compiler
In-Reply-To: <0d4fde30-28c2-5897-9d73-26be31f99bdb@oracle.com>
References: <680444AC-6DD8-49CF-9B3D-D71A2AD6B4C1@oracle.com>
 
 <006C3BFB-A553-45B8-828E-190F1A39D46F@oracle.com>
 <0d4fde30-28c2-5897-9d73-26be31f99bdb@oracle.com>
Message-ID: <8D6F82E2-205B-4EB5-98D1-72A680B66377@oracle.com>

Thanks Jon. I will wait for you to revert back to me.

Separately, here's one more typo:

@@ -90,7 +90,7 @@ public interface DocSourcePositions extends SourcePositions {
      * @param comment the comment tree that encloses the tree for which the
      *                position is being sought
      * @param tree tree for which a position is sought
-     * @return the start position of tree
+     * @return the end position of tree
      */
     long getEndPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree);

I'll add that to the patch.

-Pavel

> On 17 Aug 2020, at 15:28, Jonathan Gibbons  wrote:
> 
> I've read your responses, which all look OK.
> 
> I'll give the webrev a look as well.
> 
> -- Jon
> 
> On 8/17/20 5:30 AM, Pavel Rappo wrote:
>> Thanks for having a good look at it, Jon. My replies are inline.
>> 
>>> On 14 Aug 2020, at 17:49, Jonathan Gibbons  wrote:
>>> 
>>> Good cleanup.
>>> 
>>> Some systemic changes needed. Details below.
>>> 
>>> -- Jon
>>> 
>>> On 8/13/20 11:48 AM, Pavel Rappo wrote:
>>>> Hello,
>>>> 
>>>> Please review the below change for
>>>> https://bugs.openjdk.java.net/browse/JDK-8251550
>>>> 
>>>> 
>>>>   http://cr.openjdk.java.net/~prappo/8251550/webrev.00/
>>>> 
>>>> 
>>>> This represents squashed commits that have accumulated in my git branch. Since the changeset has started to look dangerously big, I decided not to wait until we finish the migration to Git and GitHub, and push it sooner. The less the others have to merge, the better.
>>>> 
>>>> -Pavel
>>>> 
>>>> 
>>> 
>>> Some of the doctree changes contain this sequence:
>>> 
>>>     

>>>     
>>> 
>>> That will trigger a doccheck warning for a redundant 
 tag.
>> Fixed.
>> 
>>> Since you're improving the doc comments for the DocTree nodes, it would be nice to use ... or (better) ,,, around the variables in the templates.  For example:
>>> 
>>>   34  * 
>>>   35  *    @author name-text
>>>   36  * 

>>> 
>>>   37  *
>> Understood. However, for now I would prefer consistency (with the interfaces of the com.sun.source.tree package) over further improvement.
>> 
>>> DocRootTree:
>>> 
>>> I think you need {@literal ...} on line 33.
>> Why? The doc comment uses an HTML entity, not a naked "@" symbol:
>> 
>>     * 

>>     * 
>>     *    {@docroot}
>>     * 

>> 
>> Are you looking at the actual *diff* rather than at a *view* of the webrev? Webrev is infamous for producing a certain type of illusions.
>> 
>>> DocTypeTree:
>>> As an enhancement, given that the tools only support HTML 5 these days, It might be helpful to give the specific text for an HTML 5 document
>>> 
>>>   32  * 
>>> 
>>>   33  *    <!doctype text>
>>> 
>>>   34  * 

>>>     + * For HTML5 documents, the correct form is  {@code }.
>> Added the proposed line.
>> 
>>> EntityTree:
>>> Maybe remove the "misleading" spaces in the examples?
>> Removed the spaces.
>> 
>>> General:
>>> 
>>> Thinking aloud, for a future update when we have the `{@spec}` tag. In the introductory sentence for each tag, replace the use of `{@code}` by `{@spec}` linking to the right place in the doc-comment tag specification. I guess for many, it's not necessary, but the idea came to mind reading IndexTree, where more information may be helpful. That being said, additional info belongs in the tag spec, not the tree node spec.
>> Agreed.
>> 
>>> DocSourcePositions:57,89
>>> replace `CompilationUnit` with `compilation unit`
>> Replaced.
>> 
>>> DocTreeFactory:112
>>> We are inconsistent about whether to use `{..}` for inline tags, which will be worse when we add our first bimodal standard tag, `@return`, but using `{...}` for `{@deprecated}` is definitely wrong
>> Yes, I have that thought too. I fixed "@deprecated" along with other block tags in DocTreeFactory.java. On the other hand, I added missing curly braces around "@summary".
>> 
>>> General: (question)
>>> Does a trailing space inside `{@code something }` cause extra whitespace in the rendered HTML?
>> Yes, it does. I removed those *outer* trailing whitespace characters.
>> 
>>> DocTreePath:37,96,98,99
>>> More un-code-d type names. Follow existing conventions for either using `{@code...}` or the descriptive equivalent (e.g. "tree path")
>> @code-d those and some others.
>> 
>>> Trees:239,240
>>> replace "The" by "the"
>> Replaced there and in one other place.
>> 
>>> remove package name from TypeMirror, and use @code for that and ErrorType
>> Removed the package, but will NOT do the rest: it would be completely inconsistent with everything else in that file.
>> 
>>> DocCommentParser:
>>> avoid Latin abbreviations; use "for example, such as"
>> Fixed. Although, I don't get the rationale behind this piece of advice. One reason not to use any abbreviations would be the period characters: periods interfere with detecting first sentences in doc comments.
>> 
>>> 1103: another candidate for `{@spec}` !!
>> Yes. I just felt I have to provide something more fresh and immediately accessible.
>> 
>>> Pretty: removing import
>>> In general, this is a dangerous edit; throughout javac, you will see imports of javac.util.List in preference to java.util.List. I assume you have compiled and run the tests, to validate this change.
>> Correct, before posting the initial webrev I ran the tiers 1 through 3 in our CI. It was fine.
>> 
>>> WriterFactory:135
>>> Trailing period.
>> Removed there and in some other places.
>> 
>>> BaseTaglet
>>> Yay for removing redundant doc comments from overridden methods!
>>> 
>>> toolkit/taglets/Taglet.java
>>> 41,143:
>>> If you think "tag" refers to instances in doc comments, the original was correct
>>> If you think "tag" refers to the class of the instances, the new text should use "the block tag"
>> Those terms have to be better defined in the spec.
>> 
>>> 142: consider remove "all" from end of line
>> Removed.
>> 
>> -Pavel
>> 
>>> -- Jon
>>> 


From jonathan.gibbons at oracle.com  Tue Aug 18 04:09:25 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 17 Aug 2020 21:09:25 -0700
Subject: RFR [16] 8251550: Clean up jdk.javadoc and the related parts of
 jdk.compiler
In-Reply-To: <0d4fde30-28c2-5897-9d73-26be31f99bdb@oracle.com>
References: <680444AC-6DD8-49CF-9B3D-D71A2AD6B4C1@oracle.com>
 
 <006C3BFB-A553-45B8-828E-190F1A39D46F@oracle.com>
 <0d4fde30-28c2-5897-9d73-26be31f99bdb@oracle.com>
Message-ID: 

ErroreousTree:32
delete "a" before "malformed text"

This is good; thanks for doing this.? I still see places where we don't 
use {@code} around type names, or are inconsistent in the HTML 
typography around variables names, arising from the general tension of 
whether to make the presented form more consistent or the source code 
easier to read. But that's a different bikeshed half way down a 
different slippery slope that can wait until another day.

-- Jon

On 8/17/20 7:28 AM, Jonathan Gibbons wrote:
> I've read your responses, which all look OK.
>
> I'll give the webrev a look as well.
>
> -- Jon
>
> On 8/17/20 5:30 AM, Pavel Rappo wrote:
>> Thanks for having a good look at it, Jon. My replies are inline.
>>
>>> On 14 Aug 2020, at 17:49, Jonathan Gibbons 
>>>  wrote:
>>>
>>> Good cleanup.
>>>
>>> Some systemic changes needed. Details below.
>>>
>>> -- Jon
>>>
>>> On 8/13/20 11:48 AM, Pavel Rappo wrote:
>>>> Hello,
>>>>
>>>> Please review the below change for
>>>> https://bugs.openjdk.java.net/browse/JDK-8251550
>>>>
>>>>
>>>> ?? http://cr.openjdk.java.net/~prappo/8251550/webrev.00/
>>>>
>>>>
>>>> This represents squashed commits that have accumulated in my git 
>>>> branch. Since the changeset has started to look dangerously big, I 
>>>> decided not to wait until we finish the migration to Git and 
>>>> GitHub, and push it sooner. The less the others have to merge, the 
>>>> better.
>>>>
>>>> -Pavel
>>>>
>>>>
>>>
>>> Some of the doctree changes contain this sequence:
>>>
>>> ???? 

>>> ???? 
>>>
>>> That will trigger a doccheck warning for a redundant 
 tag.
>> Fixed.
>>
>>> Since you're improving the doc comments for the DocTree nodes, it 
>>> would be nice to use ... or (better) ,,, around 
>>> the variables in the templates.? For example:
>>>
>>> ?? 34? * 
>>> ?? 35? *??? @author name-text
>>> ?? 36? * 

>>>
>>> ?? 37? *
>> Understood. However, for now I would prefer consistency (with the 
>> interfaces of the com.sun.source.tree package) over further improvement.
>>
>>> DocRootTree:
>>>
>>> I think you need {@literal ...} on line 33.
>> Why? The doc comment uses an HTML entity, not a naked "@" symbol:
>>
>> ???? * 

>> ???? * 
>> ???? *??? {@docroot}
>> ???? * 

>>
>> Are you looking at the actual *diff* rather than at a *view* of the 
>> webrev? Webrev is infamous for producing a certain type of illusions.
>>
>>> DocTypeTree:
>>> As an enhancement, given that the tools only support HTML 5 these 
>>> days, It might be helpful to give the specific text for an HTML 5 
>>> document
>>>
>>> ?? 32? * 
>>>
>>> ?? 33? *??? <!doctype text>
>>>
>>> ?? 34? * 

>>> ???? + * For HTML5 documents, the correct form is? {@code >> html>}.
>> Added the proposed line.
>>
>>> EntityTree:
>>> Maybe remove the "misleading" spaces in the examples?
>> Removed the spaces.
>>
>>> General:
>>>
>>> Thinking aloud, for a future update when we have the `{@spec}` tag. 
>>> In the introductory sentence for each tag, replace the use of 
>>> `{@code}` by `{@spec}` linking to the right place in the doc-comment 
>>> tag specification. I guess for many, it's not necessary, but the 
>>> idea came to mind reading IndexTree, where more information may be 
>>> helpful. That being said, additional info belongs in the tag spec, 
>>> not the tree node spec.
>> Agreed.
>>
>>> DocSourcePositions:57,89
>>> replace `CompilationUnit` with `compilation unit`
>> Replaced.
>>
>>> DocTreeFactory:112
>>> We are inconsistent about whether to use `{..}` for inline tags, 
>>> which will be worse when we add our first bimodal standard tag, 
>>> `@return`, but using `{...}` for `{@deprecated}` is definitely wrong
>> Yes, I have that thought too. I fixed "@deprecated" along with other 
>> block tags in DocTreeFactory.java. On the other hand, I added missing 
>> curly braces around "@summary".
>>
>>> General: (question)
>>> Does a trailing space inside `{@code something }` cause extra 
>>> whitespace in the rendered HTML?
>> Yes, it does. I removed those *outer* trailing whitespace characters.
>>
>>> DocTreePath:37,96,98,99
>>> More un-code-d type names. Follow existing conventions for either 
>>> using `{@code...}` or the descriptive equivalent (e.g. "tree path")
>> @code-d those and some others.
>>
>>> Trees:239,240
>>> replace "The" by "the"
>> Replaced there and in one other place.
>>
>>> remove package name from TypeMirror, and use @code for that and 
>>> ErrorType
>> Removed the package, but will NOT do the rest: it would be completely 
>> inconsistent with everything else in that file.
>>
>>> DocCommentParser:
>>> avoid Latin abbreviations; use "for example, such as"
>> Fixed. Although, I don't get the rationale behind this piece of 
>> advice. One reason not to use any abbreviations would be the period 
>> characters: periods interfere with detecting first sentences in doc 
>> comments.
>>
>>> 1103: another candidate for `{@spec}` !!
>> Yes. I just felt I have to provide something more fresh and 
>> immediately accessible.
>>
>>> Pretty: removing import
>>> In general, this is a dangerous edit; throughout javac, you will see 
>>> imports of javac.util.List in preference to java.util.List. I assume 
>>> you have compiled and run the tests, to validate this change.
>> Correct, before posting the initial webrev I ran the tiers 1 through 
>> 3 in our CI. It was fine.
>>
>>> WriterFactory:135
>>> Trailing period.
>> Removed there and in some other places.
>>
>>> BaseTaglet
>>> Yay for removing redundant doc comments from overridden methods!
>>>
>>> toolkit/taglets/Taglet.java
>>> 41,143:
>>> If you think "tag" refers to instances in doc comments, the original 
>>> was correct
>>> If you think "tag" refers to the class of the instances, the new 
>>> text should use "the block tag"
>> Those terms have to be better defined in the spec.
>>
>>> 142: consider remove "all" from end of line
>> Removed.
>>
>> -Pavel
>>
>>> -- Jon
>>>

From pavel.rappo at oracle.com  Tue Aug 18 11:03:35 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Tue, 18 Aug 2020 12:03:35 +0100
Subject: RFR [16] 8251939: Fix copy-paste issues and address TODOs
Message-ID: <79A8B70F-32BA-4468-9E0E-F566216E2532@oracle.com>

Hello,

Please review the below inline patch for https://bugs.openjdk.java.net/browse/JDK-8251939. Although this patch modifies the wording of two public APIs, I don't think it requires a CSR for either of them.

Thanks,
-Pavel


diff --git a/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java b/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java
index ae82c72b4a3..181d0495774 100644
--- a/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java
+++ b/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java
@@ -1,12 +1,12 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle in the LICENSE file that accompanied this code.
  *
  * This code is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@@ -26,21 +26,21 @@
 package com.sun.source.tree;
 
 /**
  * A tree node for a {@code yield} statement.
  *
  * For example:
  * 
  *   yield expression ;
  * 

  *
- * @jls section TODO
+ * @jls 14.21 The yield Statement
  *
  * @since 13
  */
 public interface YieldTree extends StatementTree {
 
     /**
      * Returns the expression for this {@code yield} statement.
      *
      * @return the expression
      */
diff --git a/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java b/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
index 631bac627e0..0ed59fe31b4 100644
--- a/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
+++ b/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
@@ -268,21 +268,21 @@ public class DocTreeScanner implements DocTreeVisitor {
      * @param node  {@inheritDoc}
      * @param p  {@inheritDoc}
      * @return the result of scanning
      */
     @Override
     public R visitIdentifier(IdentifierTree node, P p) {
         return null;
     }
 
     /**
-     * {@inheritDoc} This implementation returns {@code null}.
+     * {@inheritDoc} This implementation scans the children in left to right order.
      *
      * @param node  {@inheritDoc}
      * @param p  {@inheritDoc}
      * @return the result of scanning
      */
     @Override
     public R visitIndex(IndexTree node, P p) {
         R r = scan(node.getSearchTerm(), p);
         r = scanAndReduce(node.getDescription(), p, r);
         return r;
diff --git a/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java b/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java
index 46d173f5ba2..e7cff68e384 100644
--- a/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java
+++ b/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java
@@ -943,21 +943,21 @@ public class TreeScanner implements TreeVisitor {
      * @param node  {@inheritDoc}
      * @param p  {@inheritDoc}
      * @return the result of scanning
      */
     @Override
     public R visitErroneous(ErroneousTree node, P p) {
         return null;
     }
 
     /**
-     * {@inheritDoc} This implementation returns {@code null}.
+     * {@inheritDoc} This implementation scans the children in left to right order.
      *
      * @param node  {@inheritDoc}
      * @param p  {@inheritDoc}
      * @return the result of scanning
      */
     @Override
     public R visitYield(YieldTree node, P p) {
         return scan(node.getValue(), p);
     }
 }


From pavel.rappo at oracle.com  Tue Aug 18 14:38:46 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Tue, 18 Aug 2020 07:38:46 -0700 (PDT)
Subject: RFR [16] 8251939: Fix copy-paste issues and address TODOs
In-Reply-To: <79A8B70F-32BA-4468-9E0E-F566216E2532@oracle.com>
References: <79A8B70F-32BA-4468-9E0E-F566216E2532@oracle.com>
Message-ID: 

Please consider one more copy-paste kind of issue:

diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
index 0374e8e0eec..bfff486ad51 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
@@ -31,6 +31,7 @@ import java.util.Map;
 import com.sun.source.doctree.AttributeTree.ValueKind;
 import com.sun.source.doctree.ErroneousTree;
 import com.sun.source.doctree.UnknownBlockTagTree;
+import com.sun.source.doctree.UnknownInlineTagTree;
 import com.sun.tools.javac.parser.Tokens.Comment;
 import com.sun.tools.javac.tree.DCTree;
 import com.sun.tools.javac.tree.DCTree.DCAttribute;
@@ -303,7 +304,7 @@ public class DocCommentParser {
     /**
      * Read a single inline tag, including its content.
      * Standard tags parse their content appropriately.
-     * Non-standard tags are represented by {@link UnknownBlockTagTree}.
+     * Non-standard tags are represented by {@link UnknownInlineTagTree}.
      * Malformed tags may be returned as {@link ErroneousTree}.
      */
     protected DCTree inlineTag() {

> On 18 Aug 2020, at 12:03, Pavel Rappo  wrote:
> 
> Hello,
> 
> Please review the below inline patch for https://bugs.openjdk.java.net/browse/JDK-8251939. Although this patch modifies the wording of two public APIs, I don't think it requires a CSR for either of them.
> 
> Thanks,
> -Pavel
> 
> 
> diff --git a/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java b/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java
> index ae82c72b4a3..181d0495774 100644
> --- a/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java
> +++ b/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java
> @@ -1,12 +1,12 @@
> /*
> - * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
> + * Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
>  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>  *
>  * This code is free software; you can redistribute it and/or modify it
>  * under the terms of the GNU General Public License version 2 only, as
>  * published by the Free Software Foundation.  Oracle designates this
>  * particular file as subject to the "Classpath" exception as provided
>  * by Oracle in the LICENSE file that accompanied this code.
>  *
>  * This code is distributed in the hope that it will be useful, but WITHOUT
>  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
> @@ -26,21 +26,21 @@
> package com.sun.source.tree;
> 
> /**
>  * A tree node for a {@code yield} statement.
>  *
>  * For example:
>  * 
>  *   yield expression ;
>  * 

>  *
> - * @jls section TODO
> + * @jls 14.21 The yield Statement
>  *
>  * @since 13
>  */
> public interface YieldTree extends StatementTree {
> 
>     /**
>      * Returns the expression for this {@code yield} statement.
>      *
>      * @return the expression
>      */
> diff --git a/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java b/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
> index 631bac627e0..0ed59fe31b4 100644
> --- a/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
> +++ b/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
> @@ -268,21 +268,21 @@ public class DocTreeScanner implements DocTreeVisitor {
>      * @param node  {@inheritDoc}
>      * @param p  {@inheritDoc}
>      * @return the result of scanning
>      */
>     @Override
>     public R visitIdentifier(IdentifierTree node, P p) {
>         return null;
>     }
> 
>     /**
> -     * {@inheritDoc} This implementation returns {@code null}.
> +     * {@inheritDoc} This implementation scans the children in left to right order.
>      *
>      * @param node  {@inheritDoc}
>      * @param p  {@inheritDoc}
>      * @return the result of scanning
>      */
>     @Override
>     public R visitIndex(IndexTree node, P p) {
>         R r = scan(node.getSearchTerm(), p);
>         r = scanAndReduce(node.getDescription(), p, r);
>         return r;
> diff --git a/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java b/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java
> index 46d173f5ba2..e7cff68e384 100644
> --- a/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java
> +++ b/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java
> @@ -943,21 +943,21 @@ public class TreeScanner implements TreeVisitor {
>      * @param node  {@inheritDoc}
>      * @param p  {@inheritDoc}
>      * @return the result of scanning
>      */
>     @Override
>     public R visitErroneous(ErroneousTree node, P p) {
>         return null;
>     }
> 
>     /**
> -     * {@inheritDoc} This implementation returns {@code null}.
> +     * {@inheritDoc} This implementation scans the children in left to right order.
>      *
>      * @param node  {@inheritDoc}
>      * @param p  {@inheritDoc}
>      * @return the result of scanning
>      */
>     @Override
>     public R visitYield(YieldTree node, P p) {
>         return scan(node.getValue(), p);
>     }
> }
> 


From jonathan.gibbons at oracle.com  Tue Aug 18 15:02:31 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 18 Aug 2020 08:02:31 -0700
Subject: RFR [16] 8251939: Fix copy-paste issues and address TODOs
In-Reply-To: 
References: <79A8B70F-32BA-4468-9E0E-F566216E2532@oracle.com>
 
Message-ID: <168f7041-55bd-50ed-9a35-ba0ad414fb7d@oracle.com>

+1

-- Jon

On 8/18/20 7:38 AM, Pavel Rappo wrote:
> Please consider one more copy-paste kind of issue:
>
> diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
> index 0374e8e0eec..bfff486ad51 100644
> --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
> +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
> @@ -31,6 +31,7 @@ import java.util.Map;
>   import com.sun.source.doctree.AttributeTree.ValueKind;
>   import com.sun.source.doctree.ErroneousTree;
>   import com.sun.source.doctree.UnknownBlockTagTree;
> +import com.sun.source.doctree.UnknownInlineTagTree;
>   import com.sun.tools.javac.parser.Tokens.Comment;
>   import com.sun.tools.javac.tree.DCTree;
>   import com.sun.tools.javac.tree.DCTree.DCAttribute;
> @@ -303,7 +304,7 @@ public class DocCommentParser {
>       /**
>        * Read a single inline tag, including its content.
>        * Standard tags parse their content appropriately.
> -     * Non-standard tags are represented by {@link UnknownBlockTagTree}.
> +     * Non-standard tags are represented by {@link UnknownInlineTagTree}.
>        * Malformed tags may be returned as {@link ErroneousTree}.
>        */
>       protected DCTree inlineTag() {
>
>> On 18 Aug 2020, at 12:03, Pavel Rappo  wrote:
>>
>> Hello,
>>
>> Please review the below inline patch for https://bugs.openjdk.java.net/browse/JDK-8251939. Although this patch modifies the wording of two public APIs, I don't think it requires a CSR for either of them.
>>
>> Thanks,
>> -Pavel
>>
>>
>> diff --git a/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java b/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java
>> index ae82c72b4a3..181d0495774 100644
>> --- a/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java
>> +++ b/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java
>> @@ -1,12 +1,12 @@
>> /*
>> - * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
>> + * Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
>>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>>   *
>>   * This code is free software; you can redistribute it and/or modify it
>>   * under the terms of the GNU General Public License version 2 only, as
>>   * published by the Free Software Foundation.  Oracle designates this
>>   * particular file as subject to the "Classpath" exception as provided
>>   * by Oracle in the LICENSE file that accompanied this code.
>>   *
>>   * This code is distributed in the hope that it will be useful, but WITHOUT
>>   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
>> @@ -26,21 +26,21 @@
>> package com.sun.source.tree;
>>
>> /**
>>   * A tree node for a {@code yield} statement.
>>   *
>>   * For example:
>>   * 
>>   *   yield expression ;
>>   * 

>>   *
>> - * @jls section TODO
>> + * @jls 14.21 The yield Statement
>>   *
>>   * @since 13
>>   */
>> public interface YieldTree extends StatementTree {
>>
>>      /**
>>       * Returns the expression for this {@code yield} statement.
>>       *
>>       * @return the expression
>>       */
>> diff --git a/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java b/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
>> index 631bac627e0..0ed59fe31b4 100644
>> --- a/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
>> +++ b/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
>> @@ -268,21 +268,21 @@ public class DocTreeScanner implements DocTreeVisitor {
>>       * @param node  {@inheritDoc}
>>       * @param p  {@inheritDoc}
>>       * @return the result of scanning
>>       */
>>      @Override
>>      public R visitIdentifier(IdentifierTree node, P p) {
>>          return null;
>>      }
>>
>>      /**
>> -     * {@inheritDoc} This implementation returns {@code null}.
>> +     * {@inheritDoc} This implementation scans the children in left to right order.
>>       *
>>       * @param node  {@inheritDoc}
>>       * @param p  {@inheritDoc}
>>       * @return the result of scanning
>>       */
>>      @Override
>>      public R visitIndex(IndexTree node, P p) {
>>          R r = scan(node.getSearchTerm(), p);
>>          r = scanAndReduce(node.getDescription(), p, r);
>>          return r;
>> diff --git a/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java b/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java
>> index 46d173f5ba2..e7cff68e384 100644
>> --- a/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java
>> +++ b/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java
>> @@ -943,21 +943,21 @@ public class TreeScanner implements TreeVisitor {
>>       * @param node  {@inheritDoc}
>>       * @param p  {@inheritDoc}
>>       * @return the result of scanning
>>       */
>>      @Override
>>      public R visitErroneous(ErroneousTree node, P p) {
>>          return null;
>>      }
>>
>>      /**
>> -     * {@inheritDoc} This implementation returns {@code null}.
>> +     * {@inheritDoc} This implementation scans the children in left to right order.
>>       *
>>       * @param node  {@inheritDoc}
>>       * @param p  {@inheritDoc}
>>       * @return the result of scanning
>>       */
>>      @Override
>>      public R visitYield(YieldTree node, P p) {
>>          return scan(node.getValue(), p);
>>      }
>> }
>>

From HANNES.WALLNOEFER at ORACLE.COM  Thu Aug 20 12:47:02 2020
From: HANNES.WALLNOEFER at ORACLE.COM (Hannes Wallnoefer)
Date: Thu, 20 Aug 2020 14:47:02 +0200
Subject: RFR: 8216497: javadoc should auto-link to platform classes
Message-ID: <37E6F40A-BD68-4F70-A21A-3572ACFB0D7D@ORACLE.COM>

Please review:

JBS: https://bugs.openjdk.java.net/browse/JDK-8216497
Webrev: http://cr.openjdk.java.net/~hannesw/8216497/webrev.00/
CSR: https://bugs.openjdk.java.net/browse/JDK-8251181

Most of the new code is added to the Extern class where it fits in quite nicely and can use the existing supporting code for setting up external links.

The default behaviour is to generate links to docs.oracle.com for released versions and download.java.net for prereleases. Platform documentation URLs can be configured using the new --link-platform-properties  option to provide a properties file with URLs pointing to to alternative locations. See the CSR linked above for more details on the new options.

The feature can be disabled using the --no-platform-link option, generating the same output as previously. 

One problem I had to solve was how to handle the transition from prerelease versions to final releases, since the location of the documentation changes in this transition. For obvious reasons we don?t want to make that switch via code change at a time shortly before release.

The way it is done is that we determine if the current javadoc instance is a prerelease version as indicated by the Version returned by BaseConfiguration#getDocletVersion(), and then check whether the release/source version of the current javadoc execution uses the same (latest) version. This means that that only the latest version will ever generate prerelease links (e.g. running current javadoc 16 with source version 15 will generate links to the final release documentation) but I think this is acceptable.

Another issue I spent some time getting right was tests. New releases require a new element-list resource*), so tests have to pick up new releases. On the other hand, we don?t want hundreds of tests to fail when a new release is added, ideally there should be one test  with a clear message. Because of this, when a release is encountered for which no element-list is available a warning is generated instead of an error, and the documentation is generated without platform links as if running with --no-platform-link option. This allows most existing tests to pass and just the new test to fail with a relatively clear message of what is wrong.

*) I also thought about generating the element-list for the current release at build time. It?s quite involved, and we still need to maintain element-lists for older versions, so I?m not sure it?s worth it. 

For existing tests that check output affected by the new option I added  the --no-platform-link option to disable the feature. Otherwise we?d have to update those tests with each new release (or else freeze the tests to use some static release or source version, which we don?t want either).

I updated the CSR to the new code. It also needs to be reviewed.

Thanks,
Hannes