From hannes.wallnoefer at oracle.com  Wed Jan  8 11:31:03 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Wed, 8 Jan 2020 12:31:03 +0100
Subject: RFR: 8220002: Improve anchor definitions in generated files
Message-ID: <B875AC6E-78A3-497C-BE1E-8739F8057D26@oracle.com>

Please review:

JBS: https://bugs.openjdk.java.net/browse/JDK-8220002
Webrev: http://cr.openjdk.java.net/~hannesw/8220002/webrev.01/
API docs: http://cr.openjdk.java.net/~hannesw/8220002/api.01/

In places where a <section> tag is available I always moved the id attribute there instead of the heading. This required a bit more changes in some places, but was necessary to get the anchoring position right (see for example the section and individual member anchors in type pages, both of which are now just right IMO).

This patch should cover all occurrences of <a id=?> tags in generated docs, but there are still dozens in static HTML files. I?ll file a separate issue for those.

Hannes

From jonathan.gibbons at oracle.com  Fri Jan 10 01:10:38 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 9 Jan 2020 17:10:38 -0800
Subject: RFR: 8220002: Improve anchor definitions in generated files
In-Reply-To: <B875AC6E-78A3-497C-BE1E-8739F8057D26@oracle.com>
References: <B875AC6E-78A3-497C-BE1E-8739F8057D26@oracle.com>
Message-ID: <1c0e932c-365a-8d34-6262-575c5cfa6313@oracle.com>

Generally wonderful (i.e generally approved.)

I like the new HtmlTree.setId method and the fluent use at most use 
sites. There were a couple of places that did not use fluent invocation, 
that easily could be updated, but that's not a big deal.? I also like 
the amount of anchor-related code that got simplified or removed.

I'm not entirely convinced the new HtmlTree.SPAN_ID carries it's own 
weight: I agree it is a natural conversion from the previous A_ID, but 
it seems that in some places the id could have been moved onto an 
enclosing node. Not a big deal at this time, especially as changing this 
would affect tests.

There are some places/changes with questionable code, but it was never 
new questionable code; it was code that was previously questionable that 
was being updated or moved.? Now is not really the time to clean stuff 
like that up.

I looked at the generated docs, scanning for instances of "<section". 
Very nice!

-- Jon


On 01/08/2020 03:31 AM, Hannes Walln?fer wrote:
> Please review:
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8220002
> Webrev: http://cr.openjdk.java.net/~hannesw/8220002/webrev.01/
> API docs: http://cr.openjdk.java.net/~hannesw/8220002/api.01/
>
> In places where a <section> tag is available I always moved the id attribute there instead of the heading. This required a bit more changes in some places, but was necessary to get the anchoring position right (see for example the section and individual member anchors in type pages, both of which are now just right IMO).
>
> This patch should cover all occurrences of <a id=?> tags in generated docs, but there are still dozens in static HTML files. I?ll file a separate issue for those.
>
> Hannes


From dawid.weiss at gmail.com  Fri Jan 10 15:12:06 2020
From: dawid.weiss at gmail.com (Dawid Weiss)
Date: Fri, 10 Jan 2020 16:12:06 +0100
Subject: Repeated lint option parsing and difference in behavior
Message-ID: <CAM21Rt_2VhQ0Fxc0dbiBvGGsu_RLayBkXa34HaMSNpRkNuAF+w@mail.gmail.com>

Hello,

I just filed a bug for Lucene [1] but I can't explain why there is a
difference between calling javadoc with several lint options:

javadoc ... -Xdoclint:all -Xdoclint:-missing -Xdoclint:-accessibility

versus aggregating them in one line:

javadoc ... -Xdoclint:all,-missing,-accessibility

It seems to me that the first version disables everything -- none of
the lint options are running (no errors are reported) while the second
version seems to work just fine.

Am I missing something?

Dawid

[1] https://issues.apache.org/jira/browse/LUCENE-9126

From jonathan.gibbons at oracle.com  Fri Jan 10 15:45:38 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 10 Jan 2020 07:45:38 -0800
Subject: Repeated lint option parsing and difference in behavior
In-Reply-To: <CAM21Rt_2VhQ0Fxc0dbiBvGGsu_RLayBkXa34HaMSNpRkNuAF+w@mail.gmail.com>
References: <CAM21Rt_2VhQ0Fxc0dbiBvGGsu_RLayBkXa34HaMSNpRkNuAF+w@mail.gmail.com>
Message-ID: <de2664e7-3917-7e52-8505-0abe5100c68f@oracle.com>

Dawid,

Thanks for reporting this. If this is the case, it is a bug.
I'll investigate and file a bug if necessary.

-- Jon

On 1/10/20 7:12 AM, Dawid Weiss wrote:
> Hello,
>
> I just filed a bug for Lucene [1] but I can't explain why there is a
> difference between calling javadoc with several lint options:
>
> javadoc ... -Xdoclint:all -Xdoclint:-missing -Xdoclint:-accessibility
>
> versus aggregating them in one line:
>
> javadoc ... -Xdoclint:all,-missing,-accessibility
>
> It seems to me that the first version disables everything -- none of
> the lint options are running (no errors are reported) while the second
> version seems to work just fine.
>
> Am I missing something?
>
> Dawid
>
> [1] https://issues.apache.org/jira/browse/LUCENE-9126

From jonathan.gibbons at oracle.com  Fri Jan 10 22:43:15 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 10 Jan 2020 14:43:15 -0800
Subject: Repeated lint option parsing and difference in behavior
In-Reply-To: <de2664e7-3917-7e52-8505-0abe5100c68f@oracle.com>
References: <CAM21Rt_2VhQ0Fxc0dbiBvGGsu_RLayBkXa34HaMSNpRkNuAF+w@mail.gmail.com>
 <de2664e7-3917-7e52-8505-0abe5100c68f@oracle.com>
Message-ID: <cf7cc1be-eb27-afa6-1bc9-c8d2b057e412@oracle.com>

Filed

https://bugs.openjdk.java.net/browse/JDK-8236949

-- Jon

On 01/10/2020 07:45 AM, Jonathan Gibbons wrote:
> Dawid,
>
> Thanks for reporting this. If this is the case, it is a bug.
> I'll investigate and file a bug if necessary.
>
> -- Jon
>
> On 1/10/20 7:12 AM, Dawid Weiss wrote:
>> Hello,
>>
>> I just filed a bug for Lucene [1] but I can't explain why there is a
>> difference between calling javadoc with several lint options:
>>
>> javadoc ... -Xdoclint:all -Xdoclint:-missing -Xdoclint:-accessibility
>>
>> versus aggregating them in one line:
>>
>> javadoc ... -Xdoclint:all,-missing,-accessibility
>>
>> It seems to me that the first version disables everything -- none of
>> the lint options are running (no errors are reported) while the second
>> version seems to work just fine.
>>
>> Am I missing something?
>>
>> Dawid
>>
>> [1] https://issues.apache.org/jira/browse/LUCENE-9126


From jonathan.gibbons at oracle.com  Sun Jan 12 16:43:30 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Sun, 12 Jan 2020 08:43:30 -0800
Subject: Repeated lint option parsing and difference in behavior
In-Reply-To: <CAM21Rt-Ep=T9O-gShzBQm70EZP7ORtWFgN22W5ap7fomPtENRA@mail.gmail.com>
References: <CAM21Rt_2VhQ0Fxc0dbiBvGGsu_RLayBkXa34HaMSNpRkNuAF+w@mail.gmail.com>
 <de2664e7-3917-7e52-8505-0abe5100c68f@oracle.com>
 <cf7cc1be-eb27-afa6-1bc9-c8d2b057e412@oracle.com>
 <CAM21Rt-zHGFCdRcbJ3n6HfR1H8yrrRqaS88sgwy4TYFEd_CY=Q@mail.gmail.com>
 <CAM21Rt-Ep=T9O-gShzBQm70EZP7ORtWFgN22W5ap7fomPtENRA@mail.gmail.com>
Message-ID: <56cef729-e6f5-b4ef-0559-a8f11c72dcbc@oracle.com>

Yes, that is as I would expect. Much of the code was rewritten in JDK 9.

As for backports, the first job is to fix the latest version. It's a 
separate decision whether it should be backported.

-- Jon


On 1/11/20 6:50 AM, Dawid Weiss wrote:
> For the record -- Java 8 works as expected, Java 9 and on does not.
>
> Dawid
>
> On Sat, Jan 11, 2020 at 3:41 PM Dawid Weiss <dawid.weiss at gmail.com> wrote:
>> Thank you, Jon.
>>
>>  From what I can see on github this buggy scenario is fairly common...
>> I checked with Java 11 on and it's present in all versions up to the
>> most recent one. Should it be backported to LTS releases?
>>
>> Dawid
>>
>> On Fri, Jan 10, 2020 at 11:43 PM Jonathan Gibbons
>> <jonathan.gibbons at oracle.com> wrote:
>>> Filed
>>>
>>> https://bugs.openjdk.java.net/browse/JDK-8236949
>>>
>>> -- Jon
>>>
>>> On 01/10/2020 07:45 AM, Jonathan Gibbons wrote:
>>>> Dawid,
>>>>
>>>> Thanks for reporting this. If this is the case, it is a bug.
>>>> I'll investigate and file a bug if necessary.
>>>>
>>>> -- Jon
>>>>
>>>> On 1/10/20 7:12 AM, Dawid Weiss wrote:
>>>>> Hello,
>>>>>
>>>>> I just filed a bug for Lucene [1] but I can't explain why there is a
>>>>> difference between calling javadoc with several lint options:
>>>>>
>>>>> javadoc ... -Xdoclint:all -Xdoclint:-missing -Xdoclint:-accessibility
>>>>>
>>>>> versus aggregating them in one line:
>>>>>
>>>>> javadoc ... -Xdoclint:all,-missing,-accessibility
>>>>>
>>>>> It seems to me that the first version disables everything -- none of
>>>>> the lint options are running (no errors are reported) while the second
>>>>> version seems to work just fine.
>>>>>
>>>>> Am I missing something?
>>>>>
>>>>> Dawid
>>>>>
>>>>> [1] https://issues.apache.org/jira/browse/LUCENE-9126

From dawid.weiss at gmail.com  Sat Jan 11 14:41:38 2020
From: dawid.weiss at gmail.com (Dawid Weiss)
Date: Sat, 11 Jan 2020 15:41:38 +0100
Subject: Repeated lint option parsing and difference in behavior
In-Reply-To: <cf7cc1be-eb27-afa6-1bc9-c8d2b057e412@oracle.com>
References: <CAM21Rt_2VhQ0Fxc0dbiBvGGsu_RLayBkXa34HaMSNpRkNuAF+w@mail.gmail.com>
 <de2664e7-3917-7e52-8505-0abe5100c68f@oracle.com>
 <cf7cc1be-eb27-afa6-1bc9-c8d2b057e412@oracle.com>
Message-ID: <CAM21Rt-zHGFCdRcbJ3n6HfR1H8yrrRqaS88sgwy4TYFEd_CY=Q@mail.gmail.com>

Thank you, Jon.

>From what I can see on github this buggy scenario is fairly common...
I checked with Java 11 on and it's present in all versions up to the
most recent one. Should it be backported to LTS releases?

Dawid

On Fri, Jan 10, 2020 at 11:43 PM Jonathan Gibbons
<jonathan.gibbons at oracle.com> wrote:
>
> Filed
>
> https://bugs.openjdk.java.net/browse/JDK-8236949
>
> -- Jon
>
> On 01/10/2020 07:45 AM, Jonathan Gibbons wrote:
> > Dawid,
> >
> > Thanks for reporting this. If this is the case, it is a bug.
> > I'll investigate and file a bug if necessary.
> >
> > -- Jon
> >
> > On 1/10/20 7:12 AM, Dawid Weiss wrote:
> >> Hello,
> >>
> >> I just filed a bug for Lucene [1] but I can't explain why there is a
> >> difference between calling javadoc with several lint options:
> >>
> >> javadoc ... -Xdoclint:all -Xdoclint:-missing -Xdoclint:-accessibility
> >>
> >> versus aggregating them in one line:
> >>
> >> javadoc ... -Xdoclint:all,-missing,-accessibility
> >>
> >> It seems to me that the first version disables everything -- none of
> >> the lint options are running (no errors are reported) while the second
> >> version seems to work just fine.
> >>
> >> Am I missing something?
> >>
> >> Dawid
> >>
> >> [1] https://issues.apache.org/jira/browse/LUCENE-9126
>

From dawid.weiss at gmail.com  Sat Jan 11 14:50:36 2020
From: dawid.weiss at gmail.com (Dawid Weiss)
Date: Sat, 11 Jan 2020 15:50:36 +0100
Subject: Repeated lint option parsing and difference in behavior
In-Reply-To: <CAM21Rt-zHGFCdRcbJ3n6HfR1H8yrrRqaS88sgwy4TYFEd_CY=Q@mail.gmail.com>
References: <CAM21Rt_2VhQ0Fxc0dbiBvGGsu_RLayBkXa34HaMSNpRkNuAF+w@mail.gmail.com>
 <de2664e7-3917-7e52-8505-0abe5100c68f@oracle.com>
 <cf7cc1be-eb27-afa6-1bc9-c8d2b057e412@oracle.com>
 <CAM21Rt-zHGFCdRcbJ3n6HfR1H8yrrRqaS88sgwy4TYFEd_CY=Q@mail.gmail.com>
Message-ID: <CAM21Rt-Ep=T9O-gShzBQm70EZP7ORtWFgN22W5ap7fomPtENRA@mail.gmail.com>

For the record -- Java 8 works as expected, Java 9 and on does not.

Dawid

On Sat, Jan 11, 2020 at 3:41 PM Dawid Weiss <dawid.weiss at gmail.com> wrote:
>
> Thank you, Jon.
>
> From what I can see on github this buggy scenario is fairly common...
> I checked with Java 11 on and it's present in all versions up to the
> most recent one. Should it be backported to LTS releases?
>
> Dawid
>
> On Fri, Jan 10, 2020 at 11:43 PM Jonathan Gibbons
> <jonathan.gibbons at oracle.com> wrote:
> >
> > Filed
> >
> > https://bugs.openjdk.java.net/browse/JDK-8236949
> >
> > -- Jon
> >
> > On 01/10/2020 07:45 AM, Jonathan Gibbons wrote:
> > > Dawid,
> > >
> > > Thanks for reporting this. If this is the case, it is a bug.
> > > I'll investigate and file a bug if necessary.
> > >
> > > -- Jon
> > >
> > > On 1/10/20 7:12 AM, Dawid Weiss wrote:
> > >> Hello,
> > >>
> > >> I just filed a bug for Lucene [1] but I can't explain why there is a
> > >> difference between calling javadoc with several lint options:
> > >>
> > >> javadoc ... -Xdoclint:all -Xdoclint:-missing -Xdoclint:-accessibility
> > >>
> > >> versus aggregating them in one line:
> > >>
> > >> javadoc ... -Xdoclint:all,-missing,-accessibility
> > >>
> > >> It seems to me that the first version disables everything -- none of
> > >> the lint options are running (no errors are reported) while the second
> > >> version seems to work just fine.
> > >>
> > >> Am I missing something?
> > >>
> > >> Dawid
> > >>
> > >> [1] https://issues.apache.org/jira/browse/LUCENE-9126
> >

From dawid.weiss at gmail.com  Mon Jan 13 17:31:30 2020
From: dawid.weiss at gmail.com (Dawid Weiss)
Date: Mon, 13 Jan 2020 18:31:30 +0100
Subject: Sources read from classpath JARs cause errors during compilation
Message-ID: <CAM21Rt9vMu2HJ3uO5nMgMkmUqri+tgOZhg2F1dDQrO0Q_7Qs6A@mail.gmail.com>

Here is another gem I discovered while porting an ant build to gradle.
Applies to Java 11-14. Say you're compiling class Bat like this:

javadoc -classpath p2.jar -d tmp p3/bat/Bat.java

p2 contains class Baz which Bat imports. Baz in turn has a reference
to a class not on classpath (annotation, for example).

The runtime behavior now forks into two scenarios:

1) p2 contains just Baz.class: compilation succeeds, documentation is generated.

1) p2 contains Baz.class AND Baz.java (sources inside the archive):
javadoc fails with something like this:

Loading source file p3\bat\Bat.java...
Constructing Javadoc information...
O:\repos\lucene-gradle-master\solr\solrj\build\tmp\repro\p2.jar(/baz/Baz.java):3:
error: package bar does not exist
import bar.Bar;
          ^
O:\repos\lucene-gradle-master\solr\solrj\build\tmp\repro\p2.jar(/baz/Baz.java):5:
error: cannot find symbol
@Bar
 ^
  symbol: class Bar
2 errors

Note the error message refers to the source file from classpath (!),
not javadoc's source path.

This causes grief when you don't have control over classpath entries.
In Lucene's case it's this one:

zookeeper-jute-3.5.5.jar(/org/apache/zookeeper/data/Stat.java):23:
error: package org.apache.yetus.audience does not exist
import org.apache.yetus.audience.InterfaceAudience;
                                ^

A repro code for the above is attached to the Lucene issue at [1]
(can't send attachments from gmail).

Dawid

[1] https://issues.apache.org/jira/browse/LUCENE-9132

From jonathan.gibbons at oracle.com  Mon Jan 13 18:56:38 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 13 Jan 2020 10:56:38 -0800
Subject: Sources read from classpath JARs cause errors during compilation
In-Reply-To: <CAM21Rt9vMu2HJ3uO5nMgMkmUqri+tgOZhg2F1dDQrO0Q_7Qs6A@mail.gmail.com>
References: <CAM21Rt9vMu2HJ3uO5nMgMkmUqri+tgOZhg2F1dDQrO0Q_7Qs6A@mail.gmail.com>
Message-ID: <b614a3d8-f8d5-4217-4a98-a402e37480a1@oracle.com>

Dawid,

Hmm, interesting case. Thanks for reporting, complete with a description 
of the stripped down test-case.

For what it's worth, this looks like a javac issue more than a javadoc 
issue, because for the most part, javadoc delegates path handling and 
source/class loading to javac.

-- Jon



On 01/13/2020 09:31 AM, Dawid Weiss wrote:
> Here is another gem I discovered while porting an ant build to gradle.
> Applies to Java 11-14. Say you're compiling class Bat like this:
>
> javadoc -classpath p2.jar -d tmp p3/bat/Bat.java
>
> p2 contains class Baz which Bat imports. Baz in turn has a reference
> to a class not on classpath (annotation, for example).
>
> The runtime behavior now forks into two scenarios:
>
> 1) p2 contains just Baz.class: compilation succeeds, documentation is generated.
>
> 1) p2 contains Baz.class AND Baz.java (sources inside the archive):
> javadoc fails with something like this:
>
> Loading source file p3\bat\Bat.java...
> Constructing Javadoc information...
> O:\repos\lucene-gradle-master\solr\solrj\build\tmp\repro\p2.jar(/baz/Baz.java):3:
> error: package bar does not exist
> import bar.Bar;
>            ^
> O:\repos\lucene-gradle-master\solr\solrj\build\tmp\repro\p2.jar(/baz/Baz.java):5:
> error: cannot find symbol
> @Bar
>   ^
>    symbol: class Bar
> 2 errors
>
> Note the error message refers to the source file from classpath (!),
> not javadoc's source path.
>
> This causes grief when you don't have control over classpath entries.
> In Lucene's case it's this one:
>
> zookeeper-jute-3.5.5.jar(/org/apache/zookeeper/data/Stat.java):23:
> error: package org.apache.yetus.audience does not exist
> import org.apache.yetus.audience.InterfaceAudience;
>                                  ^
>
> A repro code for the above is attached to the Lucene issue at [1]
> (can't send attachments from gmail).
>
> Dawid
>
> [1] https://issues.apache.org/jira/browse/LUCENE-9132


From jonathan.gibbons at oracle.com  Wed Jan 15 00:23:31 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 14 Jan 2020 16:23:31 -0800
Subject: RFR: JDK-8223536 jdk/javadoc/doclet/MetaTag/MetaTag.java still fails
 when run across midnight
Message-ID: <70713c0c-fde3-fe63-5a83-1fb086f5da64@oracle.com>

Please review a fix for a problem that occurs when a test is run across 
midnight.

Although it is difficult to confirm the root cause, and equally 
difficult to test, the root cause is believed to be a static final 
instance of java.util.Calendar that is used to obtain the date written 
into the generated files, and which is subsequently verified by tests. 
When javadoc is run multiple times in the same JVM, as will occur when 
running the MetaTag.java test, the static final Calendar may be 
initialized to a time that is outside the range checked by the test.

The fix is to replace the static instance by a non-static instance 
created in HtmlConfiguration.

The fix is noreg-hard, because it can only be fully tested by running 
within milliseconds of midnight. It's remarkable that this has actually 
occurred multiple times in productio build/test runs.

-- Jon


JBS: https://bugs.openjdk.java.net/browse/JDK-8223536
Webrev: http://cr.openjdk.java.net/~jjg/8223536/webrev/


From pavel.rappo at oracle.com  Wed Jan 15 13:51:36 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Wed, 15 Jan 2020 13:51:36 +0000
Subject: RFR: JDK-8223536 jdk/javadoc/doclet/MetaTag/MetaTag.java still
 fails when run across midnight
In-Reply-To: <70713c0c-fde3-fe63-5a83-1fb086f5da64@oracle.com>
References: <70713c0c-fde3-fe63-5a83-1fb086f5da64@oracle.com>
Message-ID: <EEB11CB4-7D28-4C31-B8E6-036780F6F3DA@oracle.com>

Three dates are created in succession: (1) `startDate` on MetaTag:103, (2) `startTime` on HtmlConfiguration:265, and `date`
on MetaTag:95. If dates (1) and (3) are equal, we then conclude that (2) must be the same as (1) and (3). If I read the intent correctly, this implication warrants the conditional logic on MetaTag:96.

This looks reasonable, provided we are not concerned with other date sorcery. Maybe one of these days we could switch to the more modern java.time API. Looks good to me.

-Pavel

> On 15 Jan 2020, at 00:23, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Please review a fix for a problem that occurs when a test is run across midnight.
> 
> Although it is difficult to confirm the root cause, and equally difficult to test, the root cause is believed to be a static final instance of java.util.Calendar that is used to obtain the date written into the generated files, and which is subsequently verified by tests. When javadoc is run multiple times in the same JVM, as will occur when running the MetaTag.java test, the static final Calendar may be initialized to a time that is outside the range checked by the test.
> 
> The fix is to replace the static instance by a non-static instance created in HtmlConfiguration.
> 
> The fix is noreg-hard, because it can only be fully tested by running within milliseconds of midnight. It's remarkable that this has actually occurred multiple times in productio build/test runs.
> 
> -- Jon
> 
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8223536
> Webrev: http://cr.openjdk.java.net/~jjg/8223536/webrev/
> 


From Roger.Riggs at oracle.com  Wed Jan 15 14:38:12 2020
From: Roger.Riggs at oracle.com (Roger Riggs)
Date: Wed, 15 Jan 2020 09:38:12 -0500
Subject: RFR: JDK-8223536 jdk/javadoc/doclet/MetaTag/MetaTag.java still
 fails when run across midnight
In-Reply-To: <70713c0c-fde3-fe63-5a83-1fb086f5da64@oracle.com>
References: <70713c0c-fde3-fe63-5a83-1fb086f5da64@oracle.com>
Message-ID: <b2a06243-b2bf-a3c5-1679-ebb6c3a81bcd@oracle.com>

A bold suggestion is to switch to using java.time and move on from the 
legacy java.Date.

On 1/14/20 7:23 PM, Jonathan Gibbons wrote:
> Please review a fix for a problem that occurs when a test is run 
> across midnight.
>
> Although it is difficult to confirm the root cause, and equally 
> difficult to test, the root cause is believed to be a static final 
> instance of java.util.Calendar that is used to obtain the date written 
> into the generated files, and which is subsequently verified by tests. 
> When javadoc is run multiple times in the same JVM, as will occur when 
> running the MetaTag.java test, the static final Calendar may be 
> initialized to a time that is outside the range checked by the test.
>
> The fix is to replace the static instance by a non-static instance 
> created in HtmlConfiguration.
>
> The fix is noreg-hard, because it can only be fully tested by running 
> within milliseconds of midnight. It's remarkable that this has 
> actually occurred multiple times in productio build/test runs.
>
> -- Jon
>
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8223536
> Webrev: http://cr.openjdk.java.net/~jjg/8223536/webrev/
>


From jonathan.gibbons at oracle.com  Wed Jan 15 15:42:09 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 15 Jan 2020 07:42:09 -0800
Subject: RFR: JDK-8223536 jdk/javadoc/doclet/MetaTag/MetaTag.java still
 fails when run across midnight
In-Reply-To: <EEB11CB4-7D28-4C31-B8E6-036780F6F3DA@oracle.com>
References: <70713c0c-fde3-fe63-5a83-1fb086f5da64@oracle.com>
 <EEB11CB4-7D28-4C31-B8E6-036780F6F3DA@oracle.com>
Message-ID: <0f0dbbf7-53ce-17e5-26d8-b6eda2b8f353@oracle.com>

Thanks.

-- Jon

On 1/15/20 5:51 AM, Pavel Rappo wrote:
> Three dates are created in succession: (1) `startDate` on MetaTag:103, (2) `startTime` on HtmlConfiguration:265, and `date`
> on MetaTag:95. If dates (1) and (3) are equal, we then conclude that (2) must be the same as (1) and (3). If I read the intent correctly, this implication warrants the conditional logic on MetaTag:96.
>
> This looks reasonable, provided we are not concerned with other date sorcery. Maybe one of these days we could switch to the more modern java.time API. Looks good to me.
>
> -Pavel
>
>> On 15 Jan 2020, at 00:23, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Please review a fix for a problem that occurs when a test is run across midnight.
>>
>> Although it is difficult to confirm the root cause, and equally difficult to test, the root cause is believed to be a static final instance of java.util.Calendar that is used to obtain the date written into the generated files, and which is subsequently verified by tests. When javadoc is run multiple times in the same JVM, as will occur when running the MetaTag.java test, the static final Calendar may be initialized to a time that is outside the range checked by the test.
>>
>> The fix is to replace the static instance by a non-static instance created in HtmlConfiguration.
>>
>> The fix is noreg-hard, because it can only be fully tested by running within milliseconds of midnight. It's remarkable that this has actually occurred multiple times in productio build/test runs.
>>
>> -- Jon
>>
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8223536
>> Webrev: http://cr.openjdk.java.net/~jjg/8223536/webrev/
>>

From jonathan.gibbons at oracle.com  Wed Jan 15 15:45:49 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 15 Jan 2020 07:45:49 -0800
Subject: RFR: JDK-8223536 jdk/javadoc/doclet/MetaTag/MetaTag.java still
 fails when run across midnight
In-Reply-To: <b2a06243-b2bf-a3c5-1679-ebb6c3a81bcd@oracle.com>
References: <70713c0c-fde3-fe63-5a83-1fb086f5da64@oracle.com>
 <b2a06243-b2bf-a3c5-1679-ebb6c3a81bcd@oracle.com>
Message-ID: <8152e8e6-0a2b-8bb3-aed3-5ec6716f7627@oracle.com>

Roger,

Thanks for the suggestion. The old code used Calendar, but deep down in 
the impl, I see even that used Date.?? Given that the requirements are 
very very low, that the code is not using any Deprecated methods on 
Date, and the difficulty of reliably testing in this area, it seemed 
like staying with Date was "good enough".

-- Jon

On 1/15/20 6:38 AM, Roger Riggs wrote:
> A bold suggestion is to switch to using java.time and move on from the 
> legacy java.Date.
>
> On 1/14/20 7:23 PM, Jonathan Gibbons wrote:
>> Please review a fix for a problem that occurs when a test is run 
>> across midnight.
>>
>> Although it is difficult to confirm the root cause, and equally 
>> difficult to test, the root cause is believed to be a static final 
>> instance of java.util.Calendar that is used to obtain the date 
>> written into the generated files, and which is subsequently verified 
>> by tests. When javadoc is run multiple times in the same JVM, as will 
>> occur when running the MetaTag.java test, the static final Calendar 
>> may be initialized to a time that is outside the range checked by the 
>> test.
>>
>> The fix is to replace the static instance by a non-static instance 
>> created in HtmlConfiguration.
>>
>> The fix is noreg-hard, because it can only be fully tested by running 
>> within milliseconds of midnight. It's remarkable that this has 
>> actually occurred multiple times in productio build/test runs.
>>
>> -- Jon
>>
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8223536
>> Webrev: http://cr.openjdk.java.net/~jjg/8223536/webrev/
>>
>

From hannes.wallnoefer at oracle.com  Wed Jan 15 18:46:29 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Wed, 15 Jan 2020 19:46:29 +0100
Subject: RFR: 8224052: Javadoc doesn't handle non-public intermediate types
 well
Message-ID: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>

Please review: 

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

This is based on Maurizio?s patch, which fixes signatures of instantiated generic methods in javadoc pages. 

What was missing was support for the @throws taglet, which happens to be the only javadoc taglet that actually displays type names. Unfortunately fixing @throws was rather involved. I first had to add getCurrentPageElement() methods in TagletWriter and HtmlDocletWriter to let taglets retrieve the current type element as suggested by Jon on the JBS issue. We then set up a map of type variables to their type substitutes. This seemed like the simplest way to go since there is no fixed correlation between the list of thrown types and @throws tags; tags may be missing, in no particular order etc. 

There was another problem in ThrowsTaglet where Utils.getFullyQualifiedName(Element) was used to keep track of already documented thrown types in ThrowsTaglet. However, this replaces type-variables with the name of the enclosing type, so thrown type vars were not tracked correctly and could be documented multiple times. This is fixed by using Utils.getFullyQualifiedName(Element, boolean) instead and passing false as second argument. 

Finally, as hinted by Jon on JBS, there was a bug where methods inherited from private intermediate classes where not documented. This is also fixed by accepting private types in Utils.isUndocumentedEnclosure(TypeElement).

Another problem I found with methods inherited this way is that they are not included in the search index. I?ll file a new JBS issue for this.

Hannes

From jonathan.gibbons at oracle.com  Wed Jan 15 19:03:06 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 15 Jan 2020 11:03:06 -0800
Subject: RFR: 8224052: Javadoc doesn't handle non-public intermediate
 types well
In-Reply-To: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>
References: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>
Message-ID: <7db4aa26-341e-cdcd-0ba3-3be2111ad4ac@oracle.com>


On 1/15/20 10:46 AM, Hannes Walln?fer wrote:
> Finally, as hinted by Jon on JBS, there was a bug where methods inherited from private intermediate classes where not documented. This is also fixed by accepting private types in Utils.isUndocumentedEnclosure(TypeElement).


I'm not sure this was a bug, just an unexpected behavior. We might need 
to investigate this one a bit more.

-- Jon


From jonathan.gibbons at oracle.com  Wed Jan 15 23:47:45 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 15 Jan 2020 15:47:45 -0800
Subject: RFR: 8224052: Javadoc doesn't handle non-public intermediate
 types well
In-Reply-To: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>
References: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>
Message-ID: <291e9da5-727b-dce5-0ade-8747bdbbb943@oracle.com>

Approved.

For subsequent followup, the following is a pre-existing condition and 
not new to your patch ....
I wonder why alreadyDocumented is a Set<String> ... would it not be 
better as a Set<TypeElement>?
I see it was declared as Set<String> back in JDK 8 javadoc, so it may be 
that this is just "old code" that did not get properly modernized in the 
conversion to the new doclet.

As regards package-private and private intermediate supertypes, in the 
absence of any pre-existing comment to the contrary, your inclusion of 
isPrivate in isUndocumentedEnclosure is morally justifiable, even if it 
is a change in behavior in an absurdly weird corner case that (to the 
best of my knowledge) is undocumented.

-- Jon


On 01/15/2020 10:46 AM, Hannes Walln?fer wrote:
> Please review:
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8224052
> Webrev: http://cr.openjdk.java.net/~hannesw/8224052/webrev.00/
>
> This is based on Maurizio?s patch, which fixes signatures of instantiated generic methods in javadoc pages.
>
> What was missing was support for the @throws taglet, which happens to be the only javadoc taglet that actually displays type names. Unfortunately fixing @throws was rather involved. I first had to add getCurrentPageElement() methods in TagletWriter and HtmlDocletWriter to let taglets retrieve the current type element as suggested by Jon on the JBS issue. We then set up a map of type variables to their type substitutes. This seemed like the simplest way to go since there is no fixed correlation between the list of thrown types and @throws tags; tags may be missing, in no particular order etc.
>
> There was another problem in ThrowsTaglet where Utils.getFullyQualifiedName(Element) was used to keep track of already documented thrown types in ThrowsTaglet. However, this replaces type-variables with the name of the enclosing type, so thrown type vars were not tracked correctly and could be documented multiple times. This is fixed by using Utils.getFullyQualifiedName(Element, boolean) instead and passing false as second argument.
>
> Finally, as hinted by Jon on JBS, there was a bug where methods inherited from private intermediate classes where not documented. This is also fixed by accepting private types in Utils.isUndocumentedEnclosure(TypeElement).
>
> Another problem I found with methods inherited this way is that they are not included in the search index. I?ll file a new JBS issue for this.
>
> Hannes


From jonathan.gibbons at oracle.com  Thu Jan 16 01:14:32 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 15 Jan 2020 17:14:32 -0800
Subject: RFR: 8224052: Javadoc doesn't handle non-public intermediate
 types well
In-Reply-To: <291e9da5-727b-dce5-0ade-8747bdbbb943@oracle.com>
References: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>
 <291e9da5-727b-dce5-0ade-8747bdbbb943@oracle.com>
Message-ID: <6ad4b540-95ed-29d3-3eae-fd607ffc9d46@oracle.com>



On 01/15/2020 03:47 PM, Jonathan Gibbons wrote:
>
> As regards package-private and private intermediate supertypes, in the 
> absence of any pre-existing comment to the contrary, your inclusion of 
> isPrivate in isUndocumentedEnclosure is morally justifiable, even if 
> it is a change in behavior in an absurdly weird corner case that (to 
> the best of my knowledge) is undocumented.

As further justification for this change in behavior to be regarded as a 
bug fix, I note that javac allows access to public methods of private 
intermediate supertypes.? This implies the behavior is required by JLS, 
and so is justification for javadoc documenting the available methods.

Toy files attached, for the record.

-- Jon
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Client.java
Type: text/x-java
Size: 148 bytes
Desc: not available
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200115/9da386de/Client.java>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Demo.java
Type: text/x-java
Size: 341 bytes
Desc: not available
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200115/9da386de/Demo.java>

From sundararajan.athijegannathan at oracle.com  Thu Jan 16 03:03:07 2020
From: sundararajan.athijegannathan at oracle.com (sundararajan.athijegannathan at oracle.com)
Date: Thu, 16 Jan 2020 08:33:07 +0530
Subject: RFR: 8224052: Javadoc doesn't handle non-public intermediate
 types well
In-Reply-To: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>
References: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>
Message-ID: <7e09b4fa-831d-5a03-f963-b648ff66ef08@oracle.com>

Not a review. Just a comment: New test code PrivateGenericParent.java 
misses copyright.

-Sundar

On 16/01/20 12:16 am, Hannes Walln?fer wrote:
> Please review:
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8224052
> Webrev: http://cr.openjdk.java.net/~hannesw/8224052/webrev.00/
>
> This is based on Maurizio?s patch, which fixes signatures of instantiated generic methods in javadoc pages.
>
> What was missing was support for the @throws taglet, which happens to be the only javadoc taglet that actually displays type names. Unfortunately fixing @throws was rather involved. I first had to add getCurrentPageElement() methods in TagletWriter and HtmlDocletWriter to let taglets retrieve the current type element as suggested by Jon on the JBS issue. We then set up a map of type variables to their type substitutes. This seemed like the simplest way to go since there is no fixed correlation between the list of thrown types and @throws tags; tags may be missing, in no particular order etc.
>
> There was another problem in ThrowsTaglet where Utils.getFullyQualifiedName(Element) was used to keep track of already documented thrown types in ThrowsTaglet. However, this replaces type-variables with the name of the enclosing type, so thrown type vars were not tracked correctly and could be documented multiple times. This is fixed by using Utils.getFullyQualifiedName(Element, boolean) instead and passing false as second argument.
>
> Finally, as hinted by Jon on JBS, there was a bug where methods inherited from private intermediate classes where not documented. This is also fixed by accepting private types in Utils.isUndocumentedEnclosure(TypeElement).
>
> Another problem I found with methods inherited this way is that they are not included in the search index. I?ll file a new JBS issue for this.
>
> Hannes

From hannes.wallnoefer at oracle.com  Thu Jan 16 13:42:32 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Thu, 16 Jan 2020 14:42:32 +0100
Subject: RFR: 8224052: Javadoc doesn't handle non-public intermediate
 types well
In-Reply-To: <6ad4b540-95ed-29d3-3eae-fd607ffc9d46@oracle.com>
References: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>
 <291e9da5-727b-dce5-0ade-8747bdbbb943@oracle.com>
 <6ad4b540-95ed-29d3-3eae-fd607ffc9d46@oracle.com>
Message-ID: <C28AEC69-1CFC-4608-95C5-E660CE14C7A9@oracle.com>

Yes, the fact that this is allowed by javac was what lead me to include this in the patch.

Unfortunately the webrev I sent was against JDK 15 instead of 14. I uploaded a new webrev for 14. Merging was straightforward and no changes were required for the code. Only test output had to be adapted to the old HTML anchor style.

http://cr.openjdk.java.net/~hannesw/8224052/webrev.01/

This also adds the copyright header that was missing in the new test file as noted by Sundar.

Hannes


> Am 16.01.2020 um 02:14 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
> 
> 
> 
> On 01/15/2020 03:47 PM, Jonathan Gibbons wrote:
>> 
>> As regards package-private and private intermediate supertypes, in the absence of any pre-existing comment to the contrary, your inclusion of isPrivate in isUndocumentedEnclosure is morally justifiable, even if it is a change in behavior in an absurdly weird corner case that (to the best of my knowledge) is undocumented.
> 
> As further justification for this change in behavior to be regarded as a bug fix, I note that javac allows access to public methods of private intermediate supertypes.  This implies the behavior is required by JLS, and so is justification for javadoc documenting the available methods.
> 
> Toy files attached, for the record.
> 
> -- Jon
> <Client.java><Demo.java>


From jonathan.gibbons at oracle.com  Thu Jan 16 18:37:28 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 16 Jan 2020 10:37:28 -0800
Subject: RFR: 8224052: Javadoc doesn't handle non-public intermediate
 types well
In-Reply-To: <C28AEC69-1CFC-4608-95C5-E660CE14C7A9@oracle.com>
References: <50D0BDE1-E349-43CD-BD16-EBC5B99B4255@oracle.com>
 <291e9da5-727b-dce5-0ade-8747bdbbb943@oracle.com>
 <6ad4b540-95ed-29d3-3eae-fd607ffc9d46@oracle.com>
 <C28AEC69-1CFC-4608-95C5-E660CE14C7A9@oracle.com>
Message-ID: <d8700ebd-eede-d04a-de8a-6fa72dce05f7@oracle.com>

If you can get this in under the wire for 14, go for it.

Otherwise, go for 15.

-- Jon

On 01/16/2020 05:42 AM, Hannes Walln?fer wrote:
> Yes, the fact that this is allowed by javac was what lead me to include this in the patch.
>
> Unfortunately the webrev I sent was against JDK 15 instead of 14. I uploaded a new webrev for 14. Merging was straightforward and no changes were required for the code. Only test output had to be adapted to the old HTML anchor style.
>
> http://cr.openjdk.java.net/~hannesw/8224052/webrev.01/
>
> This also adds the copyright header that was missing in the new test file as noted by Sundar.
>
> Hannes
>
>
>> Am 16.01.2020 um 02:14 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>>
>>
>>
>> On 01/15/2020 03:47 PM, Jonathan Gibbons wrote:
>>> As regards package-private and private intermediate supertypes, in the absence of any pre-existing comment to the contrary, your inclusion of isPrivate in isUndocumentedEnclosure is morally justifiable, even if it is a change in behavior in an absurdly weird corner case that (to the best of my knowledge) is undocumented.
>> As further justification for this change in behavior to be regarded as a bug fix, I note that javac allows access to public methods of private intermediate supertypes.  This implies the behavior is required by JLS, and so is justification for javadoc documenting the available methods.
>>
>> Toy files attached, for the record.
>>
>> -- Jon
>> <Client.java><Demo.java>


From jonathan.gibbons at oracle.com  Thu Jan 16 20:13:52 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 16 Jan 2020 12:13:52 -0800
Subject: RFR CSR: JDK-8237391 Add -Werror option to javadoc
Message-ID: <33bc234f-09f6-379e-1bf9-ca40c00fb32c@oracle.com>

Please review a simple CSR to have javadoc support a new option, 
-Werror, similar to the equivalent javac option.

https://bugs.openjdk.java.net/browse/JDK-8237391

-- Jon


From pavel.rappo at oracle.com  Thu Jan 16 21:35:42 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Thu, 16 Jan 2020 21:35:42 +0000
Subject: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
Message-ID: <C489946A-614F-407A-9C9B-F45F31F9ACAA@oracle.com>

Hello,

Please review the following change for https://bugs.openjdk.java.net/browse/JDK-8236700:

    http://cr.openjdk.java.net/~prappo/8236700/webrev.00/

This change upgrades the JSZip JavaScript library, used in Javadoc Search [1],
to v3.22. I tested this change as follows.

1. Commented out lines 90 through 104 in
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/script.js:

    // if (!moduleSearchIndex) {
    //     createElem(doc, tag, 'module-search-index.js');
    // }
    // if (!packageSearchIndex) {
    //     createElem(doc, tag, 'package-search-index.js');
    // }
    // if (!typeSearchIndex) {
    //     createElem(doc, tag, 'type-search-index.js');
    // }
    // if (!memberSearchIndex) {
    //     createElem(doc, tag, 'member-search-index.js');
    // }
    // if (!tagSearchIndex) {
    //     createElem(doc, tag, 'tag-search-index.js');
    // }

This effectively makes *-search-index.js, the 5 non-zipped index files above,
unavailable. So the search UI is forced to use the zipped files and, therefore,
the JSZip library.
2. Built docs using `make docs`
3. Started a simple HTTP server in build/.../images/docs as there needs to be a
web server to serve the zipped files, via HTTP requests, to the search UI.
4. Cleared the cache of the browser
5. Opened the main docs page, index.html, in the browser and verified that only
the *-search-index.zip files were transferred.
6. Checked that the search UI produced the expected results for typical search
terms such as list, thread, string, stream, etc.
7. Checked the same for a module, package, member, and tag search terms.
This is to make sure that each of the 5 index files are accessed.

Thanks,
-Pavel

--------------------------------------------------------------------------------
[1] https://bugs.openjdk.java.net/browse/JDK-8044243


From jonathan.gibbons at oracle.com  Thu Jan 16 22:53:59 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 16 Jan 2020 14:53:59 -0800
Subject: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
In-Reply-To: <C489946A-614F-407A-9C9B-F45F31F9ACAA@oracle.com>
References: <C489946A-614F-407A-9C9B-F45F31F9ACAA@oracle.com>
Message-ID: <a20ecd25-21f7-04cb-402f-9cbbbc3134e8@oracle.com>

+1


On 01/16/2020 01:35 PM, Pavel Rappo wrote:
> Hello,
>
> Please review the following change for https://bugs.openjdk.java.net/browse/JDK-8236700:
>
>      http://cr.openjdk.java.net/~prappo/8236700/webrev.00/
>
> This change upgrades the JSZip JavaScript library, used in Javadoc Search [1],
> to v3.22. I tested this change as follows.
>
> 1. Commented out lines 90 through 104 in
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/script.js:
>
>      // if (!moduleSearchIndex) {
>      //     createElem(doc, tag, 'module-search-index.js');
>      // }
>      // if (!packageSearchIndex) {
>      //     createElem(doc, tag, 'package-search-index.js');
>      // }
>      // if (!typeSearchIndex) {
>      //     createElem(doc, tag, 'type-search-index.js');
>      // }
>      // if (!memberSearchIndex) {
>      //     createElem(doc, tag, 'member-search-index.js');
>      // }
>      // if (!tagSearchIndex) {
>      //     createElem(doc, tag, 'tag-search-index.js');
>      // }
>
> This effectively makes *-search-index.js, the 5 non-zipped index files above,
> unavailable. So the search UI is forced to use the zipped files and, therefore,
> the JSZip library.
> 2. Built docs using `make docs`
> 3. Started a simple HTTP server in build/.../images/docs as there needs to be a
> web server to serve the zipped files, via HTTP requests, to the search UI.
> 4. Cleared the cache of the browser
> 5. Opened the main docs page, index.html, in the browser and verified that only
> the *-search-index.zip files were transferred.
> 6. Checked that the search UI produced the expected results for typical search
> terms such as list, thread, string, stream, etc.
> 7. Checked the same for a module, package, member, and tag search terms.
> This is to make sure that each of the 5 index files are accessed.
>
> Thanks,
> -Pavel
>
> --------------------------------------------------------------------------------
> [1] https://bugs.openjdk.java.net/browse/JDK-8044243
>


From hannes.wallnoefer at oracle.com  Fri Jan 17 12:00:58 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Fri, 17 Jan 2020 13:00:58 +0100
Subject: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
In-Reply-To: <C489946A-614F-407A-9C9B-F45F31F9ACAA@oracle.com>
References: <C489946A-614F-407A-9C9B-F45F31F9ACAA@oracle.com>
Message-ID: <3F3DCD02-3006-4E1E-AB74-B24F778ABA05@oracle.com>

Looks good. Thanks for the manual testing/checking.

Hannes

> Am 16.01.2020 um 22:35 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
> 
> Hello,
> 
> Please review the following change for https://bugs.openjdk.java.net/browse/JDK-8236700:
> 
>    http://cr.openjdk.java.net/~prappo/8236700/webrev.00/
> 
> This change upgrades the JSZip JavaScript library, used in Javadoc Search [1],
> to v3.22. I tested this change as follows.
> 
> 1. Commented out lines 90 through 104 in
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/script.js:
> 
>    // if (!moduleSearchIndex) {
>    //     createElem(doc, tag, 'module-search-index.js');
>    // }
>    // if (!packageSearchIndex) {
>    //     createElem(doc, tag, 'package-search-index.js');
>    // }
>    // if (!typeSearchIndex) {
>    //     createElem(doc, tag, 'type-search-index.js');
>    // }
>    // if (!memberSearchIndex) {
>    //     createElem(doc, tag, 'member-search-index.js');
>    // }
>    // if (!tagSearchIndex) {
>    //     createElem(doc, tag, 'tag-search-index.js');
>    // }
> 
> This effectively makes *-search-index.js, the 5 non-zipped index files above,
> unavailable. So the search UI is forced to use the zipped files and, therefore,
> the JSZip library.
> 2. Built docs using `make docs`
> 3. Started a simple HTTP server in build/.../images/docs as there needs to be a
> web server to serve the zipped files, via HTTP requests, to the search UI.
> 4. Cleared the cache of the browser
> 5. Opened the main docs page, index.html, in the browser and verified that only
> the *-search-index.zip files were transferred.
> 6. Checked that the search UI produced the expected results for typical search
> terms such as list, thread, string, stream, etc.
> 7. Checked the same for a module, package, member, and tag search terms.
> This is to make sure that each of the 5 index files are accessed.
> 
> Thanks,
> -Pavel
> 
> --------------------------------------------------------------------------------
> [1] https://bugs.openjdk.java.net/browse/JDK-8044243
> 


From pavel.rappo at oracle.com  Fri Jan 17 13:57:12 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Fri, 17 Jan 2020 13:57:12 +0000
Subject: RFR CSR: JDK-8237391 Add -Werror option to javadoc
In-Reply-To: <33bc234f-09f6-379e-1bf9-ca40c00fb32c@oracle.com>
References: <33bc234f-09f6-379e-1bf9-ca40c00fb32c@oracle.com>
Message-ID: <FF46DA6C-C362-4250-A8A2-AAC9C3567ECC@oracle.com>

I like it.

When comparing the wording for the corresponding option for javac I noticed that
it is more vague than that of the proposed for javadoc:

    -Werror  Terminate compilation if warnings occur (javac)
    -Werror: treat warnings as if they were errors (proposed for javadoc)

Does the latter preclude lazy behaviour (i.e. the documenting process terminates
immediately after the first warning occurs)?

It might not be a big deal, especially taking into account that javadoc doesn't
have options such as:

     -Xmaxerrors number
              Set the maximum number of errors to print.

       -Xmaxwarns number
              Set the maximum number of warnings to print.

-Pavel

> On 16 Jan 2020, at 20:13, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Please review a simple CSR to have javadoc support a new option, -Werror, similar to the equivalent javac option.
> 
> https://bugs.openjdk.java.net/browse/JDK-8237391
> 
> -- Jon
> 


From jonathan.gibbons at oracle.com  Fri Jan 17 18:25:03 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 17 Jan 2020 10:25:03 -0800
Subject: RFR CSR: JDK-8237391 Add -Werror option to javadoc
In-Reply-To: <FF46DA6C-C362-4250-A8A2-AAC9C3567ECC@oracle.com>
References: <33bc234f-09f6-379e-1bf9-ca40c00fb32c@oracle.com>
 <FF46DA6C-C362-4250-A8A2-AAC9C3567ECC@oracle.com>
Message-ID: <c6efc7a9-d452-42eb-731b-5d81c59d9acc@oracle.com>

Hi Pavel,

Good feedback.

The javadoc wording was deliberately more vague, because I couldn't 
think of anything accurate and more specific to say. Essentially, we 
just want to convey/enable one bit of info ... you'll get a non-zero 
exit code if any warnings occur.

The "terminate early" barely applies to javadoc, since we don't have the 
same concept of phases as javac. That being said, there is ...

  * Option decoding
  * Read files (using javac)
  * Another other prep in the tool before handing control to the doclet
  * The doclet

 ?The other reason was because I couldn't think of a good word to 
replace "compilation".?? Any suggestions?

The proposed javadoc text does not preclude lazy behavior; it delegates 
to the general rules for errors, for which nothing is specified(!) 
although it is common practice to terminate work "sometime after" the 
diagnostic occurs. Normally, javac continues to the end of the current 
phase, since the check of "should I continue" is done between phases.

Note that javadoc *does* have -Xmaxerrs and -Xmaxwarns, and 
(surprisingly?) they are actually in alignment with javac!

> jjg at jjg-Precision-T7600:/w/jjg/work/jdk.ref$ 
> ./build/linux-x86_64-server-release/images/jdk/bin/javac -X | grep max
> ? -Xmaxerrs <number>?????????? Set the maximum number of errors to print
> ? -Xmaxwarns <number>????????? Set the maximum number of warnings to print
> jjg at jjg-Precision-T7600:/w/jjg/work/jdk.ref$ 
> ./build/linux-x86_64-server-release/images/jdk/bin/javadoc -X | grep max
> ??? -Xmaxerrs <number>
> ????????????????? Set the maximum number of errors to print
> ??? -Xmaxwarns <number>
> ????????????????? Set the maximum number of warnings to print

-- Jon


On 01/17/2020 05:57 AM, Pavel Rappo wrote:
> I like it.
>
> When comparing the wording for the corresponding option for javac I noticed that
> it is more vague than that of the proposed for javadoc:
>
>      -Werror  Terminate compilation if warnings occur (javac)
>      -Werror: treat warnings as if they were errors (proposed for javadoc)
>
> Does the latter preclude lazy behaviour (i.e. the documenting process terminates
> immediately after the first warning occurs)?
>
> It might not be a big deal, especially taking into account that javadoc doesn't
> have options such as:
>
>       -Xmaxerrors number
>                Set the maximum number of errors to print.
>
>         -Xmaxwarns number
>                Set the maximum number of warnings to print.
>
> -Pavel
>
>> On 16 Jan 2020, at 20:13, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Please review a simple CSR to have javadoc support a new option, -Werror, similar to the equivalent javac option.
>>
>> https://bugs.openjdk.java.net/browse/JDK-8237391
>>
>> -- Jon
>>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200117/8ed1bda3/attachment.htm>

From pavel.rappo at oracle.com  Fri Jan 17 19:04:39 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Fri, 17 Jan 2020 19:04:39 +0000
Subject: RFR CSR: JDK-8237391 Add -Werror option to javadoc
In-Reply-To: <c6efc7a9-d452-42eb-731b-5d81c59d9acc@oracle.com>
References: <33bc234f-09f6-379e-1bf9-ca40c00fb32c@oracle.com>
 <FF46DA6C-C362-4250-A8A2-AAC9C3567ECC@oracle.com>
 <c6efc7a9-d452-42eb-731b-5d81c59d9acc@oracle.com>
Message-ID: <2F2FB873-D106-4B86-A048-A9FABA23A524@oracle.com>

Hi Jon,

> On 17 Jan 2020, at 18:25, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Hi Pavel,
> 
> Good feedback.
> 
> The javadoc wording was deliberately more vague, because I couldn't think of anything accurate and more specific to say.  Essentially, we just want to convey/enable one bit of info ... you'll get a non-zero exit code if any warnings occur.

I thought that javac's wording was more vague. The intent is clear though.

> <snip>
> 
> The other reason was because I couldn't think of a good word to replace "compilation".   Any suggestions?

Could (compilation, compiling) map to (documentation, documenting)?
    
    https://www.merriam-webster.com/dictionary/documentation

        1: the act or an instance of furnishing or authenticating with documents

    https://www.merriam-webster.com/dictionary/documenting

> The proposed javadoc text does not preclude lazy behavior; it delegates to the general rules for errors, for which nothing is specified(!) although it is common practice to terminate work "sometime after" the diagnostic occurs. Normally, javac continues to the end of the current phase, since the check of "should I continue" is done between phases.

ok.

> Note that javadoc *does* have -Xmaxerrs and -Xmaxwarns, and (surprisingly?) they are actually in alignment with javac!

Dang! I missed that. Perhaps because I was looking at (sadly, outdated) man
pages, rather than the output of `%tool-name% -X`. In contrast to javadoc's man
page, javac's does provide info about those options.

-Pavel


From jonathan.gibbons at oracle.com  Sat Jan 18 01:51:24 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 17 Jan 2020 17:51:24 -0800
Subject: RFR: [15] JDK-8237492 Reorganize impl of doclet options
Message-ID: <842d95f8-a31d-b1cd-34f3-f11e924c78cb@oracle.com>

Please review a code-cleanup to reorganize the code to handle doclet 
options.

Fundamentally, the change is to move the methods and fields to handle 
option processing from BaseConfiguration and HtmlConfiguration out into 
new abstractions BaseOptions and HtmlOptions.? As such, the dominant 
changes are to these 4 files.

The impact on the rest of the doclet code is just to change where to 
access the values for options: instead of accessing the values directly 
from the *Configuration classes, the values are now obtained from the 
corresponding *Option classes, which are in turn accessed from the 
*Configuration classes. The reference to the Options objects are 
typically cached when there are a large number of usages in the code. In 
a? number of cases, the cache is in a supertype, which reduces the 
visible churn.

I've taken this opportunity to rename the fields for the values of 
options into the standard camelCase convention. And, I've done some 
basic work to clean up comments, although more could be done (later).

Fixing a bunch of spurious warnings uncoverable a real warning, that the 
code was creating a sorted set of incomparable Option objects. This 
changeset also fixes that issue, which mostly just shows up in the 
signatures for internal collections of option objects.

There is no change in functionality here. All the tests pass without 
change, except for one that was tunneling into an impl class, and which 
needed to be updated.

There's probably a similar cleanup coming to the code to handle tool 
options.

-- Jon


JBS: https://bugs.openjdk.java.net/browse/JDK-8237492
Webrev: http://cr.openjdk.java.net/~jjg/8237492/webrev/




From christoph.langer at sap.com  Sat Jan 18 05:58:27 2020
From: christoph.langer at sap.com (Langer, Christoph)
Date: Sat, 18 Jan 2020 05:58:27 +0000
Subject: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
In-Reply-To: <3F3DCD02-3006-4E1E-AB74-B24F778ABA05@oracle.com>
References: <C489946A-614F-407A-9C9B-F45F31F9ACAA@oracle.com>
 <3F3DCD02-3006-4E1E-AB74-B24F778ABA05@oracle.com>
Message-ID: <AM0PR02MB571467A457E62FCB884760618A300@AM0PR02MB5714.eurprd02.prod.outlook.com>

Hi,

I've just seen, that the bug https://bugs.openjdk.java.net/browse/JDK-8236700 is closed. Is it possible to open it up?

Thanks
Christoph

> -----Original Message-----
> From: javadoc-dev <javadoc-dev-bounces at openjdk.java.net> On Behalf Of
> Hannes Walln?fer
> Sent: Freitag, 17. Januar 2020 13:01
> To: Pavel Rappo <pavel.rappo at oracle.com>
> Cc: javadoc-dev <javadoc-dev at openjdk.java.net>
> Subject: Re: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
>
> Looks good. Thanks for the manual testing/checking.
>
> Hannes
>
> > Am 16.01.2020 um 22:35 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
> >
> > Hello,
> >
> > Please review the following change for
> https://bugs.openjdk.java.net/browse/JDK-8236700:
> >
> >    http://cr.openjdk.java.net/~prappo/8236700/webrev.00/
> >
> > This change upgrades the JSZip JavaScript library, used in Javadoc Search
> [1],
> > to v3.22. I tested this change as follows.
> >
> > 1. Commented out lines 90 through 104 in
> >
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resource
> s/script.js:
> >
> >    // if (!moduleSearchIndex) {
> >    //     createElem(doc, tag, 'module-search-index.js');
> >    // }
> >    // if (!packageSearchIndex) {
> >    //     createElem(doc, tag, 'package-search-index.js');
> >    // }
> >    // if (!typeSearchIndex) {
> >    //     createElem(doc, tag, 'type-search-index.js');
> >    // }
> >    // if (!memberSearchIndex) {
> >    //     createElem(doc, tag, 'member-search-index.js');
> >    // }
> >    // if (!tagSearchIndex) {
> >    //     createElem(doc, tag, 'tag-search-index.js');
> >    // }
> >
> > This effectively makes *-search-index.js, the 5 non-zipped index files
> above,
> > unavailable. So the search UI is forced to use the zipped files and,
> therefore,
> > the JSZip library.
> > 2. Built docs using `make docs`
> > 3. Started a simple HTTP server in build/.../images/docs as there needs to
> be a
> > web server to serve the zipped files, via HTTP requests, to the search UI.
> > 4. Cleared the cache of the browser
> > 5. Opened the main docs page, index.html, in the browser and verified that
> only
> > the *-search-index.zip files were transferred.
> > 6. Checked that the search UI produced the expected results for typical
> search
> > terms such as list, thread, string, stream, etc.
> > 7. Checked the same for a module, package, member, and tag search
> terms.
> > This is to make sure that each of the 5 index files are accessed.
> >
> > Thanks,
> > -Pavel
> >
> > --------------------------------------------------------------------------------
> > [1] https://bugs.openjdk.java.net/browse/JDK-8044243
> >


From pavel.rappo at oracle.com  Tue Jan 21 12:24:35 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Tue, 21 Jan 2020 12:24:35 +0000
Subject: RFR: [15] JDK-8237492 Reorganize impl of doclet options
In-Reply-To: <842d95f8-a31d-b1cd-34f3-f11e924c78cb@oracle.com>
References: <842d95f8-a31d-b1cd-34f3-f11e924c78cb@oracle.com>
Message-ID: <F76CBD1F-5B2C-4DCA-9744-5ECF7DE2CC36@oracle.com>

Jon,

I don't have a strong opinion on this refactoring. I will rely on your judgment
and the fact that you know that code well.

My initial reaction was "Isn't it violating the Law of Demeter or something?"
But on a closer look, I understood that it was merely a restructuring action.
What you seem to be doing is trying to compartmentalize that code better.

This refactoring preserves the collocation that exists between the code that
parses the properties and the code that provides these properties for internal
consumption.

1. You have reintroduced a forgotten bounded wildcard to

    public Set<? extends Doclet.Option> getSupportedOptions()

Good. Compatibility-wise this should be benign. Hopefully, no one tries to put
anything into that set, which should be assumed unmodifiable anyway.

2. You consistently used camelCase naming for fields that represent options.
This effectively "unlinks" them from their command-line names, which is not bad.
Fewer possibilities to mess this during (automated) future refactorings if you
ask me.

3. I'm not sure what can be done about that TreeSet on HtmlOptions.java:458.
Statically it operates on a non-comparable type, Doclet.Option.

4. What is the purpose of the BaseOptions.getOptions() method?

5. HtmlConfiguration:170 feels like a debugging leftover. I'm not sure that
this condition is even possible. Could it be an `assert` instead?

6. AbstractMemberWriter's fields `printedSummaryHeader` and `nodepr` seem not to
be used. Can those be deleted?

7. AbstractMemberWriter.java: 385, 603. Those could use the internal (alias)
field `options`.

8. I noticed that BaseConfiguration have many blank lines. Was it done on purpose?

9. Should BaseOptions use 2020 as the second copyright year?

While we are in this area, consider hyphenating "command line" where it is a
compound adjective rather than a noun (possibly, not an exhaustive list):

  * HtmlConfiguration: 54, 56
  * HtmlOptions: 68, 74, 87, 125, 132, 138, 144, 162
  * BaseConfiguration: 396, 693
  * BaseOptions: 178
  * IllegalOptionValue: 32
  * Main: 49, 58, 70, 83
  * javadoc.properties: 94

-Pavel

P.S. Thanks for being super careful and not only updating the javadoc comments
but also the commented out code in SourceToHTMLConverter!

> On 18 Jan 2020, at 01:51, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Please review a code-cleanup to reorganize the code to handle doclet options.
> 
> Fundamentally, the change is to move the methods and fields to handle option processing from BaseConfiguration and HtmlConfiguration out into new abstractions BaseOptions and HtmlOptions.  As such, the dominant changes are to these 4 files.
> 
> The impact on the rest of the doclet code is just to change where to access the values for options: instead of accessing the values directly from the *Configuration classes, the values are now obtained from the corresponding *Option classes, which are in turn accessed from the *Configuration classes. The reference to the Options objects are typically cached when there are a large number of usages in the code. In a  number of cases, the cache is in a supertype, which reduces the visible churn.
> 
> I've taken this opportunity to rename the fields for the values of options into the standard camelCase convention. And, I've done some basic work to clean up comments, although more could be done (later).
> 
> Fixing a bunch of spurious warnings uncoverable a real warning, that the code was creating a sorted set of incomparable Option objects. This changeset also fixes that issue, which mostly just shows up in the signatures for internal collections of option objects.
> 
> There is no change in functionality here. All the tests pass without change, except for one that was tunneling into an impl class, and which needed to be updated.
> 
> There's probably a similar cleanup coming to the code to handle tool options.
> 
> -- Jon
> 
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8237492
> Webrev: http://cr.openjdk.java.net/~jjg/8237492/webrev/
> 
> 
> 


From jonathan.gibbons at oracle.com  Tue Jan 21 15:15:33 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 21 Jan 2020 07:15:33 -0800
Subject: RFR: [15] JDK-8237492 Reorganize impl of doclet options
In-Reply-To: <F76CBD1F-5B2C-4DCA-9744-5ECF7DE2CC36@oracle.com>
References: <842d95f8-a31d-b1cd-34f3-f11e924c78cb@oracle.com>
 <F76CBD1F-5B2C-4DCA-9744-5ECF7DE2CC36@oracle.com>
Message-ID: <6bb151f4-74ba-c3ef-fd1d-59d3eaef5a53@oracle.com>

Pavel,

Thanks for the detailed comments. I'll go through the list and respond 
in detail when I have the code and review in front of me.

I also have in mind some more detailed class-level doc comments for 
BaseOptions and HtmlOptions classes that I will put in the next round.

-- Jon

On 1/21/20 4:24 AM, Pavel Rappo wrote:
> Jon,
>
> I don't have a strong opinion on this refactoring. I will rely on your judgment
> and the fact that you know that code well.
>
> My initial reaction was "Isn't it violating the Law of Demeter or something?"
> But on a closer look, I understood that it was merely a restructuring action.
> What you seem to be doing is trying to compartmentalize that code better.
>
> This refactoring preserves the collocation that exists between the code that
> parses the properties and the code that provides these properties for internal
> consumption.
>
> 1. You have reintroduced a forgotten bounded wildcard to
>
>      public Set<? extends Doclet.Option> getSupportedOptions()
>
> Good. Compatibility-wise this should be benign. Hopefully, no one tries to put
> anything into that set, which should be assumed unmodifiable anyway.
>
> 2. You consistently used camelCase naming for fields that represent options.
> This effectively "unlinks" them from their command-line names, which is not bad.
> Fewer possibilities to mess this during (automated) future refactorings if you
> ask me.
>
> 3. I'm not sure what can be done about that TreeSet on HtmlOptions.java:458.
> Statically it operates on a non-comparable type, Doclet.Option.
>
> 4. What is the purpose of the BaseOptions.getOptions() method?
>
> 5. HtmlConfiguration:170 feels like a debugging leftover. I'm not sure that
> this condition is even possible. Could it be an `assert` instead?
>
> 6. AbstractMemberWriter's fields `printedSummaryHeader` and `nodepr` seem not to
> be used. Can those be deleted?
>
> 7. AbstractMemberWriter.java: 385, 603. Those could use the internal (alias)
> field `options`.
>
> 8. I noticed that BaseConfiguration have many blank lines. Was it done on purpose?
>
> 9. Should BaseOptions use 2020 as the second copyright year?
>
> While we are in this area, consider hyphenating "command line" where it is a
> compound adjective rather than a noun (possibly, not an exhaustive list):
>
>    * HtmlConfiguration: 54, 56
>    * HtmlOptions: 68, 74, 87, 125, 132, 138, 144, 162
>    * BaseConfiguration: 396, 693
>    * BaseOptions: 178
>    * IllegalOptionValue: 32
>    * Main: 49, 58, 70, 83
>    * javadoc.properties: 94
>
> -Pavel
>
> P.S. Thanks for being super careful and not only updating the javadoc comments
> but also the commented out code in SourceToHTMLConverter!
>
>> On 18 Jan 2020, at 01:51, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Please review a code-cleanup to reorganize the code to handle doclet options.
>>
>> Fundamentally, the change is to move the methods and fields to handle option processing from BaseConfiguration and HtmlConfiguration out into new abstractions BaseOptions and HtmlOptions.  As such, the dominant changes are to these 4 files.
>>
>> The impact on the rest of the doclet code is just to change where to access the values for options: instead of accessing the values directly from the *Configuration classes, the values are now obtained from the corresponding *Option classes, which are in turn accessed from the *Configuration classes. The reference to the Options objects are typically cached when there are a large number of usages in the code. In a  number of cases, the cache is in a supertype, which reduces the visible churn.
>>
>> I've taken this opportunity to rename the fields for the values of options into the standard camelCase convention. And, I've done some basic work to clean up comments, although more could be done (later).
>>
>> Fixing a bunch of spurious warnings uncoverable a real warning, that the code was creating a sorted set of incomparable Option objects. This changeset also fixes that issue, which mostly just shows up in the signatures for internal collections of option objects.
>>
>> There is no change in functionality here. All the tests pass without change, except for one that was tunneling into an impl class, and which needed to be updated.
>>
>> There's probably a similar cleanup coming to the code to handle tool options.
>>
>> -- Jon
>>
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237492
>> Webrev: http://cr.openjdk.java.net/~jjg/8237492/webrev/
>>
>>
>>

From jonathan.gibbons at oracle.com  Tue Jan 21 15:26:36 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 21 Jan 2020 07:26:36 -0800
Subject: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
In-Reply-To: <AM0PR02MB571467A457E62FCB884760618A300@AM0PR02MB5714.eurprd02.prod.outlook.com>
References: <C489946A-614F-407A-9C9B-F45F31F9ACAA@oracle.com>
 <3F3DCD02-3006-4E1E-AB74-B24F778ABA05@oracle.com>
 <AM0PR02MB571467A457E62FCB884760618A300@AM0PR02MB5714.eurprd02.prod.outlook.com>
Message-ID: <82c819ba-4504-a6e9-7728-4b4cac63b9bc@oracle.com>

Christoph,

Thanks for asking.? It would have been better for this to have been 
filed as a non-Confidential issue in the first place.

I realize you are probably asking for the purpose of backporting the 
update. Would it work to create a non-Confidential "shadow" issue that 
duplicates the original, that can be used in a backport?

-- Jon

On 1/17/20 9:58 PM, Langer, Christoph wrote:
> Hi,
>
> I've just seen, that the bug https://bugs.openjdk.java.net/browse/JDK-8236700 is closed. Is it possible to open it up?
>
> Thanks
> Christoph
>
>> -----Original Message-----
>> From: javadoc-dev <javadoc-dev-bounces at openjdk.java.net> On Behalf Of
>> Hannes Walln?fer
>> Sent: Freitag, 17. Januar 2020 13:01
>> To: Pavel Rappo <pavel.rappo at oracle.com>
>> Cc: javadoc-dev <javadoc-dev at openjdk.java.net>
>> Subject: Re: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
>>
>> Looks good. Thanks for the manual testing/checking.
>>
>> Hannes
>>
>>> Am 16.01.2020 um 22:35 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
>>>
>>> Hello,
>>>
>>> Please review the following change for
>> https://bugs.openjdk.java.net/browse/JDK-8236700:
>>>     http://cr.openjdk.java.net/~prappo/8236700/webrev.00/
>>>
>>> This change upgrades the JSZip JavaScript library, used in Javadoc Search
>> [1],
>>> to v3.22. I tested this change as follows.
>>>
>>> 1. Commented out lines 90 through 104 in
>>>
>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resource
>> s/script.js:
>>>     // if (!moduleSearchIndex) {
>>>     //     createElem(doc, tag, 'module-search-index.js');
>>>     // }
>>>     // if (!packageSearchIndex) {
>>>     //     createElem(doc, tag, 'package-search-index.js');
>>>     // }
>>>     // if (!typeSearchIndex) {
>>>     //     createElem(doc, tag, 'type-search-index.js');
>>>     // }
>>>     // if (!memberSearchIndex) {
>>>     //     createElem(doc, tag, 'member-search-index.js');
>>>     // }
>>>     // if (!tagSearchIndex) {
>>>     //     createElem(doc, tag, 'tag-search-index.js');
>>>     // }
>>>
>>> This effectively makes *-search-index.js, the 5 non-zipped index files
>> above,
>>> unavailable. So the search UI is forced to use the zipped files and,
>> therefore,
>>> the JSZip library.
>>> 2. Built docs using `make docs`
>>> 3. Started a simple HTTP server in build/.../images/docs as there needs to
>> be a
>>> web server to serve the zipped files, via HTTP requests, to the search UI.
>>> 4. Cleared the cache of the browser
>>> 5. Opened the main docs page, index.html, in the browser and verified that
>> only
>>> the *-search-index.zip files were transferred.
>>> 6. Checked that the search UI produced the expected results for typical
>> search
>>> terms such as list, thread, string, stream, etc.
>>> 7. Checked the same for a module, package, member, and tag search
>> terms.
>>> This is to make sure that each of the 5 index files are accessed.
>>>
>>> Thanks,
>>> -Pavel
>>>
>>> --------------------------------------------------------------------------------
>>> [1] https://bugs.openjdk.java.net/browse/JDK-8044243
>>>

From christoph.langer at sap.com  Tue Jan 21 15:40:08 2020
From: christoph.langer at sap.com (Langer, Christoph)
Date: Tue, 21 Jan 2020 15:40:08 +0000
Subject: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
In-Reply-To: <82c819ba-4504-a6e9-7728-4b4cac63b9bc@oracle.com>
References: <C489946A-614F-407A-9C9B-F45F31F9ACAA@oracle.com>
 <3F3DCD02-3006-4E1E-AB74-B24F778ABA05@oracle.com>
 <AM0PR02MB571467A457E62FCB884760618A300@AM0PR02MB5714.eurprd02.prod.outlook.com>
 <82c819ba-4504-a6e9-7728-4b4cac63b9bc@oracle.com>
Message-ID: <AM0PR02MB57145E18FE5EA40B6862CB1A8A0D0@AM0PR02MB5714.eurprd02.prod.outlook.com>

Hi Jon,

thanks for getting back to me on that one.

You're right, it's about backporting. The problem with closed bugs is, if Oracle backports such an item, the backport would probably be marked confidential by default as well. So OpenJDK wouldn't see the backport and we would miss it. So I fear the only help for us would be if you can open up the bug. Or you can somehow make sure that potential backport items for this become public.

Thanks
Christoph

> -----Original Message-----
> From: Jonathan Gibbons <jonathan.gibbons at oracle.com>
> Sent: Dienstag, 21. Januar 2020 16:27
> To: Langer, Christoph <christoph.langer at sap.com>; Hannes Walln?fer
> <hannes.wallnoefer at oracle.com>; Pavel Rappo <pavel.rappo at oracle.com>
> Cc: javadoc-dev <javadoc-dev at openjdk.java.net>
> Subject: Re: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
> 
> Christoph,
> 
> Thanks for asking.? It would have been better for this to have been
> filed as a non-Confidential issue in the first place.
> 
> I realize you are probably asking for the purpose of backporting the
> update. Would it work to create a non-Confidential "shadow" issue that
> duplicates the original, that can be used in a backport?
> 
> -- Jon
> 
> On 1/17/20 9:58 PM, Langer, Christoph wrote:
> > Hi,
> >
> > I've just seen, that the bug https://bugs.openjdk.java.net/browse/JDK-
> 8236700 is closed. Is it possible to open it up?
> >
> > Thanks
> > Christoph
> >
> >> -----Original Message-----
> >> From: javadoc-dev <javadoc-dev-bounces at openjdk.java.net> On Behalf
> Of
> >> Hannes Walln?fer
> >> Sent: Freitag, 17. Januar 2020 13:01
> >> To: Pavel Rappo <pavel.rappo at oracle.com>
> >> Cc: javadoc-dev <javadoc-dev at openjdk.java.net>
> >> Subject: Re: RFR [15] 8236700: Upgrading JSZip from v3.1.5 to v3.2.2
> >>
> >> Looks good. Thanks for the manual testing/checking.
> >>
> >> Hannes
> >>
> >>> Am 16.01.2020 um 22:35 schrieb Pavel Rappo
> <pavel.rappo at oracle.com>:
> >>>
> >>> Hello,
> >>>
> >>> Please review the following change for
> >> https://bugs.openjdk.java.net/browse/JDK-8236700:
> >>>     http://cr.openjdk.java.net/~prappo/8236700/webrev.00/
> >>>
> >>> This change upgrades the JSZip JavaScript library, used in Javadoc Search
> >> [1],
> >>> to v3.22. I tested this change as follows.
> >>>
> >>> 1. Commented out lines 90 through 104 in
> >>>
> >>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resource
> >> s/script.js:
> >>>     // if (!moduleSearchIndex) {
> >>>     //     createElem(doc, tag, 'module-search-index.js');
> >>>     // }
> >>>     // if (!packageSearchIndex) {
> >>>     //     createElem(doc, tag, 'package-search-index.js');
> >>>     // }
> >>>     // if (!typeSearchIndex) {
> >>>     //     createElem(doc, tag, 'type-search-index.js');
> >>>     // }
> >>>     // if (!memberSearchIndex) {
> >>>     //     createElem(doc, tag, 'member-search-index.js');
> >>>     // }
> >>>     // if (!tagSearchIndex) {
> >>>     //     createElem(doc, tag, 'tag-search-index.js');
> >>>     // }
> >>>
> >>> This effectively makes *-search-index.js, the 5 non-zipped index files
> >> above,
> >>> unavailable. So the search UI is forced to use the zipped files and,
> >> therefore,
> >>> the JSZip library.
> >>> 2. Built docs using `make docs`
> >>> 3. Started a simple HTTP server in build/.../images/docs as there needs
> to
> >> be a
> >>> web server to serve the zipped files, via HTTP requests, to the search UI.
> >>> 4. Cleared the cache of the browser
> >>> 5. Opened the main docs page, index.html, in the browser and verified
> that
> >> only
> >>> the *-search-index.zip files were transferred.
> >>> 6. Checked that the search UI produced the expected results for typical
> >> search
> >>> terms such as list, thread, string, stream, etc.
> >>> 7. Checked the same for a module, package, member, and tag search
> >> terms.
> >>> This is to make sure that each of the 5 index files are accessed.
> >>>
> >>> Thanks,
> >>> -Pavel
> >>>
> >>> --------------------------------------------------------------------------------
> >>> [1] https://bugs.openjdk.java.net/browse/JDK-8044243
> >>>

From jonathan.gibbons at oracle.com  Tue Jan 21 18:55:44 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 21 Jan 2020 10:55:44 -0800
Subject: RFR: [15] JDK-8237492 Reorganize impl of doclet options
In-Reply-To: <F76CBD1F-5B2C-4DCA-9744-5ECF7DE2CC36@oracle.com>
References: <842d95f8-a31d-b1cd-34f3-f11e924c78cb@oracle.com>
 <F76CBD1F-5B2C-4DCA-9744-5ECF7DE2CC36@oracle.com>
Message-ID: <6eb4768a-d1aa-9137-a30b-d4459fbd4eba@oracle.com>

Pavel,

All great feedback, and all points addressed, as described in the 
details inline below.

New webrev, addresses all your comments, adds a couple of class-level 
doc comments
to the two new classes, and fixes a couple of inconsequential spelling 
errors. Otherwise,
no changes in all the other affected files.

http://cr.openjdk.java.net/~jjg/8237492/webrev.01/

-- Jon


On 1/21/20 4:24 AM, Pavel Rappo wrote:
> Jon,
>
> I don't have a strong opinion on this refactoring. I will rely on your judgment
> and the fact that you know that code well.
I know it "well enough". While it would have been possible to do this 
cleanup
when we converted to the new doclet, a significant factor at that time 
was to
minimize cleanup like this, in order to make it easier to review the old
and new code side by side.? With some potential (minor) functional 
improvements
coming for the command-line options, this seems like a good opportunity
to clean up this code.


>
> My initial reaction was "Isn't it violating the Law of Demeter or something?"
> But on a closer look, I understood that it was merely a restructuring action.
> What you seem to be doing is trying to compartmentalize that code better.

Yes, the intent is to improve our acknowledgement of the Law of Demeter!

The ongoing task is to draw lines around parts of the hodge-podge that is
{Base,Html}Configuration, and to pull out those parts into separate, better
defined abstractions.

Another potential cleanup, for another day, is to separate out the 
search index
tables, and any strongly related methods, from HtmlConfiguration into 
another
separate new abstraction.


>
> This refactoring preserves the collocation that exists between the code that
> parses the properties and the code that provides these properties for internal
> consumption.
>
> 1. You have reintroduced a forgotten bounded wildcard to
>
>      public Set<? extends Doclet.Option> getSupportedOptions()
>
> Good. Compatibility-wise this should be benign. Hopefully, no one tries to put
> anything into that set, which should be assumed unmodifiable anyway.

It's only an internal API, and we control the implementations. As they say,
"No public API was affected in the making of this changeset."

I changed to address an issue you make later on ... about a TreeSet
containing non-comparable objects. More on that later on.


>
> 2. You consistently used camelCase naming for fields that represent options.
> This effectively "unlinks" them from their command-line names, which is not bad.
> Fewer possibilities to mess this during (automated) future refactorings if you
> ask me.

The option names are often horrible and do not provide a really good
precedent.

It's tempting to an an informational source-only annotation that identifies
the options that affect each field, but without any checking, such 
annotations
would be little better than comments ... which is why I added comments
to identify the options for each value.


>
> 3. I'm not sure what can be done about that TreeSet on HtmlOptions.java:458.
> Statically it operates on a non-comparable type, Doclet.Option.
Good catch; now fixed. This was the reason I fixed the wildcard you 
mentioned
earlier.? The intent is that the TreeSet was for BaseOptions.Option, which
*are* comparable. I did not go back and complete the signature edits.

>
> 4. What is the purpose of the BaseOptions.getOptions() method?
Another good catch. I thought it would be necessary, to allow the provision
of a covariant override in HtmlOptions, but that logic is flawed, since 
to make
use of the covariant override, you'd have to have an HtmlOptions object
in the first place.
>
> 5. HtmlConfiguration:170 feels like a debugging leftover. I'm not sure that
> this condition is even possible. Could it be an `assert` instead?

My bad; it was a debugging leftover. The condition can arise while in the
process of constructing the BaseOptions supertype of an HtmlOptions object.

>
> 6. AbstractMemberWriter's fields `printedSummaryHeader` and `nodepr` seem not to
> be used. Can those be deleted?

Deleted


>
> 7. AbstractMemberWriter.java: 385, 603. Those could use the internal (alias)
> field `options`.

Yes, while editing the code, by itself, it did not seem worthwhile having
AbstractMemberWriter provide an alias, for just those two instances you
mention ... but it later became useful to provide the alias for the subtypes
of AbstractMemberWriter.

>
> 8. I noticed that BaseConfiguration have many blank lines. Was it done on purpose?
IDE leftovers, from moving content to the new classes. Excessive blank lines
removed.
>
> 9. Should BaseOptions use 2020 as the second copyright year?
I generally update copyrights after a review and before a push, to avoid
spurious changes showing up in the review. But since you have mentioned
it, I will fix the new files.
>
> While we are in this area, consider hyphenating "command line" where it is a
> compound adjective rather than a noun (possibly, not an exhaustive list):
>
>    * HtmlConfiguration: 54, 56
>    * HtmlOptions: 68, 74, 87, 125, 132, 138, 144, 162
>    * BaseConfiguration: 396, 693
>    * BaseOptions: 178
>    * IllegalOptionValue: 32
>    * Main: 49, 58, 70, 83
>    * javadoc.properties: 94
I fixed all instances found by searching for "command line opt"
>
> -Pavel



>
> P.S. Thanks for being super careful and not only updating the javadoc comments
> but also the commented out code in SourceToHTMLConverter!
>
>> On 18 Jan 2020, at 01:51, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Please review a code-cleanup to reorganize the code to handle doclet options.
>>
>> Fundamentally, the change is to move the methods and fields to handle option processing from BaseConfiguration and HtmlConfiguration out into new abstractions BaseOptions and HtmlOptions.  As such, the dominant changes are to these 4 files.
>>
>> The impact on the rest of the doclet code is just to change where to access the values for options: instead of accessing the values directly from the *Configuration classes, the values are now obtained from the corresponding *Option classes, which are in turn accessed from the *Configuration classes. The reference to the Options objects are typically cached when there are a large number of usages in the code. In a  number of cases, the cache is in a supertype, which reduces the visible churn.
>>
>> I've taken this opportunity to rename the fields for the values of options into the standard camelCase convention. And, I've done some basic work to clean up comments, although more could be done (later).
>>
>> Fixing a bunch of spurious warnings uncoverable a real warning, that the code was creating a sorted set of incomparable Option objects. This changeset also fixes that issue, which mostly just shows up in the signatures for internal collections of option objects.
>>
>> There is no change in functionality here. All the tests pass without change, except for one that was tunneling into an impl class, and which needed to be updated.
>>
>> There's probably a similar cleanup coming to the code to handle tool options.
>>
>> -- Jon
>>
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237492
>> Webrev: http://cr.openjdk.java.net/~jjg/8237492/webrev/
>>
>>
>>

From jonathan.gibbons at oracle.com  Tue Jan 21 21:18:21 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 21 Jan 2020 13:18:21 -0800
Subject: RFR: JDK-8237597 Fix typography in comments for Doclet.Option.Kind
Message-ID: <a3fc0add-52c1-6050-65c8-0e37fb6ce095@oracle.com>

Please review a tiny changeset (inline below) to fix the typography in 
some short javadoc comments.

No semantic changes, so no CSR.

-- Jon

JBS: https://bugs.openjdk.java.net/browse/JDK-8237597


diff -r afedfc27878c 
src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java Tue 
Jan 21 18:38:46 2020 +0000
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java Tue 
Jan 21 13:09:24 2020 -0800
@@ -154,11 +154,11 @@
 ????????? * The kind of an option.
 ????????? */
 ???????? enum Kind {
-??????????? /** an extended option, such as those prefixed with -X */
+??????????? /** An extended option, such as those prefixed with {@code 
-X}. */
 ???????????? EXTENDED,
-??????????? /** a standard option */
+??????????? /** A standard option. */
 ???????????? STANDARD,
-??????????? /** an implementation reserved option */
+??????????? /** An implementation-reserved option. */
 ???????????? OTHER;
 ???????? }
 ???? }




From pavel.rappo at oracle.com  Tue Jan 21 22:14:04 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Tue, 21 Jan 2020 22:14:04 +0000
Subject: RFR: JDK-8237597 Fix typography in comments for Doclet.Option.Kind
In-Reply-To: <a3fc0add-52c1-6050-65c8-0e37fb6ce095@oracle.com>
References: <a3fc0add-52c1-6050-65c8-0e37fb6ce095@oracle.com>
Message-ID: <E0D6C3A4-20C7-4230-A41E-008A808DEF2E@oracle.com>

Looks good.

> On 21 Jan 2020, at 21:18, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> ?Please review a tiny changeset (inline below) to fix the typography in some short javadoc comments.
> 
> No semantic changes, so no CSR.
> 
> -- Jon
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8237597
> 
> 
> diff -r afedfc27878c src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java
> --- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java Tue Jan 21 18:38:46 2020 +0000
> +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java Tue Jan 21 13:09:24 2020 -0800
> @@ -154,11 +154,11 @@
>           * The kind of an option.
>           */
>          enum Kind {
> -            /** an extended option, such as those prefixed with -X */
> +            /** An extended option, such as those prefixed with {@code -X}. */
>              EXTENDED,
> -            /** a standard option */
> +            /** A standard option. */
>              STANDARD,
> -            /** an implementation reserved option */
> +            /** An implementation-reserved option. */
>              OTHER;
>          }
>      }
> 
> 
> 


From pavel.rappo at oracle.com  Wed Jan 22 11:58:09 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Wed, 22 Jan 2020 11:58:09 +0000
Subject: RFR [15] 8233795: Consider adding a notion of a Value-based class to
 API Documentation index
Message-ID: <553EA827-AFC7-432B-BB3B-125277E33CEE@oracle.com>

Hello,

Please review the following (documentation) change for https://bugs.openjdk.java.net/browse/JDK-8233795:

   http://cr.openjdk.java.net/~prappo/8233795/webrev.00/

The detailed explanation can be found in the description in the JBS issue. 

Thanks,
-Pavel


From hannes.wallnoefer at oracle.com  Wed Jan 22 13:15:53 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Wed, 22 Jan 2020 14:15:53 +0100
Subject: RFR [15] 8233795: Consider adding a notion of a Value-based class
 to API Documentation index
In-Reply-To: <553EA827-AFC7-432B-BB3B-125277E33CEE@oracle.com>
References: <553EA827-AFC7-432B-BB3B-125277E33CEE@oracle.com>
Message-ID: <AC9D9645-1F7F-42AB-B613-ACB98785138E@oracle.com>

Nice. +1

Hannes


> Am 22.01.2020 um 12:58 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
> 
> Hello,
> 
> Please review the following (documentation) change for https://bugs.openjdk.java.net/browse/JDK-8233795:
> 
>   http://cr.openjdk.java.net/~prappo/8233795/webrev.00/
> 
> The detailed explanation can be found in the description in the JBS issue. 
> 
> Thanks,
> -Pavel
> 


From pavel.rappo at oracle.com  Wed Jan 22 16:00:18 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Wed, 22 Jan 2020 16:00:18 +0000
Subject: RFR: [15] JDK-8237492 Reorganize impl of doclet options
In-Reply-To: <6eb4768a-d1aa-9137-a30b-d4459fbd4eba@oracle.com>
References: <842d95f8-a31d-b1cd-34f3-f11e924c78cb@oracle.com>
 <F76CBD1F-5B2C-4DCA-9744-5ECF7DE2CC36@oracle.com>
 <6eb4768a-d1aa-9137-a30b-d4459fbd4eba@oracle.com>
Message-ID: <10C98B07-CE1B-4993-B9D9-8838FEB9022B@oracle.com>

> On 21 Jan 2020, at 18:55, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Pavel,
> 
> All great feedback, and all points addressed, as described in the details inline below.
> 
> New webrev, addresses all your comments, adds a couple of class-level doc comments
> to the two new classes, and fixes a couple of inconsequential spelling errors. Otherwise,
> no changes in all the other affected files.
> 
> http://cr.openjdk.java.net/~jjg/8237492/webrev.01/

Thanks for patiently addressing my comments. I see this code review as an
opportunity to get familiar with the javadoc code base.

> <snip>
> 
> The ongoing task is to draw lines around parts of the hodge-podge that is
> {Base,Html}Configuration, and to pull out those parts into separate, better
> defined abstractions.

A noble intent.

> <snip>
> 
>> 1. You have reintroduced a forgotten bounded wildcard to
>> 
>>     public Set<? extends Doclet.Option> getSupportedOptions()
>> 
>> Good. Compatibility-wise this should be benign. Hopefully, no one tries to put
>> anything into that set, which should be assumed unmodifiable anyway.
> 
> It's only an internal API, and we control the implementations. As they say,
> "No public API was affected in the making of this changeset."

StandardDoclet is a public SPI. Doclets may extend that class, but it's the
"container" that calls the `getSupportedOptions` method. A corner case where the
client calls `getSupportedOptions` would be an implementation of Doclet that
delegates calls to an internal instance of StandardDoclet:

    public class MyDoclet implements Doclet {

        private final StandardDoclet standardDoclet = new StandardDoclet();

        // ...

        @Override
        public Set<? extends Option> getSupportedOptions() {
            Set<Option> supportedOptions = standardDoclet.getSupportedOptions();
            supportedOptions.add(new MyOption()); // additional option
            // ...
            return supportedOptions;
        }

        private static class MyOption implements Doclet.Option {
            // ...
        }
        // ...
    }

Agreed, this is a somewhat contrived example made for the sake of the argument.

>> 2. You consistently used camelCase naming for fields that represent options.
>> This effectively "unlinks" them from their command-line names, which is not bad.
>> Fewer possibilities to mess this during (automated) future refactorings if you
>> ask me.
> 
> The option names are often horrible and do not provide a really good
> precedent.

Agreed.

> It's tempting to an an informational source-only annotation that identifies
> the options that affect each field, but without any checking, such annotations
> would be little better than comments ... which is why I added comments
> to identify the options for each value.

This could be addressed another way. Instead of having two separate abstractions,
options classes and option fields, we could use a single abstraction, types.

We could use some sort of a container [1]. The downside might be having more
types. A somewhat related design can be seen in java.net.SocketOption API [2].
That latter API tackles the need for more types by relying on option names, yet
still benefits from the type-safety.

That could allow for more collocation of the code related to command-line options.

> <snip>
> 
>> 6. AbstractMemberWriter's fields `printedSummaryHeader` and `nodepr` seem not to
>> be used. Can those be deleted?
> 
> Deleted

The `BaseOptions.docFileDestDirName` field doesn't seem to be accessed from
anywhere. Should it be deleted?

> <snip>
> 
>> While we are in this area, consider hyphenating "command line" where it is a
>> compound adjective rather than a noun (possibly, not an exhaustive list):
>> 
>>   * HtmlConfiguration: 54, 56
>>   * HtmlOptions: 68, 74, 87, 125, 132, 138, 144, 162
>>   * BaseConfiguration: 396, 693
>>   * BaseOptions: 178
>>   * IllegalOptionValue: 32
>>   * Main: 49, 58, 70, 83
>>   * javadoc.properties: 94
> I fixed all instances found by searching for "command line opt"

Thanks!


The below is not a criticism of the refactoring, but rather a commentary on
the current state of affairs.

I don't like that command-line options are represented by public fields that can
be freely accessed from any part of the code. What I find especially unsettling
is that some of the fields of the BaseOptions and HtmlOptions are written from
the outside of those classes. These fields include:

    BaseOptions.docEncoding,
    BaseOptions.javafx,
    HtmlOptions.charset

This field is written *only* from the outside of HtmlOptions:

    HtmlOptions.createOverview

All that points out that Configuration and Options are coupled more tightly than
we may think.

-Pavel

--------------------------------------------------------------------------------
[1] Effective Java, Second Edition by Joshua Bloch,
        Item 29: Consider typesafe heterogeneous containers
[2] See java.net.SocketOption, java.net.StandardSocketOptions,
java.net.Socket.supportedOptions, java.net.Socket.getOption, java.net.Socket.setOption

>> P.S. Thanks for being super careful and not only updating the javadoc comments
>> but also the commented out code in SourceToHTMLConverter!
>> 
>>> On 18 Jan 2020, at 01:51, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>> 
>>> Please review a code-cleanup to reorganize the code to handle doclet options.
>>> 
>>> Fundamentally, the change is to move the methods and fields to handle option processing from BaseConfiguration and HtmlConfiguration out into new abstractions BaseOptions and HtmlOptions.  As such, the dominant changes are to these 4 files.
>>> 
>>> The impact on the rest of the doclet code is just to change where to access the values for options: instead of accessing the values directly from the *Configuration classes, the values are now obtained from the corresponding *Option classes, which are in turn accessed from the *Configuration classes. The reference to the Options objects are typically cached when there are a large number of usages in the code. In a  number of cases, the cache is in a supertype, which reduces the visible churn.
>>> 
>>> I've taken this opportunity to rename the fields for the values of options into the standard camelCase convention. And, I've done some basic work to clean up comments, although more could be done (later).
>>> 
>>> Fixing a bunch of spurious warnings uncoverable a real warning, that the code was creating a sorted set of incomparable Option objects. This changeset also fixes that issue, which mostly just shows up in the signatures for internal collections of option objects.
>>> 
>>> There is no change in functionality here. All the tests pass without change, except for one that was tunneling into an impl class, and which needed to be updated.
>>> 
>>> There's probably a similar cleanup coming to the code to handle tool options.
>>> 
>>> -- Jon
>>> 
>>> 
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237492
>>> Webrev: http://cr.openjdk.java.net/~jjg/8237492/webrev/



From jonathan.gibbons at oracle.com  Wed Jan 22 19:29:16 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 22 Jan 2020 11:29:16 -0800
Subject: RFR: [15] JDK-8237492 Reorganize impl of doclet options
In-Reply-To: <10C98B07-CE1B-4993-B9D9-8838FEB9022B@oracle.com>
References: <842d95f8-a31d-b1cd-34f3-f11e924c78cb@oracle.com>
 <F76CBD1F-5B2C-4DCA-9744-5ECF7DE2CC36@oracle.com>
 <6eb4768a-d1aa-9137-a30b-d4459fbd4eba@oracle.com>
 <10C98B07-CE1B-4993-B9D9-8838FEB9022B@oracle.com>
Message-ID: <48928913-994a-eec1-4876-67edb3e11827@oracle.com>

Pavel,

Thanks for your additional feedback. There's a couple of actionable 
items, most notably
with respect to StandardDoclet.

As for the rest, I agree there's a whole bunch more stuff that we 
*could* do, but I would
prefer to get the work so far staged into the repo. As the ancient 
Roman's used to say,

javadoc was not cleaned up in a single changeset.

-- Jon


On 01/22/2020 08:00 AM, Pavel Rappo wrote:
>> On 21 Jan 2020, at 18:55, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Pavel,
>>
>> All great feedback, and all points addressed, as described in the details inline below.
>>
>> New webrev, addresses all your comments, adds a couple of class-level doc comments
>> to the two new classes, and fixes a couple of inconsequential spelling errors. Otherwise,
>> no changes in all the other affected files.
>>
>> http://cr.openjdk.java.net/~jjg/8237492/webrev.01/
> Thanks for patiently addressing my comments. I see this code review as an
> opportunity to get familiar with the javadoc code base.
>
>> <snip>
>>
>> The ongoing task is to draw lines around parts of the hodge-podge that is
>> {Base,Html}Configuration, and to pull out those parts into separate, better
>> defined abstractions.
> A noble intent.
>
>> <snip>
>>
>>> 1. You have reintroduced a forgotten bounded wildcard to
>>>
>>>      public Set<? extends Doclet.Option> getSupportedOptions()
>>>
>>> Good. Compatibility-wise this should be benign. Hopefully, no one tries to put
>>> anything into that set, which should be assumed unmodifiable anyway.
>> It's only an internal API, and we control the implementations. As they say,
>> "No public API was affected in the making of this changeset."
> StandardDoclet is a public SPI. Doclets may extend that class, but it's the
> "container" that calls the `getSupportedOptions` method. A corner case where the
> client calls `getSupportedOptions` would be an implementation of Doclet that
> delegates calls to an internal instance of StandardDoclet:
>
>      public class MyDoclet implements Doclet {
>
>          private final StandardDoclet standardDoclet = new StandardDoclet();
>
>          // ...
>
>          @Override
>          public Set<? extends Option> getSupportedOptions() {
>              Set<Option> supportedOptions = standardDoclet.getSupportedOptions();
>              supportedOptions.add(new MyOption()); // additional option
>              // ...
>              return supportedOptions;
>          }
>
>          private static class MyOption implements Doclet.Option {
>              // ...
>          }
>          // ...
>      }
>
> Agreed, this is a somewhat contrived example made for the sake of the argument.

You're right; I'd missed that this was a change to StandardDoclet, which 
is a public API.
This will need to be sorted out, separately.

>
>>> 2. You consistently used camelCase naming for fields that represent options.
>>> This effectively "unlinks" them from their command-line names, which is not bad.
>>> Fewer possibilities to mess this during (automated) future refactorings if you
>>> ask me.
>> The option names are often horrible and do not provide a really good
>> precedent.
> Agreed.
>
>> It's tempting to an an informational source-only annotation that identifies
>> the options that affect each field, but without any checking, such annotations
>> would be little better than comments ... which is why I added comments
>> to identify the options for each value.
> This could be addressed another way. Instead of having two separate abstractions,
> options classes and option fields, we could use a single abstraction, types.
>
> We could use some sort of a container [1]. The downside might be having more
> types. A somewhat related design can be seen in java.net.SocketOption API [2].
> That latter API tackles the need for more types by relying on option names, yet
> still benefits from the type-safety.
>
> That could allow for more collocation of the code related to command-line options.

I think this is more than I want to consider for this round of cleanup.

>
>> <snip>
>>
>>> 6. AbstractMemberWriter's fields `printedSummaryHeader` and `nodepr` seem not to
>>> be used. Can those be deleted?
>> Deleted
> The `BaseOptions.docFileDestDirName` field doesn't seem to be accessed from
> anywhere. Should it be deleted?

Yes, will do.

>
>> <snip>
>>
>>> While we are in this area, consider hyphenating "command line" where it is a
>>> compound adjective rather than a noun (possibly, not an exhaustive list):
>>>
>>>    * HtmlConfiguration: 54, 56
>>>    * HtmlOptions: 68, 74, 87, 125, 132, 138, 144, 162
>>>    * BaseConfiguration: 396, 693
>>>    * BaseOptions: 178
>>>    * IllegalOptionValue: 32
>>>    * Main: 49, 58, 70, 83
>>>    * javadoc.properties: 94
>> I fixed all instances found by searching for "command line opt"
> Thanks!
>
>
> The below is not a criticism of the refactoring, but rather a commentary on
> the current state of affairs.
>
> I don't like that command-line options are represented by public fields that can
> be freely accessed from any part of the code. What I find especially unsettling
> is that some of the fields of the BaseOptions and HtmlOptions are written from
> the outside of those classes. These fields include:
>
>      BaseOptions.docEncoding,
>      BaseOptions.javafx,
>      HtmlOptions.charset
>
> This field is written *only* from the outside of HtmlOptions:
>
>      HtmlOptions.createOverview

I agree that the mutable public fields are not great, and that we might 
want to use
an IDE to encapsulate the fields.? The 3 fields that are modified from 
inside and out of
the class have default values being set. If/when we encapsulate the 
fields, it may be
possible to handle the fault in the access method.

The same probably goes for HtmlOptions.createOverview.

>
> All that points out that Configuration and Options are coupled more tightly than
> we may think.

No, it just means we have not quite got the boundary in quite the right 
place yet.
But, they are clearly related since part of the configuration is the 
options, but there
is more code in the configuration classes that uses the options to 
determine more
configuration values.

>
> -Pavel
>
> --------------------------------------------------------------------------------
> [1] Effective Java, Second Edition by Joshua Bloch,
>          Item 29: Consider typesafe heterogeneous containers
> [2] See java.net.SocketOption, java.net.StandardSocketOptions,
> java.net.Socket.supportedOptions, java.net.Socket.getOption, java.net.Socket.setOption
>
>>> P.S. Thanks for being super careful and not only updating the javadoc comments
>>> but also the commented out code in SourceToHTMLConverter!
>>>
>>>> On 18 Jan 2020, at 01:51, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>>>
>>>> Please review a code-cleanup to reorganize the code to handle doclet options.
>>>>
>>>> Fundamentally, the change is to move the methods and fields to handle option processing from BaseConfiguration and HtmlConfiguration out into new abstractions BaseOptions and HtmlOptions.  As such, the dominant changes are to these 4 files.
>>>>
>>>> The impact on the rest of the doclet code is just to change where to access the values for options: instead of accessing the values directly from the *Configuration classes, the values are now obtained from the corresponding *Option classes, which are in turn accessed from the *Configuration classes. The reference to the Options objects are typically cached when there are a large number of usages in the code. In a  number of cases, the cache is in a supertype, which reduces the visible churn.
>>>>
>>>> I've taken this opportunity to rename the fields for the values of options into the standard camelCase convention. And, I've done some basic work to clean up comments, although more could be done (later).
>>>>
>>>> Fixing a bunch of spurious warnings uncoverable a real warning, that the code was creating a sorted set of incomparable Option objects. This changeset also fixes that issue, which mostly just shows up in the signatures for internal collections of option objects.
>>>>
>>>> There is no change in functionality here. All the tests pass without change, except for one that was tunneling into an impl class, and which needed to be updated.
>>>>
>>>> There's probably a similar cleanup coming to the code to handle tool options.
>>>>
>>>> -- Jon
>>>>
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237492
>>>> Webrev: http://cr.openjdk.java.net/~jjg/8237492/webrev/
>


From pavel.rappo at oracle.com  Wed Jan 22 19:42:09 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Wed, 22 Jan 2020 19:42:09 +0000
Subject: RFR: [15] JDK-8237492 Reorganize impl of doclet options
In-Reply-To: <48928913-994a-eec1-4876-67edb3e11827@oracle.com>
References: <48928913-994a-eec1-4876-67edb3e11827@oracle.com>
Message-ID: <E0D4E8B6-423B-476A-88E9-8DD1F74E06C0@oracle.com>



> On 22 Jan 2020, at 19:29, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> As the ancient Roman's used to say,
> 
> javadoc was not cleaned up in a single changeset.

Reviewed. Thanks.



From kusrinivasan at vmware.com  Thu Jan 23 17:47:32 2020
From: kusrinivasan at vmware.com (Kumar Srinivasan)
Date: Thu, 23 Jan 2020 17:47:32 +0000
Subject: RFR: [15] JDK-8237492 Reorganize impl of doclet options
In-Reply-To: <48928913-994a-eec1-4876-67edb3e11827@oracle.com>
References: <842d95f8-a31d-b1cd-34f3-f11e924c78cb@oracle.com>
 <F76CBD1F-5B2C-4DCA-9744-5ECF7DE2CC36@oracle.com>
 <6eb4768a-d1aa-9137-a30b-d4459fbd4eba@oracle.com>
 <10C98B07-CE1B-4993-B9D9-8838FEB9022B@oracle.com>
 <48928913-994a-eec1-4876-67edb3e11827@oracle.com>
Message-ID: <CE00C3A3-CBBE-47F5-A0AB-09469920090C@vmware.com>

Hi Jon,

Sorry for the late arrival,  I did not do a deep dive,  however  this caught my eye.
I realize you must have used the IDE to refactor, in any case, in the lines you have changed there
are these old constructs:

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractOverviewIndexWriter.java
+        if (doctitle.length() > 0) {

These can be replaced with doctitle.isEmpty().


On Jan 22, 2020, at 11:29 AM, Jonathan Gibbons <jonathan.gibbons at oracle.com<mailto:jonathan.gibbons at oracle.com>> wrote:

Pavel,

Thanks for your additional feedback. There's a couple of actionable items, most notably
with respect to StandardDoclet.

As for the rest, I agree there's a whole bunch more stuff that we *could* do, but I would
prefer to get the work so far staged into the repo. As the ancient Roman's used to say,

javadoc was not cleaned up in a single changeset.

Very true indeed!. :)


Kumar


-- Jon


On 01/22/2020 08:00 AM, Pavel Rappo wrote:
On 21 Jan 2020, at 18:55, Jonathan Gibbons <jonathan.gibbons at oracle.com<mailto:jonathan.gibbons at oracle.com>> wrote:

Pavel,

All great feedback, and all points addressed, as described in the details inline below.

New webrev, addresses all your comments, adds a couple of class-level doc comments
to the two new classes, and fixes a couple of inconsequential spelling errors. Otherwise,
no changes in all the other affected files.

https://nam04.safelinks.protection.outlook.com/?url=http:%2F%2Fcr.openjdk.java.net%2F~jjg%2F8237492%2Fwebrev.01%2F&amp;data=02%7C01%7Ckusrinivasan%40vmware.com%7Ccb446ac59a204a6741f608d79f71c5fe%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637153183321632928&amp;sdata=Tio9bquIDiwfRh4R8bmfrMqxShy8JP5KlW%2FdmBeQv60%3D&amp;reserved=0
Thanks for patiently addressing my comments. I see this code review as an
opportunity to get familiar with the javadoc code base.

<snip>

The ongoing task is to draw lines around parts of the hodge-podge that is
{Base,Html}Configuration, and to pull out those parts into separate, better
defined abstractions.
A noble intent.

<snip>

1. You have reintroduced a forgotten bounded wildcard to

    public Set<? extends Doclet.Option> getSupportedOptions()

Good. Compatibility-wise this should be benign. Hopefully, no one tries to put
anything into that set, which should be assumed unmodifiable anyway.
It's only an internal API, and we control the implementations. As they say,
"No public API was affected in the making of this changeset."
StandardDoclet is a public SPI. Doclets may extend that class, but it's the
"container" that calls the `getSupportedOptions` method. A corner case where the
client calls `getSupportedOptions` would be an implementation of Doclet that
delegates calls to an internal instance of StandardDoclet:

    public class MyDoclet implements Doclet {

        private final StandardDoclet standardDoclet = new StandardDoclet();

        // ...

        @Override
        public Set<? extends Option> getSupportedOptions() {
            Set<Option> supportedOptions = standardDoclet.getSupportedOptions();
            supportedOptions.add(new MyOption()); // additional option
            // ...
            return supportedOptions;
        }

        private static class MyOption implements Doclet.Option {
            // ...
        }
        // ...
    }

Agreed, this is a somewhat contrived example made for the sake of the argument.

You're right; I'd missed that this was a change to StandardDoclet, which is a public API.
This will need to be sorted out, separately.


2. You consistently used camelCase naming for fields that represent options.
This effectively "unlinks" them from their command-line names, which is not bad.
Fewer possibilities to mess this during (automated) future refactorings if you
ask me.
The option names are often horrible and do not provide a really good
precedent.
Agreed.

It's tempting to an an informational source-only annotation that identifies
the options that affect each field, but without any checking, such annotations
would be little better than comments ... which is why I added comments
to identify the options for each value.
This could be addressed another way. Instead of having two separate abstractions,
options classes and option fields, we could use a single abstraction, types.

We could use some sort of a container [1]. The downside might be having more
types. A somewhat related design can be seen in java.net.SocketOption API [2].
That latter API tackles the need for more types by relying on option names, yet
still benefits from the type-safety.

That could allow for more collocation of the code related to command-line options.

I think this is more than I want to consider for this round of cleanup.


<snip>

6. AbstractMemberWriter's fields `printedSummaryHeader` and `nodepr` seem not to
be used. Can those be deleted?
Deleted
The `BaseOptions.docFileDestDirName` field doesn't seem to be accessed from
anywhere. Should it be deleted?

Yes, will do.


<snip>

While we are in this area, consider hyphenating "command line" where it is a
compound adjective rather than a noun (possibly, not an exhaustive list):

  * HtmlConfiguration: 54, 56
  * HtmlOptions: 68, 74, 87, 125, 132, 138, 144, 162
  * BaseConfiguration: 396, 693
  * BaseOptions: 178
  * IllegalOptionValue: 32
  * Main: 49, 58, 70, 83
  * javadoc.properties: 94
I fixed all instances found by searching for "command line opt"
Thanks!


The below is not a criticism of the refactoring, but rather a commentary on
the current state of affairs.

I don't like that command-line options are represented by public fields that can
be freely accessed from any part of the code. What I find especially unsettling
is that some of the fields of the BaseOptions and HtmlOptions are written from
the outside of those classes. These fields include:

    BaseOptions.docEncoding,
    BaseOptions.javafx,
    HtmlOptions.charset

This field is written *only* from the outside of HtmlOptions:

    HtmlOptions.createOverview

I agree that the mutable public fields are not great, and that we might want to use
an IDE to encapsulate the fields.  The 3 fields that are modified from inside and out of
the class have default values being set. If/when we encapsulate the fields, it may be
possible to handle the fault in the access method.

The same probably goes for HtmlOptions.createOverview.


All that points out that Configuration and Options are coupled more tightly than
we may think.

No, it just means we have not quite got the boundary in quite the right place yet.
But, they are clearly related since part of the configuration is the options, but there
is more code in the configuration classes that uses the options to determine more
configuration values.


-Pavel

--------------------------------------------------------------------------------
[1] Effective Java, Second Edition by Joshua Bloch,
        Item 29: Consider typesafe heterogeneous containers
[2] See java.net.SocketOption, java.net.StandardSocketOptions,
java.net.Socket.supportedOptions, java.net.Socket.getOption, java.net.Socket.setOption

P.S. Thanks for being super careful and not only updating the javadoc comments
but also the commented out code in SourceToHTMLConverter!

On 18 Jan 2020, at 01:51, Jonathan Gibbons <jonathan.gibbons at oracle.com<mailto:jonathan.gibbons at oracle.com>> wrote:

Please review a code-cleanup to reorganize the code to handle doclet options.

Fundamentally, the change is to move the methods and fields to handle option processing from BaseConfiguration and HtmlConfiguration out into new abstractions BaseOptions and HtmlOptions.  As such, the dominant changes are to these 4 files.

The impact on the rest of the doclet code is just to change where to access the values for options: instead of accessing the values directly from the *Configuration classes, the values are now obtained from the corresponding *Option classes, which are in turn accessed from the *Configuration classes. The reference to the Options objects are typically cached when there are a large number of usages in the code. In a  number of cases, the cache is in a supertype, which reduces the visible churn.

I've taken this opportunity to rename the fields for the values of options into the standard camelCase convention. And, I've done some basic work to clean up comments, although more could be done (later).

Fixing a bunch of spurious warnings uncoverable a real warning, that the code was creating a sorted set of incomparable Option objects. This changeset also fixes that issue, which mostly just shows up in the signatures for internal collections of option objects.

There is no change in functionality here. All the tests pass without change, except for one that was tunneling into an impl class, and which needed to be updated.

There's probably a similar cleanup coming to the code to handle tool options.

-- Jon


JBS: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fbugs.openjdk.java.net%2Fbrowse%2FJDK-8237492&amp;data=02%7C01%7Ckusrinivasan%40vmware.com%7Ccb446ac59a204a6741f608d79f71c5fe%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637153183321632928&amp;sdata=w2xJGSbuItjHTHfg95KhpWbtsBOSgR02JoLoxwHGPvM%3D&amp;reserved=0
Webrev: https://nam04.safelinks.protection.outlook.com/?url=http:%2F%2Fcr.openjdk.java.net%2F~jjg%2F8237492%2Fwebrev%2F&amp;data=02%7C01%7Ckusrinivasan%40vmware.com%7Ccb446ac59a204a6741f608d79f71c5fe%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637153183321632928&amp;sdata=bcgajooeHWoA5vUjrjEsmImYBOcdf21Y3o49jg7tdPc%3D&amp;reserved=0



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200123/3657b7e2/attachment-0001.htm>

From jonathan.gibbons at oracle.com  Thu Jan 23 19:05:33 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 23 Jan 2020 11:05:33 -0800
Subject: RFR: [15] JDK-8237492 Reorganize impl of doclet options
In-Reply-To: <CE00C3A3-CBBE-47F5-A0AB-09469920090C@vmware.com>
References: <842d95f8-a31d-b1cd-34f3-f11e924c78cb@oracle.com>
 <F76CBD1F-5B2C-4DCA-9744-5ECF7DE2CC36@oracle.com>
 <6eb4768a-d1aa-9137-a30b-d4459fbd4eba@oracle.com>
 <10C98B07-CE1B-4993-B9D9-8838FEB9022B@oracle.com>
 <48928913-994a-eec1-4876-67edb3e11827@oracle.com>
 <CE00C3A3-CBBE-47F5-A0AB-09469920090C@vmware.com>
Message-ID: <4ee21934-2b2e-7f34-f638-10393ab0340f@oracle.com>

Kumar,

Thanks for the feedback; I'll incorporate this change.? (I'm currently 
waiting on a minor CSR approval).

-- Jon


On 01/23/2020 09:47 AM, Kumar Srinivasan wrote:
> Hi Jon,
>
> Sorry for the late arrival, ?I did not do a deep dive, ?however ?this 
> caught my eye.
> I realize you must have used the IDE to refactor, in any case, in the 
> lines you have changed there
> are these old constructs:
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractOverviewIndexWriter.java
> + ? ? ? ?if (doctitle.length() > 0) {
>
> These can be replaced with doctitle.isEmpty().
>
>
>> On Jan 22, 2020, at 11:29 AM, Jonathan Gibbons 
>> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>>
>> Pavel,
>>
>> Thanks for your additional feedback. There's a couple of actionable 
>> items, most notably
>> with respect to StandardDoclet.
>>
>> As for the rest, I agree there's a whole bunch more stuff that we 
>> *could* do, but I would
>> prefer to get the work so far staged into the repo. As the ancient 
>> Roman's used to say,
>>
>> javadoc was not cleaned up in a single changeset.
>
> Very true indeed!. :)
>
>
> Kumar
>
>>
>> -- Jon
>>
>>
>> On 01/22/2020 08:00 AM, Pavel Rappo wrote:
>>>> On 21 Jan 2020, at 18:55, Jonathan Gibbons 
>>>> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> 
>>>> wrote:
>>>>
>>>> Pavel,
>>>>
>>>> All great feedback, and all points addressed, as described in the 
>>>> details inline below.
>>>>
>>>> New webrev, addresses all your comments, adds a couple of 
>>>> class-level doc comments
>>>> to the two new classes, and fixes a couple of inconsequential 
>>>> spelling errors. Otherwise,
>>>> no changes in all the other affected files.
>>>>
>>>> https://nam04.safelinks.protection.outlook.com/?url=http:%2F%2Fcr.openjdk.java.net%2F~jjg%2F8237492%2Fwebrev.01%2F&amp;data=02%7C01%7Ckusrinivasan%40vmware.com%7Ccb446ac59a204a6741f608d79f71c5fe%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637153183321632928&amp;sdata=Tio9bquIDiwfRh4R8bmfrMqxShy8JP5KlW%2FdmBeQv60%3D&amp;reserved=0 
>>>> <https://nam04.safelinks.protection.outlook.com/?url=http:%2F%2Fcr.openjdk.java.net%2F%7Ejjg%2F8237492%2Fwebrev.01%2F&amp;data=02%7C01%7Ckusrinivasan%40vmware.com%7Ccb446ac59a204a6741f608d79f71c5fe%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637153183321632928&amp;sdata=Tio9bquIDiwfRh4R8bmfrMqxShy8JP5KlW%2FdmBeQv60%3D&amp;reserved=0>
>>> Thanks for patiently addressing my comments. I see this code review 
>>> as an
>>> opportunity to get familiar with the javadoc code base.
>>>
>>>> <snip>
>>>>
>>>> The ongoing task is to draw lines around parts of the hodge-podge 
>>>> that is
>>>> {Base,Html}Configuration, and to pull out those parts into 
>>>> separate, better
>>>> defined abstractions.
>>> A noble intent.
>>>
>>>> <snip>
>>>>
>>>>> 1. You have reintroduced a forgotten bounded wildcard to
>>>>>
>>>>> ????public Set<? extends Doclet.Option> getSupportedOptions()
>>>>>
>>>>> Good. Compatibility-wise this should be benign. Hopefully, no one 
>>>>> tries to put
>>>>> anything into that set, which should be assumed unmodifiable anyway.
>>>> It's only an internal API, and we control the implementations. As 
>>>> they say,
>>>> "No public API was affected in the making of this changeset."
>>> StandardDoclet is a public SPI. Doclets may extend that class, but 
>>> it's the
>>> "container" that calls the `getSupportedOptions` method. A corner 
>>> case where the
>>> client calls `getSupportedOptions` would be an implementation of 
>>> Doclet that
>>> delegates calls to an internal instance of StandardDoclet:
>>>
>>> ????public class MyDoclet implements Doclet {
>>>
>>> ????????private final StandardDoclet standardDoclet = new 
>>> StandardDoclet();
>>>
>>> ????????// ...
>>>
>>> ????????@Override
>>> ????????public Set<? extends Option> getSupportedOptions() {
>>> ????????????Set<Option> supportedOptions = 
>>> standardDoclet.getSupportedOptions();
>>> ????????????supportedOptions.add(new MyOption()); // additional option
>>> ????????????// ...
>>> ????????????return supportedOptions;
>>> ????????}
>>>
>>> ????????private static class MyOption implements Doclet.Option {
>>> ????????????// ...
>>> ????????}
>>> ????????// ...
>>> ????}
>>>
>>> Agreed, this is a somewhat contrived example made for the sake of 
>>> the argument.
>>
>> You're right; I'd missed that this was a change to StandardDoclet, 
>> which is a public API.
>> This will need to be sorted out, separately.
>>
>>>
>>>>> 2. You consistently used camelCase naming for fields that 
>>>>> represent options.
>>>>> This effectively "unlinks" them from their command-line names, 
>>>>> which is not bad.
>>>>> Fewer possibilities to mess this during (automated) future 
>>>>> refactorings if you
>>>>> ask me.
>>>> The option names are often horrible and do not provide a really good
>>>> precedent.
>>> Agreed.
>>>
>>>> It's tempting to an an informational source-only annotation that 
>>>> identifies
>>>> the options that affect each field, but without any checking, such 
>>>> annotations
>>>> would be little better than comments ... which is why I added comments
>>>> to identify the options for each value.
>>> This could be addressed another way. Instead of having two separate 
>>> abstractions,
>>> options classes and option fields, we could use a single 
>>> abstraction, types.
>>>
>>> We could use some sort of a container [1]. The downside might be 
>>> having more
>>> types. A somewhat related design can be seen in 
>>> java.net.SocketOption API [2].
>>> That latter API tackles the need for more types by relying on option 
>>> names, yet
>>> still benefits from the type-safety.
>>>
>>> That could allow for more collocation of the code related to 
>>> command-line options.
>>
>> I think this is more than I want to consider for this round of cleanup.
>>
>>>
>>>> <snip>
>>>>
>>>>> 6. AbstractMemberWriter's fields `printedSummaryHeader` and 
>>>>> `nodepr` seem not to
>>>>> be used. Can those be deleted?
>>>> Deleted
>>> The `BaseOptions.docFileDestDirName` field doesn't seem to be 
>>> accessed from
>>> anywhere. Should it be deleted?
>>
>> Yes, will do.
>>
>>>
>>>> <snip>
>>>>
>>>>> While we are in this area, consider hyphenating "command line" 
>>>>> where it is a
>>>>> compound adjective rather than a noun (possibly, not an exhaustive 
>>>>> list):
>>>>>
>>>>> ??* HtmlConfiguration: 54, 56
>>>>> ??* HtmlOptions: 68, 74, 87, 125, 132, 138, 144, 162
>>>>> ??* BaseConfiguration: 396, 693
>>>>> ??* BaseOptions: 178
>>>>> ??* IllegalOptionValue: 32
>>>>> ??* Main: 49, 58, 70, 83
>>>>> ??* javadoc.properties: 94
>>>> I fixed all instances found by searching for "command line opt"
>>> Thanks!
>>>
>>>
>>> The below is not a criticism of the refactoring, but rather a 
>>> commentary on
>>> the current state of affairs.
>>>
>>> I don't like that command-line options are represented by public 
>>> fields that can
>>> be freely accessed from any part of the code. What I find especially 
>>> unsettling
>>> is that some of the fields of the BaseOptions and HtmlOptions are 
>>> written from
>>> the outside of those classes. These fields include:
>>>
>>> ????BaseOptions.docEncoding,
>>> ????BaseOptions.javafx,
>>> ????HtmlOptions.charset
>>>
>>> This field is written *only* from the outside of HtmlOptions:
>>>
>>> ????HtmlOptions.createOverview
>>
>> I agree that the mutable public fields are not great, and that we 
>> might want to use
>> an IDE to encapsulate the fields.? The 3 fields that are modified 
>> from inside and out of
>> the class have default values being set. If/when we encapsulate the 
>> fields, it may be
>> possible to handle the fault in the access method.
>>
>> The same probably goes for HtmlOptions.createOverview.
>>
>>>
>>> All that points out that Configuration and Options are coupled more 
>>> tightly than
>>> we may think.
>>
>> No, it just means we have not quite got the boundary in quite the 
>> right place yet.
>> But, they are clearly related since part of the configuration is the 
>> options, but there
>> is more code in the configuration classes that uses the options to 
>> determine more
>> configuration values.
>>
>>>
>>> -Pavel
>>>
>>> --------------------------------------------------------------------------------
>>> [1] Effective Java, Second Edition by Joshua Bloch,
>>> ????????Item 29: Consider typesafe heterogeneous containers
>>> [2] See java.net.SocketOption, java.net.StandardSocketOptions,
>>> java.net.Socket.supportedOptions, java.net.Socket.getOption, 
>>> java.net.Socket.setOption
>>>
>>>>> P.S. Thanks for being super careful and not only updating the 
>>>>> javadoc comments
>>>>> but also the commented out code in SourceToHTMLConverter!
>>>>>
>>>>>> On 18 Jan 2020, at 01:51, Jonathan Gibbons 
>>>>>> <jonathan.gibbons at oracle.com 
>>>>>> <mailto:jonathan.gibbons at oracle.com>> wrote:
>>>>>>
>>>>>> Please review a code-cleanup to reorganize the code to handle 
>>>>>> doclet options.
>>>>>>
>>>>>> Fundamentally, the change is to move the methods and fields to 
>>>>>> handle option processing from BaseConfiguration and 
>>>>>> HtmlConfiguration out into new abstractions BaseOptions and 
>>>>>> HtmlOptions. ?As such, the dominant changes are to these 4 files.
>>>>>>
>>>>>> The impact on the rest of the doclet code is just to change where 
>>>>>> to access the values for options: instead of accessing the values 
>>>>>> directly from the *Configuration classes, the values are now 
>>>>>> obtained from the corresponding *Option classes, which are in 
>>>>>> turn accessed from the *Configuration classes. The reference to 
>>>>>> the Options objects are typically cached when there are a large 
>>>>>> number of usages in the code. In a ?number of cases, the cache is 
>>>>>> in a supertype, which reduces the visible churn.
>>>>>>
>>>>>> I've taken this opportunity to rename the fields for the values 
>>>>>> of options into the standard camelCase convention. And, I've done 
>>>>>> some basic work to clean up comments, although more could be done 
>>>>>> (later).
>>>>>>
>>>>>> Fixing a bunch of spurious warnings uncoverable a real warning, 
>>>>>> that the code was creating a sorted set of incomparable Option 
>>>>>> objects. This changeset also fixes that issue, which mostly just 
>>>>>> shows up in the signatures for internal collections of option 
>>>>>> objects.
>>>>>>
>>>>>> There is no change in functionality here. All the tests pass 
>>>>>> without change, except for one that was tunneling into an impl 
>>>>>> class, and which needed to be updated.
>>>>>>
>>>>>> There's probably a similar cleanup coming to the code to handle 
>>>>>> tool options.
>>>>>>
>>>>>> -- Jon
>>>>>>
>>>>>>
>>>>>> JBS: 
>>>>>> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fbugs.openjdk.java.net%2Fbrowse%2FJDK-8237492&amp;data=02%7C01%7Ckusrinivasan%40vmware.com%7Ccb446ac59a204a6741f608d79f71c5fe%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637153183321632928&amp;sdata=w2xJGSbuItjHTHfg95KhpWbtsBOSgR02JoLoxwHGPvM%3D&amp;reserved=0
>>>>>> Webrev: 
>>>>>> https://nam04.safelinks.protection.outlook.com/?url=http:%2F%2Fcr.openjdk.java.net%2F~jjg%2F8237492%2Fwebrev%2F&amp;data=02%7C01%7Ckusrinivasan%40vmware.com%7Ccb446ac59a204a6741f608d79f71c5fe%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637153183321632928&amp;sdata=bcgajooeHWoA5vUjrjEsmImYBOcdf21Y3o49jg7tdPc%3D&amp;reserved=0 
>>>>>> <https://nam04.safelinks.protection.outlook.com/?url=http:%2F%2Fcr.openjdk.java.net%2F%7Ejjg%2F8237492%2Fwebrev%2F&amp;data=02%7C01%7Ckusrinivasan%40vmware.com%7Ccb446ac59a204a6741f608d79f71c5fe%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637153183321632928&amp;sdata=bcgajooeHWoA5vUjrjEsmImYBOcdf21Y3o49jg7tdPc%3D&amp;reserved=0>
>>>
>>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200123/7a015da5/attachment-0001.htm>

From jonathan.gibbons at oracle.com  Fri Jan 24 02:30:19 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 23 Jan 2020 18:30:19 -0800
Subject: RFR: JDK-8237803 Reorganize impl of tool options
Message-ID: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>

Although the underlying problems are different, the general goal of this 
cleanup is similar in nature to that of the recent cleanup for doclet 
options.

In this case, the effect is not as widespread ... just 6 source files 
affected, no tests ... but the changes to the main affected class are 
more substantial, although still primarily a refactoring and just moving 
code around, with no intentional change in functionality.

To describe the changes, let me describe the world before this change:

The ToolOption class followed the javac model for options and used an 
enum to represent the individual supported options. One problem of using 
an enum is that they are implicitly static, and so have never have any 
enclosing context. This means that when analyzing command-line 
arguments, the enum members need to be given an object providing the 
necessary context. In the case of ToolOption, this was a nested Helper 
class, which contained a mix of fields containing the values for some 
options, most notably those used in Start, and a map of objects for the 
values of other options, where the map was literally, 
Map<ToolOption,Object>. This led to "clunky" code to access the values 
in the map and to cast the result to the correct type for each value.

In general, while there were some benefits to using the enum (such as 
being able to refer to some of the options by their member name), the 
cost outweighed the benefits.

The primary change is to invert the nesting relationship between 
ToolOption and its Helper, and to rename and refactor the code accordingly.

To summarize the changes,

1. ?? ToolOption.Helper becomes a new top-level class ToolOptions, which 
is the new primary abstraction for the accessing everything to do with 
tool options.

2.??? ToolOption is changed from a top-level enum to a nested class in 
ToolOptions, with the members becoming a simple List<ToolOption>.

3.??? All option values are represented as properly-typed encapsulated 
fields of ToolOptions. The fields are encapsulated, based on the 
feedback for the doclet options review.

4.??? The direct use and passing around of the Map jdToolOpts is 
replaced by direct use of the new ToolOptions class.

5.??? ToolOptions uses a new ShowHelper interface to separate out the 
functionality for handling options like --help and --verbose. 
Previously, Start implemented ToolOption.Help directly; now, it just 
uses a local anonymous class instead.

6.??? ToolOption.java is renamed to ToolOptions.java, to retain history 
and to maximize the opportunity to compare the old and new versions.

There are no significant changes to the high-level option handling in 
Start, which continues to do the double scan, to pick up selection 
options, like -doclet, -docletpath, -locale, before doing the main 
scan.? The handling of OptionException could also be simplified 
(separately), possibly allowing the ShowHelper class to be eliminated.

One of the advantages of using the enum (in the old code) was that it 
allowed symbolic references to options handled in Start.preprocess.? 
These references are fixed up by defining string constants for the names 
of the handful of options in question, which is all that is needed.

While the code is generally cleaner for allowing the ToolOption objects 
to be inner classes of ToolOptions, it does mean they can only exist in 
the context of a ToolOptions object. This has an impact on a little-used 
method on the DocumentationTask interface, to determine if an option 
name is supported. The body of the implementing method is moved into 
ToolOptions, which creates a temporary minimal ToolOptions object, 
sufficient to the needs of the isSupportedOption method.

-- Jon

JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/


From pavel.rappo at oracle.com  Fri Jan 24 12:53:56 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Fri, 24 Jan 2020 12:53:56 +0000
Subject: RFR [15] 8233795: Consider adding a notion of a Value-based class
 to API Documentation index
In-Reply-To: <AC9D9645-1F7F-42AB-B613-ACB98785138E@oracle.com>
References: <553EA827-AFC7-432B-BB3B-125277E33CEE@oracle.com>
 <AC9D9645-1F7F-42AB-B613-ACB98785138E@oracle.com>
Message-ID: <D76778FC-5857-4CA4-A2F3-986820224635@oracle.com>

Thanks, Hannes. Surprisingly enough, the copyright header was missing. I added it before pushing.

> On 22 Jan 2020, at 13:15, Hannes Walln?fer <hannes.wallnoefer at oracle.com> wrote:
> 
> Nice. +1
> 
> Hannes
> 
> 
>> Am 22.01.2020 um 12:58 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
>> 
>> Hello,
>> 
>> Please review the following (documentation) change for https://bugs.openjdk.java.net/browse/JDK-8233795:
>> 
>>  http://cr.openjdk.java.net/~prappo/8233795/webrev.00/
>> 
>> The detailed explanation can be found in the description in the JBS issue. 
>> 
>> Thanks,
>> -Pavel
>> 
> 


From pavel.rappo at oracle.com  Fri Jan 24 16:51:02 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Fri, 24 Jan 2020 16:51:02 +0000
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
Message-ID: <973DBF09-602C-49CD-AC43-B34B84321DBE@oracle.com>

Hi Jon,

I'm still working through the review but I have to say that degree to which com.sun.tools.javac.main.Option.* types have percolated to the javadoc internal interfaces is unsettling. I understand this is probably due to practical and historical reasons. Maybe we could address that later.

-Pavel

> On 24 Jan 2020, at 02:30, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Although the underlying problems are different, the general goal of this cleanup is similar in nature to that of the recent cleanup for doclet options.
> 
> In this case, the effect is not as widespread ... just 6 source files affected, no tests ... but the changes to the main affected class are more substantial, although still primarily a refactoring and just moving code around, with no intentional change in functionality.
> 
> To describe the changes, let me describe the world before this change:
> 
> The ToolOption class followed the javac model for options and used an enum to represent the individual supported options. One problem of using an enum is that they are implicitly static, and so have never have any enclosing context. This means that when analyzing command-line arguments, the enum members need to be given an object providing the necessary context. In the case of ToolOption, this was a nested Helper class, which contained a mix of fields containing the values for some options, most notably those used in Start, and a map of objects for the values of other options, where the map was literally, Map<ToolOption,Object>. This led to "clunky" code to access the values in the map and to cast the result to the correct type for each value.
> 
> In general, while there were some benefits to using the enum (such as being able to refer to some of the options by their member name), the cost outweighed the benefits.
> 
> The primary change is to invert the nesting relationship between ToolOption and its Helper, and to rename and refactor the code accordingly.
> 
> To summarize the changes,
> 
> 1.    ToolOption.Helper becomes a new top-level class ToolOptions, which is the new primary abstraction for the accessing everything to do with tool options.
> 
> 2.    ToolOption is changed from a top-level enum to a nested class in ToolOptions, with the members becoming a simple List<ToolOption>.
> 
> 3.    All option values are represented as properly-typed encapsulated fields of ToolOptions. The fields are encapsulated, based on the feedback for the doclet options review.
> 
> 4.    The direct use and passing around of the Map jdToolOpts is replaced by direct use of the new ToolOptions class.
> 
> 5.    ToolOptions uses a new ShowHelper interface to separate out the functionality for handling options like --help and --verbose. Previously, Start implemented ToolOption.Help directly; now, it just uses a local anonymous class instead.
> 
> 6.    ToolOption.java is renamed to ToolOptions.java, to retain history and to maximize the opportunity to compare the old and new versions.
> 
> There are no significant changes to the high-level option handling in Start, which continues to do the double scan, to pick up selection options, like -doclet, -docletpath, -locale, before doing the main scan.  The handling of OptionException could also be simplified (separately), possibly allowing the ShowHelper class to be eliminated.
> 
> One of the advantages of using the enum (in the old code) was that it allowed symbolic references to options handled in Start.preprocess.  These references are fixed up by defining string constants for the names of the handful of options in question, which is all that is needed.
> 
> While the code is generally cleaner for allowing the ToolOption objects to be inner classes of ToolOptions, it does mean they can only exist in the context of a ToolOptions object. This has an impact on a little-used method on the DocumentationTask interface, to determine if an option name is supported. The body of the implementing method is moved into ToolOptions, which creates a temporary minimal ToolOptions object, sufficient to the needs of the isSupportedOption method.
> 
> -- Jon
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/
> 


From jonathan.gibbons at oracle.com  Fri Jan 24 16:57:21 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 24 Jan 2020 08:57:21 -0800
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <973DBF09-602C-49CD-AC43-B34B84321DBE@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <973DBF09-602C-49CD-AC43-B34B84321DBE@oracle.com>
Message-ID: <a867a9d7-5e72-72d4-98e6-8fa50020ab21@oracle.com>

Re: com.sun.tools.javac.main.Option.*

Well, it is deliberate and intentional that we fully delegate to javac 
those options that are handled by javac, like path-related options, 
--source, --release, --enable-preview etc. This reflects the fact that 
we totally rely on the javac front end to read source and class files.

It was actually a big step forward in the JDK 9 rewrite that we properly 
delegate through the underlying Option objects, as compared to tunneling 
values into the compOpts object, as was done previously, which bypassed 
much of javac's checking.

-- Jon

On 1/24/20 8:51 AM, Pavel Rappo wrote:
> Hi Jon,
>
> I'm still working through the review but I have to say that degree to which com.sun.tools.javac.main.Option.* types have percolated to the javadoc internal interfaces is unsettling. I understand this is probably due to practical and historical reasons. Maybe we could address that later.
>
> -Pavel
>
>> On 24 Jan 2020, at 02:30, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Although the underlying problems are different, the general goal of this cleanup is similar in nature to that of the recent cleanup for doclet options.
>>
>> In this case, the effect is not as widespread ... just 6 source files affected, no tests ... but the changes to the main affected class are more substantial, although still primarily a refactoring and just moving code around, with no intentional change in functionality.
>>
>> To describe the changes, let me describe the world before this change:
>>
>> The ToolOption class followed the javac model for options and used an enum to represent the individual supported options. One problem of using an enum is that they are implicitly static, and so have never have any enclosing context. This means that when analyzing command-line arguments, the enum members need to be given an object providing the necessary context. In the case of ToolOption, this was a nested Helper class, which contained a mix of fields containing the values for some options, most notably those used in Start, and a map of objects for the values of other options, where the map was literally, Map<ToolOption,Object>. This led to "clunky" code to access the values in the map and to cast the result to the correct type for each value.
>>
>> In general, while there were some benefits to using the enum (such as being able to refer to some of the options by their member name), the cost outweighed the benefits.
>>
>> The primary change is to invert the nesting relationship between ToolOption and its Helper, and to rename and refactor the code accordingly.
>>
>> To summarize the changes,
>>
>> 1.    ToolOption.Helper becomes a new top-level class ToolOptions, which is the new primary abstraction for the accessing everything to do with tool options.
>>
>> 2.    ToolOption is changed from a top-level enum to a nested class in ToolOptions, with the members becoming a simple List<ToolOption>.
>>
>> 3.    All option values are represented as properly-typed encapsulated fields of ToolOptions. The fields are encapsulated, based on the feedback for the doclet options review.
>>
>> 4.    The direct use and passing around of the Map jdToolOpts is replaced by direct use of the new ToolOptions class.
>>
>> 5.    ToolOptions uses a new ShowHelper interface to separate out the functionality for handling options like --help and --verbose. Previously, Start implemented ToolOption.Help directly; now, it just uses a local anonymous class instead.
>>
>> 6.    ToolOption.java is renamed to ToolOptions.java, to retain history and to maximize the opportunity to compare the old and new versions.
>>
>> There are no significant changes to the high-level option handling in Start, which continues to do the double scan, to pick up selection options, like -doclet, -docletpath, -locale, before doing the main scan.  The handling of OptionException could also be simplified (separately), possibly allowing the ShowHelper class to be eliminated.
>>
>> One of the advantages of using the enum (in the old code) was that it allowed symbolic references to options handled in Start.preprocess.  These references are fixed up by defining string constants for the names of the handful of options in question, which is all that is needed.
>>
>> While the code is generally cleaner for allowing the ToolOption objects to be inner classes of ToolOptions, it does mean they can only exist in the context of a ToolOptions object. This has an impact on a little-used method on the DocumentationTask interface, to determine if an option name is supported. The body of the implementing method is moved into ToolOptions, which creates a temporary minimal ToolOptions object, sufficient to the needs of the isSupportedOption method.
>>
>> -- Jon
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
>> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/
>>

From pavel.rappo at oracle.com  Fri Jan 24 17:11:56 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Fri, 24 Jan 2020 17:11:56 +0000
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <a867a9d7-5e72-72d4-98e6-8fa50020ab21@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <973DBF09-602C-49CD-AC43-B34B84321DBE@oracle.com>
 <a867a9d7-5e72-72d4-98e6-8fa50020ab21@oracle.com>
Message-ID: <20BC5B43-3F3B-4EB3-89B5-AD717BEE7D21@oracle.com>

Hm... I mean that the ToolOption type uses javac types (e.g. com.sun.tools.javac.main.Option.OptionKind) in its methods signatures, and that it also throws javac exceptions (e.g. com.sun.tools.javac.main.Option.InvalidValueException).

Please correct me if I'm wrong.

It's as if javadoc borrows something that it doesn't have. In a perfect world this would suggest that there should be a common "module" dealing with the CLI options on which both tools would depend.

> On 24 Jan 2020, at 16:57, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Re: com.sun.tools.javac.main.Option.*
> 
> Well, it is deliberate and intentional that we fully delegate to javac those options that are handled by javac, like path-related options, --source, --release, --enable-preview etc. This reflects the fact that we totally rely on the javac front end to read source and class files.
> 
> It was actually a big step forward in the JDK 9 rewrite that we properly delegate through the underlying Option objects, as compared to tunneling values into the compOpts object, as was done previously, which bypassed much of javac's checking.
> 
> -- Jon
> 
> On 1/24/20 8:51 AM, Pavel Rappo wrote:
>> Hi Jon,
>> 
>> I'm still working through the review but I have to say that degree to which com.sun.tools.javac.main.Option.* types have percolated to the javadoc internal interfaces is unsettling. I understand this is probably due to practical and historical reasons. Maybe we could address that later.
>> 
>> -Pavel
>> 
>>> On 24 Jan 2020, at 02:30, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>> 
>>> Although the underlying problems are different, the general goal of this cleanup is similar in nature to that of the recent cleanup for doclet options.
>>> 
>>> In this case, the effect is not as widespread ... just 6 source files affected, no tests ... but the changes to the main affected class are more substantial, although still primarily a refactoring and just moving code around, with no intentional change in functionality.
>>> 
>>> To describe the changes, let me describe the world before this change:
>>> 
>>> The ToolOption class followed the javac model for options and used an enum to represent the individual supported options. One problem of using an enum is that they are implicitly static, and so have never have any enclosing context. This means that when analyzing command-line arguments, the enum members need to be given an object providing the necessary context. In the case of ToolOption, this was a nested Helper class, which contained a mix of fields containing the values for some options, most notably those used in Start, and a map of objects for the values of other options, where the map was literally, Map<ToolOption,Object>. This led to "clunky" code to access the values in the map and to cast the result to the correct type for each value.
>>> 
>>> In general, while there were some benefits to using the enum (such as being able to refer to some of the options by their member name), the cost outweighed the benefits.
>>> 
>>> The primary change is to invert the nesting relationship between ToolOption and its Helper, and to rename and refactor the code accordingly.
>>> 
>>> To summarize the changes,
>>> 
>>> 1.    ToolOption.Helper becomes a new top-level class ToolOptions, which is the new primary abstraction for the accessing everything to do with tool options.
>>> 
>>> 2.    ToolOption is changed from a top-level enum to a nested class in ToolOptions, with the members becoming a simple List<ToolOption>.
>>> 
>>> 3.    All option values are represented as properly-typed encapsulated fields of ToolOptions. The fields are encapsulated, based on the feedback for the doclet options review.
>>> 
>>> 4.    The direct use and passing around of the Map jdToolOpts is replaced by direct use of the new ToolOptions class.
>>> 
>>> 5.    ToolOptions uses a new ShowHelper interface to separate out the functionality for handling options like --help and --verbose. Previously, Start implemented ToolOption.Help directly; now, it just uses a local anonymous class instead.
>>> 
>>> 6.    ToolOption.java is renamed to ToolOptions.java, to retain history and to maximize the opportunity to compare the old and new versions.
>>> 
>>> There are no significant changes to the high-level option handling in Start, which continues to do the double scan, to pick up selection options, like -doclet, -docletpath, -locale, before doing the main scan.  The handling of OptionException could also be simplified (separately), possibly allowing the ShowHelper class to be eliminated.
>>> 
>>> One of the advantages of using the enum (in the old code) was that it allowed symbolic references to options handled in Start.preprocess.  These references are fixed up by defining string constants for the names of the handful of options in question, which is all that is needed.
>>> 
>>> While the code is generally cleaner for allowing the ToolOption objects to be inner classes of ToolOptions, it does mean they can only exist in the context of a ToolOptions object. This has an impact on a little-used method on the DocumentationTask interface, to determine if an option name is supported. The body of the implementing method is moved into ToolOptions, which creates a temporary minimal ToolOptions object, sufficient to the needs of the isSupportedOption method.
>>> 
>>> -- Jon
>>> 
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
>>> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/
>>> 


From jonathan.gibbons at oracle.com  Fri Jan 24 17:13:41 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 24 Jan 2020 09:13:41 -0800
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <a867a9d7-5e72-72d4-98e6-8fa50020ab21@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <973DBF09-602C-49CD-AC43-B34B84321DBE@oracle.com>
 <a867a9d7-5e72-72d4-98e6-8fa50020ab21@oracle.com>
Message-ID: <ed2d54ea-2a41-4e80-757a-b9455aee28ca@oracle.com>

Note also that unlike the doclet part of javadoc, the tool part of 
javadoc is (and has always been) tightly coupled to javac, and directly 
uses a number of internal javac interfaces, to modify javac behavior. 
For example, this includes providing custom subtypes to override javac 
behavior to read files like package.html, to not analyze method bodies, 
and even to discard method bodies, which are of no relevance to javadoc.

In other words, the tool part of javadoc is allowed access to javac 
internals, whereas we try and restrict the doclet, which is conceptually 
a plugin, to the public APIs like Compiler Tree API (com.sun.source.*) 
and Language Model API (javax.lang.model.*)

-- Jon


On 1/24/20 8:57 AM, Jonathan Gibbons wrote:
> Re: com.sun.tools.javac.main.Option.*
>
> Well, it is deliberate and intentional that we fully delegate to javac 
> those options that are handled by javac, like path-related options, 
> --source, --release, --enable-preview etc. This reflects the fact that 
> we totally rely on the javac front end to read source and class files.
>
> It was actually a big step forward in the JDK 9 rewrite that we 
> properly delegate through the underlying Option objects, as compared 
> to tunneling values into the compOpts object, as was done previously, 
> which bypassed much of javac's checking.
>
> -- Jon
>
> On 1/24/20 8:51 AM, Pavel Rappo wrote:
>> Hi Jon,
>>
>> I'm still working through the review but I have to say that degree to 
>> which com.sun.tools.javac.main.Option.* types have percolated to the 
>> javadoc internal interfaces is unsettling. I understand this is 
>> probably due to practical and historical reasons. Maybe we could 
>> address that later.
>>
>> -Pavel
>>
>>> On 24 Jan 2020, at 02:30, Jonathan Gibbons 
>>> <jonathan.gibbons at oracle.com> wrote:
>>>
>>> Although the underlying problems are different, the general goal of 
>>> this cleanup is similar in nature to that of the recent cleanup for 
>>> doclet options.
>>>
>>> In this case, the effect is not as widespread ... just 6 source 
>>> files affected, no tests ... but the changes to the main affected 
>>> class are more substantial, although still primarily a refactoring 
>>> and just moving code around, with no intentional change in 
>>> functionality.
>>>
>>> To describe the changes, let me describe the world before this change:
>>>
>>> The ToolOption class followed the javac model for options and used 
>>> an enum to represent the individual supported options. One problem 
>>> of using an enum is that they are implicitly static, and so have 
>>> never have any enclosing context. This means that when analyzing 
>>> command-line arguments, the enum members need to be given an object 
>>> providing the necessary context. In the case of ToolOption, this was 
>>> a nested Helper class, which contained a mix of fields containing 
>>> the values for some options, most notably those used in Start, and a 
>>> map of objects for the values of other options, where the map was 
>>> literally, Map<ToolOption,Object>. This led to "clunky" code to 
>>> access the values in the map and to cast the result to the correct 
>>> type for each value.
>>>
>>> In general, while there were some benefits to using the enum (such 
>>> as being able to refer to some of the options by their member name), 
>>> the cost outweighed the benefits.
>>>
>>> The primary change is to invert the nesting relationship between 
>>> ToolOption and its Helper, and to rename and refactor the code 
>>> accordingly.
>>>
>>> To summarize the changes,
>>>
>>> 1.??? ToolOption.Helper becomes a new top-level class ToolOptions, 
>>> which is the new primary abstraction for the accessing everything to 
>>> do with tool options.
>>>
>>> 2.??? ToolOption is changed from a top-level enum to a nested class 
>>> in ToolOptions, with the members becoming a simple List<ToolOption>.
>>>
>>> 3.??? All option values are represented as properly-typed 
>>> encapsulated fields of ToolOptions. The fields are encapsulated, 
>>> based on the feedback for the doclet options review.
>>>
>>> 4.??? The direct use and passing around of the Map jdToolOpts is 
>>> replaced by direct use of the new ToolOptions class.
>>>
>>> 5.??? ToolOptions uses a new ShowHelper interface to separate out 
>>> the functionality for handling options like --help and --verbose. 
>>> Previously, Start implemented ToolOption.Help directly; now, it just 
>>> uses a local anonymous class instead.
>>>
>>> 6.??? ToolOption.java is renamed to ToolOptions.java, to retain 
>>> history and to maximize the opportunity to compare the old and new 
>>> versions.
>>>
>>> There are no significant changes to the high-level option handling 
>>> in Start, which continues to do the double scan, to pick up 
>>> selection options, like -doclet, -docletpath, -locale, before doing 
>>> the main scan.? The handling of OptionException could also be 
>>> simplified (separately), possibly allowing the ShowHelper class to 
>>> be eliminated.
>>>
>>> One of the advantages of using the enum (in the old code) was that 
>>> it allowed symbolic references to options handled in 
>>> Start.preprocess.? These references are fixed up by defining string 
>>> constants for the names of the handful of options in question, which 
>>> is all that is needed.
>>>
>>> While the code is generally cleaner for allowing the ToolOption 
>>> objects to be inner classes of ToolOptions, it does mean they can 
>>> only exist in the context of a ToolOptions object. This has an 
>>> impact on a little-used method on the DocumentationTask interface, 
>>> to determine if an option name is supported. The body of the 
>>> implementing method is moved into ToolOptions, which creates a 
>>> temporary minimal ToolOptions object, sufficient to the needs of the 
>>> isSupportedOption method.
>>>
>>> -- Jon
>>>
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
>>> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/
>>>

From jonathan.gibbons at oracle.com  Fri Jan 24 17:29:57 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 24 Jan 2020 09:29:57 -0800
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <20BC5B43-3F3B-4EB3-89B5-AD717BEE7D21@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <973DBF09-602C-49CD-AC43-B34B84321DBE@oracle.com>
 <a867a9d7-5e72-72d4-98e6-8fa50020ab21@oracle.com>
 <20BC5B43-3F3B-4EB3-89B5-AD717BEE7D21@oracle.com>
Message-ID: <9a8d7d26-8ef2-ebb2-fc02-6f0648f7ae86@oracle.com>


On 1/24/20 9:11 AM, Pavel Rappo wrote:
> Hm... I mean that the ToolOption type uses javac types (e.g. com.sun.tools.javac.main.Option.OptionKind) in its methods signatures, and that it also throws javac exceptions (e.g. com.sun.tools.javac.main.Option.InvalidValueException).
>
> Please correct me if I'm wrong.
Not entirely wrong.
>
> It's as if javadoc borrows something that it doesn't have. In a perfect world this would suggest that there should be a common "module" dealing with the CLI options on which both tools would depend.

javadoc doesn't "borrow" it, it is almost compelled to use it, by virtue 
of delegating to the Option objects.

That being said, in this rewrite, there are a couple of methods 
(processCompilerOption) where we could catch/wrap/convert the javac 
exceptions and turn them into javadoc-only exceptions, but I'd have to 
think whether it's worth it.

As for a common module,

1. Early drafts of Project Jigsaw had much finer grain modules, but we 
backed off to the larger modules you see today. If we had smaller 
modules, my first split would be to separate the tool part of javadoc 
from the doclet part of javadoc.

2. There's ongoing chatter about a module for option decoding. We 
already have JOptSimple somewhere, and recently Brian G was chatting 
about another library that he found and liked.? My general opinion is 
that some common shared library would be good for new code, but would be 
hard to introduce into existing tools. For better or worse, javac has a 
mix of styles that has accreted over the years ...
 ??? -multiwordname, --multi-word-name,? -Aname=value, -name:value, 
--name value, --name=value, -name/p:value, -name/a:value
 ??? last-one-wins, values-accumulate, etc

There's also subtle differences:

  * javac keeps decoding options after --help, --version etc, and prints
    out info when all is done
  * javadoc handles --help, --version immediately and exits (I believe
    this is more like the launcher behavior.)

Changing all this (especially javac!) is more than I wanted to do in 
this changeset!

-- Jon

>
>> On 24 Jan 2020, at 16:57, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Re: com.sun.tools.javac.main.Option.*
>>
>> Well, it is deliberate and intentional that we fully delegate to javac those options that are handled by javac, like path-related options, --source, --release, --enable-preview etc. This reflects the fact that we totally rely on the javac front end to read source and class files.
>>
>> It was actually a big step forward in the JDK 9 rewrite that we properly delegate through the underlying Option objects, as compared to tunneling values into the compOpts object, as was done previously, which bypassed much of javac's checking.
>>
>> -- Jon
>>
>> On 1/24/20 8:51 AM, Pavel Rappo wrote:
>>> Hi Jon,
>>>
>>> I'm still working through the review but I have to say that degree to which com.sun.tools.javac.main.Option.* types have percolated to the javadoc internal interfaces is unsettling. I understand this is probably due to practical and historical reasons. Maybe we could address that later.
>>>
>>> -Pavel
>>>
>>>> On 24 Jan 2020, at 02:30, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>>>
>>>> Although the underlying problems are different, the general goal of this cleanup is similar in nature to that of the recent cleanup for doclet options.
>>>>
>>>> In this case, the effect is not as widespread ... just 6 source files affected, no tests ... but the changes to the main affected class are more substantial, although still primarily a refactoring and just moving code around, with no intentional change in functionality.
>>>>
>>>> To describe the changes, let me describe the world before this change:
>>>>
>>>> The ToolOption class followed the javac model for options and used an enum to represent the individual supported options. One problem of using an enum is that they are implicitly static, and so have never have any enclosing context. This means that when analyzing command-line arguments, the enum members need to be given an object providing the necessary context. In the case of ToolOption, this was a nested Helper class, which contained a mix of fields containing the values for some options, most notably those used in Start, and a map of objects for the values of other options, where the map was literally, Map<ToolOption,Object>. This led to "clunky" code to access the values in the map and to cast the result to the correct type for each value.
>>>>
>>>> In general, while there were some benefits to using the enum (such as being able to refer to some of the options by their member name), the cost outweighed the benefits.
>>>>
>>>> The primary change is to invert the nesting relationship between ToolOption and its Helper, and to rename and refactor the code accordingly.
>>>>
>>>> To summarize the changes,
>>>>
>>>> 1.    ToolOption.Helper becomes a new top-level class ToolOptions, which is the new primary abstraction for the accessing everything to do with tool options.
>>>>
>>>> 2.    ToolOption is changed from a top-level enum to a nested class in ToolOptions, with the members becoming a simple List<ToolOption>.
>>>>
>>>> 3.    All option values are represented as properly-typed encapsulated fields of ToolOptions. The fields are encapsulated, based on the feedback for the doclet options review.
>>>>
>>>> 4.    The direct use and passing around of the Map jdToolOpts is replaced by direct use of the new ToolOptions class.
>>>>
>>>> 5.    ToolOptions uses a new ShowHelper interface to separate out the functionality for handling options like --help and --verbose. Previously, Start implemented ToolOption.Help directly; now, it just uses a local anonymous class instead.
>>>>
>>>> 6.    ToolOption.java is renamed to ToolOptions.java, to retain history and to maximize the opportunity to compare the old and new versions.
>>>>
>>>> There are no significant changes to the high-level option handling in Start, which continues to do the double scan, to pick up selection options, like -doclet, -docletpath, -locale, before doing the main scan.  The handling of OptionException could also be simplified (separately), possibly allowing the ShowHelper class to be eliminated.
>>>>
>>>> One of the advantages of using the enum (in the old code) was that it allowed symbolic references to options handled in Start.preprocess.  These references are fixed up by defining string constants for the names of the handful of options in question, which is all that is needed.
>>>>
>>>> While the code is generally cleaner for allowing the ToolOption objects to be inner classes of ToolOptions, it does mean they can only exist in the context of a ToolOptions object. This has an impact on a little-used method on the DocumentationTask interface, to determine if an option name is supported. The body of the implementing method is moved into ToolOptions, which creates a temporary minimal ToolOptions object, sufficient to the needs of the isSupportedOption method.
>>>>
>>>> -- Jon
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
>>>> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/
>>>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200124/b6bba9ea/attachment.htm>

From pavel.rappo at oracle.com  Fri Jan 24 17:36:06 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Fri, 24 Jan 2020 17:36:06 +0000
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <9a8d7d26-8ef2-ebb2-fc02-6f0648f7ae86@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <973DBF09-602C-49CD-AC43-B34B84321DBE@oracle.com>
 <a867a9d7-5e72-72d4-98e6-8fa50020ab21@oracle.com>
 <20BC5B43-3F3B-4EB3-89B5-AD717BEE7D21@oracle.com>
 <9a8d7d26-8ef2-ebb2-fc02-6f0648f7ae86@oracle.com>
Message-ID: <55069614-0782-42E3-8D38-3B207F13693D@oracle.com>

I was definitely not suggesting that! Rather, I was commenting on what I saw. The state of affairs, that predate your changeset.

> On 24 Jan 2020, at 17:29, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Changing all this (especially javac!) is more than I wanted to do in this changeset!


From jonathan.gibbons at oracle.com  Fri Jan 24 18:32:14 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 24 Jan 2020 10:32:14 -0800
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <55069614-0782-42E3-8D38-3B207F13693D@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <973DBF09-602C-49CD-AC43-B34B84321DBE@oracle.com>
 <a867a9d7-5e72-72d4-98e6-8fa50020ab21@oracle.com>
 <20BC5B43-3F3B-4EB3-89B5-AD717BEE7D21@oracle.com>
 <9a8d7d26-8ef2-ebb2-fc02-6f0648f7ae86@oracle.com>
 <55069614-0782-42E3-8D38-3B207F13693D@oracle.com>
Message-ID: <a325f0f4-36de-e02e-8790-1111ab3d2a94@oracle.com>

Your observation is well-founded.

The use of javac OptionKind is merely a convenience, and not inherently 
required as part of interacting with javac's option mechanism.? It can 
be replaced by a similar, local enum in ToolOption.

I could envisage a world in which javac's Option enum is split into an 
interface and an enum which implements that interface. Then, javadoc 
could also implement that interface instead of defining the ToolOption 
interface. That would also allow us to directly include javac Option 
objects in the list of javadoc Option objects, instead of using proxy 
objects that delegate.

However, that would tighten the connection between javadoc and javac, 
and I'm not sure that is a direction in which we want to go. Demeter 
would not probably not approve.

-- Jon



On 01/24/2020 09:36 AM, Pavel Rappo wrote:
> I was definitely not suggesting that! Rather, I was commenting on what I saw. The state of affairs, that predate your changeset.
>
>> On 24 Jan 2020, at 17:29, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Changing all this (especially javac!) is more than I wanted to do in this changeset!


From pavel.rappo at oracle.com  Fri Jan 24 19:23:28 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Fri, 24 Jan 2020 19:23:28 +0000
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
Message-ID: <A1E1EF0F-50D3-42A0-9C2E-B8A77118B013@oracle.com>

The crux of the change is gathering options into a more monolithic and more
encapsulated design. If I were to describe this change in a nutshell, it would be:

   Map<ToolOption, Object> -> class ToolOptions

The change, as you described, does away with the enum. So ToolOption.values()
become ToolOptions.getSupportedOptions(). Equality checks (==) on ToolOption
constants turn into equality checks (equals()) on a handful of String constants
(DOCLET, DOCLET_PATH, DUMP_ON_ERROR, J, and LOCALE).

Commentary
==========

1. Map is a rich general-purpose interface. Still, ToolOptions could provide a
more apt interface for our needs. What we lose (at least in this changeset) is
the ability to control the behavior for nonexistent options (e.g.
getOrDefault/contains). Not sure if that was truly ever needed, though.

2. It's good to see fixes to Javadoc comments in the javadoc codebase.
If something is not continuously tested (built/compiled/run), it quickly gets
out of date. Some of the javadoc's javadoc comments are ridiculously inaccurate
or stale.

At this stage it is neither practical nor fair to ask ourselves to build the
documentation continuously fixing all the comments along the way. Still, we
should think about a solution to this. Meanwhile, thanks for doing this
manually, Jon!

3. The previous design, Map<ToolOption, Object>, imposed a lot of casting.
Though this could be solved using a ToolOption design similar to that of
java.net.SocketOption, the proposed design solves this problem another way.
Namely, read access to properties is performed through named methods with the
specific return types. Come to think of it, this should allow to get rid of
@SuppressWarning("unchecked") in places like:

    - ElementsTable.java:409, 504
    - Start.java:475

It's also good to see, naked (as opposed to Collections.emptyList())
Collections.EMPTY_LIST goes away.

4. Removing the `extends Helper` in Start looks a whole lot cleaner as it
removes all the fields inherited from Helper.

Looks good to me.

-Pavel

> On 24 Jan 2020, at 02:30, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Although the underlying problems are different, the general goal of this cleanup is similar in nature to that of the recent cleanup for doclet options.
> 
> In this case, the effect is not as widespread ... just 6 source files affected, no tests ... but the changes to the main affected class are more substantial, although still primarily a refactoring and just moving code around, with no intentional change in functionality.
> 
> To describe the changes, let me describe the world before this change:
> 
> The ToolOption class followed the javac model for options and used an enum to represent the individual supported options. One problem of using an enum is that they are implicitly static, and so have never have any enclosing context. This means that when analyzing command-line arguments, the enum members need to be given an object providing the necessary context. In the case of ToolOption, this was a nested Helper class, which contained a mix of fields containing the values for some options, most notably those used in Start, and a map of objects for the values of other options, where the map was literally, Map<ToolOption,Object>. This led to "clunky" code to access the values in the map and to cast the result to the correct type for each value.
> 
> In general, while there were some benefits to using the enum (such as being able to refer to some of the options by their member name), the cost outweighed the benefits.
> 
> The primary change is to invert the nesting relationship between ToolOption and its Helper, and to rename and refactor the code accordingly.
> 
> To summarize the changes,
> 
> 1.    ToolOption.Helper becomes a new top-level class ToolOptions, which is the new primary abstraction for the accessing everything to do with tool options.
> 
> 2.    ToolOption is changed from a top-level enum to a nested class in ToolOptions, with the members becoming a simple List<ToolOption>.
> 
> 3.    All option values are represented as properly-typed encapsulated fields of ToolOptions. The fields are encapsulated, based on the feedback for the doclet options review.
> 
> 4.    The direct use and passing around of the Map jdToolOpts is replaced by direct use of the new ToolOptions class.
> 
> 5.    ToolOptions uses a new ShowHelper interface to separate out the functionality for handling options like --help and --verbose. Previously, Start implemented ToolOption.Help directly; now, it just uses a local anonymous class instead.
> 
> 6.    ToolOption.java is renamed to ToolOptions.java, to retain history and to maximize the opportunity to compare the old and new versions.
> 
> There are no significant changes to the high-level option handling in Start, which continues to do the double scan, to pick up selection options, like -doclet, -docletpath, -locale, before doing the main scan.  The handling of OptionException could also be simplified (separately), possibly allowing the ShowHelper class to be eliminated.
> 
> One of the advantages of using the enum (in the old code) was that it allowed symbolic references to options handled in Start.preprocess.  These references are fixed up by defining string constants for the names of the handful of options in question, which is all that is needed.
> 
> While the code is generally cleaner for allowing the ToolOption objects to be inner classes of ToolOptions, it does mean they can only exist in the context of a ToolOptions object. This has an impact on a little-used method on the DocumentationTask interface, to determine if an option name is supported. The body of the implementing method is moved into ToolOptions, which creates a temporary minimal ToolOptions object, sufficient to the needs of the isSupportedOption method.
> 
> -- Jon
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/
> 


From jonathan.gibbons at oracle.com  Fri Jan 24 20:04:09 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 24 Jan 2020 12:04:09 -0800
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <A1E1EF0F-50D3-42A0-9C2E-B8A77118B013@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <A1E1EF0F-50D3-42A0-9C2E-B8A77118B013@oracle.com>
Message-ID: <db06496b-4572-28d7-59de-f5816cc1cb17@oracle.com>

Thanks for all the commentary/feedback.

-- Jon


On 01/24/2020 11:23 AM, Pavel Rappo wrote:
>   If I were to describe this change in a nutshell, it would be:
>
>     Map<ToolOption, Object> -> class ToolOptions

A slightly bigger, more accurate nutshell is

	{ Map<ToolOption, Object>, misc fields } -> class ToolOptions

> 1. Map is a rich general-purpose interface. Still, ToolOptions could provide a
> more apt interface for our needs. What we lose (at least in this changeset) is
> the ability to control the behavior for nonexistent options (e.g.
> getOrDefault/contains). Not sure if that was truly ever needed, though.

Not entirely true.?? Defaults are established, it just happens early on, 
in the field initialization.

Agreed that we lose the easy ability to determine if an option was 
specified.? We use that ability in javac, when checking for conflicts 
between incompatible options ... for example, all the 
platform-class-path related options and all the module-related options 
are allowed/disallowed depending on the source/release version. We don't 
need the ability here.? I note that an interim version of this work 
(before the review) left the enum in place, but then you have to pass in 
and use a reference to the enclosing ToolOptions object in all the 
"process" methods. If we needed to detect whether options were 
specified, we could certainly do something, such as maintaining a set of 
the ToolOption objects for options that have been found on the 
command-line. This could even be done in the option decoding loop in 
Start, and not in individual ToolOption objects.

> 2. It's good to see fixes to Javadoc comments in the javadoc codebase.
> If something is not continuously tested (built/compiled/run), it quickly gets
> out of date. Some of the javadoc's javadoc comments are ridiculously inaccurate
> or stale.

At least for now, the solution is to raise the bar, and fix comments on 
code that
are being worked on, and for reviewers to note stale comments.
> 3. The previous design, Map<ToolOption, Object>, imposed a lot of casting.
> Though this could be solved using a ToolOption design similar to that of
> java.net.SocketOption, the proposed design solves this problem another way.
> Namely, read access to properties is performed through named methods with the
> specific return types. Come to think of it, this should allow to get rid of
> @SuppressWarning("unchecked") in places like:
>
>      - ElementsTable.java:409, 504
>      - Start.java:475
>
> It's also good to see, naked (as opposed to Collections.emptyList())
> Collections.EMPTY_LIST goes away.

The intent is to make doclet options work the same way, i.e. encapsulate 
them.
I'll look for and remove the unnecessary SuppressWarnings.

> 4. Removing the `extends Helper` in Start looks a whole lot cleaner as it
> removes all the fields inherited from Helper.

Yes, that's a very old antipattern.? It almost leaked into this review, 
in that ToolOptions
was abstract, until I realized it would be better to use something like 
the ShowOptions
interface and use a local anon class.

-- Jon


From jonathan.gibbons at oracle.com  Fri Jan 24 21:44:28 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 24 Jan 2020 13:44:28 -0800
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <A1E1EF0F-50D3-42A0-9C2E-B8A77118B013@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <A1E1EF0F-50D3-42A0-9C2E-B8A77118B013@oracle.com>
Message-ID: <4610a562-24d0-d11f-df69-1ef95c2d9874@oracle.com>

Updated webrev.

Replaced use of javac OptionKind with new ToolOption.Kind.

Removed redundant @SuppressWarnings("unchecked") and by editing
a couple of lines in Utils.java, I got rid of the last remaining 
occurrences of
unchecked warnings in the jdk.javadoc module. Woohoo!

-- Jon

Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev.01/


On 01/24/2020 11:23 AM, Pavel Rappo wrote:
> The crux of the change is gathering options into a more monolithic and more
> encapsulated design. If I were to describe this change in a nutshell, it would be:
>
>     Map<ToolOption, Object> -> class ToolOptions
>
> The change, as you described, does away with the enum. So ToolOption.values()
> become ToolOptions.getSupportedOptions(). Equality checks (==) on ToolOption
> constants turn into equality checks (equals()) on a handful of String constants
> (DOCLET, DOCLET_PATH, DUMP_ON_ERROR, J, and LOCALE).
>
> Commentary
> ==========
>
> 1. Map is a rich general-purpose interface. Still, ToolOptions could provide a
> more apt interface for our needs. What we lose (at least in this changeset) is
> the ability to control the behavior for nonexistent options (e.g.
> getOrDefault/contains). Not sure if that was truly ever needed, though.
>
> 2. It's good to see fixes to Javadoc comments in the javadoc codebase.
> If something is not continuously tested (built/compiled/run), it quickly gets
> out of date. Some of the javadoc's javadoc comments are ridiculously inaccurate
> or stale.
>
> At this stage it is neither practical nor fair to ask ourselves to build the
> documentation continuously fixing all the comments along the way. Still, we
> should think about a solution to this. Meanwhile, thanks for doing this
> manually, Jon!
>
> 3. The previous design, Map<ToolOption, Object>, imposed a lot of casting.
> Though this could be solved using a ToolOption design similar to that of
> java.net.SocketOption, the proposed design solves this problem another way.
> Namely, read access to properties is performed through named methods with the
> specific return types. Come to think of it, this should allow to get rid of
> @SuppressWarning("unchecked") in places like:
>
>      - ElementsTable.java:409, 504
>      - Start.java:475
>
> It's also good to see, naked (as opposed to Collections.emptyList())
> Collections.EMPTY_LIST goes away.
>
> 4. Removing the `extends Helper` in Start looks a whole lot cleaner as it
> removes all the fields inherited from Helper.
>
> Looks good to me.
>
> -Pavel
>
>> On 24 Jan 2020, at 02:30, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Although the underlying problems are different, the general goal of this cleanup is similar in nature to that of the recent cleanup for doclet options.
>>
>> In this case, the effect is not as widespread ... just 6 source files affected, no tests ... but the changes to the main affected class are more substantial, although still primarily a refactoring and just moving code around, with no intentional change in functionality.
>>
>> To describe the changes, let me describe the world before this change:
>>
>> The ToolOption class followed the javac model for options and used an enum to represent the individual supported options. One problem of using an enum is that they are implicitly static, and so have never have any enclosing context. This means that when analyzing command-line arguments, the enum members need to be given an object providing the necessary context. In the case of ToolOption, this was a nested Helper class, which contained a mix of fields containing the values for some options, most notably those used in Start, and a map of objects for the values of other options, where the map was literally, Map<ToolOption,Object>. This led to "clunky" code to access the values in the map and to cast the result to the correct type for each value.
>>
>> In general, while there were some benefits to using the enum (such as being able to refer to some of the options by their member name), the cost outweighed the benefits.
>>
>> The primary change is to invert the nesting relationship between ToolOption and its Helper, and to rename and refactor the code accordingly.
>>
>> To summarize the changes,
>>
>> 1.    ToolOption.Helper becomes a new top-level class ToolOptions, which is the new primary abstraction for the accessing everything to do with tool options.
>>
>> 2.    ToolOption is changed from a top-level enum to a nested class in ToolOptions, with the members becoming a simple List<ToolOption>.
>>
>> 3.    All option values are represented as properly-typed encapsulated fields of ToolOptions. The fields are encapsulated, based on the feedback for the doclet options review.
>>
>> 4.    The direct use and passing around of the Map jdToolOpts is replaced by direct use of the new ToolOptions class.
>>
>> 5.    ToolOptions uses a new ShowHelper interface to separate out the functionality for handling options like --help and --verbose. Previously, Start implemented ToolOption.Help directly; now, it just uses a local anonymous class instead.
>>
>> 6.    ToolOption.java is renamed to ToolOptions.java, to retain history and to maximize the opportunity to compare the old and new versions.
>>
>> There are no significant changes to the high-level option handling in Start, which continues to do the double scan, to pick up selection options, like -doclet, -docletpath, -locale, before doing the main scan.  The handling of OptionException could also be simplified (separately), possibly allowing the ShowHelper class to be eliminated.
>>
>> One of the advantages of using the enum (in the old code) was that it allowed symbolic references to options handled in Start.preprocess.  These references are fixed up by defining string constants for the names of the handful of options in question, which is all that is needed.
>>
>> While the code is generally cleaner for allowing the ToolOption objects to be inner classes of ToolOptions, it does mean they can only exist in the context of a ToolOptions object. This has an impact on a little-used method on the DocumentationTask interface, to determine if an option name is supported. The body of the implementing method is moved into ToolOptions, which creates a temporary minimal ToolOptions object, sufficient to the needs of the isSupportedOption method.
>>
>> -- Jon
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
>> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/
>>


From jonathan.gibbons at oracle.com  Fri Jan 24 21:49:15 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 24 Jan 2020 13:49:15 -0800
Subject: FYI: suppressed warnings in jdk.javadoc module
In-Reply-To: <4610a562-24d0-d11f-df69-1ef95c2d9874@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <A1E1EF0F-50D3-42A0-9C2E-B8A77118B013@oracle.com>
 <4610a562-24d0-d11f-df69-1ef95c2d9874@oracle.com>
Message-ID: <5f4bf752-7621-a8ba-abb3-ccb9afdbf193@oracle.com>

FYI

suppressed warnings in jdk.javadoc module

$ for i in deprecation fallthrough preview removal ; do echo $i `fgrep 
-r 'SuppressWarnings("'$i open/src/jdk.javadoc/ | wc -l` ; done
deprecation 2
fallthrough 1
preview 35
removal 1

-- Jon

From jonathan.gibbons at oracle.com  Sat Jan 25 00:33:53 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 24 Jan 2020 16:33:53 -0800
Subject: RFR: JDK-8237845 Encapsulate doclet options
Message-ID: <59629df3-9a67-ed3f-6909-c78301b594fd@oracle.com>

Please review a conceptually simple review to encapsulate the fields 
holding the values of doclet options, in the BaseOptions and HtmlOptions 
classes.

The encapsulation was done with an IDE. The fields are all changed to 
private access; the access methods are package-private by default, and 
public when necessary, although in general, there is no problem if it is 
determined they should all have public access.? This is the same policy 
as was done for ToolOptions, currently in review.

Some fields need public "setters". These were added manually.

In a few places, code was simplified manually, joining short lines, or 
replacing `configuration.getOptions()` with just `options`.

This is intended to be the last in the current round of option-code 
cleanup, for now, although I think there is scope for future work to 
rationalize the names of the fields and corresponding accessor methods.

-- Jon


JBS: https://bugs.openjdk.java.net/browse/JDK-8237845
Webrev: http://cr.openjdk.java.net/~jjg/8237845/webrev.00/


From pavel.rappo at oracle.com  Mon Jan 27 13:38:20 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Mon, 27 Jan 2020 13:38:20 +0000
Subject: RFR: JDK-8237845 Encapsulate doclet options
In-Reply-To: <59629df3-9a67-ed3f-6909-c78301b594fd@oracle.com>
References: <59629df3-9a67-ed3f-6909-c78301b594fd@oracle.com>
Message-ID: <A17E6FF9-2B3A-49B8-B873-30CBEDA389A9@oracle.com>

I remember we had an offline conversation on whether we should use shorter
method names for accessing stuff [ stuff() ], or more familiar ones
[ getStuff()/hasStuff()/isStuff()/etc. ].
I remember saying that I had no strong opinion about it. Not thank I'm
rethinking it, but I can now see how some of the accessor methods look weird.
Unsurprisingly, those are the ones whose name starts with a verb. For example,

    copyDocfileSubdirs(),
    createIndex(),
    createOverview(),
    linkSource(),
    showAuthor(),
    showVersion(),
    splitIndex(),
    summarizeOverriddenMethods(), etc.

Naming is hard, no doubt about it. While giving something a name, that name
should not be expected to be the sole guide on how to use that something.
A name should be a good mnemonic.

We could put a top-level comment in both BaseOptions and HtmlOptions. Something
to the effect that "unless otherwise stated, the methods below do not have any
behavior beyond simply accessing stuff".

Otherwise, looks good.

-Pavel

> On 25 Jan 2020, at 00:33, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Please review a conceptually simple review to encapsulate the fields holding the values of doclet options, in the BaseOptions and HtmlOptions classes.
> 
> The encapsulation was done with an IDE. The fields are all changed to private access; the access methods are package-private by default, and public when necessary, although in general, there is no problem if it is determined they should all have public access.  This is the same policy as was done for ToolOptions, currently in review.
> 
> Some fields need public "setters". These were added manually.
> 
> In a few places, code was simplified manually, joining short lines, or replacing `configuration.getOptions()` with just `options`.
> 
> This is intended to be the last in the current round of option-code cleanup, for now, although I think there is scope for future work to rationalize the names of the fields and corresponding accessor methods.
> 
> -- Jon
> 
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8237845
> Webrev: http://cr.openjdk.java.net/~jjg/8237845/webrev.00/
> 


From hannes.wallnoefer at oracle.com  Mon Jan 27 15:20:31 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Mon, 27 Jan 2020 16:20:31 +0100
Subject: RFR: JDK-8237845 Encapsulate doclet options
In-Reply-To: <A17E6FF9-2B3A-49B8-B873-30CBEDA389A9@oracle.com>
References: <59629df3-9a67-ed3f-6909-c78301b594fd@oracle.com>
 <A17E6FF9-2B3A-49B8-B873-30CBEDA389A9@oracle.com>
Message-ID: <D93C1A92-28AB-40F8-AF62-A4BDC59EF890@oracle.com>

I agree some of these method names taken on their own are slightly deceptive. But given their mostly ()boolean  signatures and the fact that they?re always invoked on ?options? or similar make their purpose clear enough without having to look at their implementation or doc comments. 

Given that neither get*, is*, or has* prefix is really great for this use case I think keeping these names and maybe adding a comment as suggested by Pavel is the best option.

Hannes


> Am 27.01.2020 um 14:38 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
> 
> I remember we had an offline conversation on whether we should use shorter
> method names for accessing stuff [ stuff() ], or more familiar ones
> [ getStuff()/hasStuff()/isStuff()/etc. ].
> I remember saying that I had no strong opinion about it. Not thank I'm
> rethinking it, but I can now see how some of the accessor methods look weird.
> Unsurprisingly, those are the ones whose name starts with a verb. For example,
> 
>    copyDocfileSubdirs(),
>    createIndex(),
>    createOverview(),
>    linkSource(),
>    showAuthor(),
>    showVersion(),
>    splitIndex(),
>    summarizeOverriddenMethods(), etc.
> 
> Naming is hard, no doubt about it. While giving something a name, that name
> should not be expected to be the sole guide on how to use that something.
> A name should be a good mnemonic.
> 
> We could put a top-level comment in both BaseOptions and HtmlOptions. Something
> to the effect that "unless otherwise stated, the methods below do not have any
> behavior beyond simply accessing stuff".
> 
> Otherwise, looks good.
> 
> -Pavel
> 
>> On 25 Jan 2020, at 00:33, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>> 
>> Please review a conceptually simple review to encapsulate the fields holding the values of doclet options, in the BaseOptions and HtmlOptions classes.
>> 
>> The encapsulation was done with an IDE. The fields are all changed to private access; the access methods are package-private by default, and public when necessary, although in general, there is no problem if it is determined they should all have public access.  This is the same policy as was done for ToolOptions, currently in review.
>> 
>> Some fields need public "setters". These were added manually.
>> 
>> In a few places, code was simplified manually, joining short lines, or replacing `configuration.getOptions()` with just `options`.
>> 
>> This is intended to be the last in the current round of option-code cleanup, for now, although I think there is scope for future work to rationalize the names of the fields and corresponding accessor methods.
>> 
>> -- Jon
>> 
>> 
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237845
>> Webrev: http://cr.openjdk.java.net/~jjg/8237845/webrev.00/
>> 
> 


From hannes.wallnoefer at oracle.com  Mon Jan 27 15:22:43 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Mon, 27 Jan 2020 16:22:43 +0100
Subject: RFR: JDK-8237845 Encapsulate doclet options
In-Reply-To: <D93C1A92-28AB-40F8-AF62-A4BDC59EF890@oracle.com>
References: <59629df3-9a67-ed3f-6909-c78301b594fd@oracle.com>
 <A17E6FF9-2B3A-49B8-B873-30CBEDA389A9@oracle.com>
 <D93C1A92-28AB-40F8-AF62-A4BDC59EF890@oracle.com>
Message-ID: <9723D17E-2021-4B96-8859-05572646DCD3@oracle.com>

I forgot: +1 on the change itself.

Hannes

> Am 27.01.2020 um 16:20 schrieb Hannes Walln?fer <hannes.wallnoefer at oracle.com>:
> 
> I agree some of these method names taken on their own are slightly deceptive. But given their mostly ()boolean  signatures and the fact that they?re always invoked on ?options? or similar make their purpose clear enough without having to look at their implementation or doc comments. 
> 
> Given that neither get*, is*, or has* prefix is really great for this use case I think keeping these names and maybe adding a comment as suggested by Pavel is the best option.
> 
> Hannes
> 
> 
>> Am 27.01.2020 um 14:38 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
>> 
>> I remember we had an offline conversation on whether we should use shorter
>> method names for accessing stuff [ stuff() ], or more familiar ones
>> [ getStuff()/hasStuff()/isStuff()/etc. ].
>> I remember saying that I had no strong opinion about it. Not thank I'm
>> rethinking it, but I can now see how some of the accessor methods look weird.
>> Unsurprisingly, those are the ones whose name starts with a verb. For example,
>> 
>>   copyDocfileSubdirs(),
>>   createIndex(),
>>   createOverview(),
>>   linkSource(),
>>   showAuthor(),
>>   showVersion(),
>>   splitIndex(),
>>   summarizeOverriddenMethods(), etc.
>> 
>> Naming is hard, no doubt about it. While giving something a name, that name
>> should not be expected to be the sole guide on how to use that something.
>> A name should be a good mnemonic.
>> 
>> We could put a top-level comment in both BaseOptions and HtmlOptions. Something
>> to the effect that "unless otherwise stated, the methods below do not have any
>> behavior beyond simply accessing stuff".
>> 
>> Otherwise, looks good.
>> 
>> -Pavel
>> 
>>> On 25 Jan 2020, at 00:33, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>> 
>>> Please review a conceptually simple review to encapsulate the fields holding the values of doclet options, in the BaseOptions and HtmlOptions classes.
>>> 
>>> The encapsulation was done with an IDE. The fields are all changed to private access; the access methods are package-private by default, and public when necessary, although in general, there is no problem if it is determined they should all have public access.  This is the same policy as was done for ToolOptions, currently in review.
>>> 
>>> Some fields need public "setters". These were added manually.
>>> 
>>> In a few places, code was simplified manually, joining short lines, or replacing `configuration.getOptions()` with just `options`.
>>> 
>>> This is intended to be the last in the current round of option-code cleanup, for now, although I think there is scope for future work to rationalize the names of the fields and corresponding accessor methods.
>>> 
>>> -- Jon
>>> 
>>> 
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237845
>>> Webrev: http://cr.openjdk.java.net/~jjg/8237845/webrev.00/
>>> 
>> 
> 


From pavel.rappo at oracle.com  Mon Jan 27 17:12:33 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Mon, 27 Jan 2020 17:12:33 +0000
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <4610a562-24d0-d11f-df69-1ef95c2d9874@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <A1E1EF0F-50D3-42A0-9C2E-B8A77118B013@oracle.com>
 <4610a562-24d0-d11f-df69-1ef95c2d9874@oracle.com>
Message-ID: <C422257E-553A-4548-93CD-442DCAD65C3B@oracle.com>


This looks a lot better, Jon.

You got rid of two extra instances of SuppressWarning("unchecked"), good.

Even though we now have our own option kind, ToolOptions.ToolOption.Kind,
I'm still not comfortable with ToolOption.process methods throwing
com.sun.tools.javac.main.Option.InvalidValueException.

I understand the "we totally rely on the javac front end to read source and
class files" thing. Still, I don't think it warrants mentioning this specific
exception in the throws clause of a rather abstract method.
Not all options deal with javac, why would they all depend on this exception?

If this exception does need to be handled differently, which doesn't seem to be the case,
we could still pass it wrapping in an higher-level jdk.javadoc.internal.tool.OptionException
exception.

Call me pedantic, but while this doesn't look bad in and of itself, things likes
this tend to add up pretty quickly and result in code that is difficult to
comprehend.

It's okay to defer addressing this to some other time.
No need to update webrev.
Looks good.

-Pavel

> On 24 Jan 2020, at 21:44, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Updated webrev.
> 
> Replaced use of javac OptionKind with new ToolOption.Kind.
> 
> Removed redundant @SuppressWarnings("unchecked") and by editing
> a couple of lines in Utils.java, I got rid of the last remaining occurrences of
> unchecked warnings in the jdk.javadoc module. Woohoo!
> 
> -- Jon
> 
> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev.01/
> 
> 
> On 01/24/2020 11:23 AM, Pavel Rappo wrote:
>> The crux of the change is gathering options into a more monolithic and more
>> encapsulated design. If I were to describe this change in a nutshell, it would be:
>> 
>>    Map<ToolOption, Object> -> class ToolOptions
>> 
>> The change, as you described, does away with the enum. So ToolOption.values()
>> become ToolOptions.getSupportedOptions(). Equality checks (==) on ToolOption
>> constants turn into equality checks (equals()) on a handful of String constants
>> (DOCLET, DOCLET_PATH, DUMP_ON_ERROR, J, and LOCALE).
>> 
>> Commentary
>> ==========
>> 
>> 1. Map is a rich general-purpose interface. Still, ToolOptions could provide a
>> more apt interface for our needs. What we lose (at least in this changeset) is
>> the ability to control the behavior for nonexistent options (e.g.
>> getOrDefault/contains). Not sure if that was truly ever needed, though.
>> 
>> 2. It's good to see fixes to Javadoc comments in the javadoc codebase.
>> If something is not continuously tested (built/compiled/run), it quickly gets
>> out of date. Some of the javadoc's javadoc comments are ridiculously inaccurate
>> or stale.
>> 
>> At this stage it is neither practical nor fair to ask ourselves to build the
>> documentation continuously fixing all the comments along the way. Still, we
>> should think about a solution to this. Meanwhile, thanks for doing this
>> manually, Jon!
>> 
>> 3. The previous design, Map<ToolOption, Object>, imposed a lot of casting.
>> Though this could be solved using a ToolOption design similar to that of
>> java.net.SocketOption, the proposed design solves this problem another way.
>> Namely, read access to properties is performed through named methods with the
>> specific return types. Come to think of it, this should allow to get rid of
>> @SuppressWarning("unchecked") in places like:
>> 
>>     - ElementsTable.java:409, 504
>>     - Start.java:475
>> 
>> It's also good to see, naked (as opposed to Collections.emptyList())
>> Collections.EMPTY_LIST goes away.
>> 
>> 4. Removing the `extends Helper` in Start looks a whole lot cleaner as it
>> removes all the fields inherited from Helper.
>> 
>> Looks good to me.
>> 
>> -Pavel
>> 
>>> On 24 Jan 2020, at 02:30, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>> 
>>> Although the underlying problems are different, the general goal of this cleanup is similar in nature to that of the recent cleanup for doclet options.
>>> 
>>> In this case, the effect is not as widespread ... just 6 source files affected, no tests ... but the changes to the main affected class are more substantial, although still primarily a refactoring and just moving code around, with no intentional change in functionality.
>>> 
>>> To describe the changes, let me describe the world before this change:
>>> 
>>> The ToolOption class followed the javac model for options and used an enum to represent the individual supported options. One problem of using an enum is that they are implicitly static, and so have never have any enclosing context. This means that when analyzing command-line arguments, the enum members need to be given an object providing the necessary context. In the case of ToolOption, this was a nested Helper class, which contained a mix of fields containing the values for some options, most notably those used in Start, and a map of objects for the values of other options, where the map was literally, Map<ToolOption,Object>. This led to "clunky" code to access the values in the map and to cast the result to the correct type for each value.
>>> 
>>> In general, while there were some benefits to using the enum (such as being able to refer to some of the options by their member name), the cost outweighed the benefits.
>>> 
>>> The primary change is to invert the nesting relationship between ToolOption and its Helper, and to rename and refactor the code accordingly.
>>> 
>>> To summarize the changes,
>>> 
>>> 1.    ToolOption.Helper becomes a new top-level class ToolOptions, which is the new primary abstraction for the accessing everything to do with tool options.
>>> 
>>> 2.    ToolOption is changed from a top-level enum to a nested class in ToolOptions, with the members becoming a simple List<ToolOption>.
>>> 
>>> 3.    All option values are represented as properly-typed encapsulated fields of ToolOptions. The fields are encapsulated, based on the feedback for the doclet options review.
>>> 
>>> 4.    The direct use and passing around of the Map jdToolOpts is replaced by direct use of the new ToolOptions class.
>>> 
>>> 5.    ToolOptions uses a new ShowHelper interface to separate out the functionality for handling options like --help and --verbose. Previously, Start implemented ToolOption.Help directly; now, it just uses a local anonymous class instead.
>>> 
>>> 6.    ToolOption.java is renamed to ToolOptions.java, to retain history and to maximize the opportunity to compare the old and new versions.
>>> 
>>> There are no significant changes to the high-level option handling in Start, which continues to do the double scan, to pick up selection options, like -doclet, -docletpath, -locale, before doing the main scan.  The handling of OptionException could also be simplified (separately), possibly allowing the ShowHelper class to be eliminated.
>>> 
>>> One of the advantages of using the enum (in the old code) was that it allowed symbolic references to options handled in Start.preprocess.  These references are fixed up by defining string constants for the names of the handful of options in question, which is all that is needed.
>>> 
>>> While the code is generally cleaner for allowing the ToolOption objects to be inner classes of ToolOptions, it does mean they can only exist in the context of a ToolOptions object. This has an impact on a little-used method on the DocumentationTask interface, to determine if an option name is supported. The body of the implementing method is moved into ToolOptions, which creates a temporary minimal ToolOptions object, sufficient to the needs of the isSupportedOption method.
>>> 
>>> -- Jon
>>> 
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
>>> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/
>>> 
> 


From jonathan.gibbons at oracle.com  Mon Jan 27 17:45:05 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 27 Jan 2020 09:45:05 -0800
Subject: RFR: JDK-8237845 Encapsulate doclet options
In-Reply-To: <9723D17E-2021-4B96-8859-05572646DCD3@oracle.com>
References: <59629df3-9a67-ed3f-6909-c78301b594fd@oracle.com>
 <A17E6FF9-2B3A-49B8-B873-30CBEDA389A9@oracle.com>
 <D93C1A92-28AB-40F8-AF62-A4BDC59EF890@oracle.com>
 <9723D17E-2021-4B96-8859-05572646DCD3@oracle.com>
Message-ID: <10a1405a-55cc-63d1-945a-3e35323fbbf8@oracle.com>

Yeah, I was very aware of the weirdness when I submitted the review, 
particularly for the names that are more like verbs than nouns or 
adjectives.

My short-term justification is, as Hannes noted, they're always invoked 
on an "options" object.? Further out, I'm open to better naming. One 
thing to note is that this changeset moves us towards a more consistent 
design that is more amenable to IDE-based updates (i.e. "rename method" 
refactoring) down the line.

We can also try and come up with a scheme for naming option accessor 
methods that covers both tool options and all the doclet options.

-- Jon


On 1/27/20 7:22 AM, Hannes Walln?fer wrote:
> I forgot: +1 on the change itself.
>
> Hannes
>
>> Am 27.01.2020 um 16:20 schrieb Hannes Walln?fer <hannes.wallnoefer at oracle.com>:
>>
>> I agree some of these method names taken on their own are slightly deceptive. But given their mostly ()boolean  signatures and the fact that they?re always invoked on ?options? or similar make their purpose clear enough without having to look at their implementation or doc comments.
>>
>> Given that neither get*, is*, or has* prefix is really great for this use case I think keeping these names and maybe adding a comment as suggested by Pavel is the best option.
>>
>> Hannes
>>
>>
>>> Am 27.01.2020 um 14:38 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
>>>
>>> I remember we had an offline conversation on whether we should use shorter
>>> method names for accessing stuff [ stuff() ], or more familiar ones
>>> [ getStuff()/hasStuff()/isStuff()/etc. ].
>>> I remember saying that I had no strong opinion about it. Not thank I'm
>>> rethinking it, but I can now see how some of the accessor methods look weird.
>>> Unsurprisingly, those are the ones whose name starts with a verb. For example,
>>>
>>>    copyDocfileSubdirs(),
>>>    createIndex(),
>>>    createOverview(),
>>>    linkSource(),
>>>    showAuthor(),
>>>    showVersion(),
>>>    splitIndex(),
>>>    summarizeOverriddenMethods(), etc.
>>>
>>> Naming is hard, no doubt about it. While giving something a name, that name
>>> should not be expected to be the sole guide on how to use that something.
>>> A name should be a good mnemonic.
>>>
>>> We could put a top-level comment in both BaseOptions and HtmlOptions. Something
>>> to the effect that "unless otherwise stated, the methods below do not have any
>>> behavior beyond simply accessing stuff".
>>>
>>> Otherwise, looks good.
>>>
>>> -Pavel
>>>
>>>> On 25 Jan 2020, at 00:33, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>>>
>>>> Please review a conceptually simple review to encapsulate the fields holding the values of doclet options, in the BaseOptions and HtmlOptions classes.
>>>>
>>>> The encapsulation was done with an IDE. The fields are all changed to private access; the access methods are package-private by default, and public when necessary, although in general, there is no problem if it is determined they should all have public access.  This is the same policy as was done for ToolOptions, currently in review.
>>>>
>>>> Some fields need public "setters". These were added manually.
>>>>
>>>> In a few places, code was simplified manually, joining short lines, or replacing `configuration.getOptions()` with just `options`.
>>>>
>>>> This is intended to be the last in the current round of option-code cleanup, for now, although I think there is scope for future work to rationalize the names of the fields and corresponding accessor methods.
>>>>
>>>> -- Jon
>>>>
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237845
>>>> Webrev: http://cr.openjdk.java.net/~jjg/8237845/webrev.00/
>>>>

From leventov.ru at gmail.com  Mon Jan 27 15:45:47 2020
From: leventov.ru at gmail.com (Roman Leventov)
Date: Mon, 27 Jan 2020 18:45:47 +0300
Subject: Methods from package-private classes don't appear on the Index page
Message-ID: <CAAMLo=aOzNASGybyAy12vb7PrH2OETF8-UGKCVHuFDsG4Ov3Sg@mail.gmail.com>

Foo.java:
package a;
class Foo {
 public void foo() {}
}

Bar.java:
package a;
public class Bar extends Foo {}

in generated Javadoc site, foo() method is not listed on the index page.

I verified this with OpenJDK 11.0.3.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200127/ca8918e4/attachment.htm>

From pavel.rappo at oracle.com  Mon Jan 27 17:55:46 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Mon, 27 Jan 2020 17:55:46 +0000
Subject: Methods from package-private classes don't appear on the Index
 page
In-Reply-To: <CAAMLo=aOzNASGybyAy12vb7PrH2OETF8-UGKCVHuFDsG4Ov3Sg@mail.gmail.com>
References: <CAAMLo=aOzNASGybyAy12vb7PrH2OETF8-UGKCVHuFDsG4Ov3Sg@mail.gmail.com>
Message-ID: <9499F14B-37A9-40A1-9E95-80A60B19699C@oracle.com>

How did you generate those javadoc pages?

> On 27 Jan 2020, at 15:45, Roman Leventov <leventov.ru at gmail.com> wrote:
> 
> Foo.java:
> package a;
> class Foo {
>  public void foo() {}
> }
> 
> Bar.java:
> package a;
> public class Bar extends Foo {}
> 
> in generated Javadoc site, foo() method is not listed on the index page.
> 
> I verified this with OpenJDK 11.0.3.


From jonathan.gibbons at oracle.com  Mon Jan 27 17:56:15 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 27 Jan 2020 09:56:15 -0800
Subject: RFR: JDK-8237803 Reorganize impl of tool options
In-Reply-To: <C422257E-553A-4548-93CD-442DCAD65C3B@oracle.com>
References: <573615a0-8026-dcff-f2cb-a9062aa5ae26@oracle.com>
 <A1E1EF0F-50D3-42A0-9C2E-B8A77118B013@oracle.com>
 <4610a562-24d0-d11f-df69-1ef95c2d9874@oracle.com>
 <C422257E-553A-4548-93CD-442DCAD65C3B@oracle.com>
Message-ID: <2710d72d-ec03-7a1b-cb0c-81e78ce8c20c@oracle.com>

Thanks for the feedback, and yes, I share some of your concerns about 
the exception handling.?? While the use of a `Runnable` parameter was 
expedient at the time, in the face of this changeset, I see it as 
cumbersome.

I think there is scope for having a base type OptionException, with 
subtypes for specific use cases, such as to process --help/--version 
options, or to wrap the javac exception type, and then have different 
catch clauses where it matters for the different subtypes.

-- Jon


On 1/27/20 9:12 AM, Pavel Rappo wrote:
> This looks a lot better, Jon.
>
> You got rid of two extra instances of SuppressWarning("unchecked"), good.
>
> Even though we now have our own option kind, ToolOptions.ToolOption.Kind,
> I'm still not comfortable with ToolOption.process methods throwing
> com.sun.tools.javac.main.Option.InvalidValueException.
>
> I understand the "we totally rely on the javac front end to read source and
> class files" thing. Still, I don't think it warrants mentioning this specific
> exception in the throws clause of a rather abstract method.
> Not all options deal with javac, why would they all depend on this exception?
>
> If this exception does need to be handled differently, which doesn't seem to be the case,
> we could still pass it wrapping in an higher-level jdk.javadoc.internal.tool.OptionException
> exception.
>
> Call me pedantic, but while this doesn't look bad in and of itself, things likes
> this tend to add up pretty quickly and result in code that is difficult to
> comprehend.
>
> It's okay to defer addressing this to some other time.
> No need to update webrev.
> Looks good.
>
> -Pavel
>
>> On 24 Jan 2020, at 21:44, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Updated webrev.
>>
>> Replaced use of javac OptionKind with new ToolOption.Kind.
>>
>> Removed redundant @SuppressWarnings("unchecked") and by editing
>> a couple of lines in Utils.java, I got rid of the last remaining occurrences of
>> unchecked warnings in the jdk.javadoc module. Woohoo!
>>
>> -- Jon
>>
>> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev.01/
>>
>>
>> On 01/24/2020 11:23 AM, Pavel Rappo wrote:
>>> The crux of the change is gathering options into a more monolithic and more
>>> encapsulated design. If I were to describe this change in a nutshell, it would be:
>>>
>>>     Map<ToolOption, Object> -> class ToolOptions
>>>
>>> The change, as you described, does away with the enum. So ToolOption.values()
>>> become ToolOptions.getSupportedOptions(). Equality checks (==) on ToolOption
>>> constants turn into equality checks (equals()) on a handful of String constants
>>> (DOCLET, DOCLET_PATH, DUMP_ON_ERROR, J, and LOCALE).
>>>
>>> Commentary
>>> ==========
>>>
>>> 1. Map is a rich general-purpose interface. Still, ToolOptions could provide a
>>> more apt interface for our needs. What we lose (at least in this changeset) is
>>> the ability to control the behavior for nonexistent options (e.g.
>>> getOrDefault/contains). Not sure if that was truly ever needed, though.
>>>
>>> 2. It's good to see fixes to Javadoc comments in the javadoc codebase.
>>> If something is not continuously tested (built/compiled/run), it quickly gets
>>> out of date. Some of the javadoc's javadoc comments are ridiculously inaccurate
>>> or stale.
>>>
>>> At this stage it is neither practical nor fair to ask ourselves to build the
>>> documentation continuously fixing all the comments along the way. Still, we
>>> should think about a solution to this. Meanwhile, thanks for doing this
>>> manually, Jon!
>>>
>>> 3. The previous design, Map<ToolOption, Object>, imposed a lot of casting.
>>> Though this could be solved using a ToolOption design similar to that of
>>> java.net.SocketOption, the proposed design solves this problem another way.
>>> Namely, read access to properties is performed through named methods with the
>>> specific return types. Come to think of it, this should allow to get rid of
>>> @SuppressWarning("unchecked") in places like:
>>>
>>>      - ElementsTable.java:409, 504
>>>      - Start.java:475
>>>
>>> It's also good to see, naked (as opposed to Collections.emptyList())
>>> Collections.EMPTY_LIST goes away.
>>>
>>> 4. Removing the `extends Helper` in Start looks a whole lot cleaner as it
>>> removes all the fields inherited from Helper.
>>>
>>> Looks good to me.
>>>
>>> -Pavel
>>>
>>>> On 24 Jan 2020, at 02:30, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>>>
>>>> Although the underlying problems are different, the general goal of this cleanup is similar in nature to that of the recent cleanup for doclet options.
>>>>
>>>> In this case, the effect is not as widespread ... just 6 source files affected, no tests ... but the changes to the main affected class are more substantial, although still primarily a refactoring and just moving code around, with no intentional change in functionality.
>>>>
>>>> To describe the changes, let me describe the world before this change:
>>>>
>>>> The ToolOption class followed the javac model for options and used an enum to represent the individual supported options. One problem of using an enum is that they are implicitly static, and so have never have any enclosing context. This means that when analyzing command-line arguments, the enum members need to be given an object providing the necessary context. In the case of ToolOption, this was a nested Helper class, which contained a mix of fields containing the values for some options, most notably those used in Start, and a map of objects for the values of other options, where the map was literally, Map<ToolOption,Object>. This led to "clunky" code to access the values in the map and to cast the result to the correct type for each value.
>>>>
>>>> In general, while there were some benefits to using the enum (such as being able to refer to some of the options by their member name), the cost outweighed the benefits.
>>>>
>>>> The primary change is to invert the nesting relationship between ToolOption and its Helper, and to rename and refactor the code accordingly.
>>>>
>>>> To summarize the changes,
>>>>
>>>> 1.    ToolOption.Helper becomes a new top-level class ToolOptions, which is the new primary abstraction for the accessing everything to do with tool options.
>>>>
>>>> 2.    ToolOption is changed from a top-level enum to a nested class in ToolOptions, with the members becoming a simple List<ToolOption>.
>>>>
>>>> 3.    All option values are represented as properly-typed encapsulated fields of ToolOptions. The fields are encapsulated, based on the feedback for the doclet options review.
>>>>
>>>> 4.    The direct use and passing around of the Map jdToolOpts is replaced by direct use of the new ToolOptions class.
>>>>
>>>> 5.    ToolOptions uses a new ShowHelper interface to separate out the functionality for handling options like --help and --verbose. Previously, Start implemented ToolOption.Help directly; now, it just uses a local anonymous class instead.
>>>>
>>>> 6.    ToolOption.java is renamed to ToolOptions.java, to retain history and to maximize the opportunity to compare the old and new versions.
>>>>
>>>> There are no significant changes to the high-level option handling in Start, which continues to do the double scan, to pick up selection options, like -doclet, -docletpath, -locale, before doing the main scan.  The handling of OptionException could also be simplified (separately), possibly allowing the ShowHelper class to be eliminated.
>>>>
>>>> One of the advantages of using the enum (in the old code) was that it allowed symbolic references to options handled in Start.preprocess.  These references are fixed up by defining string constants for the names of the handful of options in question, which is all that is needed.
>>>>
>>>> While the code is generally cleaner for allowing the ToolOption objects to be inner classes of ToolOptions, it does mean they can only exist in the context of a ToolOptions object. This has an impact on a little-used method on the DocumentationTask interface, to determine if an option name is supported. The body of the implementing method is moved into ToolOptions, which creates a temporary minimal ToolOptions object, sufficient to the needs of the isSupportedOption method.
>>>>
>>>> -- Jon
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8237803
>>>> Webrev: http://cr.openjdk.java.net/~jjg/8237803/webrev/
>>>>

From hannes.wallnoefer at oracle.com  Mon Jan 27 19:18:12 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Mon, 27 Jan 2020 20:18:12 +0100
Subject: Methods from package-private classes don't appear on the Index
 page
In-Reply-To: <CAAMLo=aOzNASGybyAy12vb7PrH2OETF8-UGKCVHuFDsG4Ov3Sg@mail.gmail.com>
References: <CAAMLo=aOzNASGybyAy12vb7PrH2OETF8-UGKCVHuFDsG4Ov3Sg@mail.gmail.com>
Message-ID: <3F946B18-9AD2-4A9B-B85A-FC9B9D13DC73@oracle.com>

Hi Roman,

I recently discovered and filed this bug:

https://bugs.openjdk.java.net/browse/JDK-8237383

Although the bug I filed is about the search index, I?m quite sure the two issues are actually one and the same. I?ll update the Jira issue to include mention of the index page. 

Thanks for reporting!

Hannes


> Am 27.01.2020 um 16:45 schrieb Roman Leventov <leventov.ru at gmail.com>:
> 
> Foo.java:
> package a;
> class Foo {
>  public void foo() {}
> }
> 
> Bar.java:
> package a;
> public class Bar extends Foo {}
> 
> in generated Javadoc site, foo() method is not listed on the index page.
> 
> I verified this with OpenJDK 11.0.3.


From pavel.rappo at oracle.com  Tue Jan 28 15:55:45 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Tue, 28 Jan 2020 15:55:45 +0000
Subject: RFR [15] 8237909: Remove zipped index files feature
Message-ID: <CBCAD155-6B70-4676-8E7A-5A3EDB904B8B@oracle.com>

Hello,

Please review the change for https://bugs.openjdk.java.net/browse/JDK-8237909:

   http://cr.openjdk.java.net/~prappo/8237909/webrev.00/

This change removes the "zipped index files" feature, which was introduced as
part of 8141492: Implement search feature in javadoc.

The "zipped index files" feature consists of generating the zipped index files
on the back end, and fetching & unzipping mechanics on the front end.

When documenting source files, the standard doclet accumulates index which is
later used by the JavaScript code serving the interactive search. The index
is written in two formats, .js (JavaScript) and .json (JSON). The latter is
then zipped.

When a browser accesses the pages using "http://" urls, the .zip index files are
transferred using XHR. Those files are then unzipped by the browser, using the
JSZip library, and parsed as JSON. If the transfer of the .zip index files fails
for whatever reason, the browser falls back on the alternative mechanism. This
mechanism transfers the .js index files by referring to them from dynamically
inserted <script src="... .js"> elements. Those files then are not additionally
parsed, as they are already data hardcoded in JavaScript code.

One of the reasons the .zip index files transfer may fail is using javadoc pages
in the "standalone" mode. When a browser accesses "file://" urls, there's no
HTTP server to send the XHR requests to. So the fallback mechanism kicks in and
the browser loads the .js index files instead.

Analysis
========

From what I understand, the original intent was to reduce the transfer size of
the index files. The observations made during the recent upgrade of JSZip
(JDK-8236700) suggest that the feature is not working as intended. It is not
clear if it ever did. The proposal is to remove it for the following reasons:

1. The feature in its current state does more harm than good (see JDK-8236922)
2. Fixing, debugging, testing, and evolving require expertise beyond that of
   typical for the javadoc area
3. The feature significantly complicates the front end and less so the back end
   code
4. The feature relies on the 3rd party libraries, which require tracking &
   periodical upgrades
5. The difference in size between the .zip and .js files is not that big (see below)
6. The index files are transferred once and then used from cache
7. Modern HTTP servers provide compression. This makes the net result
   virtually the same, compare:

                      | (current) js + zip, MB | (proposal) js files, MB
    ------------------+------------------------+------------------------
    no compression                        7.4                      5.8
    HTTP compression                      2.7                      1.4

Had this feature worked as intended, we would always transfer only the zipped
index files and the transfer size would not depend on whether the server uses
HTTP compression. But does this really outweigh the reasons stated above?

Summing all up. Removing the zipped index files feature will make the overall
interactive search feature (JDK-8141492) more robust. It will be less
complicated, have fewer dependencies (JSZip, JSZip Utils), and will push the
optimization down to HTTP.

Testing
=======

Here is how I tested this change.

1. make clean && make docs
2. Standalone test
    2.1. Opened the browser at file://...images/docs/index.html
3. HTTP test
    3.1. Started an HTTP server at build/...images/docs
    3.2. Opened the browser at http://localhost...images/docs/index.html

Browser cache was cleared each time immediately before accessing the index.html page.
In both cases I checked that no zipped index files or the related JavaScript
libraries were accessed, and that the search worked as intended.

I also tried to access the resulting javadoc pages, served by an HTTP server on
my laptop, from a couple of mobile devices, all of which were on the same WiFi
network. Everything worked as intended.

Thanks,
-Pavel


From hannes.wallnoefer at oracle.com  Tue Jan 28 17:15:20 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Tue, 28 Jan 2020 18:15:20 +0100
Subject: RFR [15] 8237909: Remove zipped index files feature
In-Reply-To: <CBCAD155-6B70-4676-8E7A-5A3EDB904B8B@oracle.com>
References: <CBCAD155-6B70-4676-8E7A-5A3EDB904B8B@oracle.com>
Message-ID: <B02F6B9D-4A2A-432D-8605-9124853244A2@oracle.com>

Hi Pavel, 

I fully concur with your reasoning for removing the jszip feature.

In script.js you left in the checks whether the *SearchIndex variables are undefined:

     if (!moduleSearchIndex) {
         ...
     }
These if-statements can be removed as the conditions will always be true (the vars are declared a few lines above but not assigned any value, so they will always be undefined). It?s ok to just invoke createElem(?) for all scripts/index files.
I also wonder if there is any benefit left in creating the script tags dynamically vs. just adding them to the pages statically. I?m fine with keeping it that way for now, but maybe we could file another issue to check if there?s any reason to keep this over static <script> tags.
Everything else looks good to me.
Hannes


> Am 28.01.2020 um 16:55 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
> 
> Hello,
> 
> Please review the change for https://bugs.openjdk.java.net/browse/JDK-8237909:
> 
>   http://cr.openjdk.java.net/~prappo/8237909/webrev.00/
> 
> This change removes the "zipped index files" feature, which was introduced as
> part of 8141492: Implement search feature in javadoc.
> 
> The "zipped index files" feature consists of generating the zipped index files
> on the back end, and fetching & unzipping mechanics on the front end.
> 
> When documenting source files, the standard doclet accumulates index which is
> later used by the JavaScript code serving the interactive search. The index
> is written in two formats, .js (JavaScript) and .json (JSON). The latter is
> then zipped.
> 
> When a browser accesses the pages using "http://" urls, the .zip index files are
> transferred using XHR. Those files are then unzipped by the browser, using the
> JSZip library, and parsed as JSON. If the transfer of the .zip index files fails
> for whatever reason, the browser falls back on the alternative mechanism. This
> mechanism transfers the .js index files by referring to them from dynamically
> inserted <script src="... .js"> elements. Those files then are not additionally
> parsed, as they are already data hardcoded in JavaScript code.
> 
> One of the reasons the .zip index files transfer may fail is using javadoc pages
> in the "standalone" mode. When a browser accesses "file://" urls, there's no
> HTTP server to send the XHR requests to. So the fallback mechanism kicks in and
> the browser loads the .js index files instead.
> 
> Analysis
> ========
> 
> From what I understand, the original intent was to reduce the transfer size of
> the index files. The observations made during the recent upgrade of JSZip
> (JDK-8236700) suggest that the feature is not working as intended. It is not
> clear if it ever did. The proposal is to remove it for the following reasons:
> 
> 1. The feature in its current state does more harm than good (see JDK-8236922)
> 2. Fixing, debugging, testing, and evolving require expertise beyond that of
>   typical for the javadoc area
> 3. The feature significantly complicates the front end and less so the back end
>   code
> 4. The feature relies on the 3rd party libraries, which require tracking &
>   periodical upgrades
> 5. The difference in size between the .zip and .js files is not that big (see below)
> 6. The index files are transferred once and then used from cache
> 7. Modern HTTP servers provide compression. This makes the net result
>   virtually the same, compare:
> 
>                      | (current) js + zip, MB | (proposal) js files, MB
>    ------------------+------------------------+------------------------
>    no compression                        7.4                      5.8
>    HTTP compression                      2.7                      1.4
> 
> Had this feature worked as intended, we would always transfer only the zipped
> index files and the transfer size would not depend on whether the server uses
> HTTP compression. But does this really outweigh the reasons stated above?
> 
> Summing all up. Removing the zipped index files feature will make the overall
> interactive search feature (JDK-8141492) more robust. It will be less
> complicated, have fewer dependencies (JSZip, JSZip Utils), and will push the
> optimization down to HTTP.
> 
> Testing
> =======
> 
> Here is how I tested this change.
> 
> 1. make clean && make docs
> 2. Standalone test
>    2.1. Opened the browser at file://...images/docs/index.html
> 3. HTTP test
>    3.1. Started an HTTP server at build/...images/docs
>    3.2. Opened the browser at http://localhost...images/docs/index.html
> 
> Browser cache was cleared each time immediately before accessing the index.html page.
> In both cases I checked that no zipped index files or the related JavaScript
> libraries were accessed, and that the search worked as intended.
> 
> I also tried to access the resulting javadoc pages, served by an HTTP server on
> my laptop, from a couple of mobile devices, all of which were on the same WiFi
> network. Everything worked as intended.
> 
> Thanks,
> -Pavel
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200128/c6aad18b/attachment.htm>

From pavel.rappo at oracle.com  Tue Jan 28 18:41:00 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Tue, 28 Jan 2020 18:41:00 +0000
Subject: RFR [15] 8237909: Remove zipped index files feature
In-Reply-To: <B02F6B9D-4A2A-432D-8605-9124853244A2@oracle.com>
References: <CBCAD155-6B70-4676-8E7A-5A3EDB904B8B@oracle.com>
 <B02F6B9D-4A2A-432D-8605-9124853244A2@oracle.com>
Message-ID: <43CAF824-DB10-4EF7-A82E-495FC9EFEEE5@oracle.com>

Hannes,

> On 28 Jan 2020, at 17:15, Hannes Walln?fer <hannes.wallnoefer at oracle.com> wrote:
> 
> Hi Pavel, 
> 
> I fully concur with your reasoning for removing the jszip feature.

Removing JSZip is incidental here. It's the whole "zipped index files" feature
that is being removed.

> In script.js you left in the checks whether the *SearchIndex variables are undefined:
> 
>      if (!moduleSearchIndex) {
>          ...
>      }
> 
> These if-statements can be removed as the conditions will always be true (the vars are declared a few lines above but not assigned any value, so they will always be undefined). It?s ok to just invoke createElem(?) for all scripts/index files.

I will remove those conditional checks, thanks.

> I also wonder if there is any benefit left in creating the script tags dynamically vs. just adding them to the pages statically. I?m fine with keeping it that way for now, but maybe we could file another issue to check if there?s any reason to keep this over static <script> tags.
> Everything else looks good to me.
> Hannes

One benefit of creating those script elements dynamically seems to be the effectively
asynchronous transfer of the .js index files. Those files should be transferred
asynchronously, no question about that. We should make this explicit, though.

I'm not a web developer, but from what I've read there is more than one way to
load a script asynchronously. I wanted to muse over all the options properly in
the context of 8236935: Improve UX of the search control, where this can be
evaluated together with the different sorts of script loading events.

   ***

I intend to let this RFR sit here for at least 2 weeks. This, hopefully, will
make it accessible to more pairs of eyes. Maybe the original authors will chime in.
The perceived severity of this change should not be underestimated.

-Pavel

>> Am 28.01.2020 um 16:55 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
>> 
>> Hello,
>> 
>> Please review the change for https://bugs.openjdk.java.net/browse/JDK-8237909:
>> 
>>   http://cr.openjdk.java.net/~prappo/8237909/webrev.00/
>> 
>> This change removes the "zipped index files" feature, which was introduced as
>> part of 8141492: Implement search feature in javadoc.
>> 
>> The "zipped index files" feature consists of generating the zipped index files
>> on the back end, and fetching & unzipping mechanics on the front end.
>> 
>> When documenting source files, the standard doclet accumulates index which is
>> later used by the JavaScript code serving the interactive search. The index
>> is written in two formats, .js (JavaScript) and .json (JSON). The latter is
>> then zipped.
>> 
>> When a browser accesses the pages using "http://" urls, the .zip index files are
>> transferred using XHR. Those files are then unzipped by the browser, using the
>> JSZip library, and parsed as JSON. If the transfer of the .zip index files fails
>> for whatever reason, the browser falls back on the alternative mechanism. This
>> mechanism transfers the .js index files by referring to them from dynamically
>> inserted <script src="... .js"> elements. Those files then are not additionally
>> parsed, as they are already data hardcoded in JavaScript code.
>> 
>> One of the reasons the .zip index files transfer may fail is using javadoc pages
>> in the "standalone" mode. When a browser accesses "file://" urls, there's no
>> HTTP server to send the XHR requests to. So the fallback mechanism kicks in and
>> the browser loads the .js index files instead.
>> 
>> Analysis
>> ========
>> 
>> From what I understand, the original intent was to reduce the transfer size of
>> the index files. The observations made during the recent upgrade of JSZip
>> (JDK-8236700) suggest that the feature is not working as intended. It is not
>> clear if it ever did. The proposal is to remove it for the following reasons:
>> 
>> 1. The feature in its current state does more harm than good (see JDK-8236922)
>> 2. Fixing, debugging, testing, and evolving require expertise beyond that of
>>   typical for the javadoc area
>> 3. The feature significantly complicates the front end and less so the back end
>>   code
>> 4. The feature relies on the 3rd party libraries, which require tracking &
>>   periodical upgrades
>> 5. The difference in size between the .zip and .js files is not that big (see below)
>> 6. The index files are transferred once and then used from cache
>> 7. Modern HTTP servers provide compression. This makes the net result
>>   virtually the same, compare:
>> 
>>                      | (current) js + zip, MB | (proposal) js files, MB
>>    ------------------+------------------------+------------------------
>>    no compression                        7.4                      5.8
>>    HTTP compression                      2.7                      1.4
>> 
>> Had this feature worked as intended, we would always transfer only the zipped
>> index files and the transfer size would not depend on whether the server uses
>> HTTP compression. But does this really outweigh the reasons stated above?
>> 
>> Summing all up. Removing the zipped index files feature will make the overall
>> interactive search feature (JDK-8141492) more robust. It will be less
>> complicated, have fewer dependencies (JSZip, JSZip Utils), and will push the
>> optimization down to HTTP.
>> 
>> Testing
>> =======
>> 
>> Here is how I tested this change.
>> 
>> 1. make clean && make docs
>> 2. Standalone test
>>    2.1. Opened the browser at file://...images/docs/index.html
>> 3. HTTP test
>>    3.1. Started an HTTP server at build/...images/docs
>>    3.2. Opened the browser at http://localhost...images/docs/index.html
>> 
>> Browser cache was cleared each time immediately before accessing the index.html page.
>> In both cases I checked that no zipped index files or the related JavaScript
>> libraries were accessed, and that the search worked as intended.
>> 
>> I also tried to access the resulting javadoc pages, served by an HTTP server on
>> my laptop, from a couple of mobile devices, all of which were on the same WiFi
>> network. Everything worked as intended.
>> 
>> Thanks,
>> -Pavel
>> 
> 


From jonathan.gibbons at oracle.com  Tue Jan 28 22:46:52 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 28 Jan 2020 14:46:52 -0800
Subject: RFR: JDK-8200363 Add javadoc command line setting to fail on warnings
Message-ID: <f5c42e97-ce8c-e1a6-fb3c-454cfa035288@oracle.com>

Please review a simple change to (finally) implement the long-overdue 
-Werror option.

The existing undocumented -Xwerror option is repurposed and renamed, and 
its behavior modified to match the javac -Werror option.? The old name 
is retained as a alias "for a while" but since it is an undocumented 
option it may be removed at any time, and perhaps in the next release 
after this change (i.e. 16.)

In the resource file, an unused property is removed, and an error 
(mismatched braces) is fixed in another.

-- Jon

JBS: https://bugs.openjdk.java.net/browse/JDK-8200460
Webrev: http://cr.openjdk.java.net/~jjg/8200363/webrev.00/


From hannes.wallnoefer at oracle.com  Wed Jan 29 09:35:40 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Wed, 29 Jan 2020 10:35:40 +0100
Subject: RFR [15] 8237909: Remove zipped index files feature
In-Reply-To: <43CAF824-DB10-4EF7-A82E-495FC9EFEEE5@oracle.com>
References: <CBCAD155-6B70-4676-8E7A-5A3EDB904B8B@oracle.com>
 <B02F6B9D-4A2A-432D-8605-9124853244A2@oracle.com>
 <43CAF824-DB10-4EF7-A82E-495FC9EFEEE5@oracle.com>
Message-ID: <251C82FF-4D78-4D34-AB28-882C31947F61@oracle.com>

Am 28.01.2020 um 19:41 schrieb Pavel Rappo <pavel.rappo at oracle.com>:
> 
> Hannes,
> 
>> On 28 Jan 2020, at 17:15, Hannes Walln?fer <hannes.wallnoefer at oracle.com> wrote:
>> 
>> Hi Pavel, 
>> 
>> I fully concur with your reasoning for removing the jszip feature.
> 
> Removing JSZip is incidental here. It's the whole "zipped index files" feature
> that is being removed.
> 

Understood.

>> In script.js you left in the checks whether the *SearchIndex variables are undefined:
>> 
>>     if (!moduleSearchIndex) {
>>         ...
>>     }
>> 
>> These if-statements can be removed as the conditions will always be true (the vars are declared a few lines above but not assigned any value, so they will always be undefined). It?s ok to just invoke createElem(?) for all scripts/index files.
> 
> I will remove those conditional checks, thanks.

Actually my analysis was not correct since the variables are defined in top-level script code while the script tag creation happens in function code, so other things could happen between execution of the two. The conclusion is still correct though since the *-search-index.js files is the only code that assign to these variables.

> 
>> I also wonder if there is any benefit left in creating the script tags dynamically vs. just adding them to the pages statically. I?m fine with keeping it that way for now, but maybe we could file another issue to check if there?s any reason to keep this over static <script> tags.
>> Everything else looks good to me.
>> Hannes
> 
> One benefit of creating those script elements dynamically seems to be the effectively
> asynchronous transfer of the .js index files. Those files should be transferred
> asynchronously, no question about that. We should make this explicit, though.
> 
> I'm not a web developer, but from what I've read there is more than one way to
> load a script asynchronously. I wanted to muse over all the options properly in
> the context of 8236935: Improve UX of the search control, where this can be
> evaluated together with the different sorts of script loading events.
> 

You?re right, async loading is probably the main benefit of loading scripts this way. It seems HTML5 provides an `async` attribute to the script tag for this purpose, and there?s also the older `defer` attribute for older browsers. I think I?ll file a separate issue for this as the implementation detail of async loading doesn?t really belong to a UX bug (unless we decide to switch to synchronous loading, which I don?t think we should).

> 
> I intend to let this RFR sit here for at least 2 weeks. This, hopefully, will
> make it accessible to more pairs of eyes. Maybe the original authors will chime in.
> The perceived severity of this change should not be underestimated.
> 

Sounds like a good plan.

Hannes

> -Pavel
> 


From hannes.wallnoefer at oracle.com  Wed Jan 29 15:18:46 2020
From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=)
Date: Wed, 29 Jan 2020 16:18:46 +0100
Subject: RFR: JDK-8200363 Add javadoc command line setting to fail on
 warnings
In-Reply-To: <f5c42e97-ce8c-e1a6-fb3c-454cfa035288@oracle.com>
References: <f5c42e97-ce8c-e1a6-fb3c-454cfa035288@oracle.com>
Message-ID: <0D6EF990-BEC5-4605-99C7-8387127A4A46@oracle.com>

Hi Jon,

This looks good. I just found a few minor things to clean up:

- in ToolOptions.java the definitions of the rejectWarnings field and method both have comments mentioning the old -Xwerror option. These should be updated to refer to the new -Werror option

- main.opt.Xold.desc property should probably also be removed from javadoc_ja.properties and javadoc-zh_CN.properties. It is also documented in share/man/javadoc.1

Hannes


> Am 28.01.2020 um 23:46 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
> 
> Please review a simple change to (finally) implement the long-overdue -Werror option.
> 
> The existing undocumented -Xwerror option is repurposed and renamed, and its behavior modified to match the javac -Werror option.  The old name is retained as a alias "for a while" but since it is an undocumented option it may be removed at any time, and perhaps in the next release after this change (i.e. 16.)
> 
> In the resource file, an unused property is removed, and an error (mismatched braces) is fixed in another.
> 
> -- Jon
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8200460
> Webrev: http://cr.openjdk.java.net/~jjg/8200363/webrev.00/
> 


From pavel.rappo at oracle.com  Wed Jan 29 15:39:13 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Wed, 29 Jan 2020 15:39:13 +0000
Subject: RFR [15] 8238167: Remove stray files from jdk.javadoc
Message-ID: <10CE1313-7F71-4943-92B1-50766496E7D6@oracle.com>

Hello,

Please review the change for https://bugs.openjdk.java.net/browse/JDK-8238167:

  http://cr.openjdk.java.net/~prappo/8238167/webrev.00/

This is a cleanup change that removes a couple of files that I have not found
to be of any use.

The first file, jquery.js, was introduced in

    changeset:   33920:bd731341c405
    user:        bpatel
    date:        Fri Nov 20 20:55:07 2015 +0000
    summary:     8141492: Implement search feature in javadoc

That same changeset also brought the jquery-1.10.2.js file. While the contents
of these files were identical, only the latter file was used. Since then both
files have been updated together, with the same content. Every time that happened,
the latter file, jquery-1.10.2.js, was simultaneously renamed to reflect the
version of the JQuery library it was updated with.
As of today, jquery.js is still not used.

The second file, help.html, is part of the test scenario. The file first appeared in

    changeset:   36705:890c250d8da8
    parent:      36503:4a95f4b1bd8b
    user:        ksrini
    date:        Mon Mar 14 15:04:57 2016 -0700
    summary:     8071982: Update tests for revamped Doclet API

I flagged this file as suspicious while testing the change for 8237909: Remove
zipped index files feature. I noticed that the TestOptions test did not seem to
care whether the JSZip library was present or not, despite the fact that its
resource, help.html, explicitly referred to that library. Further investigation
showed that this file was never used by that test, or anyone for that matter.
The javadoc tool has only a handful of "help" options:

    javadoc -help | grep help
        --help, -help, -?, -h
        --help-extra, -X
        -helpfile <file>
                      Include file that help link links to
        -nohelp       Do not generate help link

all of which are covered by the TestHelpOption and TestXOption tests. There
doesn't seem to be any need in testing anything related to "help" options in
TestOptions. Its @summary, otherwise very specific, certainly doesn't mention
anything like that.

    ***

Both files, jquery.js and help.html, have been diligently updated over the
years. They seem to be leftovers from the development stage. Since they are not
used, updating those files is a burden to maintainers and provides nothing in
return. I propose to delete them.

All javadoc tests pass, and the functionality of the generated pages
seems to be intact.

Thanks,
-Pavel


From jonathan.gibbons at oracle.com  Wed Jan 29 17:19:39 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 29 Jan 2020 09:19:39 -0800
Subject: RFR [15] 8238167: Remove stray files from jdk.javadoc
In-Reply-To: <10CE1313-7F71-4943-92B1-50766496E7D6@oracle.com>
References: <10CE1313-7F71-4943-92B1-50766496E7D6@oracle.com>
Message-ID: <8f373b93-01b2-f17d-6ca4-7cbc0461cce0@oracle.com>

+1

On 1/29/20 7:39 AM, Pavel Rappo wrote:
> Hello,
>
> Please review the change for https://bugs.openjdk.java.net/browse/JDK-8238167:
>
>    http://cr.openjdk.java.net/~prappo/8238167/webrev.00/
>
> This is a cleanup change that removes a couple of files that I have not found
> to be of any use.
>
> The first file, jquery.js, was introduced in
>
>      changeset:   33920:bd731341c405
>      user:        bpatel
>      date:        Fri Nov 20 20:55:07 2015 +0000
>      summary:     8141492: Implement search feature in javadoc
>
> That same changeset also brought the jquery-1.10.2.js file. While the contents
> of these files were identical, only the latter file was used. Since then both
> files have been updated together, with the same content. Every time that happened,
> the latter file, jquery-1.10.2.js, was simultaneously renamed to reflect the
> version of the JQuery library it was updated with.
> As of today, jquery.js is still not used.
>
> The second file, help.html, is part of the test scenario. The file first appeared in
>
>      changeset:   36705:890c250d8da8
>      parent:      36503:4a95f4b1bd8b
>      user:        ksrini
>      date:        Mon Mar 14 15:04:57 2016 -0700
>      summary:     8071982: Update tests for revamped Doclet API
>
> I flagged this file as suspicious while testing the change for 8237909: Remove
> zipped index files feature. I noticed that the TestOptions test did not seem to
> care whether the JSZip library was present or not, despite the fact that its
> resource, help.html, explicitly referred to that library. Further investigation
> showed that this file was never used by that test, or anyone for that matter.
> The javadoc tool has only a handful of "help" options:
>
>      javadoc -help | grep help
>          --help, -help, -?, -h
>          --help-extra, -X
>          -helpfile <file>
>                        Include file that help link links to
>          -nohelp       Do not generate help link
>
> all of which are covered by the TestHelpOption and TestXOption tests. There
> doesn't seem to be any need in testing anything related to "help" options in
> TestOptions. Its @summary, otherwise very specific, certainly doesn't mention
> anything like that.
>
>      ***
>
> Both files, jquery.js and help.html, have been diligently updated over the
> years. They seem to be leftovers from the development stage. Since they are not
> used, updating those files is a burden to maintainers and provides nothing in
> return. I propose to delete them.
>
> All javadoc tests pass, and the functionality of the generated pages
> seems to be intact.
>
> Thanks,
> -Pavel
>

From jonathan.gibbons at oracle.com  Wed Jan 29 18:06:26 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 29 Jan 2020 10:06:26 -0800
Subject: RFR: JDK-8200363 Add javadoc command line setting to fail on
 warnings
In-Reply-To: <0D6EF990-BEC5-4605-99C7-8387127A4A46@oracle.com>
References: <f5c42e97-ce8c-e1a6-fb3c-454cfa035288@oracle.com>
 <0D6EF990-BEC5-4605-99C7-8387127A4A46@oracle.com>
Message-ID: <3ee0c7d2-4291-c54f-1d2c-75d0e7ac7da2@oracle.com>


On 1/29/20 7:18 AM, Hannes Walln?fer wrote:
> - main.opt.Xold.desc property should probably also be removed from javadoc_ja.properties and javadoc-zh_CN.properties. It is also documented in share/man/javadoc.1

Hannes,

The general policy, for all JDK resource files, is that developers need 
not update the localized versions of resource files.? These updates 
happen "automagically", by the L10N team, when they update the localized 
files.

-- Jon


From jonathan.gibbons at oracle.com  Wed Jan 29 20:21:22 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 29 Jan 2020 12:21:22 -0800
Subject: RFR: JDK-8200363 Add javadoc command line setting to fail on
 warnings
In-Reply-To: <0D6EF990-BEC5-4605-99C7-8387127A4A46@oracle.com>
References: <f5c42e97-ce8c-e1a6-fb3c-454cfa035288@oracle.com>
 <0D6EF990-BEC5-4605-99C7-8387127A4A46@oracle.com>
Message-ID: <60cfbfef-c481-efa0-8c31-a338feecd649@oracle.com>

Hannes,

Thanks for catching the references to Xwerror in comments. Fixed, new 
webrev uploaded.? I will leave the localized resource files to be 
updated by the L10N team and their tools.

No other changes in the webrev.

-- Jon

Webrev: http://cr.openjdk.java.net/~jjg/8200363/webrev.01/


On 01/29/2020 07:18 AM, Hannes Walln?fer wrote:
> Hi Jon,
>
> This looks good. I just found a few minor things to clean up:
>
> - in ToolOptions.java the definitions of the rejectWarnings field and method both have comments mentioning the old -Xwerror option. These should be updated to refer to the new -Werror option
>
> - main.opt.Xold.desc property should probably also be removed from javadoc_ja.properties and javadoc-zh_CN.properties. It is also documented in share/man/javadoc.1
>
> Hannes
>
>
>> Am 28.01.2020 um 23:46 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>>
>> Please review a simple change to (finally) implement the long-overdue -Werror option.
>>
>> The existing undocumented -Xwerror option is repurposed and renamed, and its behavior modified to match the javac -Werror option.  The old name is retained as a alias "for a while" but since it is an undocumented option it may be removed at any time, and perhaps in the next release after this change (i.e. 16.)
>>
>> In the resource file, an unused property is removed, and an error (mismatched braces) is fixed in another.
>>
>> -- Jon
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8200460
>> Webrev: http://cr.openjdk.java.net/~jjg/8200363/webrev.00/
>>


From jonathan.gibbons at oracle.com  Thu Jan 30 01:25:39 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 29 Jan 2020 17:25:39 -0800
Subject: RFR: JDK-8236949: javadoc -Xdoclint does not accumulate options
 correctly
Message-ID: <60d68bd0-a08a-c81e-1dd4-7051fb586c22@oracle.com>

Please review a moderately simple fix to a regression in the way that 
javadoc handles doclint options.

The feature was introduced in JDK 8, and at that time, the doclet 
options were accumulated in a list.

The regression was introduced when the standard doclet was rewritten in 
JDK 9, and perhaps because of the introduction of other new doclint 
options, the options were changed to accumulate in a map, with "last one 
wins" semantics for like-named options. This is the root cause of this 
issue.

The fix is to revert to accumulating options in a list, as originally 
intended. In addition, the detection of whether doclint should be 
enabled or not is improved, compared to JDK 8, such that doclint is only 
enabled if either specific groups or all groups are enabled. Previously, 
it would only be disabled if just -Xdoclint:none was specified.

The penance for not writing a better unit test in JDK 8 is to write a 
better regression test now.? One other test (added in JDK 9) was relying 
on the bug, and needed to be updated.

In this changeset ...

HtmlConfiguration.java ... the collection is changed to a list

HtmlOptions ... the options are transformed into doclint options (as 
before) and accumulated in the list, but only if they pass the initial 
check. There is also some minor cleanup ... the option for 
-Xdocrootparent is moved out of the group of doclint options, and some 
minor warnings highlighted by the IDE were fixed.

WorkArounds ... the primary change here is better analysis of the 
doclint options to determine if doclint should be enabled. Comments are 
added, and the "TODO: fix this up correctly" is removed ;-)

The new test uses a source file that will trigger different doclint 
diagnostics, depending on which are enabled. It then runs javadoc with 
different doclint options to verify that (just) the expected diagnostics 
are generated.

-- Jon


JBS: https://bugs.openjdk.java.net/browse/JDK-8236949
Webrev: http://cr.openjdk.java.net/~jjg/8236949/webrev.00/


From pavel.rappo at oracle.com  Thu Jan 30 15:38:01 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Thu, 30 Jan 2020 15:38:01 +0000
Subject: RFR: JDK-8236949: javadoc -Xdoclint does not accumulate options
 correctly
In-Reply-To: <60d68bd0-a08a-c81e-1dd4-7051fb586c22@oracle.com>
References: <60d68bd0-a08a-c81e-1dd4-7051fb586c22@oracle.com>
Message-ID: <FE6D0C16-B4B2-44AB-9F50-085FD430EB75@oracle.com>

> On 30 Jan 2020, at 01:25, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Please review a moderately simple fix to a regression in the way that javadoc handles doclint options.
> 
> The feature was introduced in JDK 8, and at that time, the doclet options were accumulated in a list.
> 
> The regression was introduced when the standard doclet was rewritten in JDK 9, and perhaps because of the introduction of other new doclint options, the options were changed to accumulate in a map, with "last one wins" semantics for like-named options. This is the root cause of this issue.

Right. Arguments of an option are keyed by the instance, of the XOption type,
that handles this option. Like-named options are handled by the same instance of
the XOption type. Hence, when two sets of like-named options' arguments are
keyed, one of these sets is effectively overwritten.

This didn't necessarily mean we needed to do away with the map, we could use
`merge` or similar. But I agree with this change. We should keep it simple.

Nit. Could you please remove these (now obsolete) imports?

    import java.util.LinkedHashMap;
    import java.util.Map;

> The fix is to revert to accumulating options in a list, as originally intended. In addition, the detection of whether doclint should be enabled or not is improved, compared to JDK 8, such that doclint is only enabled if either specific groups or all groups are enabled. Previously, it would only be disabled if just -Xdoclint:none was specified.

Yes, current behavior seems be short-circuited by a stand-alone occurrence of
"none" (i.e. "-Xdoclint:none"). The proposed behavior always parses arguments
to completion, left to right. Is it expected behavior? Does javac do the same?

On a related note. I seem to understand how this code works. Still, why not
delegate options processing to DocLint itself? Is it because javadoc only
accepts a *subset* of DocLint options (e.g. no access qualifiers), or there
are other reasons?

> The penance for not writing a better unit test in JDK 8 is to write a better regression test now.

I think I dislike that the implementation package was added for the sake of
reusing the com.sun.tools.doclint.Messages.Group enum, but it is not that big
of a problem. It just makes the test "gray-box".

> One other test (added in JDK 9) was relying on the bug, and needed to be updated.
> 
> In this changeset ...
> 
> HtmlConfiguration.java ... the collection is changed to a list
> 
> HtmlOptions ... the options are transformed into doclint options (as before) and accumulated in the list, but only if they pass the initial check. There is also some minor cleanup ... the option for -Xdocrootparent is moved out of the group of doclint options, and some minor warnings highlighted by the IDE were fixed.

Thanks for incremental improvements and miscellaneous cleanup!

  180    doclint.init(t, doclintOpts.toArray(new String[0]), false);

What was the reason for changing this?

> WorkArounds ... the primary change here is better analysis of the doclint options to determine if doclint should be enabled. Comments are added, and the "TODO: fix this up correctly" is removed ;-)
> 
> The new test uses a source file that will trigger different doclint diagnostics, depending on which are enabled. It then runs javadoc with different doclint options to verify that (just) the expected diagnostics are generated.
> 
> -- Jon
> 
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8236949
> Webrev: http://cr.openjdk.java.net/~jjg/8236949/webrev.00/

It would be nice if the original reporter could confirm this changeset solves
their issue (this email is CC'ed to them).

Looks good.

-Pavel




From jonathan.gibbons at oracle.com  Thu Jan 30 17:56:19 2020
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 30 Jan 2020 09:56:19 -0800
Subject: RFR: JDK-8236949: javadoc -Xdoclint does not accumulate options
 correctly
In-Reply-To: <FE6D0C16-B4B2-44AB-9F50-085FD430EB75@oracle.com>
References: <60d68bd0-a08a-c81e-1dd4-7051fb586c22@oracle.com>
 <FE6D0C16-B4B2-44AB-9F50-085FD430EB75@oracle.com>
Message-ID: <bdbc9786-f8d6-78a9-8d02-1d9cd0ab1387@oracle.com>



On 01/30/2020 07:38 AM, Pavel Rappo wrote:
>> On 30 Jan 2020, at 01:25, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Please review a moderately simple fix to a regression in the way that javadoc handles doclint options.
>>
>> The feature was introduced in JDK 8, and at that time, the doclet options were accumulated in a list.
>>
>> The regression was introduced when the standard doclet was rewritten in JDK 9, and perhaps because of the introduction of other new doclint options, the options were changed to accumulate in a map, with "last one wins" semantics for like-named options. This is the root cause of this issue.
> Right. Arguments of an option are keyed by the instance, of the XOption type,
> that handles this option. Like-named options are handled by the same instance of
> the XOption type. Hence, when two sets of like-named options' arguments are
> keyed, one of these sets is effectively overwritten.
>
> This didn't necessarily mean we needed to do away with the map, we could use
> `merge` or similar. But I agree with this change. We should keep it simple.

If we were to keep the map, it would most naturally be a Map<Option, 
List<String>>
but even that is suspect for losing the ordering between -Xmsgs 
and-Xmsgs:...
>
> Nit. Could you please remove these (now obsolete) imports?
>
>      import java.util.LinkedHashMap;
>      import java.util.Map;

Done, also jdk.javadoc.doclet.Doclet;
>> The fix is to revert to accumulating options in a list, as originally intended. In addition, the detection of whether doclint should be enabled or not is improved, compared to JDK 8, such that doclint is only enabled if either specific groups or all groups are enabled. Previously, it would only be disabled if just -Xdoclint:none was specified.
> Yes, current behavior seems be short-circuited by a stand-alone occurrence of
> "none" (i.e. "-Xdoclint:none"). The proposed behavior always parses arguments
> to completion, left to right. Is it expected behavior? Does javac do the same?

javac does not do the short-circuit and also parses left to right.

>
> On a related note. I seem to understand how this code works. Still, why not
> delegate options processing to DocLint itself? Is it because javadoc only
> accepts a *subset* of DocLint options (e.g. no access qualifiers), or there
> are other reasons?

It's true that javadoc only accepts a subset of options: the "no access 
qualifiers"
is to avoid conflicts with javadoc acces options, like -private, 
-protected etc.
Put another way, javac's doclint options do leverage access qualifiers, 
because
javac does not have the equivalent of javadoc's access options.

javadoc also wants to avoid using doclint if it is disabled. For javac, 
doclint is
opt-in, for javadoc it is opt-out such that it is not initialized if the 
user opts out.

The design of doclint is to use string-based options. If we were to 
change anything,
I would open up a new interface in doclint to allow options to be set 
directly via
API, but that is beyond the scope of this changeset. That also ties into the
separate architectural issue of "which module does doclint live in?"

>
>> The penance for not writing a better unit test in JDK 8 is to write a better regression test now.
> I think I dislike that the implementation package was added for the sake of
> reusing the com.sun.tools.doclint.Messages.Group enum, but it is not that big
> of a problem. It just makes the test "gray-box".

This was somewhat deliberate, so that the test could leverage 
EnumSet.allOf(Group.class)
but maybe that's not so important, since it is explicit in other ways 
what the kinds of
diagnostic are, and there is no check in this test that we have full 
coverage of the Group
enum. That's a technique I sometimes use in other tests.

>
>> One other test (added in JDK 9) was relying on the bug, and needed to be updated.
>>
>> In this changeset ...
>>
>> HtmlConfiguration.java ... the collection is changed to a list
>>
>> HtmlOptions ... the options are transformed into doclint options (as before) and accumulated in the list, but only if they pass the initial check. There is also some minor cleanup ... the option for -Xdocrootparent is moved out of the group of doclint options, and some minor warnings highlighted by the IDE were fixed.
> Thanks for incremental improvements and miscellaneous cleanup!
>
>    180    doclint.init(t, doclintOpts.toArray(new String[0]), false);
>
> What was the reason for changing this?

The IDE suggested it. Conventional wisdom these days is that it is 
(surprisingly)
more efficient to use an array size of 0.

>
>> WorkArounds ... the primary change here is better analysis of the doclint options to determine if doclint should be enabled. Comments are added, and the "TODO: fix this up correctly" is removed ;-)
>>
>> The new test uses a source file that will trigger different doclint diagnostics, depending on which are enabled. It then runs javadoc with different doclint options to verify that (just) the expected diagnostics are generated.
>>
>> -- Jon
>>
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8236949
>> Webrev: http://cr.openjdk.java.net/~jjg/8236949/webrev.00/
> It would be nice if the original reporter could confirm this changeset solves
> their issue (this email is CC'ed to them).
>
> Looks good.
>
> -Pavel
>
>
>


From pavel.rappo at oracle.com  Thu Jan 30 19:13:59 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Thu, 30 Jan 2020 19:13:59 +0000
Subject: RFR [15] 8238167: Remove stray files from jdk.javadoc
In-Reply-To: <10CE1313-7F71-4943-92B1-50766496E7D6@oracle.com>
References: <10CE1313-7F71-4943-92B1-50766496E7D6@oracle.com>
Message-ID: <4B47CF25-B2A3-47C6-A2C9-015517C8DCF1@oracle.com>

Only after this changeset had been pushed, did it occur to me to have a look at
the actual release of the JQuery UI library. I downloaded and unzipped
jquery-ui-1.12.1.zip file, which had the following structure:

    +- AUTHORS.txt
    +- LICENSE.txt
    +- external
    |   +- jquery
(!) |       +- jquery.js
    +- images
    |   +- ui-icons_444444_256x240.png
    |   +- ui-icons_555555_256x240.png
    |   +- ui-icons_777620_256x240.png
    |   +- ui-icons_777777_256x240.png
    |   +- ui-icons_cc0000_256x240.png
    |   +- ui-icons_ffffff_256x240.png
    +- index.html
    +- jquery-ui.css
    +- jquery-ui.js
    +- jquery-ui.min.css
    +- jquery-ui.min.js
    +- jquery-ui.structure.css
    +- jquery-ui.structure.min.css
    +- jquery-ui.theme.css
    +- jquery-ui.theme.min.css
    +- package.json

Note that jquery.js file. This might solve the mystery of where this file came
from. So it might not be some random "leftover from the development stage",
I called it earlier, but a JQuery library that this JQuery UI library depends on.
Silly me!

It looks like the initial changeset

    changeset:   33920:bd731341c405
    user:        bpatel
    date:        Fri Nov 20 20:55:07 2015 +0000
    summary:     8141492: Implement search feature in javadoc

brought several JS libraries "squashed" under the script-dir directory, JSZip,
JSZipUtils, JQuery, and JQuery UI. This and the fact that both the jquery.js
and jquery-1.10.2.js files had the same contents, might have confused the people
who performed subsequent upgrades of those libraries. (It certainly confused me!)

At least this would explain why the top-level jquery.js file, the one we use,
has been always updated in parallel with external/jquery/jquery.js, a JQuery's
own dependency, that we have never used.

Yet, JQuery UI depends on JQuery. I'm not sure if we are lucky and JQuery UI
"just works" with our version of JQuery or it's that JQuery UI 1.12 indeed works
with any JQuery 1.7+ library out there, as that project states on its site.

That said, the changeset that was pushed yesterday does NOT break anything.
I just felt I had to convey these further findings for the sake of future
maintainers.

I should probably file a follow-up bug that deals with tidying of all that
JS mess.

-Pavel

> On 29 Jan 2020, at 15:39, Pavel Rappo <pavel.rappo at oracle.com> wrote:
> 
> Hello,
> 
> Please review the change for https://bugs.openjdk.java.net/browse/JDK-8238167:
> 
>  http://cr.openjdk.java.net/~prappo/8238167/webrev.00/
> 
> This is a cleanup change that removes a couple of files that I have not found
> to be of any use.
> 
> The first file, jquery.js, was introduced in
> 
>    changeset:   33920:bd731341c405
>    user:        bpatel
>    date:        Fri Nov 20 20:55:07 2015 +0000
>    summary:     8141492: Implement search feature in javadoc
> 
> That same changeset also brought the jquery-1.10.2.js file. While the contents
> of these files were identical, only the latter file was used. Since then both
> files have been updated together, with the same content. Every time that happened,
> the latter file, jquery-1.10.2.js, was simultaneously renamed to reflect the
> version of the JQuery library it was updated with.
> As of today, jquery.js is still not used.
> 
> The second file, help.html, is part of the test scenario. The file first appeared in
> 
>    changeset:   36705:890c250d8da8
>    parent:      36503:4a95f4b1bd8b
>    user:        ksrini
>    date:        Mon Mar 14 15:04:57 2016 -0700
>    summary:     8071982: Update tests for revamped Doclet API
> 
> I flagged this file as suspicious while testing the change for 8237909: Remove
> zipped index files feature. I noticed that the TestOptions test did not seem to
> care whether the JSZip library was present or not, despite the fact that its
> resource, help.html, explicitly referred to that library. Further investigation
> showed that this file was never used by that test, or anyone for that matter.
> The javadoc tool has only a handful of "help" options:
> 
>    javadoc -help | grep help
>        --help, -help, -?, -h
>        --help-extra, -X
>        -helpfile <file>
>                      Include file that help link links to
>        -nohelp       Do not generate help link
> 
> all of which are covered by the TestHelpOption and TestXOption tests. There
> doesn't seem to be any need in testing anything related to "help" options in
> TestOptions. Its @summary, otherwise very specific, certainly doesn't mention
> anything like that.
> 
>    ***
> 
> Both files, jquery.js and help.html, have been diligently updated over the
> years. They seem to be leftovers from the development stage. Since they are not
> used, updating those files is a burden to maintainers and provides nothing in
> return. I propose to delete them.
> 
> All javadoc tests pass, and the functionality of the generated pages
> seems to be intact.
> 
> Thanks,
> -Pavel
> 


From pavel.rappo at oracle.com  Fri Jan 31 13:47:14 2020
From: pavel.rappo at oracle.com (Pavel Rappo)
Date: Fri, 31 Jan 2020 13:47:14 +0000
Subject: RFR [15] 8238291: Fix inconsistencies in the format of the index files
Message-ID: <000ADF89-F5F9-4E81-8D6A-034C09454B41@oracle.com>

Hello,

Please review the change for https://bugs.openjdk.java.net/browse/JDK-8238291:

  http://cr.openjdk.java.net/~prappo/8238291/webrev.00/

This is a tiny cleanup change. The goal is to fix inconsistency in abbreviating
the fields of the index structure.

The fields of the index structure, such as "label", "containingModule",
"containingPackage", "containingClass", "holder", and "description" are
abbreviated in the index files to a single letter, "l", "m", "p", "c", "h", and
"d" respectively. The "url" field is not. Sometimes it is referred to as "u",
other times as "url".

From my archival research it seems that this peculiarity has been there from day 1. 
While "url" was used for indexing packages, types, members, and then modules,
"u" was used for everything else, which back then comprised the "search tags"
category. I couldn't find any evidence of that being done for some purpose.
I do believe it's just a typo, thus I propose to fix it.

Incidentally, this change reduces the size of the index files. In case you
wonder the reduction is 1% (one percent), otherwise known as "not something to
brag about".

Thanks,
-Pavel