RFR: JDK-8194955: Warn when default HTML version is used

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

RFR: JDK-8194955: Warn when default HTML version is used

Jonathan Gibbons
Please review a simple fix to generate a warning when the user does not
explicitly specify whether to use HTML 4.01 or HTML5. The default is
(still) HTML 4.01, but is planned to be changed in an upcoming release,
such as JDK 11.

Users should ensure that they specify the version of HTML used in
their doc comments, and which will be used for the generated output.

The change to the tool is very simple.  A new test is added that is specific
to this feature. A small number of other tests that are sensitive to the
number
of warnings generated have been updated to avoid generating the warning.

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

-- Jon
Reply | Threaded
Open this post in threaded view
|

Re: RFR: JDK-8194955: Warn when default HTML version is used

Kumar Srinivasan
Hi Jon,

Generally the changes looks good to me.

One observation though, otherwise ok.

TestHtmlWarning.java:
I think that test should either create discrete directories for its output
or the test should delete all of its output, upon completion.
Running output comparators may yield false positives, as the execution
sequence of  sub-tests is not deterministic.

Kumar


On 1/11/2018 6:21 PM, Jonathan Gibbons wrote:
Please review a simple fix to generate a warning when the user does not
explicitly specify whether to use HTML 4.01 or HTML5. The default is
(still) HTML 4.01, but is planned to be changed in an upcoming release,
such as JDK 11.

Users should ensure that they specify the version of HTML used in
their doc comments, and which will be used for the generated output.

The change to the tool is very simple.  A new test is added that is specific
to this feature. A small number of other tests that are sensitive to the number
of warnings generated have been updated to avoid generating the warning.

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

-- Jon

Reply | Threaded
Open this post in threaded view
|

Re: RFR: JDK-8194955: Warn when default HTML version is used

Bhavesh Patel

Looks good.

Regards,
Bhavesh.

On 1/12/2018 7:01 AM, Kumar Srinivasan wrote:
Hi Jon,

Generally the changes looks good to me.

One observation though, otherwise ok.

TestHtmlWarning.java:
I think that test should either create discrete directories for its output
or the test should delete all of its output, upon completion.
Running output comparators may yield false positives, as the execution
sequence of  sub-tests is not deterministic.

Kumar


On 1/11/2018 6:21 PM, Jonathan Gibbons wrote:
Please review a simple fix to generate a warning when the user does not
explicitly specify whether to use HTML 4.01 or HTML5. The default is
(still) HTML 4.01, but is planned to be changed in an upcoming release,
such as JDK 11.

Users should ensure that they specify the version of HTML used in
their doc comments, and which will be used for the generated output.

The change to the tool is very simple.  A new test is added that is specific
to this feature. A small number of other tests that are sensitive to the number
of warnings generated have been updated to avoid generating the warning.

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

-- Jon


Reply | Threaded
Open this post in threaded view
|

Re: RFR: JDK-8194955: Warn when default HTML version is used

Jonathan Gibbons
In reply to this post by Kumar Srinivasan



On 1/12/18 7:01 AM, Kumar Srinivasan wrote:

TestHtmlWarning.java:
I think that test should either create discrete directories for its output
or the test should delete all of its output, upon completion.
Running output comparators may yield false positives, as the execution
sequence of  sub-tests is not deterministic.
Kumar,

The test does create separate output directories.
  54     void testHtml4() {
  55         javadoc("-d", "out-4",

  64     void testHtml5() {
  65         javadoc("-d", "out-5",

  74     void testDefault() {
  75         javadoc("-d", "out-default",

Furthermore, in this test, the output checks are on the output stream produced by javadoc, and not on any files, and so the output directory is somewhat irrelevant.

-- Jon



Reply | Threaded
Open this post in threaded view
|

Re: RFR: JDK-8194955: Warn when default HTML version is used

Kumar Srinivasan
Hi Jon,

Yes, sorry my error, it looks good.!

Kumar



On 1/12/18 7:01 AM, Kumar Srinivasan wrote:

TestHtmlWarning.java:
I think that test should either create discrete directories for its output
or the test should delete all of its output, upon completion.
Running output comparators may yield false positives, as the execution
sequence of  sub-tests is not deterministic.
Kumar,

The test does create separate output directories.
  54     void testHtml4() {
  55         javadoc("-d", "out-4",

  64     void testHtml5() {
  65         javadoc("-d", "out-5",

  74     void testDefault() {
  75         javadoc("-d", "out-default",

Furthermore, in this test, the output checks are on the output stream produced by javadoc, and not on any files, and so the output directory is somewhat irrelevant.

-- Jon