RFR: 8187521: In some corner cases the javadoc tool can reuse id attribute

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

RFR: 8187521: In some corner cases the javadoc tool can reuse id attribute

Jonathan Gibbons
Please review this fix regarding the handling of ID values generated by
the standard javadoc doclet.

The root cause of the specific issue is a corner case in Java. A class
may contain a method
with the same name as the enclosing class, and any corresponding
constructor.

The fix is to use a different name for the name of the constructor that
cannot clash with
any method name, with `<init>` being the obvious choice.

The fix is restricted, along with some other changes, to when generating
HTML5 docs.
There are other problems with IDs/anchor names when using HTML 4.01,
which are all
better addressed by using HTML5, leaving support for HTML 4.01 unchanged
at this point.

In HTML5, there are no restrictions on the individual characters in an
ID other than to prohibit
whitespace. Therefore, there is no longer any need to use the
javadoc-specific encoding
using `:` and `-` to encode otherwise invalid characters. Thus, the ID
for a member of the class
is just the signature of the member: the name for a field, the name and
parameter-type list
for a method, and `<init>` and parameter-type list for a constructor.

Finally, because this opens up the possibility of square brackets
appearing in a signature
(where previously "[]" was encoded as ":A"), the encoding of URLs which
have fragments
containing [] had to be improved, by using the standard URL %-encoding
for these characters.

The tests are updated, with additional tests being added for members
with non-ASCII
identifiers, to verify that IDs and defined and referenced correctly.

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

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

RFR: 8169819: minor cleanup for deprecated page

Bhavesh Patel
Hi,
     Can you please review the fix for JDK-8169819? The fix consists of
3 small fixes combined together for deprecated list page clean up

1) In the Contents and other sections in the deprecated list page, we
have removed the word "Deprecated" from the label.
2) The table contents are not sorted correctly when fully-qualified
names are listed. I have fixed it so that the names are sorted correctly.
3) The table column, specially for methods and constructors, do not wrap
correctly. I have fixed it and have also added the zero-width-space on
those columns.

Webrev:
http://sc11152716.us.oracle.com/people/bhavesh/scratch/bhavespa/review/8169819/webrev/
Test build:
http://sc11152716.us.oracle.com/people/bhavesh/scratch/bhavespa/mst-8169819/build/solaris-x86_64-normal-server-release/images/docs/api/overview-summary.html

Regards,
Bhavesh.
Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8187521: In some corner cases the javadoc tool can reuse id attribute

Jonathan Gibbons
In reply to this post by Jonathan Gibbons
Updated patch to address a test failure on Windows.

The test failure was specifically caused by a defensive check on the
default platform encoding.
The fix for that test failure is to enhance JavadocTester to determine
the file encoding used to
write files, and to use that when reading files in order to check their
content.

That enhancement to JavadocTester triggered the need to update another
test, TestDocEncoding.java.
which can now do a better job because of the better suport for using the
correct doc encoding.

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

-- Jon

On 09/26/2017 03:21 PM, Jonathan Gibbons wrote:

> Please review this fix regarding the handling of ID values generated
> by the standard javadoc doclet.
>
> The root cause of the specific issue is a corner case in Java. A class
> may contain a method
> with the same name as the enclosing class, and any corresponding
> constructor.
>
> The fix is to use a different name for the name of the constructor
> that cannot clash with
> any method name, with `<init>` being the obvious choice.
>
> The fix is restricted, along with some other changes, to when
> generating HTML5 docs.
> There are other problems with IDs/anchor names when using HTML 4.01,
> which are all
> better addressed by using HTML5, leaving support for HTML 4.01
> unchanged at this point.
>
> In HTML5, there are no restrictions on the individual characters in an
> ID other than to prohibit
> whitespace. Therefore, there is no longer any need to use the
> javadoc-specific encoding
> using `:` and `-` to encode otherwise invalid characters. Thus, the ID
> for a member of the class
> is just the signature of the member: the name for a field, the name
> and parameter-type list
> for a method, and `<init>` and parameter-type list for a constructor.
>
> Finally, because this opens up the possibility of square brackets
> appearing in a signature
> (where previously "[]" was encoded as ":A"), the encoding of URLs
> which have fragments
> containing [] had to be improved, by using the standard URL %-encoding
> for these characters.
>
> The tests are updated, with additional tests being added for members
> with non-ASCII
> identifiers, to verify that IDs and defined and referenced correctly.
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.00/index.html
>
> -- Jon

Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8187521: In some corner cases the javadoc tool can reuse id attribute

Kumar Srinivasan
Jon,

Looks good with a caveat, suggest a comment:
testDocEncoding.java

+        checkOutput("stylesheet.css", true,
+                "body {\n"
+                + "    background-color:#ffffff;");
+
+        charset = Charset.forName("UTF-8");   <--- this line needs an explanation comment.

I don't need to see another iteration.

Kumar



> Updated patch to address a test failure on Windows.
>
> The test failure was specifically caused by a defensive check on the
> default platform encoding.
> The fix for that test failure is to enhance JavadocTester to determine
> the file encoding used to
> write files, and to use that when reading files in order to check
> their content.
>
> That enhancement to JavadocTester triggered the need to update another
> test, TestDocEncoding.java.
> which can now do a better job because of the better suport for using
> the correct doc encoding.
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.01/index.html
>
> -- Jon
>
> On 09/26/2017 03:21 PM, Jonathan Gibbons wrote:
>> Please review this fix regarding the handling of ID values generated
>> by the standard javadoc doclet.
>>
>> The root cause of the specific issue is a corner case in Java. A
>> class may contain a method
>> with the same name as the enclosing class, and any corresponding
>> constructor.
>>
>> The fix is to use a different name for the name of the constructor
>> that cannot clash with
>> any method name, with `<init>` being the obvious choice.
>>
>> The fix is restricted, along with some other changes, to when
>> generating HTML5 docs.
>> There are other problems with IDs/anchor names when using HTML 4.01,
>> which are all
>> better addressed by using HTML5, leaving support for HTML 4.01
>> unchanged at this point.
>>
>> In HTML5, there are no restrictions on the individual characters in
>> an ID other than to prohibit
>> whitespace. Therefore, there is no longer any need to use the
>> javadoc-specific encoding
>> using `:` and `-` to encode otherwise invalid characters. Thus, the
>> ID for a member of the class
>> is just the signature of the member: the name for a field, the name
>> and parameter-type list
>> for a method, and `<init>` and parameter-type list for a constructor.
>>
>> Finally, because this opens up the possibility of square brackets
>> appearing in a signature
>> (where previously "[]" was encoded as ":A"), the encoding of URLs
>> which have fragments
>> containing [] had to be improved, by using the standard URL
>> %-encoding for these characters.
>>
>> The tests are updated, with additional tests being added for members
>> with non-ASCII
>> identifiers, to verify that IDs and defined and referenced correctly.
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
>> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.00/index.html
>>
>> -- Jon
>

Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8187521: In some corner cases the javadoc tool can reuse id attribute

Jonathan Gibbons
Updated webrev, with comment added:
http://cr.openjdk.java.net/~jjg/8187521/webrev.02

-- Jon

On 09/29/2017 01:34 PM, Kumar Srinivasan wrote:

> Jon,
>
> Looks good with a caveat, suggest a comment:
> testDocEncoding.java
>
> +        checkOutput("stylesheet.css", true,
> +                "body {\n"
> +                + "    background-color:#ffffff;");
> +
> +        charset = Charset.forName("UTF-8");   <--- this line needs an
> explanation comment.
>
> I don't need to see another iteration.
>
> Kumar
>
>
>
>> Updated patch to address a test failure on Windows.
>>
>> The test failure was specifically caused by a defensive check on the
>> default platform encoding.
>> The fix for that test failure is to enhance JavadocTester to
>> determine the file encoding used to
>> write files, and to use that when reading files in order to check
>> their content.
>>
>> That enhancement to JavadocTester triggered the need to update
>> another test, TestDocEncoding.java.
>> which can now do a better job because of the better suport for using
>> the correct doc encoding.
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
>> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.01/index.html
>>
>> -- Jon
>>
>> On 09/26/2017 03:21 PM, Jonathan Gibbons wrote:
>>> Please review this fix regarding the handling of ID values generated
>>> by the standard javadoc doclet.
>>>
>>> The root cause of the specific issue is a corner case in Java. A
>>> class may contain a method
>>> with the same name as the enclosing class, and any corresponding
>>> constructor.
>>>
>>> The fix is to use a different name for the name of the constructor
>>> that cannot clash with
>>> any method name, with `<init>` being the obvious choice.
>>>
>>> The fix is restricted, along with some other changes, to when
>>> generating HTML5 docs.
>>> There are other problems with IDs/anchor names when using HTML 4.01,
>>> which are all
>>> better addressed by using HTML5, leaving support for HTML 4.01
>>> unchanged at this point.
>>>
>>> In HTML5, there are no restrictions on the individual characters in
>>> an ID other than to prohibit
>>> whitespace. Therefore, there is no longer any need to use the
>>> javadoc-specific encoding
>>> using `:` and `-` to encode otherwise invalid characters. Thus, the
>>> ID for a member of the class
>>> is just the signature of the member: the name for a field, the name
>>> and parameter-type list
>>> for a method, and `<init>` and parameter-type list for a constructor.
>>>
>>> Finally, because this opens up the possibility of square brackets
>>> appearing in a signature
>>> (where previously "[]" was encoded as ":A"), the encoding of URLs
>>> which have fragments
>>> containing [] had to be improved, by using the standard URL
>>> %-encoding for these characters.
>>>
>>> The tests are updated, with additional tests being added for members
>>> with non-ASCII
>>> identifiers, to verify that IDs and defined and referenced correctly.
>>>
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
>>> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.00/index.html
>>>
>>> -- Jon
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8187521: In some corner cases the javadoc tool can reuse id attribute

Bhavesh Patel

Looks good. A couple of minor suggestions. HtmlDocletWriter.java (Line
1480) and HtmlDocWriter.java (Line 184) could be updated to use
configuration.isOutputHtml5() the check for HTML5 version.

Ok to push.


Regards,

Bhavesh.



On 10/6/2017 7:18 PM, Jonathan Gibbons wrote:

> Updated webrev, with comment added:
> http://cr.openjdk.java.net/~jjg/8187521/webrev.02
>
> -- Jon
>
> On 09/29/2017 01:34 PM, Kumar Srinivasan wrote:
>> Jon,
>>
>> Looks good with a caveat, suggest a comment:
>> testDocEncoding.java
>>
>> +        checkOutput("stylesheet.css", true,
>> +                "body {\n"
>> +                + "    background-color:#ffffff;");
>> +
>> +        charset = Charset.forName("UTF-8");   <--- this line needs
>> an explanation comment.
>>
>> I don't need to see another iteration.
>>
>> Kumar
>>
>>
>>
>>> Updated patch to address a test failure on Windows.
>>>
>>> The test failure was specifically caused by a defensive check on the
>>> default platform encoding.
>>> The fix for that test failure is to enhance JavadocTester to
>>> determine the file encoding used to
>>> write files, and to use that when reading files in order to check
>>> their content.
>>>
>>> That enhancement to JavadocTester triggered the need to update
>>> another test, TestDocEncoding.java.
>>> which can now do a better job because of the better suport for using
>>> the correct doc encoding.
>>>
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
>>> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.01/index.html
>>>
>>> -- Jon
>>>
>>> On 09/26/2017 03:21 PM, Jonathan Gibbons wrote:
>>>> Please review this fix regarding the handling of ID values
>>>> generated by the standard javadoc doclet.
>>>>
>>>> The root cause of the specific issue is a corner case in Java. A
>>>> class may contain a method
>>>> with the same name as the enclosing class, and any corresponding
>>>> constructor.
>>>>
>>>> The fix is to use a different name for the name of the constructor
>>>> that cannot clash with
>>>> any method name, with `<init>` being the obvious choice.
>>>>
>>>> The fix is restricted, along with some other changes, to when
>>>> generating HTML5 docs.
>>>> There are other problems with IDs/anchor names when using HTML
>>>> 4.01, which are all
>>>> better addressed by using HTML5, leaving support for HTML 4.01
>>>> unchanged at this point.
>>>>
>>>> In HTML5, there are no restrictions on the individual characters in
>>>> an ID other than to prohibit
>>>> whitespace. Therefore, there is no longer any need to use the
>>>> javadoc-specific encoding
>>>> using `:` and `-` to encode otherwise invalid characters. Thus, the
>>>> ID for a member of the class
>>>> is just the signature of the member: the name for a field, the name
>>>> and parameter-type list
>>>> for a method, and `<init>` and parameter-type list for a constructor.
>>>>
>>>> Finally, because this opens up the possibility of square brackets
>>>> appearing in a signature
>>>> (where previously "[]" was encoded as ":A"), the encoding of URLs
>>>> which have fragments
>>>> containing [] had to be improved, by using the standard URL
>>>> %-encoding for these characters.
>>>>
>>>> The tests are updated, with additional tests being added for
>>>> members with non-ASCII
>>>> identifiers, to verify that IDs and defined and referenced correctly.
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
>>>> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.00/index.html
>>>>
>>>> -- Jon
>>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8187521: In some corner cases the javadoc tool can reuse id attribute

Kumar Srinivasan
In reply to this post by Jonathan Gibbons
Looks good.

Kumar

On 10/6/2017 7:18 PM, Jonathan Gibbons wrote:

> Updated webrev, with comment added:
> http://cr.openjdk.java.net/~jjg/8187521/webrev.02
>
> -- Jon
>
> On 09/29/2017 01:34 PM, Kumar Srinivasan wrote:
>> Jon,
>>
>> Looks good with a caveat, suggest a comment:
>> testDocEncoding.java
>>
>> +        checkOutput("stylesheet.css", true,
>> +                "body {\n"
>> +                + "    background-color:#ffffff;");
>> +
>> +        charset = Charset.forName("UTF-8");   <--- this line needs
>> an explanation comment.
>>
>> I don't need to see another iteration.
>>
>> Kumar
>>
>>
>>
>>> Updated patch to address a test failure on Windows.
>>>
>>> The test failure was specifically caused by a defensive check on the
>>> default platform encoding.
>>> The fix for that test failure is to enhance JavadocTester to
>>> determine the file encoding used to
>>> write files, and to use that when reading files in order to check
>>> their content.
>>>
>>> That enhancement to JavadocTester triggered the need to update
>>> another test, TestDocEncoding.java.
>>> which can now do a better job because of the better suport for using
>>> the correct doc encoding.
>>>
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
>>> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.01/index.html
>>>
>>> -- Jon
>>>
>>> On 09/26/2017 03:21 PM, Jonathan Gibbons wrote:
>>>> Please review this fix regarding the handling of ID values
>>>> generated by the standard javadoc doclet.
>>>>
>>>> The root cause of the specific issue is a corner case in Java. A
>>>> class may contain a method
>>>> with the same name as the enclosing class, and any corresponding
>>>> constructor.
>>>>
>>>> The fix is to use a different name for the name of the constructor
>>>> that cannot clash with
>>>> any method name, with `<init>` being the obvious choice.
>>>>
>>>> The fix is restricted, along with some other changes, to when
>>>> generating HTML5 docs.
>>>> There are other problems with IDs/anchor names when using HTML
>>>> 4.01, which are all
>>>> better addressed by using HTML5, leaving support for HTML 4.01
>>>> unchanged at this point.
>>>>
>>>> In HTML5, there are no restrictions on the individual characters in
>>>> an ID other than to prohibit
>>>> whitespace. Therefore, there is no longer any need to use the
>>>> javadoc-specific encoding
>>>> using `:` and `-` to encode otherwise invalid characters. Thus, the
>>>> ID for a member of the class
>>>> is just the signature of the member: the name for a field, the name
>>>> and parameter-type list
>>>> for a method, and `<init>` and parameter-type list for a constructor.
>>>>
>>>> Finally, because this opens up the possibility of square brackets
>>>> appearing in a signature
>>>> (where previously "[]" was encoded as ":A"), the encoding of URLs
>>>> which have fragments
>>>> containing [] had to be improved, by using the standard URL
>>>> %-encoding for these characters.
>>>>
>>>> The tests are updated, with additional tests being added for
>>>> members with non-ASCII
>>>> identifiers, to verify that IDs and defined and referenced correctly.
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
>>>> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.00/index.html
>>>>
>>>> -- Jon
>>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8187521: In some corner cases the javadoc tool can reuse id attribute

Jonathan Gibbons
In reply to this post by Bhavesh Patel
Thanks.  For consistency, I'll change to use the method, although it's
not clear to me the method carries its weight.

-- Jon

On 10/10/2017 11:10 AM, Bhavesh Patel wrote:

>
> Looks good. A couple of minor suggestions. HtmlDocletWriter.java (Line
> 1480) and HtmlDocWriter.java (Line 184) could be updated to use
> configuration.isOutputHtml5() the check for HTML5 version.
>
> Ok to push.
>
>
> Regards,
>
> Bhavesh.
>
>
>
> On 10/6/2017 7:18 PM, Jonathan Gibbons wrote:
>> Updated webrev, with comment added:
>> http://cr.openjdk.java.net/~jjg/8187521/webrev.02
>>
>> -- Jon
>>
>> On 09/29/2017 01:34 PM, Kumar Srinivasan wrote:
>>> Jon,
>>>
>>> Looks good with a caveat, suggest a comment:
>>> testDocEncoding.java
>>>
>>> +        checkOutput("stylesheet.css", true,
>>> +                "body {\n"
>>> +                + "    background-color:#ffffff;");
>>> +
>>> +        charset = Charset.forName("UTF-8");   <--- this line needs
>>> an explanation comment.
>>>
>>> I don't need to see another iteration.
>>>
>>> Kumar
>>>
>>>
>>>
>>>> Updated patch to address a test failure on Windows.
>>>>
>>>> The test failure was specifically caused by a defensive check on
>>>> the default platform encoding.
>>>> The fix for that test failure is to enhance JavadocTester to
>>>> determine the file encoding used to
>>>> write files, and to use that when reading files in order to check
>>>> their content.
>>>>
>>>> That enhancement to JavadocTester triggered the need to update
>>>> another test, TestDocEncoding.java.
>>>> which can now do a better job because of the better suport for
>>>> using the correct doc encoding.
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
>>>> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.01/index.html
>>>>
>>>> -- Jon
>>>>
>>>> On 09/26/2017 03:21 PM, Jonathan Gibbons wrote:
>>>>> Please review this fix regarding the handling of ID values
>>>>> generated by the standard javadoc doclet.
>>>>>
>>>>> The root cause of the specific issue is a corner case in Java. A
>>>>> class may contain a method
>>>>> with the same name as the enclosing class, and any corresponding
>>>>> constructor.
>>>>>
>>>>> The fix is to use a different name for the name of the constructor
>>>>> that cannot clash with
>>>>> any method name, with `<init>` being the obvious choice.
>>>>>
>>>>> The fix is restricted, along with some other changes, to when
>>>>> generating HTML5 docs.
>>>>> There are other problems with IDs/anchor names when using HTML
>>>>> 4.01, which are all
>>>>> better addressed by using HTML5, leaving support for HTML 4.01
>>>>> unchanged at this point.
>>>>>
>>>>> In HTML5, there are no restrictions on the individual characters
>>>>> in an ID other than to prohibit
>>>>> whitespace. Therefore, there is no longer any need to use the
>>>>> javadoc-specific encoding
>>>>> using `:` and `-` to encode otherwise invalid characters. Thus,
>>>>> the ID for a member of the class
>>>>> is just the signature of the member: the name for a field, the
>>>>> name and parameter-type list
>>>>> for a method, and `<init>` and parameter-type list for a constructor.
>>>>>
>>>>> Finally, because this opens up the possibility of square brackets
>>>>> appearing in a signature
>>>>> (where previously "[]" was encoded as ":A"), the encoding of URLs
>>>>> which have fragments
>>>>> containing [] had to be improved, by using the standard URL
>>>>> %-encoding for these characters.
>>>>>
>>>>> The tests are updated, with additional tests being added for
>>>>> members with non-ASCII
>>>>> identifiers, to verify that IDs and defined and referenced correctly.
>>>>>
>>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8187521
>>>>> Webrev: http://cr.openjdk.java.net/~jjg/8187521/webrev.00/index.html
>>>>>
>>>>> -- Jon
>>>>
>>>
>>
>