8020409: Clean up doclint problems in java.util package, part 1
Summary: Clean up doclint problems in java.util package, part 1
Reviewed-by: darcy
Contributed-by: Brian Burkhalter <brian.burkhalter@oracle.com>
--- a/jdk/src/share/classes/java/util/ArrayList.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/ArrayList.java Mon Jul 15 14:37:01 2013 -0700
@@ -70,9 +70,9 @@
* unsynchronized access to the list:<pre>
* List list = Collections.synchronizedList(new ArrayList(...));</pre>
*
- * <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 list 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
--- a/jdk/src/share/classes/java/util/Arrays.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/Arrays.java Mon Jul 15 14:37:01 2013 -0700
@@ -984,6 +984,7 @@
* {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
* execute any parallel tasks.
*
+ * @param <T> the class of the objects to be sorted
* @param a the array to be sorted
*
* @throws ClassCastException if the array contains elements that are not
@@ -1035,6 +1036,7 @@
* array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
* used to execute any parallel tasks.
*
+ * @param <T> the class of the objects to be sorted
* @param a the array to be sorted
* @param fromIndex the index of the first element (inclusive) to be
* sorted
@@ -1087,6 +1089,7 @@
* {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
* execute any parallel tasks.
*
+ * @param <T> the class of the objects to be sorted
* @param a the array to be sorted
* @param cmp the comparator to determine the order of the array. A
* {@code null} value indicates that the elements'
@@ -1138,6 +1141,7 @@
* array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
* used to execute any parallel tasks.
*
+ * @param <T> the class of the objects to be sorted
* @param a the array to be sorted
* @param fromIndex the index of the first element (inclusive) to be
* sorted
@@ -1412,6 +1416,7 @@
* Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
* January 1993.
*
+ * @param <T> the class of the objects to be sorted
* @param a the array to be sorted
* @param c the comparator to determine the order of the array. A
* {@code null} value indicates that the elements'
@@ -1475,6 +1480,7 @@
* Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
* January 1993.
*
+ * @param <T> the class of the objects to be sorted
* @param a the array to be sorted
* @param fromIndex the index of the first element (inclusive) to be
* sorted
@@ -1569,6 +1575,7 @@
* Parallel prefix computation is usually more efficient than
* sequential loops for large arrays.
*
+ * @param <T> the class of the objects in the array
* @param array the array, which is modified in-place by this method
* @param op a side-effect-free, associative function to perform the
* cumulation
@@ -1585,6 +1592,7 @@
* Performs {@link #parallelPrefix(Object[], BinaryOperator)}
* for the given subrange of the array.
*
+ * @param <T> the class of the objects in the array
* @param array the array
* @param fromIndex the index of the first element, inclusive
* @param toIndex the index of the last element, exclusive
@@ -2437,6 +2445,7 @@
* elements equal to the specified object, there is no guarantee which one
* will be found.
*
+ * @param <T> the class of the objects in the array
* @param a the array to be searched
* @param key the value to be searched for
* @param c the comparator by which the array is ordered. A
@@ -2472,6 +2481,7 @@
* If the range contains multiple elements equal to the specified object,
* there is no guarantee which one will be found.
*
+ * @param <T> the class of the objects in the array
* @param a the array to be searched
* @param fromIndex the index of the first element (inclusive) to be
* searched
@@ -3143,6 +3153,7 @@
* is greater than that of the original array.
* The resulting array is of exactly the same class as the original array.
*
+ * @param <T> the class of the objects in the array
* @param original the array to be copied
* @param newLength the length of the copy to be returned
* @return a copy of the original array, truncated or padded with nulls
@@ -3166,6 +3177,8 @@
* is greater than that of the original array.
* The resulting array is of the class <tt>newType</tt>.
*
+ * @param <U> the class of the objects in the original array
+ * @param <T> the class of the objects in the returned array
* @param original the array to be copied
* @param newLength the length of the copy to be returned
* @param newType the class of the copy to be returned
@@ -3396,6 +3409,7 @@
* <p>
* The resulting array is of exactly the same class as the original array.
*
+ * @param <T> the class of the objects in the array
* @param original the array from which a range is to be copied
* @param from the initial index of the range to be copied, inclusive
* @param to the final index of the range to be copied, exclusive.
@@ -3428,6 +3442,8 @@
* of the returned array will be <tt>to - from</tt>.
* The resulting array is of the class <tt>newType</tt>.
*
+ * @param <U> the class of the objects in the original array
+ * @param <T> the class of the objects in the returned array
* @param original the array from which a range is to be copied
* @param from the initial index of the range to be copied, inclusive
* @param to the final index of the range to be copied, exclusive.
@@ -3760,6 +3776,7 @@
* List<String> stooges = Arrays.asList("Larry", "Moe", "Curly");
* </pre>
*
+ * @param <T> the class of the objects in the array
* @param a the array by which the list will be backed
* @return a list view of the specified array
*/
--- a/jdk/src/share/classes/java/util/Base64.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/Base64.java Mon Jul 15 14:37:01 2013 -0700
@@ -42,24 +42,21 @@
*
* <p>
* <ul>
- * <a name="basic">
- * <li><b>Basic</b>
+ * <li><a name="basic"><b>Basic</b></a>
* <p> Uses "The Base64 Alphabet" as specified in Table 1 of
* RFC 4648 and RFC 2045 for encoding and decoding operation.
* The encoder does not add any line feed (line separator)
* character. The decoder rejects data that contains characters
* outside the base64 alphabet.</p></li>
*
- * <a name="url">
- * <li><b>URL and Filename safe</b>
+ * <li><a name="url"><b>URL and Filename safe</b></a>
* <p> Uses the "URL and Filename safe Base64 Alphabet" as specified
* in Table 2 of RFC 4648 for encoding and decoding. The
* encoder does not add any line feed (line separator) character.
* The decoder rejects data that contains characters outside the
* base64 alphabet.</p></li>
*
- * <a name="mime">
- * <li><b>MIME</b>
+ * <li><a name="mime"><b>MIME</b></a>
* <p> Uses the "The Base64 Alphabet" as specified in Table 1 of
* RFC 2045 for encoding and decoding operation. The encoded output
* must be represented in lines of no more than 76 characters each
--- a/jdk/src/share/classes/java/util/BitSet.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/BitSet.java Mon Jul 15 14:37:01 2013 -0700
@@ -189,6 +189,7 @@
* @param longs a long array containing a little-endian representation
* of a sequence of bits to be used as the initial bits of the
* new bit set
+ * @return a {@code BitSet} containing all the bits in the long array
* @since 1.7
*/
public static BitSet valueOf(long[] longs) {
@@ -212,6 +213,8 @@
* @param lb a long buffer containing a little-endian representation
* of a sequence of bits between its position and limit, to be
* used as the initial bits of the new bit set
+ * @return a {@code BitSet} containing all the bits in the buffer in the
+ * specified range
* @since 1.7
*/
public static BitSet valueOf(LongBuffer lb) {
@@ -237,6 +240,7 @@
* @param bytes a byte array containing a little-endian
* representation of a sequence of bits to be used as the
* initial bits of the new bit set
+ * @return a {@code BitSet} containing all the bits in the byte array
* @since 1.7
*/
public static BitSet valueOf(byte[] bytes) {
@@ -257,6 +261,8 @@
* @param bb a byte buffer containing a little-endian representation
* of a sequence of bits between its position and limit, to be
* used as the initial bits of the new bit set
+ * @return a {@code BitSet} containing all the bits in the buffer in the
+ * specified range
* @since 1.7
*/
public static BitSet valueOf(ByteBuffer bb) {
--- a/jdk/src/share/classes/java/util/Calendar.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/Calendar.java Mon Jul 15 14:37:01 2013 -0700
@@ -96,7 +96,7 @@
* concrete subclass, such as <code>ERA</code>. See individual field
* documentation and subclass documentation for details.
*
- * <h4>Getting and Setting Calendar Field Values</h4>
+ * <h3>Getting and Setting Calendar Field Values</h3>
*
* <p>The calendar field values can be set by calling the <code>set</code>
* methods. Any field values set in a <code>Calendar</code> will not be
@@ -207,7 +207,7 @@
* <h4>Field Manipulation</h4>
*
* The calendar fields can be changed using three methods:
- * <code>set()</code>, <code>add()</code>, and <code>roll()</code>.</p>
+ * <code>set()</code>, <code>add()</code>, and <code>roll()</code>.
*
* <p><strong><code>set(f, value)</code></strong> changes calendar field
* <code>f</code> to <code>value</code>. In addition, it sets an
@@ -2024,6 +2024,7 @@
* including cases that the value has been set by internal fields
* calculations triggered by a <code>get</code> method call.
*
+ * @param field the calendar field to test
* @return <code>true</code> if the given calendar field has a value set;
* <code>false</code> otherwise.
*/
--- a/jdk/src/share/classes/java/util/Collection.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/Collection.java Mon Jul 15 14:37:01 2013 -0700
@@ -64,9 +64,9 @@
* but is not required to, throw the exception if the collection to be added
* is empty.
*
- * <p><a name="optional-restrictions"/>
+ * <p><a name="optional-restrictions">
* Some collection implementations have restrictions on the elements that
- * they may contain. For example, some implementations prohibit null elements,
+ * they may contain.</a> For example, some implementations prohibit null elements,
* and some have restrictions on the types of their elements. Attempting to
* add an ineligible element throws an unchecked exception, typically
* <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. Attempting
@@ -232,6 +232,7 @@
* Note that <tt>toArray(new Object[0])</tt> is identical in function to
* <tt>toArray()</tt>.
*
+ * @param <T> the runtime type of the array to contain the collection
* @param a the array into which the elements of this collection are to be
* stored, if it is big enough; otherwise, a new array of the same
* runtime type is allocated for this purpose.
@@ -537,7 +538,6 @@
* @return a {@code Spliterator} over the elements in this collection
* @since 1.8
*/
- @Override
default Spliterator<E> spliterator() {
return Spliterators.spliterator(this, 0);
}
--- a/jdk/src/share/classes/java/util/Collections.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/Collections.java Mon Jul 15 14:37:01 2013 -0700
@@ -150,6 +150,7 @@
* n<sup>2</sup> log(n) performance that would result from attempting
* to sort a linked list in place.
*
+ * @param <T> the class of the objects in the list
* @param list the list to be sorted.
* @throws ClassCastException if the list contains elements that are not
* <i>mutually comparable</i> (for example, strings and integers).
@@ -211,6 +212,7 @@
* n<sup>2</sup> log(n) performance that would result from attempting
* to sort a linked list in place.
*
+ * @param <T> the class of the objects in the list
* @param list the list to be sorted.
* @param c the comparator to determine the order of the list. A
* {@code null} value indicates that the elements' <i>natural
@@ -249,6 +251,7 @@
* this method will do an iterator-based binary search that performs
* O(n) link traversals and O(log n) element comparisons.
*
+ * @param <T> the class of the objects in the list
* @param list the list to be searched.
* @param key the key to be searched for.
* @return the index of the search key, if it is contained in the list;
@@ -349,6 +352,7 @@
* this method will do an iterator-based binary search that performs
* O(n) link traversals and O(log n) element comparisons.
*
+ * @param <T> the class of the objects in the list
* @param list the list to be searched.
* @param key the key to be searched for.
* @param c the comparator by which the list is ordered.
@@ -568,6 +572,7 @@
*
* This method runs in linear time.
*
+ * @param <T> the class of the objects in the list
* @param list the list to be filled with the specified element.
* @param obj The element with which to fill the specified list.
* @throws UnsupportedOperationException if the specified list or its
@@ -597,6 +602,7 @@
*
* This method runs in linear time.
*
+ * @param <T> the class of the objects in the lists
* @param dest The destination list.
* @param src The source list.
* @throws IndexOutOfBoundsException if the destination list is too small
@@ -635,6 +641,7 @@
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
+ * @param <T> the class of the objects in the collection
* @param coll the collection whose minimum element is to be determined.
* @return the minimum element of the given collection, according
* to the <i>natural ordering</i> of its elements.
@@ -667,6 +674,7 @@
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
+ * @param <T> the class of the objects in the collection
* @param coll the collection whose minimum element is to be determined.
* @param comp the comparator with which to determine the minimum element.
* A <tt>null</tt> value indicates that the elements' <i>natural
@@ -706,6 +714,7 @@
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
+ * @param <T> the class of the objects in the collection
* @param coll the collection whose maximum element is to be determined.
* @return the maximum element of the given collection, according
* to the <i>natural ordering</i> of its elements.
@@ -738,6 +747,7 @@
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
+ * @param <T> the class of the objects in the collection
* @param coll the collection whose maximum element is to be determined.
* @param comp the comparator with which to determine the maximum element.
* A <tt>null</tt> value indicates that the elements' <i>natural
@@ -872,6 +882,7 @@
* <tt>(oldVal==null ? e==null : oldVal.equals(e))</tt>.
* (This method has no effect on the size of the list.)
*
+ * @param <T> the class of the objects in the list
* @param list the list in which replacement is to occur.
* @param oldVal the old value to be replaced.
* @param newVal the new value with which <tt>oldVal</tt> is to be
@@ -1053,6 +1064,7 @@
* The returned collection will be serializable if the specified collection
* is serializable.
*
+ * @param <T> the class of the objects in the collection
* @param c the collection for which an unmodifiable view is to be
* returned.
* @return an unmodifiable view of the specified collection.
@@ -1148,6 +1160,7 @@
* The returned set will be serializable if the specified set
* is serializable.
*
+ * @param <T> the class of the objects in the set
* @param s the set for which an unmodifiable view is to be returned.
* @return an unmodifiable view of the specified set.
*/
@@ -1179,6 +1192,7 @@
* The returned sorted set will be serializable if the specified sorted set
* is serializable.
*
+ * @param <T> the class of the objects in the set
* @param s the sorted set for which an unmodifiable view is to be
* returned.
* @return an unmodifiable view of the specified sorted set.
@@ -1226,6 +1240,7 @@
* The returned navigable set will be serializable if the specified
* navigable set is serializable.
*
+ * @param <T> the class of the objects in the set
* @param s the navigable set for which an unmodifiable view is to be
* returned
* @return an unmodifiable view of the specified navigable set
@@ -1314,6 +1329,7 @@
* is serializable. Similarly, the returned list will implement
* {@link RandomAccess} if the specified list does.
*
+ * @param <T> the class of the objects in the list
* @param list the list for which an unmodifiable view is to be returned.
* @return an unmodifiable view of the specified list.
*/
@@ -1458,6 +1474,8 @@
* The returned map will be serializable if the specified map
* is serializable.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @param m the map for which an unmodifiable view is to be returned.
* @return an unmodifiable view of the specified map.
*/
@@ -1807,6 +1825,8 @@
* The returned sorted map will be serializable if the specified sorted map
* is serializable.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @param m the sorted map for which an unmodifiable view is to be
* returned.
* @return an unmodifiable view of the specified sorted map.
@@ -1849,6 +1869,8 @@
* The returned navigable map will be serializable if the specified
* navigable map is serializable.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @param m the navigable map for which an unmodifiable view is to be
* returned
* @return an unmodifiable view of the specified navigable map
@@ -2002,6 +2024,7 @@
* The returned collection will be serializable if the specified collection
* is serializable.
*
+ * @param <T> the class of the objects in the collection
* @param c the collection to be "wrapped" in a synchronized collection.
* @return a synchronized view of the specified collection.
*/
@@ -2117,6 +2140,7 @@
* <p>The returned set will be serializable if the specified set is
* serializable.
*
+ * @param <T> the class of the objects in the set
* @param s the set to be "wrapped" in a synchronized set.
* @return a synchronized view of the specified set.
*/
@@ -2187,6 +2211,7 @@
* <p>The returned sorted set will be serializable if the specified
* sorted set is serializable.
*
+ * @param <T> the class of the objects in the set
* @param s the sorted set to be "wrapped" in a synchronized sorted set.
* @return a synchronized view of the specified sorted set.
*/
@@ -2277,6 +2302,7 @@
* <p>The returned navigable set will be serializable if the specified
* navigable set is serializable.
*
+ * @param <T> the class of the objects in the set
* @param s the navigable set to be "wrapped" in a synchronized navigable
* set
* @return a synchronized view of the specified navigable set
@@ -2379,6 +2405,7 @@
* <p>The returned list will be serializable if the specified list is
* serializable.
*
+ * @param <T> the class of the objects in the list
* @param list the list to be "wrapped" in a synchronized list.
* @return a synchronized view of the specified list.
*/
@@ -2548,6 +2575,8 @@
* <p>The returned map will be serializable if the specified map is
* serializable.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @param m the map to be "wrapped" in a synchronized map.
* @return a synchronized view of the specified map.
*/
@@ -2738,6 +2767,8 @@
* <p>The returned sorted map will be serializable if the specified
* sorted map is serializable.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @param m the sorted map to be "wrapped" in a synchronized sorted map.
* @return a synchronized view of the specified sorted map.
*/
@@ -2833,6 +2864,8 @@
* <p>The returned navigable map will be serializable if the specified
* navigable map is serializable.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @param m the navigable map to be "wrapped" in a synchronized navigable
* map
* @return a synchronized view of the specified navigable map.
@@ -3008,6 +3041,7 @@
* type, the returned collection permits insertion of null elements
* whenever the backing collection does.
*
+ * @param <E> the class of the objects in the collection
* @param c the collection for which a dynamically typesafe view is to be
* returned
* @param type the type of element that {@code c} is permitted to hold
@@ -3153,6 +3187,7 @@
* type, the returned queue permits insertion of {@code null} elements
* whenever the backing queue does.
*
+ * @param <E> the class of the objects in the queue
* @param queue the queue for which a dynamically typesafe view is to be
* returned
* @param type the type of element that {@code queue} is permitted to hold
@@ -3211,6 +3246,7 @@
* type, the returned set permits insertion of null elements whenever
* the backing set does.
*
+ * @param <E> the class of the objects in the set
* @param s the set for which a dynamically typesafe view is to be
* returned
* @param type the type of element that {@code s} is permitted to hold
@@ -3256,6 +3292,7 @@
* type, the returned sorted set permits insertion of null elements
* whenever the backing sorted set does.
*
+ * @param <E> the class of the objects in the set
* @param s the sorted set for which a dynamically typesafe view is to be
* returned
* @param type the type of element that {@code s} is permitted to hold
@@ -3318,6 +3355,7 @@
* type, the returned navigable set permits insertion of null elements
* whenever the backing sorted set does.
*
+ * @param <E> the class of the objects in the set
* @param s the navigable set for which a dynamically typesafe view is to be
* returned
* @param type the type of element that {@code s} is permitted to hold
@@ -3398,6 +3436,7 @@
* type, the returned list permits insertion of null elements whenever
* the backing list does.
*
+ * @param <E> the class of the objects in the list
* @param list the list for which a dynamically typesafe view is to be
* returned
* @param type the type of element that {@code list} is permitted to hold
@@ -3535,6 +3574,8 @@
* type, the returned map permits insertion of null keys or values
* whenever the backing map does.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @param m the map for which a dynamically typesafe view is to be
* returned
* @param keyType the type of key that {@code m} is permitted to hold
@@ -3928,6 +3969,8 @@
* type, the returned map permits insertion of null keys or values
* whenever the backing map does.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @param m the map for which a dynamically typesafe view is to be
* returned
* @param keyType the type of key that {@code m} is permitted to hold
@@ -4149,17 +4192,13 @@
/**
* Returns an iterator that has no elements. More precisely,
*
- * <ul compact>
- *
+ * <ul>
* <li>{@link Iterator#hasNext hasNext} always returns {@code
- * false}.
- *
+ * false}.</li>
* <li>{@link Iterator#next next} always throws {@link
- * NoSuchElementException}.
- *
+ * NoSuchElementException}.</li>
* <li>{@link Iterator#remove remove} always throws {@link
- * IllegalStateException}.
- *
+ * IllegalStateException}.</li>
* </ul>
*
* <p>Implementations of this method are permitted, but not
@@ -4190,27 +4229,20 @@
/**
* Returns a list iterator that has no elements. More precisely,
*
- * <ul compact>
- *
+ * <ul>
* <li>{@link Iterator#hasNext hasNext} and {@link
* ListIterator#hasPrevious hasPrevious} always return {@code
- * false}.
- *
+ * false}.</li>
* <li>{@link Iterator#next next} and {@link ListIterator#previous
- * previous} always throw {@link NoSuchElementException}.
- *
+ * previous} always throw {@link NoSuchElementException}.</li>
* <li>{@link Iterator#remove remove} and {@link ListIterator#set
- * set} always throw {@link IllegalStateException}.
- *
+ * set} always throw {@link IllegalStateException}.</li>
* <li>{@link ListIterator#add add} always throws {@link
- * UnsupportedOperationException}.
- *
+ * UnsupportedOperationException}.</li>
* <li>{@link ListIterator#nextIndex nextIndex} always returns
- * {@code 0} .
- *
+ * {@code 0}.</li>
* <li>{@link ListIterator#previousIndex previousIndex} always
- * returns {@code -1}.
- *
+ * returns {@code -1}.</li>
* </ul>
*
* <p>Implementations of this method are permitted, but not
@@ -4243,19 +4275,17 @@
/**
* Returns an enumeration that has no elements. More precisely,
*
- * <ul compact>
- *
+ * <ul>
* <li>{@link Enumeration#hasMoreElements hasMoreElements} always
- * returns {@code false}.
- *
+ * returns {@code false}.</li>
* <li> {@link Enumeration#nextElement nextElement} always throws
- * {@link NoSuchElementException}.
- *
+ * {@link NoSuchElementException}.</li>
* </ul>
*
* <p>Implementations of this method are permitted, but not
* required, to return the same object from multiple invocations.
*
+ * @param <T> the class of the objects in the enumeration
* @return an empty enumeration
* @since 1.7
*/
@@ -4293,6 +4323,7 @@
* comparable cost to using the like-named field. (Unlike this method, the
* field does not provide type safety.)
*
+ * @param <T> the class of the objects in the set
* @return the empty set
*
* @see #EMPTY_SET
@@ -4509,6 +4540,8 @@
* comparable cost to using the like-named field. (Unlike this method, the
* field does not provide type safety.)
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @return an empty map
* @see #EMPTY_MAP
* @since 1.5
@@ -4529,6 +4562,8 @@
* @implNote Implementations of this method need not create a separate
* {@code SortedMap} object for each call.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @return an empty sorted map
* @since 1.8
*/
@@ -4548,6 +4583,8 @@
* @implNote Implementations of this method need not create a separate
* {@code NavigableMap} object for each call.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @return an empty navigable map
* @since 1.8
*/
@@ -4653,6 +4690,7 @@
* Returns an immutable set containing only the specified object.
* The returned set is serializable.
*
+ * @param <T> the class of the objects in the set
* @param o the sole object to be stored in the returned set.
* @return an immutable set containing only the specified object.
*/
@@ -4773,6 +4811,7 @@
* Returns an immutable list containing only the specified object.
* The returned list is serializable.
*
+ * @param <T> the class of the objects in the list
* @param o the sole object to be stored in the returned list.
* @return an immutable list containing only the specified object.
* @since 1.3
@@ -4834,6 +4873,8 @@
* Returns an immutable map, mapping only the specified key to the
* specified value. The returned map is serializable.
*
+ * @param <K> the class of the map keys
+ * @param <V> the class of the map values
* @param key the sole key to be stored in the returned map.
* @param value the value to which the returned map maps <tt>key</tt>.
* @return an immutable map containing only the specified key-value
@@ -4959,6 +5000,8 @@
* combination with the <tt>List.addAll</tt> method to grow lists.
* The returned list is serializable.
*
+ * @param <T> the class of the object to copy and of the objects
+ * in the returned list.
* @param n the number of elements in the returned list.
* @param o the element to appear repeatedly in the returned list.
* @return an immutable list consisting of <tt>n</tt> copies of the
@@ -5063,6 +5106,7 @@
*
* The returned comparator is serializable.
*
+ * @param <T> the class of the objects compared by the comparator
* @return A comparator that imposes the reverse of the <i>natural
* ordering</i> on a collection of objects that implement
* the <tt>Comparable</tt> interface.
@@ -5106,6 +5150,7 @@
* <p>The returned comparator is serializable (assuming the specified
* comparator is also serializable or {@code null}).
*
+ * @param <T> the class of the objects compared by the comparator
* @param cmp a comparator who's ordering is to be reversed by the returned
* comparator or {@code null}
* @return A comparator that imposes the reverse ordering of the
@@ -5169,6 +5214,7 @@
* interoperability with legacy APIs that require an enumeration
* as input.
*
+ * @param <T> the class of the objects in the collection
* @param c the collection for which an enumeration is to be returned.
* @return an enumeration over the specified collection.
* @see Enumeration
@@ -5194,6 +5240,7 @@
* legacy APIs that return enumerations and new APIs that require
* collections.
*
+ * @param <T> the class of the objects returned by the enumeration
* @param e enumeration providing elements for the returned
* array list
* @return an array list containing the elements returned
@@ -5227,6 +5274,7 @@
* @param c the collection in which to determine the frequency
* of <tt>o</tt>
* @param o the object whose frequency is to be determined
+ * @return the number of elements in {@code c} equal to {@code o}
* @throws NullPointerException if <tt>c</tt> is null
* @since 1.5
*/
@@ -5347,6 +5395,7 @@
* Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");
* </pre>
*
+ * @param <T> the class of the elements to add and of the collection
* @param c the collection into which <tt>elements</tt> are to be inserted
* @param elements the elements to insert into <tt>c</tt>
* @return <tt>true</tt> if the collection changed as a result of the call
@@ -5392,6 +5441,8 @@
* new WeakHashMap<Object, Boolean>());
* </pre>
*
+ * @param <E> the class of the map keys and of the objects in the
+ * returned set
* @param map the backing map
* @return the set backed by the map
* @throws IllegalArgumentException if <tt>map</tt> is not empty
@@ -5470,6 +5521,7 @@
* implemented as a sequence of {@link Deque#addFirst addFirst}
* invocations on the backing deque.
*
+ * @param <T> the class of the objects in the deque
* @param deque the deque
* @return the queue
* @since 1.6
--- a/jdk/src/share/classes/java/util/EnumSet.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/EnumSet.java Mon Jul 15 14:37:01 2013 -0700
@@ -100,8 +100,10 @@
/**
* Creates an empty enum set with the specified element type.
*
+ * @param <E> The class of the elements in the set
* @param elementType the class object of the element type for this enum
* set
+ * @return An empty enum set of the specified type.
* @throws NullPointerException if <tt>elementType</tt> is null
*/
public static <E extends Enum<E>> EnumSet<E> noneOf(Class<E> elementType) {
@@ -119,8 +121,10 @@
* Creates an enum set containing all of the elements in the specified
* element type.
*
+ * @param <E> The class of the elements in the set
* @param elementType the class object of the element type for this enum
* set
+ * @return An enum set containing all the elements in the specified type.
* @throws NullPointerException if <tt>elementType</tt> is null
*/
public static <E extends Enum<E>> EnumSet<E> allOf(Class<E> elementType) {
@@ -139,7 +143,9 @@
* Creates an enum set with the same element type as the specified enum
* set, initially containing the same elements (if any).
*
+ * @param <E> The class of the elements in the set
* @param s the enum set from which to initialize this enum set
+ * @return A copy of the specified enum set.
* @throws NullPointerException if <tt>s</tt> is null
*/
public static <E extends Enum<E>> EnumSet<E> copyOf(EnumSet<E> s) {
@@ -153,7 +159,9 @@
* Otherwise, the specified collection must contain at least one element
* (in order to determine the new enum set's element type).
*
+ * @param <E> The class of the elements in the collection
* @param c the collection from which to initialize this enum set
+ * @return An enum set initialized from the given collection.
* @throws IllegalArgumentException if <tt>c</tt> is not an
* <tt>EnumSet</tt> instance and contains no elements
* @throws NullPointerException if <tt>c</tt> is null
@@ -178,7 +186,9 @@
* set, initially containing all the elements of this type that are
* <i>not</i> contained in the specified set.
*
+ * @param <E> The class of the elements in the enum set
* @param s the enum set from whose complement to initialize this enum set
+ * @return The complement of the specified set in this set
* @throws NullPointerException if <tt>s</tt> is null
*/
public static <E extends Enum<E>> EnumSet<E> complementOf(EnumSet<E> s) {
@@ -196,6 +206,7 @@
* an enum set initially containing an arbitrary number of elements, but
* is likely to run slower than the overloadings that do not use varargs.
*
+ * @param <E> The class of the specified element and of the set
* @param e the element that this set is to contain initially
* @throws NullPointerException if <tt>e</tt> is null
* @return an enum set initially containing the specified element
@@ -215,6 +226,7 @@
* an enum set initially containing an arbitrary number of elements, but
* is likely to run slower than the overloadings that do not use varargs.
*
+ * @param <E> The class of the parameter elements and of the set
* @param e1 an element that this set is to contain initially
* @param e2 another element that this set is to contain initially
* @throws NullPointerException if any parameters are null
@@ -236,6 +248,7 @@
* an enum set initially containing an arbitrary number of elements, but
* is likely to run slower than the overloadings that do not use varargs.
*
+ * @param <E> The class of the parameter elements and of the set
* @param e1 an element that this set is to contain initially
* @param e2 another element that this set is to contain initially
* @param e3 another element that this set is to contain initially
@@ -259,6 +272,7 @@
* an enum set initially containing an arbitrary number of elements, but
* is likely to run slower than the overloadings that do not use varargs.
*
+ * @param <E> The class of the parameter elements and of the set
* @param e1 an element that this set is to contain initially
* @param e2 another element that this set is to contain initially
* @param e3 another element that this set is to contain initially
@@ -284,6 +298,7 @@
* an enum set initially containing an arbitrary number of elements, but
* is likely to run slower than the overloadings that do not use varargs.
*
+ * @param <E> The class of the parameter elements and of the set
* @param e1 an element that this set is to contain initially
* @param e2 another element that this set is to contain initially
* @param e3 another element that this set is to contain initially
@@ -311,6 +326,7 @@
* number of elements, but it is likely to run slower than the overloadings
* that do not use varargs.
*
+ * @param <E> The class of the parameter elements and of the set
* @param first an element that the set is to contain initially
* @param rest the remaining elements the set is to contain initially
* @throws NullPointerException if any of the specified elements are null,
@@ -332,6 +348,7 @@
* contain the endpoints themselves, which may be identical but must not
* be out of order.
*
+ * @param <E> The class of the parameter elements and of the set
* @param from the first element in the range
* @param to the last element in the range
* @throws NullPointerException if {@code from} or {@code to} are null
--- a/jdk/src/share/classes/java/util/GregorianCalendar.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/GregorianCalendar.java Mon Jul 15 14:37:01 2013 -0700
@@ -94,7 +94,7 @@
* adjustment may be made if desired for dates that are prior to the Gregorian
* changeover and which fall between January 1 and March 24.
*
- * <h4><a name="week_and_year">Week Of Year and Week Year</a></h4>
+ * <h3><a name="week_and_year">Week Of Year and Week Year</a></h3>
*
* <p>Values calculated for the {@link Calendar#WEEK_OF_YEAR
* WEEK_OF_YEAR} field range from 1 to 53. The first week of a
--- a/jdk/src/share/classes/java/util/Locale.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/Locale.java Mon Jul 15 14:37:01 2013 -0700
@@ -84,7 +84,7 @@
* described below.
*
* <dl>
- * <dt><a name="def_language"/><b>language</b></dt>
+ * <dt><a name="def_language"><b>language</b></a></dt>
*
* <dd>ISO 639 alpha-2 or alpha-3 language code, or registered
* language subtags up to 8 alpha letters (for future enhancements).
@@ -92,51 +92,51 @@
* alpha-2 code must be used. You can find a full list of valid
* language codes in the IANA Language Subtag Registry (search for
* "Type: language"). The language field is case insensitive, but
- * <code>Locale</code> always canonicalizes to lower case.</dd><br>
+ * <code>Locale</code> always canonicalizes to lower case.</dd>
*
* <dd>Well-formed language values have the form
* <code>[a-zA-Z]{2,8}</code>. Note that this is not the the full
* BCP47 language production, since it excludes extlang. They are
* not needed since modern three-letter language codes replace
- * them.</dd><br>
+ * them.</dd>
*
- * <dd>Example: "en" (English), "ja" (Japanese), "kok" (Konkani)</dd><br>
+ * <dd>Example: "en" (English), "ja" (Japanese), "kok" (Konkani)</dd>
*
- * <dt><a name="def_script"/><b>script</b></dt>
+ * <dt><a name="def_script"><b>script</b></a></dt>
*
* <dd>ISO 15924 alpha-4 script code. You can find a full list of
* valid script codes in the IANA Language Subtag Registry (search
* for "Type: script"). The script field is case insensitive, but
* <code>Locale</code> always canonicalizes to title case (the first
* letter is upper case and the rest of the letters are lower
- * case).</dd><br>
+ * case).</dd>
*
* <dd>Well-formed script values have the form
- * <code>[a-zA-Z]{4}</code></dd><br>
+ * <code>[a-zA-Z]{4}</code></dd>
*
- * <dd>Example: "Latn" (Latin), "Cyrl" (Cyrillic)</dd><br>
+ * <dd>Example: "Latn" (Latin), "Cyrl" (Cyrillic)</dd>
*
- * <dt><a name="def_region"/><b>country (region)</b></dt>
+ * <dt><a name="def_region"><b>country (region)</b></a></dt>
*
* <dd>ISO 3166 alpha-2 country code or UN M.49 numeric-3 area code.
* You can find a full list of valid country and region codes in the
* IANA Language Subtag Registry (search for "Type: region"). The
* country (region) field is case insensitive, but
- * <code>Locale</code> always canonicalizes to upper case.</dd><br>
+ * <code>Locale</code> always canonicalizes to upper case.</dd>
*
* <dd>Well-formed country/region values have
- * the form <code>[a-zA-Z]{2} | [0-9]{3}</code></dd><br>
+ * the form <code>[a-zA-Z]{2} | [0-9]{3}</code></dd>
*
* <dd>Example: "US" (United States), "FR" (France), "029"
- * (Caribbean)</dd><br>
+ * (Caribbean)</dd>
*
- * <dt><a name="def_variant"/><b>variant</b></dt>
+ * <dt><a name="def_variant"><b>variant</b></a></dt>
*
* <dd>Any arbitrary value used to indicate a variation of a
* <code>Locale</code>. Where there are two or more variant values
* each indicating its own semantics, these values should be ordered
* by importance, with most important first, separated by
- * underscore('_'). The variant field is case sensitive.</dd><br>
+ * underscore('_'). The variant field is case sensitive.</dd>
*
* <dd>Note: IETF BCP 47 places syntactic restrictions on variant
* subtags. Also BCP 47 subtags are strictly used to indicate
@@ -152,16 +152,16 @@
* cultural behaviors such as calendar type or number script. In
* BCP 47 this kind of information, which does not identify the
* language, is supported by extension subtags or private use
- * subtags.</dd><br>
+ * subtags.</dd>
*
* <dd>Well-formed variant values have the form <code>SUBTAG
* (('_'|'-') SUBTAG)*</code> where <code>SUBTAG =
* [0-9][0-9a-zA-Z]{3} | [0-9a-zA-Z]{5,8}</code>. (Note: BCP 47 only
- * uses hyphen ('-') as a delimiter, this is more lenient).</dd><br>
+ * uses hyphen ('-') as a delimiter, this is more lenient).</dd>
*
- * <dd>Example: "polyton" (Polytonic Greek), "POSIX"</dd><br>
+ * <dd>Example: "polyton" (Polytonic Greek), "POSIX"</dd>
*
- * <dt><a name="def_extensions"/><b>extensions</b></dt>
+ * <dt><a name="def_extensions"><b>extensions</b></a></dt>
*
* <dd>A map from single character keys to string values, indicating
* extensions apart from language identification. The extensions in
@@ -169,14 +169,14 @@
* extension subtags and private use subtags. The extensions are
* case insensitive, but <code>Locale</code> canonicalizes all
* extension keys and values to lower case. Note that extensions
- * cannot have empty values.</dd><br>
+ * cannot have empty values.</dd>
*
* <dd>Well-formed keys are single characters from the set
* <code>[0-9a-zA-Z]</code>. Well-formed values have the form
* <code>SUBTAG ('-' SUBTAG)*</code> where for the key 'x'
* <code>SUBTAG = [0-9a-zA-Z]{1,8}</code> and for other keys
* <code>SUBTAG = [0-9a-zA-Z]{2,8}</code> (that is, 'x' allows
- * single-character subtags).</dd><br>
+ * single-character subtags).</dd>
*
* <dd>Example: key="u"/value="ca-japanese" (Japanese Calendar),
* key="x"/value="java-1-7"</dd>
@@ -189,7 +189,7 @@
* requirement (is well-formed), but does not validate the value
* itself. See {@link Builder} for details.
*
- * <h4><a name="def_locale_extension">Unicode locale/language extension</h4>
+ * <h3><a name="def_locale_extension">Unicode locale/language extension</a></h3>
*
* <p>UTS#35, "Unicode Locale Data Markup Language" defines optional
* attributes and keywords to override or refine the default behavior
@@ -409,7 +409,7 @@
* Clients desiring a string representation of the complete locale can
* then always rely on <code>toLanguageTag</code> for this purpose.
*
- * <h5><a name="special_cases_constructor"/>Special cases</h5>
+ * <h5><a name="special_cases_constructor">Special cases</a></h5>
*
* <p>For compatibility reasons, two
* non-conforming locales are treated as special cases. These are
@@ -1007,6 +1007,8 @@
* country (region), such as 3-letter numeric UN M.49 area codes.
* Therefore, the list returned by this method does not contain ALL valid
* codes that can be used to create Locales.
+ *
+ * @return An array of ISO 3166 two-letter country codes.
*/
public static String[] getISOCountries() {
if (isoCountries == null) {
@@ -1030,6 +1032,8 @@
* 8 characters in length. Therefore, the list returned by this method does
* not contain ALL valid codes that can be used to create Locales.
* </ul>
+ *
+ * @return Am array of ISO 639 two-letter language codes.
*/
public static String[] getISOLanguages() {
if (isoLanguages == null) {
@@ -1268,15 +1272,15 @@
* fields only. To represent a Locale as a String for interchange purposes, use
* {@link #toLanguageTag}.
*
- * <p>Examples: <ul><tt>
- * <li>en
- * <li>de_DE
- * <li>_GB
- * <li>en_US_WIN
- * <li>de__POSIX
- * <li>zh_CN_#Hans
- * <li>zh_TW_#Hant-x-java
- * <li>th_TH_TH_#u-nu-thai</tt></ul>
+ * <p>Examples: <ul>
+ * <li><tt>en</tt></li>
+ * <li><tt>de_DE</tt></li>
+ * <li><tt>_GB</tt></li>
+ * <li><tt>en_US_WIN</tt></li>
+ * <li><tt>de__POSIX</tt></li>
+ * <li><tt>zh_CN_#Hans</tt></li>
+ * <li><tt>zh_TW_#Hant-x-java</tt></li>
+ * <li><tt>th_TH_TH_#u-nu-thai</tt></li></ul>
*
* @return A string representation of the Locale, for debugging.
* @see #getDisplayName
@@ -1506,7 +1510,7 @@
*
* <p>Grandfathered tags with canonical replacements are as follows:
*
- * <table>
+ * <table summary="Grandfathered tags with canonical replacements">
* <tbody align="center">
* <tr><th>grandfathered tag</th><th> </th><th>modern replacement</th></tr>
* <tr><td>art-lojban</td><td> </td><td>jbo</td></tr>
@@ -1535,7 +1539,7 @@
* <p>Grandfathered tags with no modern replacement will be
* converted as follows:
*
- * <table>
+ * <table summary="Grandfathered tags with no modern replacement">
* <tbody align="center">
* <tr><th>grandfathered tag</th><th> </th><th>converts to</th></tr>
* <tr><td>cel-gaulish</td><td> </td><td>xtg-x-cel-gaulish</td></tr>
@@ -1659,6 +1663,8 @@
* (say, we don't have a Japanese name for Croatian),
* this function falls back on the English name, and uses the ISO code as a last-resort
* value. If the locale doesn't specify a language, this function returns the empty string.
+ *
+ * @return The name of the display language.
*/
public final String getDisplayLanguage() {
return getDisplayLanguage(getDefault(Category.DISPLAY));
@@ -1677,6 +1683,8 @@
* on the ISO code as a last-resort value. If the locale doesn't specify a language,
* this function returns the empty string.
*
+ * @param inLocale The locale for which to retrieve the display language.
+ * @return The name of the display language appropriate to the given locale.
* @exception NullPointerException if <code>inLocale</code> is <code>null</code>
*/
public String getDisplayLanguage(Locale inLocale) {
@@ -1703,6 +1711,7 @@
* localized for the given locale. Returns the empty string if
* this locale doesn't specify a script code.
*
+ * @param inLocale The locale for which to retrieve the display script.
* @return the display name of the script code for the current default
* {@link Locale.Category#DISPLAY DISPLAY} locale
* @throws NullPointerException if <code>inLocale</code> is <code>null</code>
@@ -1727,6 +1736,8 @@
* (say, we don't have a Japanese name for Croatia),
* this function falls back on the English name, and uses the ISO code as a last-resort
* value. If the locale doesn't specify a country, this function returns the empty string.
+ *
+ * @return The name of the country appropriate to the locale.
*/
public final String getDisplayCountry() {
return getDisplayCountry(getDefault(Category.DISPLAY));
@@ -1745,6 +1756,8 @@
* on the ISO code as a last-resort value. If the locale doesn't specify a country,
* this function returns the empty string.
*
+ * @param inLocale The locale for which to retrieve the display country.
+ * @return The name of the country appropriate to the given locale.
* @exception NullPointerException if <code>inLocale</code> is <code>null</code>
*/
public String getDisplayCountry(Locale inLocale) {
@@ -1778,6 +1791,8 @@
* user. If possible, the name will be localized for the default
* {@link Locale.Category#DISPLAY DISPLAY} locale. If the locale
* doesn't specify a variant code, this function returns the empty string.
+ *
+ * @return The name of the display variant code appropriate to the locale.
*/
public final String getDisplayVariant() {
return getDisplayVariant(getDefault(Category.DISPLAY));
@@ -1788,6 +1803,8 @@
* user. If possible, the name will be localized for inLocale. If the locale
* doesn't specify a variant code, this function returns the empty string.
*
+ * @param inLocale The locale for which to retrieve the display variant code.
+ * @return The name of the display variant code appropriate to the given locale.
* @exception NullPointerException if <code>inLocale</code> is <code>null</code>
*/
public String getDisplayVariant(Locale inLocale) {
@@ -1821,6 +1838,8 @@
* depending on which fields are specified in the locale. If the
* language, sacript, country, and variant fields are all empty,
* this function returns the empty string.
+ *
+ * @return The name of the locale appropriate to display.
*/
public final String getDisplayName() {
return getDisplayName(getDefault(Category.DISPLAY));
@@ -1844,6 +1863,8 @@
* language, script, country, and variant fields are all empty,
* this function returns the empty string.
*
+ * @param inLocale The locale for which to retrieve the display name.
+ * @return The name of the locale appropriate to display.
* @throws NullPointerException if <code>inLocale</code> is <code>null</code>
*/
public String getDisplayName(Locale inLocale) {
@@ -2672,7 +2693,7 @@
*
* The filtering method will behave as follows:
*
- * <table cellpadding=2>
+ * <table cellpadding=2 summary="Filtering method behavior">
* <tr>
* <th>Filtering Mode</th>
* <th>Language Priority List: {@code "de-DE"}</th>
--- a/jdk/src/share/classes/java/util/ResourceBundle.java Mon Jul 15 13:42:35 2013 +0100
+++ b/jdk/src/share/classes/java/util/ResourceBundle.java Mon Jul 15 14:37:01 2013 -0700
@@ -74,7 +74,7 @@
*
* <p>
* This allows you to write programs that can:
- * <UL type=SQUARE>
+ * <UL>
* <LI> be easily localized, or translated, into different languages
* <LI> handle multiple locales at once
* <LI> be easily modified later to support even more locales
@@ -184,7 +184,7 @@
* subclass. Your subclasses must override two methods: <code>handleGetObject</code>
* and <code>getKeys()</code>.
*
- * <h4>ResourceBundle.Control</h4>
+ * <h3>ResourceBundle.Control</h3>
*
* The {@link ResourceBundle.Control} class provides information necessary
* to perform the bundle loading process by the <code>getBundle</code>
@@ -195,7 +195,7 @@
* {@link #getBundle(String, Locale, ClassLoader, Control) getBundle}
* factory method for details.
*
- * <p><a name="modify_default_behavior">For the {@code getBundle} factory
+ * <p><a name="modify_default_behavior">For the {@code getBundle} factory</a>
* methods that take no {@link Control} instance, their <a
* href="#default_behavior"> default behavior</a> of resource bundle loading
* can be modified with <em>installed</em> {@link
@@ -206,7 +206,7 @@
* more than one service provider installed for supporting the same base name,
* the first one returned from {@link ServiceLoader} will be used.
*
- * <h4>Cache Management</h4>
+ * <h3>Cache Management</h3>
*
* Resource bundle instances created by the <code>getBundle</code> factory
* methods are cached by default, and the factory methods return the same
@@ -222,7 +222,7 @@
* Control#needsReload(String, Locale, String, ClassLoader, ResourceBundle,
* long) ResourceBundle.Control.needsReload} for details.
*
- * <h4>Example</h4>
+ * <h3>Example</h3>
*
* The following is a very simple example of a <code>ResourceBundle</code>
* subclass, <code>MyResources</code>, that manages two resources (for a larger number of
@@ -878,8 +878,8 @@
* description of <a href="#modify_default_behavior">modifying the default
* behavior</a>.
*
- * <p><a name="default_behavior"/>The following describes the default
- * behavior.
+ * <p><a name="default_behavior">The following describes the default
+ * behavior</a>.
*
* <p><code>getBundle</code> uses the base name, the specified locale, and
* the default locale (obtained from {@link java.util.Locale#getDefault()
@@ -974,8 +974,8 @@
* <p>If still no result bundle is found, the base name alone is looked up. If
* this still fails, a <code>MissingResourceException</code> is thrown.
*
- * <p><a name="parent_chain"/> Once a result resource bundle has been found,
- * its <em>parent chain</em> is instantiated. If the result bundle already
+ * <p><a name="parent_chain"> Once a result resource bundle has been found,
+ * its <em>parent chain</em> is instantiated</a>. If the result bundle already
* has a parent (perhaps because it was returned from a cache) the chain is
* complete.
*
@@ -1004,8 +1004,8 @@
* path name (using "/") instead of a fully qualified class name (using
* ".").
*
- * <p><a name="default_behavior_example"/>
- * <strong>Example:</strong>
+ * <p><a name="default_behavior_example">
+ * <strong>Example:</strong></a>
* <p>
* The following class and property files are provided:
* <pre>
@@ -1026,7 +1026,7 @@
* <p>Calling <code>getBundle</code> with the locale arguments below will
* instantiate resource bundles as follows:
*
- * <table>
+ * <table summary="getBundle() locale to resource bundle mapping">
* <tr><td>Locale("fr", "CH")</td><td>MyResources_fr_CH.class, parent MyResources_fr.properties, parent MyResources.class</td></tr>
* <tr><td>Locale("fr", "FR")</td><td>MyResources_fr.properties, parent MyResources.class</td></tr>
* <tr><td>Locale("de", "DE")</td><td>MyResources_en.properties, parent MyResources.class</td></tr>
@@ -1106,45 +1106,45 @@
* <code>control.newBundle</code>.
*
* <table style="width: 50%; text-align: left; margin-left: 40px;"
- * border="0" cellpadding="2" cellspacing="2">
- * <tbody><code>
+ * border="0" cellpadding="2" cellspacing="2" summary="locale-format combinations for newBundle">
+ * <tbody>
* <tr>
* <td
- * style="vertical-align: top; text-align: left; font-weight: bold; width: 50%;">Locale<br>
+ * style="vertical-align: top; text-align: left; font-weight: bold; width: 50%;"><code>Locale</code><br>
* </td>
* <td
- * style="vertical-align: top; text-align: left; font-weight: bold; width: 50%;">format<br>
+ * style="vertical-align: top; text-align: left; font-weight: bold; width: 50%;"><code>format</code><br>
* </td>
* </tr>
* <tr>
- * <td style="vertical-align: top; width: 50%;">Locale("de", "DE")<br>
+ * <td style="vertical-align: top; width: 50%;"><code>Locale("de", "DE")</code><br>
* </td>
- * <td style="vertical-align: top; width: 50%;">java.class<br>
+ * <td style="vertical-align: top; width: 50%;"><code>java.class</code><br>
* </td>
* </tr>
* <tr>
- * <td style="vertical-align: top; width: 50%;">Locale("de", "DE")</td>
- * <td style="vertical-align: top; width: 50%;">java.properties<br>
+ * <td style="vertical-align: top; width: 50%;"><code>Locale("de", "DE")</code></td>
+ * <td style="vertical-align: top; width: 50%;"><code>java.properties</code><br>
* </td>
* </tr>
* <tr>
- * <td style="vertical-align: top; width: 50%;">Locale("de")</td>
- * <td style="vertical-align: top; width: 50%;">java.class</td>
+ * <td style="vertical-align: top; width: 50%;"><code>Locale("de")</code></td>
+ * <td style="vertical-align: top; width: 50%;"><code>java.class</code></td>
* </tr>
* <tr>
- * <td style="vertical-align: top; width: 50%;">Locale("de")</td>
- * <td style="vertical-align: top; width: 50%;">java.properties</td>
+ * <td style="vertical-align: top; width: 50%;"><code>Locale("de")</code></td>
+ * <td style="vertical-align: top; width: 50%;"><code>java.properties</code></td>
* </tr>
* <tr>
- * <td style="vertical-align: top; width: 50%;">Locale("")<br>
+ * <td style="vertical-align: top; width: 50%;"><code>Locale("")</code><br>
* </td>
- * <td style="vertical-align: top; width: 50%;">java.class</td>
+ * <td style="vertical-align: top; width: 50%;"><code>java.class</code></td>
* </tr>
* <tr>
- * <td style="vertical-align: top; width: 50%;">Locale("")</td>
- * <td style="vertical-align: top; width: 50%;">java.properties</td>
+ * <td style="vertical-align: top; width: 50%;"><code>Locale("")</code></td>
+ * <td style="vertical-align: top; width: 50%;"><code>java.properties</code></td>
* </tr>
- * </code></tbody>
+ * </tbody>
* </table>
* </li>
*
@@ -2199,11 +2199,11 @@
* one by one as below:
*
* <ul>
- * <li> [<em>L</em>, <em>C</em>, <em>V</em>]
- * <li> [<em>L</em>, <em>C</em>]
- * <li> [<em>L</em>]
- * <li> <code>Locale.ROOT</code>
- * </ul>
+ * <li> [<em>L</em>, <em>C</em>, <em>V</em>] </li>
+ * <li> [<em>L</em>, <em>C</em>] </li>
+ * <li> [<em>L</em>] </li>
+ * <li> <code>Locale.ROOT</code> </li>
+ * </ul></li>
*
* <li>For an input <code>Locale</code> with a non-empty script value,
* append candidate <code>Locale</code>s by omitting the final component
@@ -2211,14 +2211,14 @@
* <code>Locale</code> with country and variant restored:
*
* <ul>
- * <li> [<em>L</em>, <em>S</em>, <em>C</em>, <em>V</em>]
- * <li> [<em>L</em>, <em>S</em>, <em>C</em>]
- * <li> [<em>L</em>, <em>S</em>]
- * <li> [<em>L</em>, <em>C</em>, <em>V</em>]
- * <li> [<em>L</em>, <em>C</em>]
- * <li> [<em>L</em>]
- * <li> <code>Locale.ROOT</code>
- * </ul>
+ * <li> [<em>L</em>, <em>S</em>, <em>C</em>, <em>V</em>]</li>
+ * <li> [<em>L</em>, <em>S</em>, <em>C</em>]</li>
+ * <li> [<em>L</em>, <em>S</em>]</li>
+ * <li> [<em>L</em>, <em>C</em>, <em>V</em>]</li>
+ * <li> [<em>L</em>, <em>C</em>]</li>
+ * <li> [<em>L</em>]</li>
+ * <li> <code>Locale.ROOT</code></li>
+ * </ul></li>
*
* <li>For an input <code>Locale</code> with a variant value consisting
* of multiple subtags separated by underscore, generate candidate
@@ -2228,16 +2228,16 @@
* the variant consists of two subtags <em>V1</em> and <em>V2</em>:
*
* <ul>
- * <li> [<em>L</em>, <em>S</em>, <em>C</em>, <em>V1</em>, <em>V2</em>]
- * <li> [<em>L</em>, <em>S</em>, <em>C</em>, <em>V1</em>]
- * <li> [<em>L</em>, <em>S</em>, <em>C</em>]
- * <li> [<em>L</em>, <em>S</em>]
- * <li> [<em>L</em>, <em>C</em>, <em>V1</em>, <em>V2</em>]
- * <li> [<em>L</em>, <em>C</em>, <em>V1</em>]
- * <li> [<em>L</em>, <em>C</em>]
- * <li> [<em>L</em>]
- * <li> <code>Locale.ROOT</code>
- * </ul>
+ * <li> [<em>L</em>, <em>S</em>, <em>C</em>, <em>V1</em>, <em>V2</em>]</li>
+ * <li> [<em>L</em>, <em>S</em>, <em>C</em>, <em>V1</em>]</li>
+ * <li> [<em>L</em>, <em>S</em>, <em>C</em>]</li>
+ * <li> [<em>L</em>, <em>S</em>]</li>
+ * <li> [<em>L</em>, <em>C</em>, <em>V1</em>, <em>V2</em>]</li>
+ * <li> [<em>L</em>, <em>C</em>, <em>V1</em>]</li>
+ * <li> [<em>L</em>, <em>C</em>]</li>
+ * <li> [<em>L</em>]</li>
+ * <li> <code>Locale.ROOT</code></li>
+ * </ul></li>
*
* <li>Special cases for Chinese. When an input <code>Locale</code> has the
* language "zh" (Chinese) and an empty script value, either "Hans" (Simplified) or
@@ -2248,21 +2248,21 @@
* is empty, no script is supplied. For example, for <code>Locale("zh", "CN")
* </code>, the candidate list will be:
* <ul>
- * <li> [<em>L</em>("zh"), <em>S</em>("Hans"), <em>C</em>("CN")]
- * <li> [<em>L</em>("zh"), <em>S</em>("Hans")]
- * <li> [<em>L</em>("zh"), <em>C</em>("CN")]
- * <li> [<em>L</em>("zh")]
- * <li> <code>Locale.ROOT</code>
+ * <li> [<em>L</em>("zh"), <em>S</em>("Hans"), <em>C</em>("CN")]</li>
+ * <li> [<em>L</em>("zh"), <em>S</em>("Hans")]</li>
+ * <li> [<em>L</em>("zh"), <em>C</em>("CN")]</li>
+ * <li> [<em>L</em>("zh")]</li>
+ * <li> <code>Locale.ROOT</code></li>
* </ul>
*
* For <code>Locale("zh", "TW")</code>, the candidate list will be:
* <ul>
- * <li> [<em>L</em>("zh"), <em>S</em>("Hant"), <em>C</em>("TW")]
- * <li> [<em>L</em>("zh"), <em>S</em>("Hant")]
- * <li> [<em>L</em>("zh"), <em>C</em>("TW")]
- * <li> [<em>L</em>("zh")]
- * <li> <code>Locale.ROOT</code>
- * </ul>
+ * <li> [<em>L</em>("zh"), <em>S</em>("Hant"), <em>C</em>("TW")]</li>
+ * <li> [<em>L</em>("zh"), <em>S</em>("Hant")]</li>
+ * <li> [<em>L</em>("zh"), <em>C</em>("TW")]</li>
+ * <li> [<em>L</em>("zh")]</li>
+ * <li> <code>Locale.ROOT</code></li>
+ * </ul></li>
*
* <li>Special cases for Norwegian. Both <code>Locale("no", "NO",
* "NY")</code> and <code>Locale("nn", "NO")</code> represent Norwegian
@@ -2270,10 +2270,10 @@
* list is generated up to [<em>L</em>("nn")], and then the following
* candidates are added:
*
- * <ul><li> [<em>L</em>("no"), <em>C</em>("NO"), <em>V</em>("NY")]
- * <li> [<em>L</em>("no"), <em>C</em>("NO")]
- * <li> [<em>L</em>("no")]
- * <li> <code>Locale.ROOT</code>
+ * <ul><li> [<em>L</em>("no"), <em>C</em>("NO"), <em>V</em>("NY")]</li>
+ * <li> [<em>L</em>("no"), <em>C</em>("NO")]</li>
+ * <li> [<em>L</em>("no")]</li>
+ * <li> <code>Locale.ROOT</code></li>
* </ul>
*
* If the locale is exactly <code>Locale("no", "NO", "NY")</code>, it is first
@@ -2290,20 +2290,18 @@
* candidate list:
*
* <ul>
- * <li> [<em>L</em>("nb"), <em>C</em>("NO"), <em>V</em>("POSIX")]
- * <li> [<em>L</em>("no"), <em>C</em>("NO"), <em>V</em>("POSIX")]
- * <li> [<em>L</em>("nb"), <em>C</em>("NO")]
- * <li> [<em>L</em>("no"), <em>C</em>("NO")]
- * <li> [<em>L</em>("nb")]
- * <li> [<em>L</em>("no")]
- * <li> <code>Locale.ROOT</code>
+ * <li> [<em>L</em>("nb"), <em>C</em>("NO"), <em>V</em>("POSIX")]</li>
+ * <li> [<em>L</em>("no"), <em>C</em>("NO"), <em>V</em>("POSIX")]</li>
+ * <li> [<em>L</em>("nb"), <em>C</em>("NO")]</li>
+ * <li> [<em>L</em>("no"), <em>C</em>("NO")]</li>
+ * <li> [<em>L</em>("nb")]</li>
+ * <li> [<em>L</em>("no")]</li>
+ * <li> <code>Locale.ROOT</code></li>
* </ul>
*
* <code>Locale("no", "NO", "POSIX")</code> would generate the same list
* except that locales with "no" would appear before the corresponding
* locales with "nb".</li>
- *
- * </li>
* </ol>
*
* <p>The default implementation uses an {@link ArrayList} that