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

[alexander stepanov]

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.

Regards,
Alexander.


On 10.04.2015 21:27, huizhe wang wrote:
> Hi Alexander,
>
> First of all, there's no code change in this webrev, the copyright 
> year should not be changed.
>
> I see that in some cases, you removed "</p>", in a lot more cases 
> though, you didn't, for example,
> -         * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
> +         * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.
>            *
>            * <p>Value constraints for this value are summarized in
>            * <a href="#datetimefield-day">day field of date/time field mapping table</a>.</p>
>
> I suggest you do a global substitution for each of the classes.
>
> As Roger suggested in the previous view, {@code } is preferable to 
> <code>... </code>. This can be a couple of global substitutions as 
> well (s/<code>/{@code /g and s/<\/code>/}/g), An example is the 
> following change:
> +++ new/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java	2015-04-10 19:59:29.427759390 +0400
>
> @@ -787,7 +786,7 @@
>        *     </tr>
>        *     <tr>
>        *       <td>
> -     *         <code>(ZONE_OFFSET + DST_OFFSET) / (60*1000)</code><br/>
> +     *         <code>(ZONE_OFFSET + DST_OFFSET) / (60*1000)</code><br>
>
> Note also at line 35, the "s" was outside of markup:
>   * Factory that creates new <code>javax.xml.datatype</code> <code>Object</code>s that map XML to/from Java <code>Object</code>s.
>
> +++ new/src/java.xml/share/classes/javax/xml/datatype/Duration.java	2015-04-10 19:59:29.807759373 +0400
> @@ -1,5 +1,5 @@
>   /*
> - * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
> + * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
>
> *(JW) Copyright year shall not be changed.*
>
>    *
> - * <p>The first five fields have non-negative (>=0) integers or null
> + * <p>The first five fields have non-negative (≥0) integers or null
>
> *(JW) Use {@literal }**instead.*
>
> @@ -57,7 +57,7 @@
>    *  <li>A<B (A is shorter than B)
>    *  <li>A>B (A is longer than B)
>    *  <li>A==B   (A and B are of the same duration)
> - *  <li>A<>B (Comparison between A and B is indeterminate)
> + *  <li>A<>B (Comparison between A and B is indeterminate)
>
> *(JW) Use @literal instead.*
>
> There are a lot more "<>" being changed to "<>", please use 
> @literal or @code. @code is preferable if the content is presented in 
> the code font.
>
>        * <p>For example, "P1D" (one day) > "PT12H" (12 hours) and
>
>                                          *^ this one was missed by the way.*
>
> -     * "P2Y" (two years) > "P23M" (23 months).</p>
> +     * "P2Y" (two years) > "P23M" (23 months).</p>
>
> +++ new/src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java	2015-04-10 19:59:32.027759273 +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 ];
>      *
> @@ -550,7 +551,7 @@
>      * {
>      *    int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length );
>      *
> -   *   if (nCopied < length)
> +   *   if (nCopied < length)
>      *       break;
>      * }
>      * </code>
> (JW) after substituting <code></code> with {@code ...}, no need to 
> change < to <
>         Please also add <pre></pre> to the code snippet.
>
> -     * <p>Normally, result tree serialization escapes & and < (and
> +     * <p>Normally, result tree serialization escapes & and < (and
>
> *(JW) use @literal for "&" as well.*
>
> -     * <p>Use a DOM node to create a new output target with the specified System ID.<p>
> +     * <p>Use a DOM node to create a new output target with the specified System ID.</p>
>
> *(JW) again, replace and remove all "</p>"*
>
>
> Thanks,
> Joe
>
>
> On 4/10/2015 8:50 AM, alexander stepanov wrote:
>> Hello,
>>
>> Could you please review the following fix
>> http://cr.openjdk.java.net/~avstepan/8077332/
>>
>> for
>> https://bugs.openjdk.java.net/browse/JDK-8077332
>>
>> Some HTML cleanup for docs.
>>
>> Thanks,
>> Alexander
>>
>