harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772785 [4/12] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/
Date Thu, 07 May 2009 21:43:44 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Collections.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Collections.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Collections.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Collections.java Thu May  7 21:43:41 2009
@@ -25,7 +25,8 @@
 import org.apache.harmony.luni.internal.nls.Messages;
 
 /**
- * Collections contains static methods which operate on Collection classes.
+ * {@code Collections} contains static methods which operate on
+ * {@code Collection} classes.
  * 
  * @since 1.2
  */
@@ -169,25 +170,19 @@
     }
 
     /**
-     * An immutable, serializable, empty <code>List</code>.
-     *
-     * @see Collections#emptyList()
+     * An empty immutable instance of {@link List}.
      */
     @SuppressWarnings("unchecked")
     public static final List EMPTY_LIST = new EmptyList();
 
     /**
-     * An immutable, serializable, empty <code>Set</code>.
-     * 
-     * @see Collections#emptySet()
+     * An empty immutable instance of {@link Set}.
      */
     @SuppressWarnings("unchecked")
     public static final Set EMPTY_SET = new EmptySet();
 
     /**
-     * An immutable, serializable, empty <code>Map</code>.
-     * 
-     * @see Collections#emptyMap()
+     * An empty immutable instance of {@link Map}.
      */
     @SuppressWarnings("unchecked")
     public static final Map EMPTY_MAP = new EmptyMap();
@@ -1464,18 +1459,20 @@
 
     /**
      * Performs a binary search for the specified element in the specified
-     * sorted List.
+     * sorted list. The list needs to be already sorted in natural sorting
+     * order. Searching in an unsorted array has an undefined result. It's also
+     * undefined which element is found if there are multiple occurrences of the
+     * same element.
      * 
      * @param list
-     *            the sorted List to search
+     *            the sorted list to search.
      * @param object
-     *            the element to find
+     *            the element to find.
      * @return the non-negative index of the element, or a negative index which
-     *         is the -index - 1 where the element would be inserted
-     * 
+     *         is the {@code -index - 1} where the element would be inserted
      * @throws ClassCastException
-     *             when an element in the List or the search element does not
-     *             implement Comparable, or cannot be compared to each other
+     *             if an element in the List or the search element does not
+     *             implement Comparable, or cannot be compared to each other.
      */
     @SuppressWarnings("unchecked")
     public static <T> int binarySearch(
@@ -1518,23 +1515,24 @@
 
     /**
      * Performs a binary search for the specified element in the specified
-     * sorted List using the specified Comparator.
+     * sorted list using the specified comparator. The list needs to be already
+     * sorted according to the comparator passed. Searching in an unsorted array
+     * has an undefined result. It's also undefined which element is found if
+     * there are multiple occurrences of the same element.
      * 
      * @param <T> The element type
-     * 
      * @param list
-     *            the sorted List to search
+     *            the sorted List to search.
      * @param object
-     *            the element to find
+     *            the element to find.
      * @param comparator
-     *            the Comparator. If the comparator is <code>null</code> then
-     *            the search uses the objects' natural ordering.
+     *            the comparator. If the comparator is {@code null} then the
+     *            search uses the objects' natural ordering.
      * @return the non-negative index of the element, or a negative index which
-     *         is the -index - 1 where the element would be inserted
-     * 
+     *         is the {@code -index - 1} where the element would be inserted.
      * @throws ClassCastException
      *             when an element in the list and the searched element cannot
-     *             be compared to each other using the Comparator
+     *             be compared to each other using the comparator.
      */
     @SuppressWarnings("unchecked")
     public static <T> int binarySearch(List<? extends T> list, T object,
@@ -1572,16 +1570,20 @@
     }
 
     /**
-     * Copies the elements from the source list to the destination list.
+     * Copies the elements from the source list to the destination list. At the
+     * end both lists will have the same objects at the same index. If the
+     * destination array is larger than the source list, the elements in the
+     * destination list with {@code index >= source.size()} will be unchanged.
      * 
      * @param destination
+     *            the list whose elements are set from the source list.
      * @param source
-     * 
+     *            the list with the elements to be copied into the destination.
      * @throws IndexOutOfBoundsException
-     *             when the destination List is smaller than the source List
+     *             when the destination list is smaller than the source list.
      * @throws UnsupportedOperationException
      *             when replacing an element in the destination list is not
-     *             supported
+     *             supported.
      */
     public static <T> void copy(List<? super T> destination,
             List<? extends T> source) {
@@ -1601,11 +1603,11 @@
     }
 
     /**
-     * Answers an Enumeration on the specified Collection.
+     * Returns an {@code Enumeration} on the specified collection.
      * 
      * @param collection
-     *            the Collection to enumerate
-     * @return an Enumeration
+     *            the collection to enumerate.
+     * @return an Enumeration.
      */
     public static <T> Enumeration<T> enumeration(Collection<T> collection) {
         final Collection<T> c = collection;
@@ -1623,15 +1625,14 @@
     }
 
     /**
-     * Fills the specified List with the specified element.
+     * Fills the specified list with the specified element.
      * 
      * @param list
-     *            the List to fill
+     *            the list to fill.
      * @param object
-     *            the fill element
-     * 
+     *            the element to fill the list with.
      * @throws UnsupportedOperationException
-     *             when replacing an element in the List is not supported
+     *             when replacing an element in the List is not supported.
      */
     public static <T> void fill(List<? super T> list, T object) {
         ListIterator<? super T> it = list.listIterator();
@@ -1642,15 +1643,15 @@
     }
 
     /**
-     * Searches the specified Collection for the maximum element.
+     * Searches the specified collection for the maximum element.
      * 
      * @param collection
-     *            the Collection to search
-     * @return the maximum element in the Collection
-     * 
+     *            the collection to search.
+     * @return the maximum element in the Collection.
      * @throws ClassCastException
-     *             when an element in the Collection does not implement
-     *             Comparable or elements cannot be compared to each other
+     *             when an element in the collection does not implement
+     *             {@code Comparable} or elements cannot be compared to each
+     *             other.
      */
     public static <T extends Object & Comparable<? super T>> T max(
             Collection<? extends T> collection) {
@@ -1666,18 +1667,17 @@
     }
 
     /**
-     * Searches the specified Collection for the maximum element using the
-     * specified Comparator.
+     * Searches the specified collection for the maximum element using the
+     * specified comparator.
      * 
      * @param collection
-     *            the Collection to search
+     *            the collection to search.
      * @param comparator
-     *            the Comparator
-     * @return the maximum element in the Collection
-     * 
+     *            the comparator.
+     * @return the maximum element in the Collection.
      * @throws ClassCastException
-     *             when elements in the Collection cannot be compared to each
-     *             other using the Comparator
+     *             when elements in the collection cannot be compared to each
+     *             other using the {@code Comparator}.
      */
     public static <T> T max(Collection<? extends T> collection,
             Comparator<? super T> comparator) {
@@ -1693,15 +1693,15 @@
     }
 
     /**
-     * Searches the specified Collection for the minimum element.
+     * Searches the specified collection for the minimum element.
      * 
      * @param collection
-     *            the Collection to search
-     * @return the minimum element in the Collection
-     * 
+     *            the collection to search.
+     * @return the minimum element in the collection.
      * @throws ClassCastException
-     *             when an element in the Collection does not implement
-     *             Comparable or elements cannot be compared to each other
+     *             when an element in the collection does not implement
+     *             {@code Comparable} or elements cannot be compared to each
+     *             other.
      */
     public static <T extends Object & Comparable<? super T>> T min(
             Collection<? extends T> collection) {
@@ -1717,18 +1717,17 @@
     }
 
     /**
-     * Searches the specified Collection for the minimum element using the
-     * specified Comparator.
+     * Searches the specified collection for the minimum element using the
+     * specified comparator.
      * 
      * @param collection
-     *            the Collection to search
+     *            the collection to search.
      * @param comparator
-     *            the Comparator
-     * @return the minimum element in the Collection
-     * 
+     *            the comparator.
+     * @return the minimum element in the collection.
      * @throws ClassCastException
-     *             when elements in the Collection cannot be compared to each
-     *             other using the Comparator
+     *             when elements in the collection cannot be compared to each
+     *             other using the {@code Comparator}.
      */
     public static <T> T min(Collection<? extends T> collection,
             Comparator<? super T> comparator) {
@@ -1744,31 +1743,29 @@
     }
 
     /**
-     * Answers a List containing the specified number of the specified element.
-     * The list cannot be modified.
+     * Returns a list containing the specified number of the specified element.
+     * The list cannot be modified. The list is serializable.
      * 
      * @param length
-     *            the size of the returned List
+     *            the size of the returned list.
      * @param object
-     *            the element
-     * @return a List containing <code>length</code> copies of the element
-     * 
+     *            the element to be added {@code length} times to a list.
+     * @return a list containing {@code length} copies of the element.
      * @throws IllegalArgumentException
-     *             when <code>length < 0</code>
+     *             when {@code length < 0}.
      */
     public static <T> List<T> nCopies(final int length, T object) {
         return new CopiesList<T>(length, object);
     }
 
     /**
-     * Returns the supplied <code>List</code> with the order of its contained
-     * elements reversed.
+     * Modifies the specified {@code List} by reversing the order of the
+     * elements.
      * 
      * @param list
-     *            the List to reverse
-     * 
+     *            the list to reverse.
      * @throws UnsupportedOperationException
-     *             when replacing an element in the List is not supported
+     *             when replacing an element in the List is not supported.
      */
     @SuppressWarnings("unchecked")
     public static void reverse(List<?> list) {
@@ -1785,13 +1782,10 @@
     }
 
     /**
-     * <p>
-     * A Comparator which reverses the natural order of the elements. The
-     * <code>Comparator</code> that's returned is {@link Serializable}.
-     * </p>
-     * 
-     * @return A <code>Comparator</code> instance.
-     * 
+     * A comparator which reverses the natural order of the elements. The
+     * {@code Comparator} that's returned is {@link Serializable}.
+     *
+     * @return a {@code Comparator} instance.
      * @see Comparator
      * @see Comparable
      * @see Serializable
@@ -1801,21 +1795,16 @@
     }
 
     /**
-     * <p>
      * Returns a {@link Comparator} that reverses the order of the
-     * <code>Comparator</code> passed. If the <code>Comparator</code> passed
-     * is <code>null</code>, then this method is equivalent to
-     * {@link #reverseOrder()}.
-     * </p>
-     * 
+     * {@code Comparator} passed. If the {@code Comparator} passed is
+     * {@code null}, then this method is equivalent to {@link #reverseOrder()}.
      * <p>
-     * The <code>Comparator</code> that's returned is {@link Serializable} if
-     * the <code>Comparator</code> passed is serializable or <code>null</code>.
-     * </p>
-     * 
+     * The {@code Comparator} that's returned is {@link Serializable} if the
+     * {@code Comparator} passed is serializable or {@code null}.
+     *
      * @param c
-     *            The <code>Comparator</code> to reverse or <code>null</code>.
-     * @return A <code>Comparator</code> instance.
+     *            the {@code Comparator} to reverse or {@code null}.
+     * @return a {@code Comparator} instance.
      * @see Comparator
      * @since 1.5
      */
@@ -1827,29 +1816,28 @@
     }
 
     /**
-     * Moves every element of the List to a random new position in the list.
+     * Moves every element of the list to a random new position in the list.
      * 
      * @param list
-     *            the List to shuffle
+     *            the List to shuffle.
      * 
      * @throws UnsupportedOperationException
-     *             when replacing an element in the List is not supported
+     *             when replacing an element in the List is not supported.
      */
     public static void shuffle(List<?> list) {
         shuffle(list, new Random());
     }
 
     /**
-     * Moves every element of the List to a random new position in the list
+     * Moves every element of the list to a random new position in the list
      * using the specified random number generator.
      * 
      * @param list
-     *            the List to shuffle
+     *            the list to shuffle.
      * @param random
-     *            the random number generator
-     * 
+     *            the random number generator.
      * @throws UnsupportedOperationException
-     *             when replacing an element in the List is not supported
+     *             when replacing an element in the list is not supported.
      */
     @SuppressWarnings("unchecked")
     public static void shuffle(List<?> list, Random random) {
@@ -1885,52 +1873,52 @@
     }
 
     /**
-     * Answers a Set containing the specified element. The set cannot be
-     * modified.
+     * Returns a set containing the specified element. The set cannot be
+     * modified. The set is serializable.
      * 
      * @param object
-     *            the element
-     * @return a Set containing the element
+     *            the element.
+     * @return a set containing the element.
      */
     public static <E> Set<E> singleton(E object) {
         return new SingletonSet<E>(object);
     }
 
     /**
-     * Answers a List containing the specified element. The list cannot be
-     * modified.
+     * Returns a list containing the specified element. The list cannot be
+     * modified. The list is serializable.
      * 
      * @param object
-     *            the element
-     * @return a List containing the element
+     *            the element.
+     * @return a list containing the element.
      */
     public static <E> List<E> singletonList(E object) {
         return new SingletonList<E>(object);
     }
 
     /**
-     * Answers a Map containing the specified key and value. The map cannot be
-     * modified.
+     * Returns a Map containing the specified key and value. The map cannot be
+     * modified. The map is serializable.
      * 
      * @param key
-     *            the key
+     *            the key.
      * @param value
-     *            the value
-     * @return a Map containing the key and value
+     *            the value.
+     * @return a Map containing the key and value.
      */
     public static <K, V> Map<K, V> singletonMap(K key, V value) {
         return new SingletonMap<K, V>(key, value);
     }
 
     /**
-     * Sorts the specified List in ascending order.
+     * Sorts the specified list in ascending natural order. The algorithm is
+     * stable which means equal elements don't get reordered.
      * 
      * @param list
-     *            the List to be sorted
-     * 
+     *            the list to be sorted.
      * @throws ClassCastException
      *             when an element in the List does not implement Comparable or
-     *             elements cannot be compared to each other
+     *             elements cannot be compared to each other.
      */
     @SuppressWarnings("unchecked")
     public static <T extends Comparable<? super T>> void sort(List<T> list) {
@@ -1945,16 +1933,16 @@
     }
 
     /**
-     * Sorts the specified List using the specified Comparator.
+     * Sorts the specified list using the specified comparator. The algorithm is
+     * stable which means equal elements don't get reordered.
      * 
      * @param list
-     *            the List to be sorted
+     *            the list to be sorted.
      * @param comparator
-     *            the Comparator
-     * 
+     *            the comparator.
      * @throws ClassCastException
-     *             when elements in the List cannot be compared to each other
-     *             using the Comparator
+     *             when elements in the list cannot be compared to each other
+     *             using the comparator.
      */
     @SuppressWarnings("unchecked")
     public static <T> void sort(List<T> list, Comparator<? super T> comparator) {
@@ -1969,19 +1957,19 @@
     }
 
     /**
-     * Swaps the elements of List <code>list</code> at indices
-     * <code>index1</code> and <code>index2</code>
+     * Swaps the elements of list {@code list} at indices {@code index1} and
+     * {@code index2}.
      * 
      * @param list
-     *            the List to manipulate on
+     *            the list to manipulate.
      * @param index1
-     *            int position of the first element to swap with the element in
-     *            index2
+     *            position of the first element to swap with the element in
+     *            index2.
      * @param index2
-     *            int position of the other element
+     *            position of the other element.
      * 
      * @throws IndexOutOfBoundsException
-     *             if index1 or index2 is out of range of this list
+     *             if index1 or index2 is out of range of this list.
      * @since 1.4
      */
     @SuppressWarnings("unchecked")
@@ -2001,23 +1989,21 @@
     }
 
     /**
-     * Replaces all occurrences of Object <code>obj</code> in
-     * <code>list</code> with <code>newObj</code>. If the <code>obj</code>
-     * is <code>null</code>, then all occurrences of <code>null</code> is
-     * replaced with <code>newObj</code>.
+     * Replaces all occurrences of Object {@code obj} in {@code list} with
+     * {@code newObj}. If the {@code obj} is {@code null}, then all
+     * occurrences of {@code null} are replaced with {@code newObj}.
      * 
      * @param list
-     *            the List to modify
+     *            the list to modify.
      * @param obj
-     *            the Object to find and replace occurrences of.
+     *            the object to find and replace occurrences of.
      * @param obj2
-     *            the Object to replace all occurrences of <code>obj</code> in
-     *            <code>list</code>
-     * @return true, if at least one occurrence of <code>obj</code> has been
-     *         found in <code>list</code>
-     * 
+     *            the object to replace all occurrences of {@code obj} in
+     *            {@code list}.
+     * @return true, if at least one occurrence of {@code obj} has been found in
+     *         {@code list}.
      * @throws UnsupportedOperationException
-     *             if the list does not support setting elements
+     *             if the list does not support setting elements.
      */
     public static <T> boolean replaceAll(List<T> list, T obj, T obj2) {
         int index;
@@ -2031,17 +2017,17 @@
     }
 
     /**
-     * Rotates the elements in List <code>list</code> by the distance
-     * <code>dist</code>
+     * Rotates the elements in {@code list} by the distance {@code dist}
      * <p>
      * e.g. for a given list with elements [1, 2, 3, 4, 5, 6, 7, 8, 9, 0],
      * calling rotate(list, 3) or rotate(list, -7) would modify the list to look
      * like this: [8, 9, 0, 1, 2, 3, 4, 5, 6, 7]
-     * 
+     *
      * @param lst
+     *            the list whose elements are to be rotated.
      * @param dist
-     *            It can be any integer: 0, positive, negative, larger than the
-     *            list size
+     *            is the distance the list is rotated. This can be any valid
+     *            integer. Negative values rotate the list backwards.
      */
     @SuppressWarnings("unchecked")
     public static void rotate(List<?> lst, int dist) {
@@ -2089,18 +2075,17 @@
     }
 
     /**
-     * Searches the <code>list</code> for <code>sublist</code> and answers
-     * the beginning index of the first occurrence.
+     * Searches the {@code list} for {@code sublist} and returns the beginning
+     * index of the first occurrence.
      * <p>
-     * -1 is returned if the <code>sublist</code> does not exist in
-     * <code>list</code>
+     * -1 is returned if the {@code sublist} does not exist in {@code list}.
      * 
      * @param list
-     *            the List to search <code>sublist</code> in
+     *            the List to search {@code sublist} in.
      * @param sublist
-     *            the List to search in <code>list</code>
-     * @return the beginning index of the first occurrence of
-     *         <code>sublist</code> in <code>list</code>, or -1
+     *            the List to search in {@code list}.
+     * @return the beginning index of the first occurrence of {@code sublist} in
+     *         {@code list}, or -1.
      */
     public static int indexOfSubList(List<?> list, List<?> sublist) {
         int size = list.size();
@@ -2157,18 +2142,17 @@
     }
 
     /**
-     * Searches the <code>list</code> for <code>sublist</code> and answers
-     * the beginning index of the last occurrence.
+     * Searches the {@code list} for {@code sublist} and returns the beginning
+     * index of the last occurrence.
      * <p>
-     * -1 is returned if the <code>sublist</code> does not exist in
-     * <code>list</code>
+     * -1 is returned if the {@code sublist} does not exist in {@code list}.
      * 
      * @param list
-     *            the List to search <code>sublist</code> in
+     *            the list to search {@code sublist} in.
      * @param sublist
-     *            the List to search in <code>list</code>
-     * @return the beginning index of the last occurrence of
-     *         <code>sublist</code> in <code>list</code>, or -1
+     *            the list to search in {@code list}.
+     * @return the beginning index of the last occurrence of {@code sublist} in
+     *         {@code list}, or -1.
      */
     public static int lastIndexOfSubList(List<?> list, List<?> sublist) {
         int sublistSize = sublist.size();
@@ -2222,13 +2206,13 @@
     }
 
     /**
-     * Answers an ArrayList with all the elements in the
-     * <code>enumeration</code>. The elements in the returned ArrayList are
-     * in the same order as in the <code>enumeration</code>.
+     * Returns an {@code ArrayList} with all the elements in the {@code
+     * enumeration}. The elements in the returned {@code ArrayList} are in the
+     * same order as in the {@code enumeration}.
      * 
      * @param enumeration
-     *            Enumeration
-     * @return and ArrayList
+     *            the source {@link Enumeration}.
+     * @return an {@code ArrayList} from {@code enumeration}.
      */
     public static <T> ArrayList<T> list(Enumeration<T> enumeration) {
         ArrayList<T> list = new ArrayList<T>();
@@ -2239,12 +2223,12 @@
     }
 
     /**
-     * Answers a wrapper on the specified Collection which synchronizes all
-     * access to the Collection.
+     * Returns a wrapper on the specified collection which synchronizes all
+     * access to the collection.
      * 
      * @param collection
-     *            the Collection
-     * @return a synchronized Collection
+     *            the Collection to wrap in a synchronized collection.
+     * @return a synchronized Collection.
      */
     public static <T> Collection<T> synchronizedCollection(
             Collection<T> collection) {
@@ -2255,12 +2239,12 @@
     }
 
     /**
-     * Answers a wrapper on the specified List which synchronizes all access to
+     * Returns a wrapper on the specified List which synchronizes all access to
      * the List.
      * 
      * @param list
-     *            the List
-     * @return a synchronized List
+     *            the List to wrap in a synchronized list.
+     * @return a synchronized List.
      */
     public static <T> List<T> synchronizedList(List<T> list) {
         if (list == null) {
@@ -2273,12 +2257,12 @@
     }
 
     /**
-     * Answers a wrapper on the specified Map which synchronizes all access to
-     * the Map.
+     * Returns a wrapper on the specified map which synchronizes all access to
+     * the map.
      * 
      * @param map
-     *            the Map
-     * @return a synchronized Map
+     *            the map to wrap in a synchronized map.
+     * @return a synchronized Map.
      */
     public static <K, V> Map<K, V> synchronizedMap(Map<K, V> map) {
         if (map == null) {
@@ -2288,12 +2272,12 @@
     }
 
     /**
-     * Answers a wrapper on the specified Set which synchronizes all access to
-     * the Set.
+     * Returns a wrapper on the specified set which synchronizes all access to
+     * the set.
      * 
      * @param set
-     *            the Set
-     * @return a synchronized Set
+     *            the set to wrap in a synchronized set.
+     * @return a synchronized set.
      */
     public static <E> Set<E> synchronizedSet(Set<E> set) {
         if (set == null) {
@@ -2303,12 +2287,12 @@
     }
 
     /**
-     * Answers a wrapper on the specified SortedMap which synchronizes all
-     * access to the SortedMap.
+     * Returns a wrapper on the specified sorted map which synchronizes all
+     * access to the sorted map.
      * 
      * @param map
-     *            the SortedMap
-     * @return a synchronized SortedMap
+     *            the sorted map to wrap in a synchronized sorted map.
+     * @return a synchronized sorted map.
      */
     public static <K, V> SortedMap<K, V> synchronizedSortedMap(
             SortedMap<K, V> map) {
@@ -2319,12 +2303,12 @@
     }
 
     /**
-     * Answers a wrapper on the specified SortedSet which synchronizes all
-     * access to the SortedSet.
+     * Returns a wrapper on the specified sorted set which synchronizes all
+     * access to the sorted set.
      * 
      * @param set
-     *            the SortedSet
-     * @return a synchronized SortedSet
+     *            the sorted set to wrap in a synchronized sorted set.
+     * @return a synchronized sorted set.
      */
     public static <E> SortedSet<E> synchronizedSortedSet(SortedSet<E> set) {
         if (set == null) {
@@ -2334,13 +2318,13 @@
     }
 
     /**
-     * Answers a wrapper on the specified Collection which throws an
-     * <code>UnsupportedOperationException</code> whenever an attempt is made
-     * to modify the Collection.
+     * Returns a wrapper on the specified collection which throws an
+     * {@code UnsupportedOperationException} whenever an attempt is made to
+     * modify the collection.
      * 
      * @param collection
-     *            the Collection
-     * @return an unmodifiable Collection
+     *            the collection to wrap in an unmodifiable collection.
+     * @return an unmodifiable collection.
      */
     @SuppressWarnings("unchecked")
     public static <E> Collection<E> unmodifiableCollection(
@@ -2352,13 +2336,13 @@
     }
 
     /**
-     * Answers a wrapper on the specified List which throws an
-     * <code>UnsupportedOperationException</code> whenever an attempt is made
-     * to modify the List.
+     * Returns a wrapper on the specified list which throws an
+     * {@code UnsupportedOperationException} whenever an attempt is made to
+     * modify the list.
      * 
      * @param list
-     *            the List
-     * @return an unmodifiable List
+     *            the list to wrap in an unmodifiable list.
+     * @return an unmodifiable List.
      */
     @SuppressWarnings("unchecked")
     public static <E> List<E> unmodifiableList(List<? extends E> list) {
@@ -2372,13 +2356,13 @@
     }
 
     /**
-     * Answers a wrapper on the specified Map which throws an
-     * <code>UnsupportedOperationException</code> whenever an attempt is made
-     * to modify the Map.
+     * Returns a wrapper on the specified map which throws an
+     * {@code UnsupportedOperationException} whenever an attempt is made to
+     * modify the map.
      * 
      * @param map
-     *            the Map
-     * @return a unmodifiable Map
+     *            the map to wrap in an unmodifiable map.
+     * @return a unmodifiable map.
      */
     @SuppressWarnings("unchecked")
     public static <K, V> Map<K, V> unmodifiableMap(
@@ -2390,13 +2374,13 @@
     }
 
     /**
-     * Answers a wrapper on the specified Set which throws an
-     * <code>UnsupportedOperationException</code> whenever an attempt is made
-     * to modify the Set.
+     * Returns a wrapper on the specified set which throws an
+     * {@code UnsupportedOperationException} whenever an attempt is made to
+     * modify the set.
      * 
      * @param set
-     *            the Set
-     * @return a unmodifiable Set
+     *            the set to wrap in an unmodifiable set.
+     * @return a unmodifiable set
      */
     @SuppressWarnings("unchecked")
     public static <E> Set<E> unmodifiableSet(Set<? extends E> set) {
@@ -2407,13 +2391,13 @@
     }
 
     /**
-     * Answers a wrapper on the specified SortedMap which throws an
-     * <code>UnsupportedOperationException</code> whenever an attempt is made
-     * to modify the SortedMap.
+     * Returns a wrapper on the specified sorted map which throws an
+     * {@code UnsupportedOperationException} whenever an attempt is made to
+     * modify the sorted map.
      * 
      * @param map
-     *            the SortedMap
-     * @return a unmodifiable SortedMap
+     *            the sorted map to wrap in an unmodifiable sorted map.
+     * @return a unmodifiable sorted map
      */
     @SuppressWarnings("unchecked")
     public static <K, V> SortedMap<K, V> unmodifiableSortedMap(
@@ -2425,13 +2409,13 @@
     }
 
     /**
-     * Answers a wrapper on the specified SortedSet which throws an
-     * <code>UnsupportedOperationException</code> whenever an attempt is made
-     * to modify the SortedSet.
+     * Returns a wrapper on the specified sorted set which throws an
+     * {@code UnsupportedOperationException} whenever an attempt is made to
+     * modify the sorted set.
      * 
      * @param set
-     *            the SortedSet
-     * @return a unmodifiable SortedSet
+     *            the sorted set to wrap in an unmodifiable sorted set.
+     * @return a unmodifiable sorted set.
      */
     public static <E> SortedSet<E> unmodifiableSortedSet(SortedSet<E> set) {
         if (set == null) {
@@ -2441,22 +2425,17 @@
     }
 
     /**
-     * <p>
-     * Returns the number of elements in the <code>Collection</code> that
-     * match the <code>Object</code> passed. If the <code>Object</code> is
-     * <code>null</code>, then the number of <code>null</code> elements is
-     * returned.
-     * </p>
+     * Returns the number of elements in the {@code Collection} that match the
+     * {@code Object} passed. If the {@code Object} is {@code null}, then the
+     * number of {@code null} elements is returned.
      * 
      * @param c
-     *            The <code>Collection</code> to search.
+     *            the {@code Collection} to search.
      * @param o
-     *            The <code>Object</code> to search for.
-     * @return The number of matching elements.
+     *            the {@code Object} to search for.
+     * @return the number of matching elements.
      * @throws NullPointerException
-     *             if the <code>Collection</code> parameter is
-     *             <code>null</code>.
-     * 
+     *             if the {@code Collection} parameter is {@code null}.
      * @since 1.5
      */
     public static int frequency(Collection<?> c, Object o) {
@@ -2480,7 +2459,7 @@
     /**
      * Returns a type-safe empty, immutable {@link List}.
      * 
-     * @return An empty {@link List}.
+     * @return an empty {@link List}.
      * @since 1.5
      * @see #EMPTY_LIST
      */
@@ -2492,7 +2471,7 @@
     /**
      * Returns a type-safe empty, immutable {@link Set}.
      * 
-     * @return An empty {@link Set}.
+     * @return an empty {@link Set}.
      * @since 1.5
      * @see #EMPTY_SET
      */
@@ -2504,7 +2483,7 @@
     /**
      * Returns a type-safe empty, immutable {@link Map}.
      * 
-     * @return An empty {@link Map}.
+     * @return an empty {@link Map}.
      * @since 1.5
      * @see #EMPTY_MAP
      */
@@ -2514,14 +2493,16 @@
     }
 
     /**
-     * Returns a dynamically typesafe view of the specified collection.
+     * Returns a dynamically typesafe view of the specified collection. Trying
+     * to insert an element of the wrong type into this collection throws a
+     * {@code ClassCastException}. At creation time the types in {@code c} are
+     * not checked for correct type.
      * 
      * @param c
-     *            the collection
+     *            the collection to be wrapped in a typesafe collection.
      * @param type
-     *            the type of the elements is permitted to insert
-     * 
-     * @return a typesafe collection
+     *            the type of the elements permitted to insert.
+     * @return a typesafe collection.
      */
     public static <E> Collection<E> checkedCollection(Collection<E> c,
             Class<E> type) {
@@ -2529,16 +2510,18 @@
     }
 
     /**
-     * Returns a dynamically typesafe view of the specified map.
+     * Returns a dynamically typesafe view of the specified map. Trying to
+     * insert an element of the wrong type into this map throws a
+     * {@code ClassCastException}. At creation time the types in {@code m} are
+     * not checked for correct type.
      * 
      * @param m
-     *            the map
+     *            the map to be wrapped in a typesafe map.
      * @param keyType
-     *            the type of keys permitted to be inserted
+     *            the type of the keys permitted to insert.
      * @param valueType
-     *            the type of values permitted to be inserted
-     * 
-     * @return a typesafe map
+     *            the type of the values permitted to insert.
+     * @return a typesafe map.
      */
     public static <K, V> Map<K, V> checkedMap(Map<K, V> m, Class<K> keyType,
             Class<V> valueType) {
@@ -2546,14 +2529,16 @@
     }
 
     /**
-     * Returns a dynamically typesafe view of the specified list.
+     * Returns a dynamically typesafe view of the specified list. Trying to
+     * insert an element of the wrong type into this list throws a
+     * {@code ClassCastException}. At creation time the types in {@code list}
+     * are not checked for correct type.
      * 
      * @param list
-     *            the list
+     *            the list to be wrapped in a typesafe list.
      * @param type
-     *            the type of the elements is permitted to insert
-     * 
-     * @return a typesafe list
+     *            the type of the elements permitted to insert.
+     * @return a typesafe list.
      */
     public static <E> List<E> checkedList(List<E> list, Class<E> type) {
         if (list instanceof RandomAccess) {
@@ -2563,30 +2548,34 @@
     }
 
     /**
-     * Returns a dynamically typesafe view of the specified set.
+     * Returns a dynamically typesafe view of the specified set. Trying to
+     * insert an element of the wrong type into this set throws a
+     * {@code ClassCastException}. At creation time the types in {@code s} are
+     * not checked for correct type.
      * 
      * @param s
-     *            the set
+     *            the set to be wrapped in a typesafe set.
      * @param type
-     *            the type of the elements is permitted to insert
-     * 
-     * @return a typesafe set
+     *            the type of the elements permitted to insert.
+     * @return a typesafe set.
      */
     public static <E> Set<E> checkedSet(Set<E> s, Class<E> type) {
         return new CheckedSet<E>(s, type);
     }
 
     /**
-     * Returns a dynamically typesafe view of the specified sorted map.
+     * Returns a dynamically typesafe view of the specified sorted map. Trying
+     * to insert an element of the wrong type into this sorted map throws a
+     * {@code ClassCastException}. At creation time the types in {@code m} are
+     * not checked for correct type.
      * 
      * @param m
-     *            the sorted map
+     *            the sorted map to be wrapped in a typesafe sorted map.
      * @param keyType
-     *            the type of keys permitted to be inserted
+     *            the type of the keys permitted to insert.
      * @param valueType
-     *            the type of values permitted to be inserted
-     * 
-     * @return a typesafe sorted map
+     *            the type of the values permitted to insert.
+     * @return a typesafe sorted map.
      */
     public static <K, V> SortedMap<K, V> checkedSortedMap(SortedMap<K, V> m,
             Class<K> keyType, Class<V> valueType) {
@@ -2594,14 +2583,16 @@
     }
 
     /**
-     * Returns a dynamically typesafe view of the specified sorted set.
+     * Returns a dynamically typesafe view of the specified sorted set. Trying
+     * to insert an element of the wrong type into this sorted set throws a
+     * {@code ClassCastException}. At creation time the types in {@code s} are
+     * not checked for correct type.
      * 
      * @param s
-     *            the sorted set
+     *            the sorted set to be wrapped in a typesafe sorted set.
      * @param type
-     *            the type of the elements is permitted to insert
-     * 
-     * @return a typesafe sorted set
+     *            the type of the elements permitted to insert.
+     * @return a typesafe sorted set.
      */
     public static <E> SortedSet<E> checkedSortedSet(SortedSet<E> s,
             Class<E> type) {
@@ -2609,20 +2600,22 @@
     }
 
     /**
-     * Adds all the specified elements to the specified collection
+     * Adds all the specified elements to the specified collection.
      * 
      * @param c
-     *            the collection the elements are to be inserted into
+     *            the collection the elements are to be inserted into.
      * @param a
-     *            the elements to insert
-     * 
-     * @return true if the collection changed during insertion
-     * 
+     *            the elements to insert.
+     * @return true if the collection changed during insertion.
      * @throws UnsupportedOperationException
-     *             when the method is not supported
+     *             when the method is not supported.
      * @throws NullPointerException
-     *             when c or elements is null, or elements contains one or more
-     *             null elements and c doesn't support null elements
+     *             when {@code c} or {@code a} is {@code null}, or {@code a}
+     *             contains one or more {@code null} elements and {@code c}
+     *             doesn't support {@code null} elements.
+     * @throws IllegalArgumentException
+     *             if at least one of the elements can't be inserted into the
+     *             collection.
      */
     public static <T> boolean addAll(Collection<? super T> c, T... a) {
         boolean modified = false;
@@ -2633,17 +2626,16 @@
     }
 
     /**
-     * Returns true if the collections have no elements in common
+     * Returns whether the specified collections have no elements in common.
      * 
      * @param c1
-     *            the first collection
+     *            the first collection.
      * @param c2
-     *            the second collection
-     * 
-     * @return true if the collections have no elements in common
-     * 
+     *            the second collection.
+     * @return {@code true} if the collections have no elements in common,
+     *         {@code false} otherwise.
      * @throws NullPointerException
-     *             if one of the collections is null
+     *             if one of the collections is {@code null}.
      */
     public static boolean disjoint(Collection<?> c1, Collection<?> c2) {
         if ((c1 instanceof Set) && !(c2 instanceof Set)

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Comparator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Comparator.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Comparator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Comparator.java Thu May  7 21:43:41 2009
@@ -18,36 +18,56 @@
 package java.util;
 
 /**
- * Comparator is used to compare two objects to determine their ordering in
- * respect to each other.
- * 
+ * A {@code Comparator} is used to compare two objects to determine their ordering with
+ * respect to each other. On a given {@code Collection}, a {@code Comparator} can be used to
+ * obtain a sorted {@code Collection} which is <i>totally ordered</i>. For a {@code Comparator}
+ * to be <i>consistent with equals</i>, its {code #compare(Object, Object)}
+ * method has to return zero for each pair of elements (a,b) where a.equals(b)
+ * holds true. It is recommended that a {@code Comparator} implements
+ * {@link java.io.Serializable}.
+ *
  * @since 1.2
  */
 public interface Comparator<T> {
     /**
-     * Compare the two objects to determine the relative ordering.
+     * Compares the two specified objects to determine their relative ordering. The ordering
+     * implied by the return value of this method for all possible pairs of
+     * {@code (object1, object2)} should form an <i>equivalence relation</i>.
+     * This means that
+     * <ul>
+     * <li>{@code compare(a,a)} returns zero for all {@code a}</li>
+     * <li>the sign of {@code compare(a,b)} must be the opposite of the sign of {@code
+     * compare(b,a)} for all pairs of (a,b)</li>
+     * <li>From {@code compare(a,b) > 0} and {@code compare(b,c) > 0} it must
+     * follow {@code compare(a,c) > 0} for all possible combinations of {@code
+     * (a,b,c)}</li>
+     * </ul>
      * 
      * @param object1
-     *            an Object to compare
+     *            an {@code Object}.
      * @param object2
-     *            an Object to compare
-     * @return an int < 0 if object1 is less than object2, 0 if they are equal,
-     *         and > 0 if object1 is greater
-     * 
-     * @exception ClassCastException
-     *                when objects are not the correct type
+     *            a second {@code Object} to compare with {@code object1}.
+     * @return an integer < 0 if {@code object1} is less than {@code object2}, 0 if they are
+     *         equal, and > 0 if {@code object1} is greater than {@code object2}.
+     * @throws ClassCastException
+     *                if objects are not of the correct type.
      */
     public int compare(T object1, T object2);
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
-     * the <em>same</em> object using a class specific comparison.
+     * Compares this {@code Comparator} with the specified {@code Object} and indicates whether they
+     * are equal. In order to be equal, {@code object} must represent the same object
+     * as this instance using a class-specific comparison.
+     * <p>
+     * A {@code Comparator} never needs to override this method, but may choose so for
+     * performance reasons.
      * 
      * @param object
-     *            Object the object to compare with this object.
-     * @return boolean <code>true</code> if the object is the same as this
-     *         object <code>false</code> if it is different from this object.
+     *            the {@code Object} to compare with this comparator.
+     * @return boolean {@code true} if specified {@code Object} is the same as this
+     *         {@code Object}, and {@code false} otherwise.
      * @see Object#hashCode
+     * @see Object#equals
      */
     public boolean equals(Object object);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ConcurrentModificationException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ConcurrentModificationException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ConcurrentModificationException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ConcurrentModificationException.java Thu May  7 21:43:41 2009
@@ -18,8 +18,9 @@
 package java.util;
 
 /**
- * This runtime exception is thrown when a Collection is modified and an
- * existing iterator on the Collection is used to modify the Collection as well.
+ * An {@code ConcurrentModificationException} is thrown when a Collection is
+ * modified and an existing iterator on the Collection is used to modify the
+ * Collection as well.
  * 
  * @see java.lang.RuntimeException
  */
@@ -28,20 +29,22 @@
     private static final long serialVersionUID = -3666751008965953603L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code ConcurrentModificationException} with the current
+     * stack trace filled in.
      */
     public ConcurrentModificationException() {
-        /* empty */
+        /*empty*/
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code ConcurrentModificationException} with the current
+     * stack trace and message filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *           the detail message for the exception.
      */
     public ConcurrentModificationException(String detailMessage) {
         super(detailMessage);
     }
+
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Currency.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Currency.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Currency.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Currency.java Thu May  7 21:43:41 2009
@@ -39,16 +39,16 @@
     }
 
     /**
-     * Returns the Currency instance for this currency code.
+     * Returns the {@code Currency} instance for this currency code.
      * <p>
      * 
      * @param currencyCode
-     *            java.lang.String
-     * @return currency java.util.Currency
+     *            the currency code.
+     * @return the {@code Currency} instance for this currency code.
      * 
-     * @throws java.lang.IllegalArgumentException
+     * @throws IllegalArgumentException
      *             if the currency code is not a supported ISO 4217 currency
-     *             code
+     *             code.
      */
     public static Currency getInstance(String currencyCode) {
         Currency currency = codesToCurrencies.get(currencyCode);
@@ -61,15 +61,15 @@
         return currency;
     }
 
-    /***************************************************************************
-     * Returns the Currency instance for the given locale.
+    /**
+     * Returns the {@code Currency} instance for this {@code Locale}'s country.
      * 
      * @param locale
-     *            java.util.Locale
-     * @return currency java.util.Currency
+     *            the {@code Locale} of a country.
+     * @return the {@code Currency} used in the country defined by the locale parameter.
      * 
-     * @throws java.lang.IllegalArgumentException
-     *             if the locale's country is not a supported ISO 3166 Country
+     * @throws IllegalArgumentException
+     *             if the locale's country is not a supported ISO 3166 Country.
      */
     public static Currency getInstance(Locale locale) {
         com.ibm.icu.util.Currency currency = null;
@@ -91,47 +91,47 @@
     }
 
     /**
-     * Returns this currency's ISO 4217 currency code.
+     * Returns this {@code Currency}'s ISO 4217 currency code.
      * 
-     * @return this currency's ISO 4217 currency code
+     * @return this {@code Currency}'s ISO 4217 currency code.
      */
     public String getCurrencyCode() {
         return currencyCode;
     }
     
     /**
-     * Returns the currency symbol for the default locale.
+     * Returns the symbol for this currency in the default locale. For instance,
+     * if the default locale is the US, the symbol of the US dollar is "$". For
+     * other locales it may be "US$". If no symbol can be determined, the ISO
+     * 4217 currency code of the US dollar is returned.
      * 
-     * Equivalent to <code>getSymbol(Locale.getDefault())</code>
-     * 
-     * @return the currency symbol for the default locale.
+     * @return the symbol for this {@code Currency} in the default {@code Locale}.
      */
     public String getSymbol() {
         return getSymbol(Locale.getDefault());
     }
 
     /**
-     * Returns the currency symbol for the given locale.
+     * Returns the symbol for this currency in the given {@code Locale}.
      * <p>
-     * 
      * If the locale doesn't have any countries (e.g.
-     * <code>Locale.JAPANESE, new Locale("en","")</code>), currencyCode is
-     * returned.
+     * {@code Locale.JAPANESE, new Locale("en","")}), the the ISO
+     * 4217 currency code is returned.
      * <p>
-     * First the locale bundle is checked, if the locale has the same currency,
+     * First the locale's resource bundle is checked, if the locale has the same currency,
      * the CurrencySymbol in this locale bundle is returned.
      * <p>
      * Then a currency bundle for this locale is searched.
      * <p>
      * If a currency bundle for this locale does not exist, or there is no
-     * symbol for this currency in this bundle, than <code>currencyCode</code>
-     * is returned.
+     * symbol for this currency in this bundle, then the
+     * ISO 4217 currency code is returned.
      * <p>
      * 
      * @param locale
-     *            the locale
-     * @return symbol the representation of this Currency's symbol in this
-     *         locale
+     *            the locale for which the currency symbol should be returned.
+     * @return the representation of this {@code Currency}'s symbol in the specified
+     *         locale.
      */
     public String getSymbol(Locale locale) {
         if (locale.getCountry().equals("")) { //$NON-NLS-1$
@@ -141,11 +141,12 @@
     }
 
     /**
-     * Returns the default number of fraction digits for this currency (i.e. the
-     * number of digits after the decimal point). For pseudo currencies this
-     * method returns -1.
+     * Returns the default number of fraction digits for this currency. For
+     * instance, the default number of fraction digits for the US dollar is 2.
+     * For the Japanese Yen the number is 0. In the case of pseudo-currencies,
+     * such as IMF Special Drawing Rights, -1 is returned.
      * 
-     * @return the default number of fraction digits for this currency
+     * @return the default number of fraction digits for this currency.
      */
     public int getDefaultFractionDigits() {
         return com.ibm.icu.util.Currency.getInstance(currencyCode).getDefaultFractionDigits();
@@ -154,7 +155,7 @@
     /**
      * Returns this currency's ISO 4217 currency code.
      * 
-     * @return this currency's ISO 4217 currency code
+     * @return this currency's ISO 4217 currency code.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Date.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Date.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Date.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Date.java Thu May  7 21:43:41 2009
@@ -28,7 +28,7 @@
 import org.apache.harmony.luni.internal.nls.Messages;
 
 /**
- * Date represents a specific moment in time, to the millisecond.
+ * {@code Date} represents a specific moment in time, to the millisecond.
  * 
  * @see System#currentTimeMillis
  * @see Calendar
@@ -53,25 +53,25 @@
         "Aug", "Sep", "Oct", "Nov", "Dec"};  //$NON-NLS-1$//$NON-NLS-2$ //$NON-NLS-3$ //$NON-NLS-4$ //$NON-NLS-5$
 
     /**
-     * Initializes this Date instance to the current date and time.
-     * 
+     * Initializes this {@code Date} instance to the current date and time.
      */
     public Date() {
         this(System.currentTimeMillis());
     }
 
     /**
-     * Constructs a new Date initialized to midnight in the default TimeZone on
+     * Constructs a new {@code Date} initialized to midnight in the default {@code TimeZone} on
      * the specified date.
      * 
      * @param year
-     *            the year, 0 is 1900
+     *            the year, 0 is 1900.
      * @param month
-     *            the month, 0 - 11
+     *            the month, 0 - 11.
      * @param day
-     *            the day of the month, 1 - 31
+     *            the day of the month, 1 - 31.
      * 
-     * @deprecated use GregorianCalendar(int, int, int)
+     * @deprecated use
+     *             {@link GregorianCalendar#GregorianCalendar(int, int, int)}
      */
     @Deprecated
     public Date(int year, int month, int day) {
@@ -81,21 +81,22 @@
     }
 
     /**
-     * Constructs a new Date initialized to the specified date and time in the
-     * default TimeZone.
+     * Constructs a new {@code Date} initialized to the specified date and time in the
+     * default {@code TimeZone}.
      * 
      * @param year
-     *            the year, 0 is 1900
+     *            the year, 0 is 1900.
      * @param month
-     *            the month, 0 - 11
+     *            the month, 0 - 11.
      * @param day
-     *            the day of the month, 1 - 31
+     *            the day of the month, 1 - 31.
      * @param hour
-     *            the hour of day, 0 - 23
+     *            the hour of day, 0 - 23.
      * @param minute
-     *            the minute of the hour, 0 - 59
+     *            the minute of the hour, 0 - 59.
      * 
-     * @deprecated use GregorianCalendar(int, int, int, int, int)
+     * @deprecated use
+     *             {@link GregorianCalendar#GregorianCalendar(int, int, int, int, int)}
      */
     @Deprecated
     public Date(int year, int month, int day, int hour, int minute) {
@@ -105,23 +106,24 @@
     }
 
     /**
-     * Constructs a new Date initialized to the specified date and time in the
-     * default TimeZone.
+     * Constructs a new {@code Date} initialized to the specified date and time in the
+     * default {@code TimeZone}.
      * 
      * @param year
-     *            the year, 0 is 1900
+     *            the year, 0 is 1900.
      * @param month
-     *            the month, 0 - 11
+     *            the month, 0 - 11.
      * @param day
-     *            the day of the month, 1 - 31
+     *            the day of the month, 1 - 31.
      * @param hour
-     *            the hour of day, 0 - 23
+     *            the hour of day, 0 - 23.
      * @param minute
-     *            the minute of the hour, 0 - 59
+     *            the minute of the hour, 0 - 59.
      * @param second
-     *            the second of the minute, 0 - 59
+     *            the second of the minute, 0 - 59.
      * 
-     * @deprecated use GregorianCalendar(int, int, int, int, int, int)
+     * @deprecated use
+     *             {@link GregorianCalendar#GregorianCalendar(int, int, int, int, int, int)}
      */
     @Deprecated
     public Date(int year, int month, int day, int hour, int minute, int second) {
@@ -131,24 +133,24 @@
     }
 
     /**
-     * Initializes this Date instance using the specified millisecond value. The
+     * Initializes this {@code Date} instance using the specified millisecond value. The
      * value is the number of milliseconds since Jan. 1, 1970 GMT.
      * 
      * @param milliseconds
-     *            the number of milliseconds since Jan. 1, 1970 GMT
+     *            the number of milliseconds since Jan. 1, 1970 GMT.
      */
     public Date(long milliseconds) {
         this.milliseconds = milliseconds;
     }
 
     /**
-     * Constructs a new Date initialized to the date and time parsed from the
+     * Constructs a new {@code Date} initialized to the date and time parsed from the
      * specified String.
      * 
      * @param string
-     *            the String to parse
+     *            the String to parse.
      * 
-     * @deprecated use DateFormat
+     * @deprecated use {@link DateFormat}
      */
     @Deprecated
     public Date(String string) {
@@ -156,33 +158,33 @@
     }
 
     /**
-     * Answers if this Date is after the specified Date.
+     * Returns if this {@code Date} is after the specified Date.
      * 
      * @param date
-     *            a Date instance to compare
-     * @return true if this Date is after the specified Date, false otherwise
+     *            a Date instance to compare.
+     * @return {@code true} if this {@code Date} is after the specified {@code Date},
+     *         {@code false} otherwise.
      */
     public boolean after(Date date) {
         return milliseconds > date.milliseconds;
     }
 
     /**
-     * Boolean indication of whether or not this <code>Date</code> occurs
-     * earlier than the <code>Date</code> argument.
+     * Returns if this {@code Date} is before the specified Date.
      * 
      * @param date
-     *            a Date instance to compare
-     * @return <code>true</code> if this <code>Date</code> occurs earlier
-     *         than <code>date</code>, otherwise <code>false</code>
+     *            a {@code Date} instance to compare.
+     * @return {@code true} if this {@code Date} is before the specified {@code Date},
+     *         {@code false} otherwise.
      */
     public boolean before(Date date) {
         return milliseconds < date.milliseconds;
     }
 
     /**
-     * Answers a new Date with the same millisecond value as this Date.
+     * Returns a new {@code Date} with the same millisecond value as this {@code Date}.
      * 
-     * @return a shallow copy of this Date
+     * @return a shallow copy of this {@code Date}.
      * 
      * @see java.lang.Cloneable
      */
@@ -196,13 +198,13 @@
     }
 
     /**
-     * Compare the receiver to the specified Date to determine the relative
+     * Compare the receiver to the specified {@code Date} to determine the relative
      * ordering.
      * 
      * @param date
-     *            a Date
-     * @return an int < 0 if this Date is less than the specified Date, 0 if
-     *         they are equal, and > 0 if this Date is greater
+     *            a {@code Date} to compare against.
+     * @return an {@code int < 0} if this {@code Date} is less than the specified {@code Date}, {@code 0} if
+     *         they are equal, and an {@code int > 0} if this {@code Date} is greater.
      */
     public int compareTo(Date date) {
         if (milliseconds < date.milliseconds) {
@@ -215,14 +217,14 @@
     }
 
     /**
-     * Compares the specified object to this Date and answer if they are equal.
-     * The object must be an instance of Date and have the same millisecond
+     * Compares the specified object to this {@code Date} and returns if they are equal.
+     * To be equal, the object must be an instance of {@code Date} and have the same millisecond
      * value.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this Date, false
-     *         otherwise
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this {@code Date}, {@code false}
+     *         otherwise.
      * 
      * @see #hashCode
      */
@@ -233,11 +235,11 @@
     }
 
     /**
-     * Answers the gregorian calendar day of the month for this Date object.
+     * Returns the gregorian calendar day of the month for this {@code Date} object.
      * 
-     * @return the day of the month
+     * @return the day of the month.
      * 
-     * @deprecated use Calendar.get(Calendar.DATE)
+     * @deprecated use {@code Calendar.get(Calendar.DATE)}
      */
     @Deprecated
     public int getDate() {
@@ -245,11 +247,11 @@
     }
 
     /**
-     * Answers the gregorian calendar day of the week for this Date object.
+     * Returns the gregorian calendar day of the week for this {@code Date} object.
      * 
-     * @return the day of the week
+     * @return the day of the week.
      * 
-     * @deprecated use Calendar.get(Calendar.DAY_OF_WEEK)
+     * @deprecated use {@code Calendar.get(Calendar.DAY_OF_WEEK)}
      */
     @Deprecated
     public int getDay() {
@@ -257,11 +259,11 @@
     }
 
     /**
-     * Answers the gregorian calendar hour of the day for this Date object.
+     * Returns the gregorian calendar hour of the day for this {@code Date} object.
      * 
-     * @return the hour of the day
+     * @return the hour of the day.
      * 
-     * @deprecated use Calendar.get(Calendar.HOUR_OF_DAY)
+     * @deprecated use {@code Calendar.get(Calendar.HOUR_OF_DAY)}
      */
     @Deprecated
     public int getHours() {
@@ -269,11 +271,11 @@
     }
 
     /**
-     * Answers the gregorian calendar minute of the hour for this Date object.
+     * Returns the gregorian calendar minute of the hour for this {@code Date} object.
      * 
-     * @return the minutes
+     * @return the minutes.
      * 
-     * @deprecated use Calendar.get(Calendar.MINUTE)
+     * @deprecated use {@code Calendar.get(Calendar.MINUTE)}
      */
     @Deprecated
     public int getMinutes() {
@@ -281,11 +283,11 @@
     }
 
     /**
-     * Answers the gregorian calendar month for this Date object.
+     * Returns the gregorian calendar month for this {@code Date} object.
      * 
-     * @return the month
+     * @return the month.
      * 
-     * @deprecated use Calendar.get(Calendar.MONTH)
+     * @deprecated use {@code Calendar.get(Calendar.MONTH)}
      */
     @Deprecated
     public int getMonth() {
@@ -293,11 +295,11 @@
     }
 
     /**
-     * Answers the gregorian calendar second of the minute for this Date object.
+     * Returns the gregorian calendar second of the minute for this {@code Date} object.
      * 
-     * @return the seconds
+     * @return the seconds.
      * 
-     * @deprecated use Calendar.get(Calendar.SECOND)
+     * @deprecated use {@code Calendar.get(Calendar.SECOND)}
      */
     @Deprecated
     public int getSeconds() {
@@ -305,22 +307,22 @@
     }
 
     /**
-     * Answers this Date as a millisecond value. The value is the number of
-     * milliseconds since Jan. 1, 1970 GMT.
+     * Returns this {@code Date} as a millisecond value. The value is the number of
+     * milliseconds since Jan. 1, 1970, midnight GMT.
      * 
-     * @return the number of milliseconds since Jan. 1, 1970 GMT.
+     * @return the number of milliseconds since Jan. 1, 1970, midnight GMT.
      */
     public long getTime() {
         return milliseconds;
     }
 
     /**
-     * Answers the timezone offset in minutes of the default TimeZone.
+     * Returns the timezone offset in minutes of the default {@code TimeZone}.
      * 
-     * @return the timezone offset in minutes of the default TimeZone
+     * @return the timezone offset in minutes of the default {@code TimeZone}.
      * 
      * @deprecated use
-     *             <code>(Calendar.get(Calendar.ZONE_OFFSET) + Calendar.get(Calendar.DST_OFFSET)) / 60000</code>
+     *             {@code (Calendar.get(Calendar.ZONE_OFFSET) + Calendar.get(Calendar.DST_OFFSET)) / 60000}
      */
     @Deprecated
     public int getTimezoneOffset() {
@@ -329,11 +331,11 @@
     }
 
     /**
-     * Answers the gregorian calendar year since 1900 for this Date object.
+     * Returns the gregorian calendar year since 1900 for this {@code Date} object.
      * 
-     * @return the year - 1900
+     * @return the year - 1900.
      * 
-     * @deprecated use Calendar.get(Calendar.YEAR) - 1900
+     * @deprecated use {@code Calendar.get(Calendar.YEAR) - 1900}
      */
     @Deprecated
     public int getYear() {
@@ -341,10 +343,10 @@
     }
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
+     * Returns an integer hash code for the receiver. Objects which are equal
+     * return the same value for this method.
      * 
-     * @return the receiver's hash
+     * @return this {@code Date}'s hash.
      * 
      * @see #equals
      */
@@ -363,15 +365,15 @@
     }
 
     /**
-     * Answers the millisecond value of the date and time parsed from the
-     * specified String. Many date/time formats are recognized, including IETF
+     * Returns the millisecond value of the date and time parsed from the
+     * specified {@code String}. Many date/time formats are recognized, including IETF
      * standard syntax, i.e. Tue, 22 Jun 1999 12:16:00 GMT-0500
      * 
      * @param string
-     *            the String to parse
-     * @return the millisecond value parsed from the String
+     *            the String to parse.
+     * @return the millisecond value parsed from the String.
      * 
-     * @deprecated use DateFormat
+     * @deprecated use {@link DateFormat}
      */
     @Deprecated
     public static long parse(String string) {
@@ -563,12 +565,12 @@
     }
 
     /**
-     * Sets the gregorian calendar day of the month for this Date object.
+     * Sets the gregorian calendar day of the month for this {@code Date} object.
      * 
      * @param day
-     *            the day of the month
+     *            the day of the month.
      * 
-     * @deprecated use Calendar.set(Calendar.DATE, day)
+     * @deprecated use {@code Calendar.set(Calendar.DATE, day)}
      */
     @Deprecated
     public void setDate(int day) {
@@ -578,12 +580,12 @@
     }
 
     /**
-     * Sets the gregorian calendar hour of the day for this Date object.
+     * Sets the gregorian calendar hour of the day for this {@code Date} object.
      * 
      * @param hour
-     *            the hour of the day
+     *            the hour of the day.
      * 
-     * @deprecated use Calendar.set(Calendar.HOUR_OF_DAY, hour)
+     * @deprecated use {@code Calendar.set(Calendar.HOUR_OF_DAY, hour)}
      */
     @Deprecated
     public void setHours(int hour) {
@@ -593,12 +595,12 @@
     }
 
     /**
-     * Sets the gregorian calendar minute of the hour for this Date object.
+     * Sets the gregorian calendar minute of the hour for this {@code Date} object.
      * 
      * @param minute
-     *            the minutes
+     *            the minutes.
      * 
-     * @deprecated use Calendar.set(Calendar.MINUTE, minute)
+     * @deprecated use {@code Calendar.set(Calendar.MINUTE, minute)}
      */
     @Deprecated
     public void setMinutes(int minute) {
@@ -608,12 +610,12 @@
     }
 
     /**
-     * Sets the gregorian calendar month for this Date object.
+     * Sets the gregorian calendar month for this {@code Date} object.
      * 
      * @param month
-     *            the month
+     *            the month.
      * 
-     * @deprecated use Calendar.set(Calendar.MONTH, month)
+     * @deprecated use {@code Calendar.set(Calendar.MONTH, month)}
      */
     @Deprecated
     public void setMonth(int month) {
@@ -623,12 +625,12 @@
     }
 
     /**
-     * Sets the gregorian calendar second of the minute for this Date object.
+     * Sets the gregorian calendar second of the minute for this {@code Date} object.
      * 
      * @param second
-     *            the seconds
+     *            the seconds.
      * 
-     * @deprecated use Calendar.set(Calendar.SECOND, second)
+     * @deprecated use {@code Calendar.set(Calendar.SECOND, second)}
      */
     @Deprecated
     public void setSeconds(int second) {
@@ -638,7 +640,7 @@
     }
 
     /**
-     * Sets this Date to the specified millisecond value. The value is the
+     * Sets this {@code Date} to the specified millisecond value. The value is the
      * number of milliseconds since Jan. 1, 1970 GMT.
      * 
      * @param milliseconds
@@ -649,12 +651,12 @@
     }
 
     /**
-     * Sets the gregorian calendar year since 1900 for this Date object.
+     * Sets the gregorian calendar year since 1900 for this {@code Date} object.
      * 
      * @param year
-     *            the year since 1900
+     *            the year since 1900.
      * 
-     * @deprecated use Calendar.set(Calendar.YEAR, year + 1900)
+     * @deprecated use {@code Calendar.set(Calendar.YEAR, year + 1900)}
      */
     @Deprecated
     public void setYear(int year) {
@@ -664,12 +666,12 @@
     }
 
     /**
-     * Answers the string representation of this Date in GMT in the format: 22
+     * Returns the string representation of this {@code Date} in GMT in the format: 22
      * Jun 1999 13:02:00 GMT
      * 
-     * @return the string representation of this Date in GMT
+     * @return the string representation of this {@code Date} in GMT.
      * 
-     * @deprecated use DateFormat
+     * @deprecated use {@link DateFormat}
      */
     @Deprecated
     public String toGMTString() {
@@ -686,11 +688,11 @@
     }
 
     /**
-     * Answers the string representation of this Date for the current Locale.
+     * Returns the string representation of this {@code Date} for the default {@code Locale}.
      * 
-     * @return the string representation of this Date for the current Locale
+     * @return the string representation of this {@code Date} for the default {@code Locale}.
      * 
-     * @deprecated use DateFormat
+     * @deprecated use {@link DateFormat}
      */
     @Deprecated
     public String toLocaleString() {
@@ -698,10 +700,10 @@
     }
 
     /**
-     * Answers the string representation of this Date in the format: Tue Jun 22
+     * Returns the string representation of this {@code Date} in the format: Tue Jun 22
      * 13:07:00 GMT 1999
      * 
-     * @return the string representation of this Date
+     * @return the string representation of this {@code Date}.
      */
     @Override
     public String toString() {
@@ -721,26 +723,26 @@
     }
     
     /**
-     * Answers the millisecond value of the specified date and time in GMT.
+     * Returns the millisecond value of the specified date and time in GMT.
      * 
      * @param year
-     *            the year, 0 is 1900
+     *            the year, 0 is 1900.
      * @param month
-     *            the month, 0 - 11
+     *            the month, 0 - 11.
      * @param day
-     *            the day of the month, 1 - 31
+     *            the day of the month, 1 - 31.
      * @param hour
-     *            the hour of day, 0 - 23
+     *            the hour of day, 0 - 23.
      * @param minute
-     *            the minute of the hour, 0 - 59
+     *            the minute of the hour, 0 - 59.
      * @param second
-     *            the second of the minute, 0 - 59
-     * @return long
+     *            the second of the minute, 0 - 59.
+     * @return the date and time in GMT in milliseconds.
      * 
      * @deprecated use: <code>
-     * Calendar cal = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
-     * cal.set(year + 1900, month, day, hour, minute, second);
-     * cal.getTime().getTime();</code>
+     *  Calendar cal = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
+     *  cal.set(year + 1900, month, day, hour, minute, second);
+     *  cal.getTime().getTime();</code>
      */
     @Deprecated
     public static long UTC(int year, int month, int day, int hour, int minute,

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Dictionary.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Dictionary.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Dictionary.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Dictionary.java Thu May  7 21:43:41 2009
@@ -18,8 +18,11 @@
 package java.util;
 
 /**
- * Dictionary is a abstract class which is the superclass of all classes that
- * associate keys with values, such as Hashtable.
+ * <strong>Note: Do not use this class since it is obsolete. Please use the
+ * {@link Map} interface for new implementations.</strong>
+ * <p>
+ * Dictionary is an abstract class which is the superclass of all classes that
+ * associate keys with values, such as {@code Hashtable}.
  * 
  * @see Hashtable
  * @since 1.0
@@ -27,17 +30,15 @@
 public abstract class Dictionary<K, V> {
     /**
      * Constructs a new instance of this class.
-     * 
      */
     public Dictionary() {
         super();
     }
 
     /**
-     * Answers an Enumeration on the elements of this Dictionary.
-     * 
-     * @return an Enumeration of the values of this Dictionary
+     * Returns an enumeration on the elements of this dictionary.
      * 
+     * @return an enumeration of the values of this dictionary.
      * @see #keys
      * @see #size
      * @see Enumeration
@@ -45,31 +46,29 @@
     public abstract Enumeration<V> elements();
 
     /**
-     * Answers the value associated with <code>key</code>.
+     * Returns the value which is associated with {@code key}.
      * 
      * @param key
-     *            the key of the value returned
-     * @return the value associated with <code>key</code> or <code>null</code>
-     *         if the specified key does not exist
-     * 
+     *            the key of the value returned.
+     * @return the value associated with {@code key}, or {@code null} if the
+     *         specified key does not exist.
      * @see #put
      */
     public abstract V get(Object key);
 
     /**
-     * Answers if this Dictionary has no key/value pairs, a size of zero.
-     * 
-     * @return true if this Dictionary has no key/value pairs, false otherwise
+     * Returns true if this dictionary has no key/value pairs.
      * 
+     * @return {@code true} if this dictionary has no key/value pairs,
+     *         {@code false} otherwise.
      * @see #size
      */
     public abstract boolean isEmpty();
 
     /**
-     * Answers an Enumeration on the keys of this Dictionary.
-     * 
-     * @return an Enumeration of the keys of this Dictionary
+     * Returns an enumeration on the keys of this dictionary.
      * 
+     * @return an enumeration of the keys of this dictionary.
      * @see #elements
      * @see #size
      * @see Enumeration
@@ -77,19 +76,16 @@
     public abstract Enumeration<K> keys();
 
     /**
-     * Associate <code>key</code> with <code>value</code> in this
-     * <code>Dictionary</code>. If <code>key</code> exists in the
-     * <code>Dictionary</code> prior to this call being made, the old value is
-     * replaced.
+     * Associate {@code key} with {@code value} in this dictionary. If {@code
+     * key} exists in the dictionary before this call, the old value in the
+     * dictionary is replaced by {@code value}.
      * 
      * @param key
-     *            the key to add
+     *            the key to add.
      * @param value
-     *            the value to add
-     * @return the old value previously associated with <code>key</code> or
-     *         <code>null</code> if <code>key</code> is new to the
-     *         <code>Dictionary</code>.
-     * 
+     *            the value to add.
+     * @return the old value previously associated with {@code key} or {@code
+     *         null} if {@code key} is new to the dictionary.
      * @see #elements
      * @see #get
      * @see #keys
@@ -97,24 +93,22 @@
     public abstract V put(K key, V value);
 
     /**
-     * Remove the key/value pair with the specified <code>key</code> from this
-     * <code>Dictionary</code>.
+     * Removes the key/value pair with the specified {@code key} from this
+     * dictionary.
      * 
      * @param key
-     *            the key to remove
-     * @return the associated value or else <code>null</code> if
-     *         <code>key</code> is not known to this <code>Dictionary</code>
-     * 
+     *            the key to remove.
+     * @return the associated value before the deletion or {@code null} if
+     *         {@code key} was not known to this dictionary.
      * @see #get
      * @see #put
      */
     public abstract V remove(Object key);
 
     /**
-     * Answers the number of key/value pairs in this Dictionary.
-     * 
-     * @return the number of key/value pairs in this Dictionary
+     * Returns the number of key/value pairs in this dictionary.
      * 
+     * @return the number of key/value pairs in this dictionary.
      * @see #elements
      * @see #keys
      */

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/DuplicateFormatFlagsException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/DuplicateFormatFlagsException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/DuplicateFormatFlagsException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/DuplicateFormatFlagsException.java Thu May  7 21:43:41 2009
@@ -19,6 +19,8 @@
 /**
  * The unchecked exception will be thrown out if there are duplicate flags given
  * out in the format specifier.
+ *
+ * @see java.lang.RuntimeException
  */
 public class DuplicateFormatFlagsException extends IllegalFormatException {
 
@@ -27,10 +29,11 @@
     private String flags;
 
     /**
-     * Constructs a DuplicateFormatFlagsException which flags is specified.
+     * Constructs a new {@code DuplicateFormatFlagsException} with the flags
+     * containing duplicates.
      * 
      * @param f
-     *            The format flags that contain a duplicate flag.
+     *           the format flags that contain a duplicate flag.
      */
     public DuplicateFormatFlagsException(String f) {
         if (null == f) {
@@ -42,7 +45,7 @@
     /**
      * Returns the format flags that contain a duplicate flag.
      * 
-     * @return The format flags that contain a duplicate flag.
+     * @return the format flags that contain a duplicate flag.
      */
     public String getFlags() {
         return flags;
@@ -51,7 +54,7 @@
     /**
      * Returns the message string of the DuplicateFormatFlagsException.
      * 
-     * @return The message string of the DuplicateFormatFlagsException.
+     * @return the message string of the DuplicateFormatFlagsException.
      */
     @Override
     public String getMessage() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EmptyStackException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EmptyStackException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EmptyStackException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EmptyStackException.java Thu May  7 21:43:41 2009
@@ -17,16 +17,20 @@
 
 package java.util;
 
+
 /**
- * Runtime exception which is thrown when pop/peek method of stack is executed
- * on a stack which is empty
+ * An {@code EmptyStackException} is thrown if the pop/peek method of a stack is
+ * executed on an empty stack.
+ *
+ * @see java.lang.RuntimeException
  */
 public class EmptyStackException extends RuntimeException {
 
     private static final long serialVersionUID = 5084686378493302095L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code EmptyStackException} with the stack trace filled
+     * in.
      */
     public EmptyStackException() {
         super();



Mime
View raw message