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

Fri Apr 17 16:39:12 UTC 2015

Thanks!

Regards,
Alexander

On 17.04.2015 19:33, huizhe wang wrote:
> 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
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>