changeset 9468:5561b34f6d4c

8020539: Clean up doclint problems in java.util package, part 2 Summary: Clean up doclint errors and warnings in classes in java.util Reviewed-by: darcy, chegar Contributed-by: Brian Burkhalter <brian.burkhalter@oracle.com>
author bpb
date Tue, 30 Jul 2013 10:35:06 -0700
parents d30f357c6050
children 4bd51f6268f4
files src/share/classes/java/util/List.java src/share/classes/java/util/Map.java src/share/classes/java/util/Optional.java src/share/classes/java/util/Random.java src/share/classes/java/util/Scanner.java src/share/classes/java/util/ServiceLoader.java src/share/classes/java/util/StringJoiner.java src/share/classes/java/util/TimeZone.java src/share/classes/java/util/UUID.java src/share/classes/java/util/Vector.java
diffstat 10 files changed, 146 insertions(+), 181 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/List.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/List.java	Tue Jul 30 10:35:06 2013 -0700
@@ -384,10 +384,12 @@
      * @implSpec
      * The default implementation is equivalent to, for this {@code list}:
      * <pre>
+     * {@code
      * final ListIterator<E> li = list.listIterator();
      * while (li.hasNext()) {
      *   li.set(operator.apply(li.next()));
      * }
+     * }
      * </pre>
      * If the list's list-iterator does not support the {@code set} operation
      * then an {@code UnsupportedOperationException} will be thrown when
--- a/src/share/classes/java/util/Map.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/Map.java	Tue Jul 30 10:35:06 2013 -0700
@@ -561,6 +561,7 @@
     * concurrency properties.
     *
     * @param key the key whose associated value is to be returned
+    * @param defaultValue the default mapping of the key
     * @return the value to which the specified key is mapped, or
     * {@code defaultValue} if this map contains no mapping for the key
     * @throws ClassCastException if the key is of an inappropriate type for
--- a/src/share/classes/java/util/Optional.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/Optional.java	Tue Jul 30 10:35:06 2013 -0700
@@ -93,6 +93,7 @@
     /**
      * Returns an {@code Optional} with the specified present non-null value.
      *
+     * @param <T> the class of the value
      * @param value the value to be present, which must be non-null
      * @return an {@code Optional} with the value present
      */
@@ -104,6 +105,7 @@
      * Returns an {@code Optional} describing the specified value, if non-null,
      * otherwise returns an empty {@code Optional}.
      *
+     * @param <T> the class of the value
      * @param value the possibly-null value to describe
      * @return an {@code Optional} with a present value if the specified value
      * is non-null, otherwise an empty {@code Optional}
--- a/src/share/classes/java/util/Random.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/Random.java	Tue Jul 30 10:35:06 2013 -0700
@@ -225,9 +225,8 @@
      * Returns the next pseudorandom, uniformly distributed {@code int}
      * value from this random number generator's sequence. The general
      * contract of {@code nextInt} is that one {@code int} value is
-     * pseudorandomly generated and returned. All 2<font size="-1"><sup>32
-     * </sup></font> possible {@code int} values are produced with
-     * (approximately) equal probability.
+     * pseudorandomly generated and returned. All 2<sup>32</sup> possible
+     * {@code int} values are produced with (approximately) equal probability.
      *
      * <p>The method {@code nextInt} is implemented by class {@code Random}
      * as if by:
@@ -370,11 +369,9 @@
      * <p>The general contract of {@code nextFloat} is that one
      * {@code float} value, chosen (approximately) uniformly from the
      * range {@code 0.0f} (inclusive) to {@code 1.0f} (exclusive), is
-     * pseudorandomly generated and returned. All 2<font
-     * size="-1"><sup>24</sup></font> possible {@code float} values
-     * of the form <i>m&nbsp;x&nbsp;</i>2<font
-     * size="-1"><sup>-24</sup></font>, where <i>m</i> is a positive
-     * integer less than 2<font size="-1"><sup>24</sup> </font>, are
+     * pseudorandomly generated and returned. All 2<sup>24</sup> possible
+     * {@code float} values of the form <i>m&nbsp;x&nbsp;</i>2<sup>-24</sup>,
+     * where <i>m</i> is a positive integer less than 2<sup>24</sup>, are
      * produced with (approximately) equal probability.
      *
      * <p>The method {@code nextFloat} is implemented by class {@code Random}
--- a/src/share/classes/java/util/Scanner.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/Scanner.java	Tue Jul 30 10:35:06 2013 -0700
@@ -76,7 +76,7 @@
  * }</pre></blockquote>
  * <p>
  * prints the following output:
- * <blockqjote><pre>{@code
+ * <blockquote><pre>{@code
  *     1
  *     2
  *     red
@@ -149,8 +149,7 @@
  * {@link #reset} method will reset the value of the scanner's radix to
  * <code>10</code> regardless of whether it was previously changed.
  *
- * <a name="localized-numbers">
- * <h4> Localized numbers </h4>
+ * <h3> <a name="localized-numbers">Localized numbers</a> </h3>
  *
  * <p> An instance of this class is capable of scanning numbers in the standard
  * formats as well as in the formats of the scanner's locale. A scanner's
@@ -167,186 +166,139 @@
  * {@link java.text.DecimalFormatSymbols DecimalFormatSymbols} object,
  * <tt>dfs</tt>.
  *
- * <blockquote><table>
- * <tr><td valign="top"><i>LocalGroupSeparator&nbsp;&nbsp;</i></td>
- *     <td valign="top">The character used to separate thousands groups,
- *                      <i>i.e.,</i>&nbsp;<tt>dfs.</tt>{@link
- *                      java.text.DecimalFormatSymbols#getGroupingSeparator
- *                      getGroupingSeparator()}</td></tr>
- * <tr><td valign="top"><i>LocalDecimalSeparator&nbsp;&nbsp;</i></td>
- *     <td valign="top">The character used for the decimal point,
- *                      <i>i.e.,</i>&nbsp;<tt>dfs.</tt>{@link
- *                      java.text.DecimalFormatSymbols#getDecimalSeparator
- *                      getDecimalSeparator()}</td></tr>
- * <tr><td valign="top"><i>LocalPositivePrefix&nbsp;&nbsp;</i></td>
- *     <td valign="top">The string that appears before a positive number (may
- *                      be empty), <i>i.e.,</i>&nbsp;<tt>df.</tt>{@link
- *                      java.text.DecimalFormat#getPositivePrefix
- *                      getPositivePrefix()}</td></tr>
- * <tr><td valign="top"><i>LocalPositiveSuffix&nbsp;&nbsp;</i></td>
- *     <td valign="top">The string that appears after a positive number (may be
- *                      empty), <i>i.e.,</i>&nbsp;<tt>df.</tt>{@link
- *                      java.text.DecimalFormat#getPositiveSuffix
- *                      getPositiveSuffix()}</td></tr>
- * <tr><td valign="top"><i>LocalNegativePrefix&nbsp;&nbsp;</i></td>
- *     <td valign="top">The string that appears before a negative number (may
- *                      be empty), <i>i.e.,</i>&nbsp;<tt>df.</tt>{@link
- *                      java.text.DecimalFormat#getNegativePrefix
- *                      getNegativePrefix()}</td></tr>
- * <tr><td valign="top"><i>LocalNegativeSuffix&nbsp;&nbsp;</i></td>
- *     <td valign="top">The string that appears after a negative number (may be
- *                      empty), <i>i.e.,</i>&nbsp;<tt>df.</tt>{@link
- *                      java.text.DecimalFormat#getNegativeSuffix
- *                      getNegativeSuffix()}</td></tr>
- * <tr><td valign="top"><i>LocalNaN&nbsp;&nbsp;</i></td>
- *     <td valign="top">The string that represents not-a-number for
- *                      floating-point values,
- *                      <i>i.e.,</i>&nbsp;<tt>dfs.</tt>{@link
- *                      java.text.DecimalFormatSymbols#getNaN
- *                      getNaN()}</td></tr>
- * <tr><td valign="top"><i>LocalInfinity&nbsp;&nbsp;</i></td>
- *     <td valign="top">The string that represents infinity for floating-point
- *                      values, <i>i.e.,</i>&nbsp;<tt>dfs.</tt>{@link
- *                      java.text.DecimalFormatSymbols#getInfinity
- *                      getInfinity()}</td></tr>
- * </table></blockquote>
+ * <blockquote><dl>
+ *     <dt><i>LocalGroupSeparator&nbsp;&nbsp;</i>
+ *         <dd>The character used to separate thousands groups,
+ *         <i>i.e.,</i>&nbsp;<tt>dfs.</tt>{@link
+ *         java.text.DecimalFormatSymbols#getGroupingSeparator
+ *         getGroupingSeparator()}
+ *     <dt><i>LocalDecimalSeparator&nbsp;&nbsp;</i>
+ *         <dd>The character used for the decimal point,
+ *     <i>i.e.,</i>&nbsp;<tt>dfs.</tt>{@link
+ *     java.text.DecimalFormatSymbols#getDecimalSeparator
+ *     getDecimalSeparator()}
+ *     <dt><i>LocalPositivePrefix&nbsp;&nbsp;</i>
+ *         <dd>The string that appears before a positive number (may
+ *         be empty), <i>i.e.,</i>&nbsp;<tt>df.</tt>{@link
+ *         java.text.DecimalFormat#getPositivePrefix
+ *         getPositivePrefix()}
+ *     <dt><i>LocalPositiveSuffix&nbsp;&nbsp;</i>
+ *         <dd>The string that appears after a positive number (may be
+ *         empty), <i>i.e.,</i>&nbsp;<tt>df.</tt>{@link
+ *         java.text.DecimalFormat#getPositiveSuffix
+ *         getPositiveSuffix()}
+ *     <dt><i>LocalNegativePrefix&nbsp;&nbsp;</i>
+ *         <dd>The string that appears before a negative number (may
+ *         be empty), <i>i.e.,</i>&nbsp;<tt>df.</tt>{@link
+ *         java.text.DecimalFormat#getNegativePrefix
+ *         getNegativePrefix()}
+ *     <dt><i>LocalNegativeSuffix&nbsp;&nbsp;</i>
+ *         <dd>The string that appears after a negative number (may be
+ *         empty), <i>i.e.,</i>&nbsp;<tt>df.</tt>{@link
+ *     java.text.DecimalFormat#getNegativeSuffix
+ *     getNegativeSuffix()}
+ *     <dt><i>LocalNaN&nbsp;&nbsp;</i>
+ *         <dd>The string that represents not-a-number for
+ *         floating-point values,
+ *         <i>i.e.,</i>&nbsp;<tt>dfs.</tt>{@link
+ *         java.text.DecimalFormatSymbols#getNaN
+ *         getNaN()}
+ *     <dt><i>LocalInfinity&nbsp;&nbsp;</i>
+ *         <dd>The string that represents infinity for floating-point
+ *         values, <i>i.e.,</i>&nbsp;<tt>dfs.</tt>{@link
+ *         java.text.DecimalFormatSymbols#getInfinity
+ *         getInfinity()}
+ * </dl></blockquote>
  *
- * <a name="number-syntax">
- * <h4> Number syntax </h4>
+ * <h4> <a name="number-syntax">Number syntax</a> </h4>
  *
  * <p> The strings that can be parsed as numbers by an instance of this class
  * are specified in terms of the following regular-expression grammar, where
- * Rmax is the highest digit in the radix being used (for example, Rmax is 9
- * in base 10).
+ * Rmax is the highest digit in the radix being used (for example, Rmax is 9 in base 10).
  *
  * <p>
- * <table cellspacing=0 cellpadding=0 align=center>
+ * <dl>
+ *   <dt><i>NonAsciiDigit</i>:
+ *       <dd>A non-ASCII character c for which
+ *            {@link java.lang.Character#isDigit Character.isDigit}<tt>(c)</tt>
+ *                        returns&nbsp;true
  *
- *   <tr><td valign=top align=right><i>NonASCIIDigit</i>&nbsp;&nbsp;::</td>
- *       <td valign=top>= A non-ASCII character c for which
- *            {@link java.lang.Character#isDigit Character.isDigit}<tt>(c)</tt>
- *                        returns&nbsp;true</td></tr>
+ *   <dt><i>Non0Digit</i>:
+ *       <dd><tt>[1-</tt><i>Rmax</i><tt>] | </tt><i>NonASCIIDigit</i>
  *
- *   <tr><td>&nbsp;</td></tr>
+ *   <dt><i>Digit</i>:
+ *       <dd><tt>[0-</tt><i>Rmax</i><tt>] | </tt><i>NonASCIIDigit</i>
  *
- *   <tr><td align=right><i>Non0Digit</i>&nbsp;&nbsp;::</td>
- *   <td><tt>= [1-</tt><i>Rmax</i><tt>] | </tt><i>NonASCIIDigit</i></td></tr>
+ *   <dt><i>GroupedNumeral</i>:
+ *       <dd><tt>(&nbsp;</tt><i>Non0Digit</i>
+ *                   <i>Digit</i><tt>?
+ *                   </tt><i>Digit</i><tt>?</tt>
+ *       <dd>&nbsp;&nbsp;&nbsp;&nbsp;<tt>(&nbsp;</tt><i>LocalGroupSeparator</i>
+ *                         <i>Digit</i>
+ *                         <i>Digit</i>
+ *                         <i>Digit</i><tt> )+ )</tt>
  *
- *   <tr><td>&nbsp;</td></tr>
+ *   <dt><i>Numeral</i>:
+ *       <dd><tt>( ( </tt><i>Digit</i><tt>+ )
+ *               | </tt><i>GroupedNumeral</i><tt> )</tt>
  *
- *   <tr><td align=right><i>Digit</i>&nbsp;&nbsp;::</td>
- *   <td><tt>= [0-</tt><i>Rmax</i><tt>] | </tt><i>NonASCIIDigit</i></td></tr>
+ *   <dt><a name="Integer-regex"><i>Integer</i>:</a>
+ *       <dd><tt>( [-+]? ( </tt><i>Numeral</i><tt>
+ *                               ) )</tt>
+ *       <dd><tt>| </tt><i>LocalPositivePrefix</i> <i>Numeral</i>
+ *                      <i>LocalPositiveSuffix</i>
+ *       <dd><tt>| </tt><i>LocalNegativePrefix</i> <i>Numeral</i>
+ *                 <i>LocalNegativeSuffix</i>
  *
- *   <tr><td>&nbsp;</td></tr>
+ *   <dt><i>DecimalNumeral</i>:
+ *       <dd><i>Numeral</i>
+ *       <dd><tt>| </tt><i>Numeral</i>
+ *                 <i>LocalDecimalSeparator</i>
+ *                 <i>Digit</i><tt>*</tt>
+ *       <dd><tt>| </tt><i>LocalDecimalSeparator</i>
+ *                 <i>Digit</i><tt>+</tt>
  *
- *   <tr><td valign=top align=right><i>GroupedNumeral</i>&nbsp;&nbsp;::</td>
- *       <td valign=top>
- *         <table cellpadding=0 cellspacing=0>
- *           <tr><td><tt>= (&nbsp;</tt></td>
- *               <td><i>Non0Digit</i><tt>
- *                   </tt><i>Digit</i><tt>?
- *                   </tt><i>Digit</i><tt>?</tt></td></tr>
- *           <tr><td></td>
- *               <td><tt>(&nbsp;</tt><i>LocalGroupSeparator</i><tt>
- *                         </tt><i>Digit</i><tt>
- *                         </tt><i>Digit</i><tt>
- *                         </tt><i>Digit</i><tt> )+ )</tt></td></tr>
- *         </table></td></tr>
+ *   <dt><i>Exponent</i>:
+ *       <dd><tt>( [eE] [+-]? </tt><i>Digit</i><tt>+ )</tt>
  *
- *   <tr><td>&nbsp;</td></tr>
+ *   <dt><a name="Decimal-regex"><i>Decimal</i>:</a>
+ *       <dd><tt>( [-+]? </tt><i>DecimalNumeral</i>
+ *                         <i>Exponent</i><tt>? )</tt>
+ *       <dd><tt>| </tt><i>LocalPositivePrefix</i>
+ *                 <i>DecimalNumeral</i>
+ *                 <i>LocalPositiveSuffix</i>
+ *                 <i>Exponent</i><tt>?</tt>
+ *       <dd><tt>| </tt><i>LocalNegativePrefix</i>
+ *                 <i>DecimalNumeral</i>
+ *                 <i>LocalNegativeSuffix</i>
+ *                 <i>Exponent</i><tt>?</tt>
  *
- *   <tr><td align=right><i>Numeral</i>&nbsp;&nbsp;::</td>
- *       <td><tt>= ( ( </tt><i>Digit</i><tt>+ )
- *               | </tt><i>GroupedNumeral</i><tt> )</tt></td></tr>
+ *   <dt><i>HexFloat</i>:
+ *       <dd><tt>[-+]? 0[xX][0-9a-fA-F]*\.[0-9a-fA-F]+
+ *                 ([pP][-+]?[0-9]+)?</tt>
  *
- *   <tr><td>&nbsp;</td></tr>
- *
- *   <tr><td valign=top align=right>
- *         <a name="Integer-regex"><i>Integer</i>&nbsp;&nbsp;::</td>
- *       <td valign=top><tt>= ( [-+]? ( </tt><i>Numeral</i><tt>
- *                               ) )</tt></td></tr>
- *   <tr><td></td>
- *       <td><tt>| </tt><i>LocalPositivePrefix</i><tt> </tt><i>Numeral</i><tt>
- *                      </tt><i>LocalPositiveSuffix</i></td></tr>
- *   <tr><td></td>
- *       <td><tt>| </tt><i>LocalNegativePrefix</i><tt> </tt><i>Numeral</i><tt>
- *                 </tt><i>LocalNegativeSuffix</i></td></tr>
- *
- *   <tr><td>&nbsp;</td></tr>
- *
- *   <tr><td align=right><i>DecimalNumeral</i>&nbsp;&nbsp;::</td>
- *       <td><tt>= </tt><i>Numeral</i></td></tr>
- *   <tr><td></td>
- *       <td><tt>| </tt><i>Numeral</i><tt>
- *                 </tt><i>LocalDecimalSeparator</i><tt>
- *                 </tt><i>Digit</i><tt>*</tt></td></tr>
- *   <tr><td></td>
- *       <td><tt>| </tt><i>LocalDecimalSeparator</i><tt>
- *                 </tt><i>Digit</i><tt>+</tt></td></tr>
- *
- *   <tr><td>&nbsp;</td></tr>
- *
- *   <tr><td align=right><i>Exponent</i>&nbsp;&nbsp;::</td>
- *       <td><tt>= ( [eE] [+-]? </tt><i>Digit</i><tt>+ )</tt></td></tr>
- *
- *   <tr><td>&nbsp;</td></tr>
- *
- *   <tr><td align=right>
- *         <a name="Decimal-regex"><i>Decimal</i>&nbsp;&nbsp;::</td>
- *       <td><tt>= ( [-+]? </tt><i>DecimalNumeral</i><tt>
- *                         </tt><i>Exponent</i><tt>? )</tt></td></tr>
- *   <tr><td></td>
- *       <td><tt>| </tt><i>LocalPositivePrefix</i><tt>
- *                 </tt><i>DecimalNumeral</i><tt>
- *                 </tt><i>LocalPositiveSuffix</i>
- *                 </tt><i>Exponent</i><tt>?</td></tr>
- *   <tr><td></td>
- *       <td><tt>| </tt><i>LocalNegativePrefix</i><tt>
- *                 </tt><i>DecimalNumeral</i><tt>
- *                 </tt><i>LocalNegativeSuffix</i>
- *                 </tt><i>Exponent</i><tt>?</td></tr>
- *
- *   <tr><td>&nbsp;</td></tr>
- *
- *   <tr><td align=right><i>HexFloat</i>&nbsp;&nbsp;::</td>
- *       <td><tt>= [-+]? 0[xX][0-9a-fA-F]*\.[0-9a-fA-F]+
- *                 ([pP][-+]?[0-9]+)?</tt></td></tr>
- *
- *   <tr><td>&nbsp;</td></tr>
- *
- *   <tr><td align=right><i>NonNumber</i>&nbsp;&nbsp;::</td>
- *       <td valign=top><tt>= NaN
+ *   <dt><i>NonNumber</i>:
+ *       <dd><tt>NaN
  *                          | </tt><i>LocalNan</i><tt>
  *                          | Infinity
- *                          | </tt><i>LocalInfinity</i></td></tr>
+ *                          | </tt><i>LocalInfinity</i>
  *
- *   <tr><td>&nbsp;</td></tr>
+ *   <dt><i>SignedNonNumber</i>:
+ *       <dd><tt>( [-+]? </tt><i>NonNumber</i><tt> )</tt>
+ *       <dd><tt>| </tt><i>LocalPositivePrefix</i>
+ *                 <i>NonNumber</i>
+ *                 <i>LocalPositiveSuffix</i>
+ *       <dd><tt>| </tt><i>LocalNegativePrefix</i>
+ *                 <i>NonNumber</i>
+ *                 <i>LocalNegativeSuffix</i>
  *
- *   <tr><td align=right><i>SignedNonNumber</i>&nbsp;&nbsp;::</td>
- *       <td><tt>= ( [-+]? </tt><i>NonNumber</i><tt> )</tt></td></tr>
- *   <tr><td></td>
- *       <td><tt>| </tt><i>LocalPositivePrefix</i><tt>
- *                 </tt><i>NonNumber</i><tt>
- *                 </tt><i>LocalPositiveSuffix</i></td></tr>
- *   <tr><td></td>
- *       <td><tt>| </tt><i>LocalNegativePrefix</i><tt>
- *                 </tt><i>NonNumber</i><tt>
- *                 </tt><i>LocalNegativeSuffix</i></td></tr>
+ *   <dt><a name="Float-regex"><i>Float</i></a>:
+ *       <dd><i>Decimal</i>
+ *           <tt>| </tt><i>HexFloat</i>
+ *           <tt>| </tt><i>SignedNonNumber</i>
  *
- *   <tr><td>&nbsp;</td></tr>
- *
- *   <tr><td valign=top align=right>
- *         <a name="Float-regex"><i>Float</i>&nbsp;&nbsp;::</td>
- *       <td valign=top><tt>= </tt><i>Decimal</i><tt></td></tr>
- *       <tr><td></td>
- *           <td><tt>| </tt><i>HexFloat</i><tt></td></tr>
- *       <tr><td></td>
- *           <td><tt>| </tt><i>SignedNonNumber</i><tt></td></tr>
- *
- * </table>
- * </center>
- *
- * <p> Whitespace is not significant in the above regular expressions.
+ * </dl>
+ * <p>Whitespace is not significant in the above regular expressions.
  *
  * @since   1.5
  */
@@ -1675,6 +1627,7 @@
      * <tt>findWithinHorizon(Pattern.compile(pattern, horizon))</tt>.
      *
      * @param pattern a string specifying the pattern to search for
+     * @param horizon the search horizon
      * @return the text that matched the specified pattern
      * @throws IllegalStateException if this scanner is closed
      * @throws IllegalArgumentException if horizon is negative
@@ -1709,6 +1662,7 @@
      * thrown.
      *
      * @param pattern the pattern to scan for
+     * @param horizon the search horizon
      * @return the text that matched the specified pattern
      * @throws IllegalStateException if this scanner is closed
      * @throws IllegalArgumentException if horizon is negative
--- a/src/share/classes/java/util/ServiceLoader.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/ServiceLoader.java	Tue Jul 30 10:35:06 2013 -0700
@@ -68,12 +68,13 @@
  *
  * <p><a name="format"> A service provider is identified by placing a
  * <i>provider-configuration file</i> in the resource directory
- * <tt>META-INF/services</tt>.  The file's name is the fully-qualified <a
+ * <tt>META-INF/services</tt>.</a>  The file's name is the fully-qualified <a
  * href="../lang/ClassLoader.html#name">binary name</a> of the service's type.
  * The file contains a list of fully-qualified binary names of concrete
  * provider classes, one per line.  Space and tab characters surrounding each
  * name, as well as blank lines, are ignored.  The comment character is
- * <tt>'#'</tt> (<tt>'&#92;u0023'</tt>, <font size="-1">NUMBER SIGN</font>); on
+ * <tt>'#'</tt> (<tt>'&#92;u0023'</tt>,
+ * <font style="font-size:smaller;">NUMBER SIGN</font>); on
  * each line all characters following the first comment character are ignored.
  * The file must be encoded in UTF-8.
  *
@@ -484,6 +485,8 @@
      * Creates a new service loader for the given service type and class
      * loader.
      *
+     * @param  <S> the class of the service type
+     *
      * @param  service
      *         The interface or abstract class representing the service
      *
@@ -517,6 +520,8 @@
      * ServiceLoader.load(<i>service</i>,
      *                    Thread.currentThread().getContextClassLoader())</pre></blockquote>
      *
+     * @param  <S> the class of the service type
+     *
      * @param  service
      *         The interface or abstract class representing the service
      *
@@ -546,6 +551,8 @@
      * have been installed into the current Java virtual machine; providers on
      * the application's class path will be ignored.
      *
+     * @param  <S> the class of the service type
+     *
      * @param  service
      *         The interface or abstract class representing the service
      *
--- a/src/share/classes/java/util/StringJoiner.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/StringJoiner.java	Tue Jul 30 10:35:06 2013 -0700
@@ -202,6 +202,7 @@
      * @param other The {@code StringJoiner} whose contents should be merged
      *              into this one
      * @throws NullPointerException if the other {@code StringJoiner} is null
+     * @return This {@code StringJoiner}
      */
     public StringJoiner merge(StringJoiner other) {
         Objects.requireNonNull(other);
--- a/src/share/classes/java/util/TimeZone.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/TimeZone.java	Tue Jul 30 10:35:06 2013 -0700
@@ -118,7 +118,7 @@
  * </pre></blockquote>
  * For example, TimeZone.getTimeZone("GMT-8").getID() returns "GMT-08:00".
  *
- * <h4>Three-letter time zone IDs</h4>
+ * <h3>Three-letter time zone IDs</h3>
  *
  * For compatibility with JDK 1.1.x, some other three-letter time zone IDs
  * (such as "PST", "CTT", "AST") are also supported. However, <strong>their
@@ -304,10 +304,10 @@
      * presentation to the user in the default locale.
      *
      * <p>This method is equivalent to:
-     * <pre><blockquote>
+     * <blockquote><pre>
      * getDisplayName(false, {@link #LONG},
      *                Locale.getDefault({@link Locale.Category#DISPLAY}))
-     * </blockquote></pre>
+     * </pre></blockquote>
      *
      * @return the human-readable name of this time zone in the default locale.
      * @since 1.2
@@ -325,9 +325,9 @@
      * presentation to the user in the specified {@code locale}.
      *
      * <p>This method is equivalent to:
-     * <pre><blockquote>
+     * <blockquote><pre>
      * getDisplayName(false, {@link #LONG}, locale)
-     * </blockquote></pre>
+     * </pre></blockquote>
      *
      * @param locale the locale in which to supply the display name.
      * @return the human-readable name of this time zone in the given locale.
@@ -347,10 +347,10 @@
      * Time). Otherwise, a Standard Time name is returned.
      *
      * <p>This method is equivalent to:
-     * <pre><blockquote>
+     * <blockquote><pre>
      * getDisplayName(daylight, style,
      *                Locale.getDefault({@link Locale.Category#DISPLAY}))
-     * </blockquote></pre>
+     * </pre></blockquote>
      *
      * @param daylight {@code true} specifying a Daylight Saving Time name, or
      *                 {@code false} specifying a Standard Time name
--- a/src/share/classes/java/util/UUID.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/UUID.java	Tue Jul 30 10:35:06 2013 -0700
@@ -286,6 +286,7 @@
      *
      * @throws UnsupportedOperationException
      *         If this UUID is not a version 1 UUID
+     * @return The timestamp of this {@code UUID}.
      */
     public long timestamp() {
         if (version() != 1) {
--- a/src/share/classes/java/util/Vector.java	Tue Jul 30 14:03:25 2013 +0100
+++ b/src/share/classes/java/util/Vector.java	Tue Jul 30 10:35:06 2013 -0700
@@ -45,9 +45,9 @@
  * capacity of a vector before inserting a large number of
  * components; this reduces the amount of incremental reallocation.
  *
- * <p><a name="fail-fast"/>
+ * <p><a name="fail-fast">
  * The iterators returned by this class's {@link #iterator() iterator} and
- * {@link #listIterator(int) listIterator} methods are <em>fail-fast</em>:
+ * {@link #listIterator(int) listIterator} methods are <em>fail-fast</em></a>:
  * if the vector is structurally modified at any time after the iterator is
  * created, in any way except through the iterator's own
  * {@link ListIterator#remove() remove} or