# HG changeset patch # User bpb # Date 1375132549 25200 # Node ID e3bc58092be5a9f2521737de6ec6a2061c602618 # Parent 24bda55fca48194e5904b73b5cc0bba0d82bc98f 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 diff --git a/src/share/classes/java/util/List.java b/src/share/classes/java/util/List.java --- a/src/share/classes/java/util/List.java +++ b/src/share/classes/java/util/List.java @@ -384,10 +384,12 @@ * @implSpec * The default implementation is equivalent to, for this {@code list}: * 
+     * {@code
      * final ListIterator li = list.listIterator();
      * while (li.hasNext()) {
      *   li.set(operator.apply(li.next()));
      * }
+     * }
      *
* If the list's list-iterator does not support the {@code set} operation * then an {@code UnsupportedOperationException} will be thrown when diff --git a/src/share/classes/java/util/Map.java b/src/share/classes/java/util/Map.java --- a/src/share/classes/java/util/Map.java +++ b/src/share/classes/java/util/Map.java @@ -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 diff --git a/src/share/classes/java/util/Optional.java b/src/share/classes/java/util/Optional.java --- a/src/share/classes/java/util/Optional.java +++ b/src/share/classes/java/util/Optional.java @@ -93,6 +93,7 @@ /** * Returns an {@code Optional} with the specified present non-null value. * + * @param 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 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} diff --git a/src/share/classes/java/util/Random.java b/src/share/classes/java/util/Random.java --- a/src/share/classes/java/util/Random.java +++ b/src/share/classes/java/util/Random.java @@ -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 232 - * possible {@code int} values are produced with - * (approximately) equal probability. + * pseudorandomly generated and returned. All 232 possible + * {@code int} values are produced with (approximately) equal probability. * *

The method {@code nextInt} is implemented by class {@code Random} * as if by: @@ -370,11 +369,9 @@ *

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 224 possible {@code float} values - * of the form m x 2-24, where m is a positive - * integer less than 224 , are + * pseudorandomly generated and returned. All 224 possible + * {@code float} values of the form m x 2-24, + * where m is a positive integer less than 224, are * produced with (approximately) equal probability. * *

The method {@code nextFloat} is implemented by class {@code Random} diff --git a/src/share/classes/java/util/Scanner.java b/src/share/classes/java/util/Scanner.java --- a/src/share/classes/java/util/Scanner.java +++ b/src/share/classes/java/util/Scanner.java @@ -76,7 +76,7 @@ * } *

* prints the following output: - * 

{@code
+ * 
{@code
  *     1
  *     2
  *     red
@@ -149,8 +149,7 @@
  * {@link #reset} method will reset the value of the scanner's radix to
  * 10 regardless of whether it was previously changed.
  *
- * 
- * 
 Localized numbers 

+ * 
 Localized numbers 

  *
  * 
 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,
  * dfs.
  *
- * 

- * 
- *     
- * 
- *     
- * 
- *     
- * 
- *     
- * 
- *     
- * 
- *     
- * 
- *     
- * 
- *     
- * 
LocalGroupSeparator  The character used to separate thousands groups,
- *                      i.e., dfs.{@link
- *                      java.text.DecimalFormatSymbols#getGroupingSeparator
- *                      getGroupingSeparator()}
LocalDecimalSeparator  The character used for the decimal point,
- *                      i.e., dfs.{@link
- *                      java.text.DecimalFormatSymbols#getDecimalSeparator
- *                      getDecimalSeparator()}
LocalPositivePrefix  The string that appears before a positive number (may
- *                      be empty), i.e., df.{@link
- *                      java.text.DecimalFormat#getPositivePrefix
- *                      getPositivePrefix()}
LocalPositiveSuffix  The string that appears after a positive number (may be
- *                      empty), i.e., df.{@link
- *                      java.text.DecimalFormat#getPositiveSuffix
- *                      getPositiveSuffix()}
LocalNegativePrefix  The string that appears before a negative number (may
- *                      be empty), i.e., df.{@link
- *                      java.text.DecimalFormat#getNegativePrefix
- *                      getNegativePrefix()}
LocalNegativeSuffix  The string that appears after a negative number (may be
- *                      empty), i.e., df.{@link
- *                      java.text.DecimalFormat#getNegativeSuffix
- *                      getNegativeSuffix()}
LocalNaN  The string that represents not-a-number for
- *                      floating-point values,
- *                      i.e., dfs.{@link
- *                      java.text.DecimalFormatSymbols#getNaN
- *                      getNaN()}
LocalInfinity  The string that represents infinity for floating-point
- *                      values, i.e., dfs.{@link
- *                      java.text.DecimalFormatSymbols#getInfinity
- *                      getInfinity()}

+ * 

+ *     
LocalGroupSeparator  
+ *         
The character used to separate thousands groups,
+ *         i.e., dfs.{@link
+ *         java.text.DecimalFormatSymbols#getGroupingSeparator
+ *         getGroupingSeparator()}
+ *     
LocalDecimalSeparator  
+ *         
The character used for the decimal point,
+ *     i.e., dfs.{@link
+ *     java.text.DecimalFormatSymbols#getDecimalSeparator
+ *     getDecimalSeparator()}
+ *     
LocalPositivePrefix  
+ *         
The string that appears before a positive number (may
+ *         be empty), i.e., df.{@link
+ *         java.text.DecimalFormat#getPositivePrefix
+ *         getPositivePrefix()}
+ *     
LocalPositiveSuffix  
+ *         
The string that appears after a positive number (may be
+ *         empty), i.e., df.{@link
+ *         java.text.DecimalFormat#getPositiveSuffix
+ *         getPositiveSuffix()}
+ *     
LocalNegativePrefix  
+ *         
The string that appears before a negative number (may
+ *         be empty), i.e., df.{@link
+ *         java.text.DecimalFormat#getNegativePrefix
+ *         getNegativePrefix()}
+ *     
LocalNegativeSuffix  
+ *         
The string that appears after a negative number (may be
+ *         empty), i.e., df.{@link
+ *     java.text.DecimalFormat#getNegativeSuffix
+ *     getNegativeSuffix()}
+ *     
LocalNaN  
+ *         
The string that represents not-a-number for
+ *         floating-point values,
+ *         i.e., dfs.{@link
+ *         java.text.DecimalFormatSymbols#getNaN
+ *         getNaN()}
+ *     
LocalInfinity  
+ *         
The string that represents infinity for floating-point
+ *         values, i.e., dfs.{@link
+ *         java.text.DecimalFormatSymbols#getInfinity
+ *         getInfinity()}
+ * 

  *
- * 
- * 
 Number syntax 

+ * 
 Number syntax 

  *
  * 
 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).
  *
  * 

- * 
+ * 

+ *   
NonAsciiDigit:
+ *       
A non-ASCII character c for which
+ *            {@link java.lang.Character#isDigit Character.isDigit}(c)
+ *                        returns true
  *
- *   

- *       
+ *   
Non0Digit:
+ *       
[1-Rmax] | NonASCIIDigit
  *
- *   

+ *   
Digit:
+ *       
[0-Rmax] | NonASCIIDigit
  *
- *   

- *   
+ *   
GroupedNumeral:
+ *       
( Non0Digit
+ *                   Digit?
+ *                   Digit?
+ *       
    ( LocalGroupSeparator
+ *                         Digit
+ *                         Digit
+ *                         Digit )+ )
  *
- *   

+ *   
Numeral:
+ *       
( ( Digit+ )
+ *               | GroupedNumeral )
  *
- *   

- *   
+ *   
Integer:
+ *       
( [-+]? ( Numeral
+ *                               ) )
+ *       
| LocalPositivePrefix Numeral
+ *                      LocalPositiveSuffix
+ *       
| LocalNegativePrefix Numeral
+ *                 LocalNegativeSuffix
  *
- *   

+ *   
DecimalNumeral:
+ *       
Numeral
+ *       
| Numeral
+ *                 LocalDecimalSeparator
+ *                 Digit*
+ *       
| LocalDecimalSeparator
+ *                 Digit+
  *
- *   

- *       
+ *   
Exponent:
+ *       
( [eE] [+-]? Digit+ )
  *
- *   

+ *   
Decimal:
+ *       
( [-+]? DecimalNumeral
+ *                         Exponent? )
+ *       
| LocalPositivePrefix
+ *                 DecimalNumeral
+ *                 LocalPositiveSuffix
+ *                 Exponent?
+ *       
| LocalNegativePrefix
+ *                 DecimalNumeral
+ *                 LocalNegativeSuffix
+ *                 Exponent?
  *
- *   

- *       
+ *   
HexFloat:
+ *       
[-+]? 0[xX][0-9a-fA-F]*\.[0-9a-fA-F]+
+ *                 ([pP][-+]?[0-9]+)?
  *
- *   

- *
- *   
- *       
- *   
- *       
- *   
- *       
- *
- *   
- *
- *   
- *       
- *   
- *       
- *   
- *       
- *
- *   
- *
- *   
- *       
- *
- *   
- *
- *   
- *       
- *   
- *       
- *   
- *       
- *
- *   
- *
- *   
- *       
- *
- *   
- *
- *   
- *       
+ *                          | LocalInfinity
  *
- *   
+ *   
SignedNonNumber:
+ *       
( [-+]? NonNumber )
+ *       
| LocalPositivePrefix
+ *                 NonNumber
+ *                 LocalPositiveSuffix
+ *       
| LocalNegativePrefix
+ *                 NonNumber
+ *                 LocalNegativeSuffix
  *
- *   

- *       
- *   
- *       
- *   
- *       
+ *   
Float:
+ *       
Decimal
+ *           | HexFloat
+ *           | SignedNonNumber
  *
- *   

- *
- *   
- *       
- *       
- *           
- *       
- *           
- *
- * 
NonASCIIDigit  ::= A non-ASCII character c for which
- *            {@link java.lang.Character#isDigit Character.isDigit}(c)
- *                        returns true
 
Non0Digit  ::= [1-Rmax] | NonASCIIDigit
 
Digit  ::= [0-Rmax] | NonASCIIDigit
 
GroupedNumeral  ::
- *         
- *           
- *               
- *           
- *               
- *         
= ( Non0Digit
- *                   Digit?
- *                   Digit?
( LocalGroupSeparator
- *                         Digit
- *                         Digit
- *                         Digit )+ )
 
Numeral  ::= ( ( Digit+ )
- *               | GroupedNumeral )
 

- *         Integer  ::= ( [-+]? ( Numeral
- *                               ) )
| LocalPositivePrefix Numeral
- *                      LocalPositiveSuffix
| LocalNegativePrefix Numeral
- *                 LocalNegativeSuffix
 
DecimalNumeral  ::= Numeral
| Numeral
- *                 LocalDecimalSeparator
- *                 Digit*
| LocalDecimalSeparator
- *                 Digit+
 
Exponent  ::= ( [eE] [+-]? Digit+ )
 

- *         Decimal  ::= ( [-+]? DecimalNumeral
- *                         Exponent? )
| LocalPositivePrefix
- *                 DecimalNumeral
- *                 LocalPositiveSuffix
- *                 Exponent?
| LocalNegativePrefix
- *                 DecimalNumeral
- *                 LocalNegativeSuffix
- *                 Exponent?
 
HexFloat  ::= [-+]? 0[xX][0-9a-fA-F]*\.[0-9a-fA-F]+
- *                 ([pP][-+]?[0-9]+)?
 
NonNumber  ::= NaN
+ *   
NonNumber:
+ *       
NaN
  *                          | LocalNan
  *                          | Infinity
- *                          | LocalInfinity
 
SignedNonNumber  ::= ( [-+]? NonNumber )
| LocalPositivePrefix
- *                 NonNumber
- *                 LocalPositiveSuffix
| LocalNegativePrefix
- *                 NonNumber
- *                 LocalNegativeSuffix
 

- *         Float  ::= Decimal
| HexFloat
| SignedNonNumber

- * 
- *
- * 
 Whitespace is not significant in the above regular expressions.
+ * 
+ * 
Whitespace is not significant in the above regular expressions.
  *
  * @since   1.5
  */
@@ -1675,6 +1627,7 @@
      * findWithinHorizon(Pattern.compile(pattern, horizon)).
      *
      * @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
diff --git a/src/share/classes/java/util/ServiceLoader.java b/src/share/classes/java/util/ServiceLoader.java
--- a/src/share/classes/java/util/ServiceLoader.java
+++ b/src/share/classes/java/util/ServiceLoader.java
@@ -68,12 +68,13 @@
  *
  * 
 A service provider is identified by placing a
  * provider-configuration file in the resource directory
- * META-INF/services.  The file's name is the fully-qualified META-INF/services.  The file's name is the fully-qualified binary name 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
- * '#' ('\u0023', NUMBER SIGN); on
+ * '#' ('\u0023',
+ * NUMBER SIGN); 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   the class of the service type
+     *
      * @param  service
      *         The interface or abstract class representing the service
      *
@@ -517,6 +520,8 @@
      * ServiceLoader.load(service,
      *                    Thread.currentThread().getContextClassLoader())

      *
+     * @param   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   the class of the service type
+     *
      * @param  service
      *         The interface or abstract class representing the service
      *
diff --git a/src/share/classes/java/util/StringJoiner.java b/src/share/classes/java/util/StringJoiner.java
--- a/src/share/classes/java/util/StringJoiner.java
+++ b/src/share/classes/java/util/StringJoiner.java
@@ -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);
diff --git a/src/share/classes/java/util/TimeZone.java b/src/share/classes/java/util/TimeZone.java
--- a/src/share/classes/java/util/TimeZone.java
+++ b/src/share/classes/java/util/TimeZone.java
@@ -118,7 +118,7 @@
  *
* For example, TimeZone.getTimeZone("GMT-8").getID() returns "GMT-08:00". * - *

Three-letter time zone IDs

+ *

Three-letter time zone IDs

* * For compatibility with JDK 1.1.x, some other three-letter time zone IDs * (such as "PST", "CTT", "AST") are also supported. However, their @@ -304,10 +304,10 @@ * presentation to the user in the default locale. * *

This method is equivalent to: - * 


+     * 
      * getDisplayName(false, {@link #LONG},
      *                Locale.getDefault({@link Locale.Category#DISPLAY}))
-     *
+ * * * @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}. * *

This method is equivalent to: - * 


+     * 
      * getDisplayName(false, {@link #LONG}, locale)
-     *
+ * * * @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. * *

This method is equivalent to: - * 


+     * 
      * getDisplayName(daylight, style,
      *                Locale.getDefault({@link Locale.Category#DISPLAY}))
-     *
+ * * * @param daylight {@code true} specifying a Daylight Saving Time name, or * {@code false} specifying a Standard Time name diff --git a/src/share/classes/java/util/UUID.java b/src/share/classes/java/util/UUID.java --- a/src/share/classes/java/util/UUID.java +++ b/src/share/classes/java/util/UUID.java @@ -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) { diff --git a/src/share/classes/java/util/Vector.java b/src/share/classes/java/util/Vector.java --- a/src/share/classes/java/util/Vector.java +++ b/src/share/classes/java/util/Vector.java @@ -45,9 +45,9 @@ * capacity of a vector before inserting a large number of * components; this reduces the amount of incremental reallocation. * - *

+ *

* The iterators returned by this class's {@link #iterator() iterator} and - * {@link #listIterator(int) listIterator} methods are fail-fast: + * {@link #listIterator(int) listIterator} methods are fail-fast: * 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