RFR [9] 8077332: tidy warnings from javax/xml

[huizhe wang]

Hi Alexander,

That fixed the issue in the existing Javadoc. The JAXP changes look good 
now.

Thanks for doing this!

Best,
Joe

On 4/17/2015 4:36 AM, alexander stepanov wrote:
> Hello Joe,
>
> > [jw] as I mentioned, <pre></pre> is needed for the code snippet.
> Fixed, please see
> http://cr.openjdk.java.net/~avstepan/8077332/webrev.01/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java.udiff.html 
>
>
>  > [jw] I saw in a few cases where two @code tags are next to each other
> Fixed in a couple of places.
>
> Regards,
> Alexander
>
> On 16.04.2015 19:57, huizhe wang wrote:
>> Hi Alexander,
>>
>> Looks very good. Thanks for making all the changes!
>>
>> Please note that for the JAXWS, you may need to check with 
>> JAXWS/Miran (miroslav.kos at oracle.com). Changes to JAXWS generally 
>> goes into the standalone first. They do periodic integration.
>>
>> For the jaxp portion:
>> --- old/src/java.xml/share/classes/javax/xml/datatype/Duration.java 
>> 2015-04-16 13:50:25.249473095 +0400
>> +++ new/src/java.xml/share/classes/javax/xml/datatype/Duration.java 
>> 2015-04-16 13:50:25.161473099 +0400
>>
>> @@ -725,37 +725,37 @@
>>
>>       *
>> -     * @return the relationship between <code>this</code> 
>> <code>Duration</code>and <code>duration</code> parameter as
>> +     * @return the relationship between {@code this} {@code 
>> Duration}and {@code duration} parameter as
>>
>> [jw] I saw in a few cases where two @code tags are next to each 
>> other, you may do a s/} {@code//g to combine them. A space is also 
>> missing before 'and': e.g. {@code Duration} and.
>>
>>
>> --- 
>> old/src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java 
>> 2015-04-16 13:50:28.197472963 +0400
>> +++ 
>> new/src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java 
>> 2015-04-16 13:50:28.105472967 +0400
>>
>> @@ -542,7 +543,7 @@
>>     * If the number of characters actually copied is less than the 
>> "length", then there is no more text.
>>     * Otherwise, subsequent calls need to be made until all text has 
>> been retrieved. For example:
>>     *
>> -   *<code>
>> +   * {@code
>>     * int length = 1024;
>>     * char[] myBuffer = new char[ length ];
>>     *
>> @@ -553,7 +554,7 @@
>>     *   if (nCopied < length)
>>     *       break;
>>     * }
>> -   * </code>
>> +   * }
>>
>> [jw] as I mentioned, <pre></pre> is needed for the code snippet.
>>
>>
>> BTW, have you compiled and verified the Javadoc after the changes?
>>
>> Thanks,
>> Joe
>>
>> On 4/16/2015 7:07 AM, alexander stepanov wrote:
>>> I'm sorry, two extra files touched -
>>> http://cr.openjdk.java.net/~avstepan/8077332/webrev.01/jaxws/src/java.activation/share/classes/javax/activation/MailcapCommandMap.java.udiff.html 
>>>
>>> http://cr.openjdk.java.net/~avstepan/8077332/webrev.01/jaxws/src/java.activation/share/classes/javax/activation/MimetypesFileTypeMap.java.udiff.html 
>>>
>>>
>>> Hopefully that's all for this bug...
>>>
>>> Thanks,
>>> Alexander
>>>
>>> On 16.04.2015 15:48, alexander stepanov wrote:
>>>> Please note also that a couple of new files were touched:
>>>>
>>>> http://cr.openjdk.java.net/~avstepan/8077332/webrev.01/jaxws/src/java.annotations.common/share/classes/javax/annotation/PostConstruct.java.udiff.html 
>>>> <http://cr.openjdk.java.net/%7Eavstepan/8077332/webrev.01/jaxws/src/java.annotations.common/share/classes/javax/annotation/PostConstruct.java.udiff.html> 
>>>>
>>>> http://cr.openjdk.java.net/~avstepan/8077332/webrev.01/jaxws/src/java.annotations.common/share/classes/javax/annotation/PreDestroy.java.udiff.html 
>>>> <http://cr.openjdk.java.net/%7Eavstepan/8077332/webrev.01/jaxws/src/java.annotations.common/share/classes/javax/annotation/PreDestroy.java.udiff.html> 
>>>>
>>>>
>>>> On 15.04.2015 19:12, alexander stepanov wrote:
>>>>> Hello Joe,
>>>>>
>>>>> The copyright changes were reverted.
>>>>>
>>>>> Please review the updated fix:
>>>>> http://cr.openjdk.java.net/~avstepan/8077332/webrev.01/
>>>>>
>>>>> ("<code></code>" replaced with "{@code}", removed unnecessary 
>>>>> "</p>", used "@literal" tag).
>>>>>
>>>>> Thanks,
>>>>> Alexander
>>>>>
>>>>>
>>>>> On 13.04.2015 21:19, huizhe wang wrote:
>>>>>>
>>>>>> On 4/13/2015 4:42 AM, Alan Bateman wrote:
>>>>>>> On 13/04/2015 12:22, alexander stepanov wrote:
>>>>>>>> Hello Joe,
>>>>>>>>
>>>>>>>> Thank you for the notes;
>>>>>>>>
>>>>>>>> > Copyright year shall not be changed.
>>>>>>>>
>>>>>>>> That seems to be a bit controversial point; sometimes (while 
>>>>>>>> cleaning docs) I was asked to do that, other times - not to do 
>>>>>>>> that. Our internal policy seemingly assigns to change the 2nd 
>>>>>>>> date every time the sources were touched (but that may be a 
>>>>>>>> question of ambiguous interpretation).
>>>>>>>>
>>>>>>>> But of course I can easily revert these changes if you're 
>>>>>>>> totally sure it should be done.
>>>>>>>>
>>>>>>> This has always been confusing. Some areas insist on updating 
>>>>>>> the copyright dates, others don't. AFAIK, it has always been 
>>>>>>> optional. I think the original assumption was that the 
>>>>>>> update_copyright_year script (in the top-level repo) be run 
>>>>>>> periodically to do bulk updates. Unfortunately that script 
>>>>>>> doesn't seem to be run very often now and this strengthens the 
>>>>>>> case to update the dates on a continuous basis. I have not come 
>>>>>>> across the argument that html tidy tasks that don't change the 
>>>>>>> javadoc should not update the copyright date. The general topic 
>>>>>>> probably should move to jdk9-dev and get this decided once and 
>>>>>>> documented in the developer guide.
>>>>>>
>>>>>> I think the key question to ask is: is this the code I can claim 
>>>>>> Copyright with? To me, format, code style, html tags and other 
>>>>>> minor changes, these are not code changes one can claim copyright 
>>>>>> with.
>>>>>>
>>>>>> The date of a Copyright establishes how far back the claim is 
>>>>>> made. In case where the work is substantially revised, a new 
>>>>>> Copyright claim is established, which is what the 2nd year is about.
>>>>>>
>>>>>> In this case, esp. for the JAXP API (e.g. javax.xml.datatype), 
>>>>>> I'd like to see the years maintained because those are the years 
>>>>>> the API was designed and modified. The "tidy warnings" change did 
>>>>>> not change the API.
>>>>>>
>>>>>> -Joe
>>>>>>
>>>>>>>
>>>>>>> -Alan
>>>>>>
>>>>>
>>>>
>>>
>>
>