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

[alexander stepanov]

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