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

[Jonathan Gibbons]

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
>>>>
>>>
>>
>