Re: 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 (&ge;0) integers or null

*(JW) Use {@literal }**instead.*

@@ -57,7 +57,7 @@
   *  <li>A&lt;B (A is shorter than B)
   *  <li>A&gt;B (A is longer than B)
   *  <li>A==B   (A and B are of the same duration)
- *  <li>A&lt;>B (Comparison between A and B is indeterminate)
+ *  <li>A&lt;&gt;B (Comparison between A and B is indeterminate)

*(JW) Use @literal instead.*

There are a lot more "<>" being changed to "&lt;&gt;", 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) &gt; "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 &lt; length)
     *       break;
     * }
     * </code>
(JW) after substituting <code></code> with {@code ...}, no need to 
change < to &lt;
        Please also add <pre></pre> to the code snippet.

-     * <p>Normally, result tree serialization escapes & and < (and
+     * <p>Normally, result tree serialization escapes &amp; and &lt; (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