harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772785 [1/12] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/
Date Thu, 07 May 2009 21:43:44 GMT
Author: tellison
Date: Thu May  7 21:43:41 2009
New Revision: 772785

URL: http://svn.apache.org/viewvc?rev=772785&view=rev
Log:
Apply patch for HARMONY-6201 (Javadocs for java.util.*)

Modified:
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractCollection.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractList.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractMap.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractQueue.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSequentialList.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSet.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ArrayList.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Arrays.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/BitSet.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Calendar.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Collection.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Collections.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Comparator.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ConcurrentModificationException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Currency.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Date.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Dictionary.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/DuplicateFormatFlagsException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EmptyStackException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EnumMap.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EnumSet.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Enumeration.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventListenerProxy.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventObject.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatFlagsConversionMismatchException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formattable.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormattableFlags.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formatter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatterClosedException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/GregorianCalendar.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashMap.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashSet.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Hashtable.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IdentityHashMap.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatCodePointException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatConversionException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatFlagsException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatPrecisionException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatWidthException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InputMismatchException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InvalidPropertiesFormatException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Iterator.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashMap.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashSet.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedList.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/List.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListIterator.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListResourceBundle.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Locale.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Map.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingFormatArgumentException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingFormatWidthException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingResourceException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/NoSuchElementException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observable.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observer.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PriorityQueue.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Properties.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermission.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermissionCollection.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyResourceBundle.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Queue.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Random.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/RandomAccess.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ResourceBundle.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Scanner.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Set.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SimpleTimeZone.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedMap.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedSet.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Stack.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/StringTokenizer.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimeZone.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Timer.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimerTask.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TooManyListenersException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeMap.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeSet.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UUID.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatConversionException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatFlagsException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Vector.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/WeakHashMap.java

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractCollection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractCollection.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractCollection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractCollection.java Thu May  7 21:43:41 2009
@@ -20,10 +20,12 @@
 import java.lang.reflect.Array;
 
 /**
- * AbstractCollection is an abstract implementation of the Collection interface.
- * This implementation does not support adding. A subclass must implement the
- * abstract methods iterator() and size().
- * 
+ * Class {@code AbstractCollection} is an abstract implementation of the {@code
+ * Collection} interface. A subclass must implement the abstract methods {@code
+ * iterator()} and {@code size()} to create an immutable collection. To create a
+ * modifiable collection it's necessary to override the {@code add()} method that
+ * currently throws an {@code UnsupportedOperationException}.
+ *
  * @since 1.2
  */
 public abstract class AbstractCollection<E> implements Collection<E> {
@@ -35,50 +37,38 @@
         super();
     }
 
-    /**
-     * If the specified element is not contained within this collection, and
-     * addition of this element succeeds, then true will be returned. If the
-     * specified element is already contained within this collection, or
-     * duplication is not permitted, false will be returned. Different
-     * implementations may add specific limitations on this method to filter
-     * permitted elements. For example, in some implementation, null element may
-     * be denied, and NullPointerException will be thrown out. These limitations
-     * should be explicitly documented by specific collection implementation.
-     * 
-     * Add operation is not supported in this implementation, and
-     * UnsupportedOperationException will always be thrown out.
-     * 
-     * @param object
-     *            the element to be added.
-     * @return true if the collection is changed successfully after invoking
-     *         this method. Otherwise, false.
-     * @throws UnsupportedOperationException
-     *             if add operation is not supported by this class.
-     * @throws NullPointerException
-     *             if null is used to invoke this method, and null is not
-     *             permitted by this collection.
-     * @throws ClassCastException
-     *             if the class type of the specified element is not compatible
-     *             with the permitted class type.
-     * @throws IllegalArgumentException
-     *             if limitations of this collection prevent the specified
-     *             element from being added
-     */
     public boolean add(E object) {
         throw new UnsupportedOperationException();
     }
 
     /**
-     * Adds the objects in the specified Collection to this Collection.
+     * Attempts to add all of the objects contained in {@code collection}
+     * to the contents of this {@code Collection} (optional). This implementation
+     * iterates over the given {@code Collection} and calls {@code add} for each
+     * element. If any of these calls return {@code true}, then {@code true} is
+     * returned as result of this method call, {@code false} otherwise. If this
+     * {@code Collection} does not support adding elements, an {@code
+     * UnsupportedOperationException} is thrown.
+     * <p>
+     * If the passed {@code Collection} is changed during the process of adding elements
+     * to this {@code Collection}, the behavior depends on the behavior of the passed
+     * {@code Collection}.
      * 
      * @param collection
-     *            the Collection of objects
-     * @return true if this Collection is modified, false otherwise
-     * 
+     *            the collection of objects.
+     * @return {@code true} if this {@code Collection} is modified, {@code false}
+     *         otherwise.
      * @throws UnsupportedOperationException
-     *             when adding to this Collection is not supported
+     *                if adding to this {@code Collection} is not supported.
+     * @throws ClassCastException
+     *                if the class of an object is inappropriate for this
+     *                {@code Collection}.
+     * @throws IllegalArgumentException
+     *                if an object cannot be added to this {@code Collection}.
      * @throws NullPointerException
-     *             if null is used to invoke this method
+     *                if {@code collection} is {@code null}, or if it contains
+     *                {@code null} elements and this {@code Collection} does not support
+     *                such elements.
      */
     public boolean addAll(Collection<? extends E> collection) {
         boolean result = false;
@@ -92,16 +82,20 @@
     }
 
     /**
-     * Removes all the elements in this collection. This collection will be
-     * cleared up after this operation. The operation iterates over the
-     * collection, removes every element using Iterator.remove method.
-     * 
-     * UnsupportedOperationException will be thrown out if the iterator returned
-     * by this collection does not implement the remove method and the
-     * collection is not zero length.
+     * Removes all elements from this {@code Collection}, leaving it empty (optional).
+     * This implementation iterates over this {@code Collection} and calls the {@code
+     * remove} method on each element. If the iterator does not support removal
+     * of elements, an {@code UnsupportedOperationException} is thrown.
+     * <p>
+     * Concrete implementations usually can clear a {@code Collection} more efficiently
+     * and should therefore overwrite this method.
      * 
      * @throws UnsupportedOperationException
-     *             if this operation is not implemented.
+     *                it the iterator does not support removing elements from
+     *                this {@code Collection}
+     * @see #iterator
+     * @see #isEmpty
+     * @see #size
      */
     public void clear() {
         Iterator<E> it = iterator();
@@ -112,12 +106,23 @@
     }
 
     /**
-     * Searches this Collection for the specified object.
+     * Tests whether this {@code Collection} contains the specified object. This
+     * implementation iterates over this {@code Collection} and tests, whether any
+     * element is equal to the given object. If {@code object != null} then
+     * {@code object.equals(e)} is called for each element {@code e} returned by
+     * the iterator until the element is found. If {@code object == null} then
+     * each element {@code e} returned by the iterator is compared with the test
+     * {@code e == null}.
      * 
      * @param object
-     *            the object to search for
-     * @return true if <code>object</code> is an element of this Collection,
-     *         false otherwise
+     *            the object to search for.
+     * @return {@code true} if object is an element of this {@code Collection}, {@code
+     *         false} otherwise.
+     * @throws ClassCastException
+     *                if the object to look for isn't of the correct type.
+     * @throws NullPointerException
+     *                if the object to look for is {@code null} and this
+     *                {@code Collection} doesn't support {@code null} elements.
      */
     public boolean contains(Object object) {
         Iterator<E> it = iterator();
@@ -138,14 +143,24 @@
     }
 
     /**
-     * Searches this Collection for all objects in the specified Collection.
+     * Tests whether this {@code Collection} contains all objects contained in the
+     * specified {@code Collection}. This implementation iterates over the specified
+     * {@code Collection}. If one element returned by the iterator is not contained in
+     * this {@code Collection}, then {@code false} is returned; {@code true} otherwise.
      * 
      * @param collection
-     *            the Collection of objects
-     * @return true if all objects in the specified Collection are elements of
-     *         this Collection, false otherwise
+     *            the collection of objects.
+     * @return {@code true} if all objects in the specified {@code Collection} are
+     *         elements of this {@code Collection}, {@code false} otherwise.
+     * @throws ClassCastException
+     *                if one or more elements of {@code collection} isn't of the
+     *                correct type.
      * @throws NullPointerException
-     *             if null is used to invoke this method
+     *                if {@code collection} contains at least one {@code null}
+     *                element and this {@code Collection} doesn't support {@code null}
+     *                elements.
+     * @throws NullPointerException
+     *                if {@code collection} is {@code null}.
      */
     public boolean containsAll(Collection<?> collection) {
         Iterator<?> it = collection.iterator();
@@ -158,40 +173,54 @@
     }
 
     /**
-     * Returns true if the collection has no element, otherwise false.
+     * Returns if this {@code Collection} contains no elements. This implementation
+     * tests, whether {@code size} returns 0.
      * 
-     * @return true if the collection has no element.
+     * @return {@code true} if this {@code Collection} has no elements, {@code false}
+     *         otherwise.
+     *
+     * @see #size
      */
     public boolean isEmpty() {
         return size() == 0;
     }
 
     /**
-     * Answers an Iterator on the elements of this Collection. A subclass must
-     * implement the abstract methods iterator() and size().
-     * 
-     * @return an Iterator on the elements of this Collection
+     * Returns an instance of {@link Iterator} that may be used to access the
+     * objects contained by this {@code Collection}. The order in which the elements are
+     * returned by the {@link Iterator} is not defined unless the instance of the
+     * {@code Collection} has a defined order.  In that case, the elements are returned in that order.
+     * <p>
+     * In this class this method is declared abstract and has to be implemented
+     * by concrete {@code Collection} implementations.
      * 
-     * @see Iterator
+     * @return an iterator for accessing the {@code Collection} contents.
      */
     public abstract Iterator<E> iterator();
 
     /**
-     * Removes the first occurrence of the specified object from this
-     * Collection. This operation traverses over the collection, looking for the
-     * specified object. Once the object is found, the object will be removed
-     * from the collection using the iterator's remove method.
-     * 
-     * This collection will throw an UnsupportedOperationException if the
-     * iterator returned does not implement remove method, and the specified
-     * object is in this collection.
+     * Removes one instance of the specified object from this {@code Collection} if one
+     * is contained (optional). This implementation iterates over this
+     * {@code Collection} and tests for each element {@code e} returned by the iterator,
+     * whether {@code e} is equal to the given object. If {@code object != null}
+     * then this test is performed using {@code object.equals(e)}, otherwise
+     * using {@code object == null}. If an element equal to the given object is
+     * found, then the {@code remove} method is called on the iterator and
+     * {@code true} is returned, {@code false} otherwise. If the iterator does
+     * not support removing elements, an {@code UnsupportedOperationException}
+     * is thrown.
      * 
      * @param object
-     *            the object to remove
-     * @return true if this Collection is modified, false otherwise
-     * 
+     *            the object to remove.
+     * @return {@code true} if this {@code Collection} is modified, {@code false}
+     *         otherwise.
      * @throws UnsupportedOperationException
-     *             when removing from this Collection is not supported
+     *                if removing from this {@code Collection} is not supported.
+     * @throws ClassCastException
+     *                if the object passed is not of the correct type.
+     * @throws NullPointerException
+     *                if {@code object} is {@code null} and this {@code Collection}
+     *                doesn't support {@code null} elements.
      */
     public boolean remove(Object object) {
         Iterator<?> it = iterator();
@@ -214,25 +243,33 @@
     }
 
     /**
-     * Removes all occurrences in this Collection of each object in the
-     * specified Collection. This operation traverses over the collection
-     * itself, to verify whether each element is contained in the specified
-     * collection. The object will be removed from the collection itself using
-     * the iterator's remove method if it is contained in the specified
-     * collection.
-     * 
-     * This collection will throw an UnsupportedOperationException if the
-     * iterator returned does not implement remove method, and the element in
-     * the specified collection is contained in this collection.
+     * Removes all occurrences in this {@code Collection} of each object in the
+     * specified {@code Collection} (optional). After this method returns none of the
+     * elements in the passed {@code Collection} can be found in this {@code Collection}
+     * anymore.
+     * <p>
+     * This implementation iterates over this {@code Collection} and tests for each
+     * element {@code e} returned by the iterator, whether it is contained in
+     * the specified {@code Collection}. If this test is positive, then the {@code
+     * remove} method is called on the iterator. If the iterator does not
+     * support removing elements, an {@code UnsupportedOperationException} is
+     * thrown.
      * 
      * @param collection
-     *            the Collection of objects to remove
-     * @return true if this Collection is modified, false otherwise
-     * 
+     *            the collection of objects to remove.
+     * @return {@code true} if this {@code Collection} is modified, {@code false}
+     *         otherwise.
      * @throws UnsupportedOperationException
-     *             when removing from this Collection is not supported
+     *                if removing from this {@code Collection} is not supported.
+     * @throws ClassCastException
+     *                if one or more elements of {@code collection} isn't of the
+     *                correct type.
+     * @throws NullPointerException
+     *                if {@code collection} contains at least one {@code null}
+     *                element and this {@code Collection} doesn't support {@code null}
+     *                elements.
      * @throws NullPointerException
-     *             if null is used to invoke this method
+     *                if {@code collection} is {@code null}.
      */
     public boolean removeAll(Collection<?> collection) {
         boolean result = false;
@@ -247,26 +284,33 @@
     }
 
     /**
-     * Removes all objects from this Collection that are not contained in the
-     * specified Collection. This operation traverses over the collection
-     * itself, to verify whether any element is contained in the specified
-     * collection. The object will be removed from the collection itself using
-     * the iterator's remove method if it is not contained in the specified
-     * collection.
-     * 
-     * This collection will throw an UnsupportedOperationException if the
-     * iterator returned does not implement remove method, and the collection
-     * itself does contain elements which do not exist in the specified
-     * collection.
+     * Removes all objects from this {@code Collection} that are not also found in the
+     * {@code Collection} passed (optional). After this method returns this {@code Collection}
+     * will only contain elements that also can be found in the {@code Collection}
+     * passed to this method.
+     * <p>
+     * This implementation iterates over this {@code Collection} and tests for each
+     * element {@code e} returned by the iterator, whether it is contained in
+     * the specified {@code Collection}. If this test is negative, then the {@code
+     * remove} method is called on the iterator. If the iterator does not
+     * support removing elements, an {@code UnsupportedOperationException} is
+     * thrown.
      * 
      * @param collection
-     *            the Collection of objects to retain
-     * @return true if this Collection is modified, false otherwise
-     * 
+     *            the collection of objects to retain.
+     * @return {@code true} if this {@code Collection} is modified, {@code false}
+     *         otherwise.
      * @throws UnsupportedOperationException
-     *             when removing from this Collection is not supported
+     *                if removing from this {@code Collection} is not supported.
+     * @throws ClassCastException
+     *                if one or more elements of {@code collection}
+     *                isn't of the correct type.
      * @throws NullPointerException
-     *             if null is used to invoke this method
+     *                if {@code collection} contains at least one
+     *                {@code null} element and this {@code Collection} doesn't support
+     *                {@code null} elements.
+     * @throws NullPointerException
+     *                if {@code collection} is {@code null}.
      */
     public boolean retainAll(Collection<?> collection) {
         boolean result = false;
@@ -281,21 +325,17 @@
     }
 
     /**
-     * Answers the number of elements in this Collection.
-     * 
-     * @return the number of elements in this Collection
+     * Returns a count of how many objects this {@code Collection} contains.
+     * <p>
+     * In this class this method is declared abstract and has to be implemented
+     * by concrete {@code Collection} implementations.
+     * 
+     * @return how many objects this {@code Collection} contains, or {@code Integer.MAX_VALUE}
+     *         if there are more than {@code Integer.MAX_VALUE} elements in this
+     *         {@code Collection}.
      */
     public abstract int size();
 
-    /**
-     * Answers a new array containing all elements contained in this Collection.
-     * All the elements in the array will not be referenced by the collection.
-     * The elements in the returned array will be sorted to the same order as
-     * those returned by the iterator of this collection itself if the
-     * collection guarantees the order.
-     * 
-     * @return an array of the elements from this Collection
-     */
     public Object[] toArray() {
         int size = size(), index = 0;
         Iterator<?> it = iterator();
@@ -306,23 +346,6 @@
         return array;
     }
 
-    /**
-     * Answers an array containing all elements contained in this Collection. If
-     * the specified array is large enough to hold the elements, the specified
-     * array is used, otherwise an array of the same type is created. If the
-     * specified array is used and is larger than this Collection, the array
-     * element following the collection elements is set to null.
-     * 
-     * @param contents
-     *            the array
-     * @return an array of the elements from this Collection
-     * 
-     * @throws ArrayStoreException
-     *             when the type of an element in this Collection cannot be
-     *             stored in the type of the specified array
-     * @throws NullPointerException
-     *             if null is used to invoke this method
-     */
     @SuppressWarnings("unchecked")
     public <T> T[] toArray(T[] contents) {
         int size = size(), index = 0;
@@ -340,11 +363,11 @@
     }
 
     /**
-     * Answers the string representation of this Collection. The presentation
+     * Returns the string representation of this {@code Collection}. The presentation
      * has a specific format. It is enclosed by square brackets ("[]"). Elements
      * are separated by ', ' (comma and space).
      * 
-     * @return the string representation of this Collection
+     * @return the string representation of this {@code Collection}.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractList.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractList.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractList.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractList.java Thu May  7 21:43:41 2009
@@ -18,16 +18,21 @@
 package java.util;
 
 /**
- * AbstractList is an abstract implementation of the List interface, optimized
+ * {@code AbstractList} is an abstract implementation of the {@code List} interface, optimized
  * for a backing store which supports random access. This implementation does
  * not support adding or replacing. A subclass must implement the abstract
- * methods get() and size().
- * 
+ * methods {@code get()} and {@code size()}, and to create a
+ * modifiable {@code List} it's necessary to override the {@code add()} method that
+ * currently throws an {@code UnsupportedOperationException}.
+ *
  * @since 1.2
  */
 public abstract class AbstractList<E> extends AbstractCollection<E> implements
         List<E> {
 
+    /**
+     * A counter for changes to the list.
+     */
     protected transient int modCount;
 
     private class SimpleListIterator implements Iterator<E> {
@@ -370,7 +375,6 @@
 
     /**
      * Constructs a new instance of this AbstractList.
-     * 
      */
     protected AbstractList() {
         super();
@@ -381,22 +385,24 @@
      * The object is inserted before any previous element at the specified
      * location. If the location is equal to the size of this List, the object
      * is added at the end.
-     * 
-     * 
+     * <p>
+     * Concrete implementations that would like to support the add functionality
+     * must override this method.
+     *
      * @param location
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param object
-     *            the object to add
+     *            the object to add.
      * 
-     * @exception UnsupportedOperationException
-     *                when adding to this List is not supported
-     * @exception ClassCastException
-     *                when the class of the object is inappropriate for this
+     * @throws UnsupportedOperationException
+     *                if adding to this List is not supported.
+     * @throws ClassCastException
+     *                if the class of the object is inappropriate for this
      *                List
-     * @exception IllegalArgumentException
-     *                when the object cannot be added to this List
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     * @throws IllegalArgumentException
+     *                if the object cannot be added to this List
+     * @throws IndexOutOfBoundsException
+     *                if {@code location < 0 || >= size()}
      */
     public void add(int location, E object) {
         throw new UnsupportedOperationException();
@@ -410,13 +416,13 @@
      *            the object to add
      * @return true
      * 
-     * @exception UnsupportedOperationException
-     *                when adding to this List is not supported
-     * @exception ClassCastException
-     *                when the class of the object is inappropriate for this
+     * @throws UnsupportedOperationException
+     *                if adding to this List is not supported
+     * @throws ClassCastException
+     *                if the class of the object is inappropriate for this
      *                List
-     * @exception IllegalArgumentException
-     *                when the object cannot be added to this List
+     * @throws IllegalArgumentException
+     *                if the object cannot be added to this List
      */
     @Override
     public boolean add(E object) {
@@ -427,23 +433,21 @@
     /**
      * Inserts the objects in the specified Collection at the specified location
      * in this List. The objects are added in the order they are returned from
-     * the Collection iterator.
-     * 
+     * the collection's iterator.
      * 
      * @param location
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param collection
      *            the Collection of objects
-     * @return true if this List is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding to this List is not supported
-     * @exception ClassCastException
-     *                when the class of an object is inappropriate for this List
-     * @exception IllegalArgumentException
-     *                when an object cannot be added to this List
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     * @return {@code true} if this List is modified, {@code false} otherwise.
+     * @throws UnsupportedOperationException
+     *             if adding to this list is not supported.
+     * @throws ClassCastException
+     *             if the class of an object is inappropriate for this list.
+     * @throws IllegalArgumentException
+     *             if an object cannot be added to this list.
+     * @throws IndexOutOfBoundsException
+     *             if {@code location < 0 || > size()}
      */
     public boolean addAll(int location, Collection<? extends E> collection) {
         Iterator<? extends E> it = collection.iterator();
@@ -454,12 +458,10 @@
     }
 
     /**
-     * Removes all elements from this List, leaving it empty.
-     * 
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this List is not supported
+     * Removes all elements from this list, leaving it empty.
      * 
+     * @throws UnsupportedOperationException
+     *             if removing from this list is not supported.
      * @see List#isEmpty
      * @see List#size
      */
@@ -469,16 +471,14 @@
     }
 
     /**
-     * Compares the specified object to this List and answer if they are equal.
-     * The object must be a List which contains the same objects in the same
-     * order.
-     * 
+     * Compares the specified object to this list and return true if they are
+     * equal. Two lists are equal when they both contain the same objects in the
+     * same order.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this List, false
-     *         otherwise
-     * 
+     *            the object to compare to this object.
+     * @return {@code true} if the specified object is equal to this list,
+     *         {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -505,26 +505,23 @@
     }
 
     /**
-     * Answers the element at the specified location in this List.
-     * 
+     * Returns the element at the specified location in this list.
      * 
      * @param location
-     *            the index of the element to return
-     * @return the element at the specified index
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     *            the index of the element to return.
+     * @return the element at the specified index.
+     * @throws IndexOutOfBoundsException
+     *             if {@code location < 0 || >= size()}
      */
     public abstract E get(int location);
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
-     * 
-     * 
-     * @return the receiver's hash
+     * Returns the hash code of this list. The hash code is calculated by taking
+     * each element's hashcode into account.
      * 
+     * @return the hash code.
      * @see #equals
+     * @see List#hashCode()
      */
     @Override
     public int hashCode() {
@@ -538,13 +535,13 @@
     }
 
     /**
-     * Searches this List for the specified object and returns the index of the
+     * Searches this list for the specified object and returns the index of the
      * first occurrence.
      * 
-     * 
      * @param object
-     *            the object to search for
-     * @return the index of the first occurrence of the object
+     *            the object to search for.
+     * @return the index of the first occurrence of the object, or -1 if it was
+     *         not found.
      */
     public int indexOf(Object object) {
         ListIterator<?> it = listIterator();
@@ -565,12 +562,10 @@
     }
 
     /**
-     * Answers an Iterator on the elements of this List. The elements are
-     * iterated in the same order that they occur in the List.
-     * 
-     * 
-     * @return an Iterator on the elements of this List
+     * Returns an iterator on the elements of this list. The elements are
+     * iterated in the same order as they occur in the list.
      * 
+     * @return an iterator on the elements of this list.
      * @see Iterator
      */
     @Override
@@ -579,13 +574,13 @@
     }
 
     /**
-     * Searches this List for the specified object and returns the index of the
+     * Searches this list for the specified object and returns the index of the
      * last occurrence.
      * 
-     * 
      * @param object
-     *            the object to search for
-     * @return the index of the last occurrence of the object
+     *            the object to search for.
+     * @return the index of the last occurrence of the object, or -1 if the
+     *         object was not found.
      */
     public int lastIndexOf(Object object) {
         ListIterator<?> it = listIterator(size());
@@ -606,12 +601,10 @@
     }
 
     /**
-     * Answers a ListIterator on the elements of this List. The elements are
-     * iterated in the same order that they occur in the List.
-     * 
-     * 
-     * @return a ListIterator on the elements of this List
+     * Returns a ListIterator on the elements of this list. The elements are
+     * iterated in the same order that they occur in the list.
      * 
+     * @return a ListIterator on the elements of this list
      * @see ListIterator
      */
     public ListIterator<E> listIterator() {
@@ -619,18 +612,15 @@
     }
 
     /**
-     * Answers a ListIterator on the elements of this List. The elements are
-     * iterated in the same order that they occur in the List. The iteration
+     * Returns a list iterator on the elements of this list. The elements are
+     * iterated in the same order as they occur in the list. The iteration
      * starts at the specified location.
      * 
-     * 
      * @param location
-     *            the index at which to start the iteration
-     * @return a ListIterator on the elements of this List
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
-     * 
+     *            the index at which to start the iteration.
+     * @return a ListIterator on the elements of this list.
+     * @throws IndexOutOfBoundsException
+     *             if {@code location < 0 || location > size()}
      * @see ListIterator
      */
     public ListIterator<E> listIterator(int location) {
@@ -638,36 +628,32 @@
     }
 
     /**
-     * Removes the object at the specified location from this List.
-     * 
+     * Removes the object at the specified location from this list.
      * 
      * @param location
-     *            the index of the object to remove
-     * @return the removed object
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this List is not supported
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     *            the index of the object to remove.
+     * @return the removed object.
+     * @throws UnsupportedOperationException
+     *             if removing from this list is not supported.
+     * @throws IndexOutOfBoundsException
+     *             if {@code location < 0 || >= size()}
      */
     public E remove(int location) {
         throw new UnsupportedOperationException();
     }
 
     /**
-     * Removes the objects in the specified range from the start to the, but not
-     * including, end index.
-     * 
+     * Removes the objects in the specified range from the start to the end
+     * index minus one.
      * 
      * @param start
-     *            the index at which to start removing
+     *            the index at which to start removing.
      * @param end
-     *            the index one past the end of the range to remove
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this List is not supported
-     * @exception IndexOutOfBoundsException
-     *                when <code>start < 0
+     *            the index after the last element to remove.
+     * @throws UnsupportedOperationException
+     *             if removing from this list is not supported.
+     * @throws IndexOutOfBoundsException
+     *             if {@code start < 0} or {@code start >= size()}.
      */
     protected void removeRange(int start, int end) {
         Iterator<?> it = listIterator(start);
@@ -678,72 +664,70 @@
     }
 
     /**
-     * Replaces the element at the specified location in this List with the
+     * Replaces the element at the specified location in this list with the
      * specified object.
      * 
-     * 
      * @param location
-     *            the index at which to put the specified object
+     *            the index at which to put the specified object.
      * @param object
-     *            the object to add
-     * @return the previous element at the index
-     * 
-     * @exception UnsupportedOperationException
-     *                when replacing elements in this List is not supported
-     * @exception ClassCastException
-     *                when the class of an object is inappropriate for this List
-     * @exception IllegalArgumentException
-     *                when an object cannot be added to this List
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     *            the object to add.
+     * @return the previous element at the index.
+     * @throws UnsupportedOperationException
+     *             if replacing elements in this list is not supported.
+     * @throws ClassCastException
+     *             if the class of an object is inappropriate for this list.
+     * @throws IllegalArgumentException
+     *             if an object cannot be added to this list.
+     * @throws IndexOutOfBoundsException
+     *             if {@code location < 0 || >= size()}
      */
     public E set(int location, E object) {
         throw new UnsupportedOperationException();
     }
 
     /**
-     * Returns a part of consecutive elements of this list as a view. From start
-     * (inclusive), to end(exclusive). The returned view will be of zero length
-     * if start equals end. Any change occurs in the returned subList will be
-     * reflected to the original list, and vice-versa. All the supported
-     * optional operations by the original list will also be supported by this
-     * subList.
-     * 
+     * Returns a part of consecutive elements of this list as a view. The
+     * returned view will be of zero length if start equals end. Any change that
+     * occurs in the returned subList will be reflected to the original list,
+     * and vice-versa. All the supported optional operations by the original
+     * list will also be supported by this subList.
+     * <p>
      * This method can be used as a handy method to do some operations on a sub
-     * range of the original list. For example: list.subList(from, to).clear();
-     * 
-     * If the original list is modified other than through the returned subList,
-     * the behavior of the returned subList becomes undefined.
-     * 
+     * range of the original list, for example
+     * {@code list.subList(from, to).clear();}
+     * <p>
+     * If the original list is modified in other ways than through the returned
+     * subList, the behavior of the returned subList becomes undefined.
+     * <p>
      * The returned subList is a subclass of AbstractList. The subclass stores
      * offset, size of itself, and modCount of the original list. If the
      * original list implements RandomAccess interface, the returned subList
      * also implements RandomAccess interface.
-     * 
+     * <p>
      * The subList's set(int, Object), get(int), add(int, Object), remove(int),
      * addAll(int, Collection) and removeRange(int, int) methods first check the
      * bounds, adjust offsets and then call the corresponding methods of the
      * original AbstractList. addAll(Collection c) method of the returned
      * subList calls the original addAll(offset + size, c).
-     * 
+     * <p>
      * The listIterator(int) method of the subList wraps the original list
      * iterator. The iterator() method of the subList invokes the original
      * listIterator() method, and the size() method merely returns the size of
      * the subList.
-     * 
+     * <p>
      * All methods will throw a ConcurrentModificationException if the modCount
      * of the original list is not equal to the expected value.
      * 
      * @param start
-     *            start index of the subList, include start
+     *            start index of the subList (inclusive).
      * @param end
-     *            end index of the subList, exclude end
-     * @return a subList view of this list start from start (inclusive), end
-     *         with end (exclusive)
-     * @exception IndexOutOfBoundsException
-     *                when (start < 0 || end > size())
-     * @exception IllegalArgumentException
-     *                when (start > end)
+     *            end index of the subList, (exclusive).
+     * @return a subList view of this list starting from {@code start}
+     *         (inclusive), and ending with {@code end} (exclusive)
+     * @throws IndexOutOfBoundsException
+     *             if (start < 0 || end > size())
+     * @throws IllegalArgumentException
+     *             if (start > end)
      */
     public List<E> subList(int start, int end) {
         if (0 <= start && end <= size()) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractMap.java Thu May  7 21:43:41 2009
@@ -18,7 +18,7 @@
 package java.util;
 
 /**
- * AbstractMap is an abstract implementation of the Map interface. This
+ * This class is an abstract implementation of the {@code Map} interface. This
  * implementation does not support adding. A subclass must implement the
  * abstract method entrySet().
  * 
@@ -32,31 +32,31 @@
     Collection<V> valuesCollection;
 
     /**
-     * Constructs a new instance of this AbstractMap.
+     * Constructs a new instance of this {@code AbstractMap}.
      */
     protected AbstractMap() {
         super();
     }
 
     /**
-     * Removes all elements from this Map, leaving it empty.
+     * Removes all elements from this map, leaving it empty.
      * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Map is not supported
-     * 
-     * @see #isEmpty
-     * @see #size
+     * @throws UnsupportedOperationException
+     *                if removing from this map is not supported.
+     * @see #isEmpty()
+     * @see #size()
      */
     public void clear() {
         entrySet().clear();
     }
 
     /**
-     * Searches this Map for the specified key.
+     * Returns whether this map contains the specified key.
      * 
      * @param key
-     *            the object to search for
-     * @return true if <code>key</code> is a key of this Map, false otherwise
+     *            the key to search for.
+     * @return {@code true} if this map contains the specified key,
+     *         {@code false} otherwise.
      */
     public boolean containsKey(Object key) {
         Iterator<Map.Entry<K, V>> it = entrySet().iterator();
@@ -77,12 +77,12 @@
     }
 
     /**
-     * Searches this Map for the specified value.
+     * Returns whether this map contains the specified value.
      * 
      * @param value
-     *            the object to search for
-     * @return true if <code>value</code> is a value of this Map, false
-     *         otherwise
+     *            the value to search for.
+     * @return {@code true} if this map contains the specified value,
+     *         {@code false} otherwise.
      */
     public boolean containsValue(Object value) {
         Iterator<Map.Entry<K, V>> it = entrySet().iterator();
@@ -103,27 +103,24 @@
     }
 
     /**
-     * Returns a Set of <code>Map.Entry</code>s that represent the entries in
-     * this Map. Making changes to this Set will change the original Map and
-     * vice-versa. Entries can be removed from the Set, or their values can be
-     * changed, but new entries cannot be added to the Set.
+     * Returns a set containing all of the mappings in this map. Each mapping is
+     * an instance of {@link Map.Entry}. As the set is backed by this map,
+     * changes in one will be reflected in the other.
      * 
-     * @return a Set of <code>Map.Entry</code>s representing the entries in
-     *         this Map
+     * @return a set of the mappings.
      */
     public abstract Set<Map.Entry<K, V>> entrySet();
 
     /**
-     * Compares the specified object to this Map and answer if they are equal.
-     * The object must be an instance of Map and contain the same key/value
-     * pairs.
+     * Compares the specified object to this instance, and returns {@code true}
+     * if the specified object is a map and both maps contain the same mappings.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this Map, false
-     *         otherwise
-     * 
-     * @see #hashCode
+     *            the object to compare with this object.
+     * @return boolean {@code true} if the object is the same as this object,
+     *         and {@code false} if it is different from this object.
+     * @see #hashCode()
+     * @see #entrySet()
      */
     @Override
     public boolean equals(Object object) {
@@ -157,11 +154,12 @@
     }
 
     /**
-     * Answers the value of the mapping with the specified key.
+     * Returns the value of the mapping with the specified key.
      * 
      * @param key
-     *            the key
-     * @return the value of the mapping with the specified key
+     *            the key.
+     * @return the value of the mapping with the specified key, or {@code null}
+     *         if no mapping for the specified key is found.
      */
     public V get(Object key) {
         Iterator<Map.Entry<K, V>> it = entrySet().iterator();
@@ -184,12 +182,11 @@
     }
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
+     * Returns the hash code for this object. Objects which are equal must
+     * return the same value for this method.
      * 
-     * @see #equals
+     * @return the hash code of this object.
+     * @see #equals(Object)
      */
     @Override
     public int hashCode() {
@@ -202,22 +199,22 @@
     }
 
     /**
-     * Answers if this Map has no elements, a size of zero.
+     * Returns whether this map is empty.
      * 
-     * @return true if this Map has no elements, false otherwise
-     * 
-     * @see #size
+     * @return {@code true} if this map has no elements, {@code false}
+     *         otherwise.
+     * @see #size()
      */
     public boolean isEmpty() {
         return size() == 0;
     }
 
     /**
-     * Answers a Set of the keys contained in this Map. The set is backed by
-     * this Map so changes to one are reflected by the other. The set does not
-     * support adding.
+     * Returns a set of the keys contained in this map. The set is backed by
+     * this map so changes to one are reflected by the other. The returned set
+     * does not support adding.
      * 
-     * @return a Set of the keys
+     * @return a set of the keys.
      */
     public Set<K> keySet() {
         if (keySet == null) {
@@ -260,43 +257,41 @@
      * Maps the specified key to the specified value.
      * 
      * @param key
-     *            the key
+     *            the key.
      * @param value
-     *            the value
-     * @return the value of any previous mapping with the specified key or null
-     *         if there was no mapping
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding to this Map is not supported
-     * @exception ClassCastException
-     *                when the class of the key or value is inappropriate for
-     *                this Map
-     * @exception IllegalArgumentException
-     *                when the key or value cannot be added to this Map
-     * @exception NullPointerException
-     *                when the key or value is null and this Map does not
-     *                support null keys or values
+     *            the value.
+     * @return the value of any previous mapping with the specified key or
+     *         {@code null} if there was no mapping.
+     * @throws UnsupportedOperationException
+     *                if adding to this map is not supported.
+     * @throws ClassCastException
+     *                if the class of the key or value is inappropriate for this
+     *                map.
+     * @throws IllegalArgumentException
+     *                if the key or value cannot be added to this map.
+     * @throws NullPointerException
+     *                if the key or value is {@code null} and this Map does not
+     *                support {@code null} keys or values.
      */
     public V put(K key, V value) {
         throw new UnsupportedOperationException();
     }
 
     /**
-     * Copies every mapping in the specified Map to this Map.
+     * Copies every mapping in the specified map to this map.
      * 
      * @param map
-     *            the Map to copy mappings from
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding to this Map is not supported
-     * @exception ClassCastException
-     *                when the class of a key or value is inappropriate for this
-     *                Map
-     * @exception IllegalArgumentException
-     *                when a key or value cannot be added to this Map
-     * @exception NullPointerException
-     *                when a key or value is null and this Map does not support
-     *                null keys or values
+     *            the map to copy mappings from.
+     * @throws UnsupportedOperationException
+     *                if adding to this map is not supported.
+     * @throws ClassCastException
+     *                if the class of a key or value is inappropriate for this
+     *                map.
+     * @throws IllegalArgumentException
+     *                if a key or value cannot be added to this map.
+     * @throws NullPointerException
+     *                if a key or value is {@code null} and this map does not
+     *                support {@code null} keys or values.
      */
     public void putAll(Map<? extends K, ? extends V> map) {
         for (Map.Entry<? extends K, ? extends V> entry : map.entrySet()) {
@@ -308,12 +303,11 @@
      * Removes a mapping with the specified key from this Map.
      * 
      * @param key
-     *            the key of the mapping to remove
-     * @return the value of the removed mapping or null if key is not a key in
-     *         this Map
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Map is not supported
+     *            the key of the mapping to remove.
+     * @return the value of the removed mapping or {@code null} if no mapping
+     *         for the specified key was found.
+     * @throws UnsupportedOperationException
+     *                if removing from this map is not supported.
      */
     public V remove(Object key) {
         Iterator<Map.Entry<K, V>> it = entrySet().iterator();
@@ -338,18 +332,18 @@
     }
 
     /**
-     * Answers the number of elements in this Map.
+     * Returns the number of elements in this map.
      * 
-     * @return the number of elements in this Map
+     * @return the number of elements in this map.
      */
     public int size() {
         return entrySet().size();
     }
 
     /**
-     * Answers the string representation of this Map.
+     * Returns the string representation of this map.
      * 
-     * @return the string representation of this Map
+     * @return the string representation of this map.
      */
     @Override
     public String toString() {
@@ -384,24 +378,23 @@
     }
 
     /**
-     * Answers a collection of the values contained in this map. The collection
+     * Returns a collection of the values contained in this map. The collection
      * is backed by this map so changes to one are reflected by the other. The
      * collection supports remove, removeAll, retainAll and clear operations,
      * and it does not support add or addAll operations.
-     * 
-     * This method answers a collection which is the subclass of
-     * AbstractCollection. The iterator method of this subclass answers a
-     * "wrapper object" over the iterator of map's entrySet(). The size method
-     * wraps the map's size method and the contains method wraps the map's
-     * containsValue method.
-     * 
-     * The collection is created when this method is called at first time and
-     * returned in response to all subsequent calls. This method may return
-     * different Collection when multiple calls to this method, since it has no
-     * synchronization performed.
-     * 
-     * @return a collection of the values contained in this map
-     * 
+     * <p>
+     * This method returns a collection which is the subclass of
+     * AbstractCollection. The iterator method of this subclass returns a
+     * "wrapper object" over the iterator of map's entrySet(). The {@code size}
+     * method wraps the map's size method and the {@code contains} method wraps
+     * the map's containsValue method.
+     * <p>
+     * The collection is created when this method is called for the first time
+     * and returned in response to all subsequent calls. This method may return
+     * different collections when multiple concurrent calls occur to this
+     * method, since no synchronization is performed.
+     *
+     * @return a collection of the values contained in this map.
      */
     public Collection<V> values() {
         if (valuesCollection == null) {
@@ -441,13 +434,13 @@
     }
 
     /**
-     * Answers a new instance of the same class as the receiver, whose slots
-     * have been filled in with the values in the slots of the receiver.
+     * Returns a new instance of the same class as this instance, whose slots
+     * have been filled in with the values of the slots of this instance.
      * 
-     * @return Object a shallow copy of this object.
-     * @exception CloneNotSupportedException
+     * @return a shallow copy of this object.
+     * @throws CloneNotSupportedException
      *                if the receiver's class does not implement the interface
-     *                Cloneable.
+     *                {@code Cloneable}.
      */
     @Override
     @SuppressWarnings("unchecked")

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractQueue.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractQueue.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractQueue.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractQueue.java Thu May  7 21:43:41 2009
@@ -17,12 +17,12 @@
 package java.util;
 
 /**
- * 
- * An abstract class which gives out skeletal implementations for some methods
- * in Queue which include add, remove, and element that are based on offer,
- * poll, and peek except that they throw exception to indicate the occurrence of
- * some error instead of the return value of false or null.
- * 
+ * AbstractQueue is an abstract class which implements some of the methods in
+ * {@link Queue}. The provided implementations of {@code add, remove} and
+ * {@code element} are based on {@code offer, poll}, and {@code peek} except
+ * that they throw exceptions to indicate some error instead of returning true
+ * or false.
+ *
  * @param <E>
  *            the type of the element in the collection.
  */
@@ -30,8 +30,7 @@
         Queue<E> {
 
     /**
-     * Constructor for the sub classes.
-     * 
+     * Constructor to be used by subclasses.
      */
     protected AbstractQueue() {
         super();
@@ -40,11 +39,11 @@
     /**
      * Adds an element to the queue.
      * 
-     * @param o the element added to the queue.
-     * @return true if the operation succeeds.
-     * @throws NullPointerException if the element is null.
-     * @throws IllegalStateException if the element is not allowed to be added
-     *         to the queue.
+     * @param o
+     *            the element to be added to the queue.
+     * @return {@code true} if the operation succeeds, otherwise {@code false}.
+     * @throws IllegalStateException
+     *             if the element is not allowed to be added to the queue.
      */
     @Override
     public boolean add(E o) {
@@ -59,20 +58,20 @@
 
     /**
      * Adds all the elements of a collection to the queue. If the collection is
-     * the queue itself, then an IllegalArgumentException will be thrown out. If
-     * during the process, some runtime exception is thrown out, then part of
-     * the elements in the collection that have successfully added will remain
-     * in the queue.
-     * 
-     * The result of the method is undefined if the collection is modified
-     * during the process of the method.
-     * 
-     * @param c the collection to be added to the queue.
-     * @return true if the operation succeeds.
-     * @throws NullPointerException if the collection or any element of it is
-     *         null.
-     * @throws IllegalArgumentException If the collection to be added to the
-     *         queue is the queue itself.
+     * the queue itself, then an IllegalArgumentException will be thrown. If
+     * during the process, some runtime exception is thrown, then those elements
+     * in the collection which have already successfully been added will remain
+     * in the queue. The result of the method is undefined if the collection is
+     * modified during the process of the method.
+     * 
+     * @param c
+     *            the collection to be added to the queue.
+     * @return {@code true} if the operation succeeds, otherwise {@code false}.
+     * @throws NullPointerException
+     *             if the collection or any element of it is null.
+     * @throws IllegalArgumentException
+     *             If the collection to be added to the queue is the queue
+     *             itself.
      */
     @Override
     public boolean addAll(Collection<? extends E> c) {
@@ -86,10 +85,11 @@
     }
 
     /**
-     * Gets and removes the element in the head of the queue.
+     * Removes the element at the head of the queue and returns it.
      * 
-     * @return the element in the head of the queue.
-     * @throws NoSuchElementException if the queue is empty.
+     * @return the element at the head of the queue.
+     * @throws NoSuchElementException
+     *             if the queue is empty.
      */
     public E remove() {
         E o = poll();
@@ -100,10 +100,11 @@
     }
 
     /**
-     * Gets but not removes the element in the head of the queue.
+     * Returns but does not remove the element at the head of the queue.
      * 
-     * @return the element in the head of the queue.
-     * @throws NoSuchElementException if the queue is empty.
+     * @return the element at the head of the queue.
+     * @throws NoSuchElementException
+     *             if the queue is empty.
      */
     public E element() {
         E o = peek();
@@ -114,7 +115,7 @@
     }
 
     /**
-     * Removes all elements of the queue.
+     * Removes all elements of the queue, leaving it empty.
      */
     @Override
     public void clear() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSequentialList.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSequentialList.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSequentialList.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSequentialList.java Thu May  7 21:43:41 2009
@@ -33,55 +33,11 @@
         super();
     }
 
-    /**
-     * Inserts the specified object into this List at the specified location.
-     * The object is inserted before any previous element at the specified
-     * location. If the location is equal to the size of this List, the object
-     * is added at the end.
-     * 
-     * @param location
-     *            the index at which to insert
-     * @param object
-     *            the object to add
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding to this List is not supported
-     * @exception ClassCastException
-     *                when the class of the object is inappropriate for this
-     *                List
-     * @exception IllegalArgumentException
-     *                when the object cannot be added to this List
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
-     * @exception NullPointerException
-     *                when the object is null and this List does not support
-     *                null elements
-     */
     @Override
     public void add(int location, E object) {
         listIterator(location).add(object);
     }
 
-    /**
-     * Inserts the objects in the specified Collection at the specified location
-     * in this List. The objects are added in the order they are returned from
-     * the Collection iterator.
-     * 
-     * @param location
-     *            the index at which to insert
-     * @param collection
-     *            the Collection of objects
-     * @return true if this List is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding to this List is not supported
-     * @exception ClassCastException
-     *                when the class of an object is inappropriate for this List
-     * @exception IllegalArgumentException
-     *                when an object cannot be added to this List
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
-     */
     @Override
     public boolean addAll(int location, Collection<? extends E> collection) {
         ListIterator<E> it = listIterator(location);
@@ -93,16 +49,6 @@
         return next != it.nextIndex();
     }
 
-    /**
-     * Answers the element at the specified location in this List.
-     * 
-     * @param location
-     *            the index of the element to return
-     * @return the element at the specified location
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
-     */
     @Override
     public E get(int location) {
         try {
@@ -112,48 +58,14 @@
         }
     }
 
-    /**
-     * Answers an Iterator on the elements of this List. The elements are
-     * iterated in the same order that they occur in the List.
-     * 
-     * @return an Iterator on the elements of this List
-     * 
-     * @see Iterator
-     */
     @Override
     public Iterator<E> iterator() {
         return listIterator(0);
     }
 
-    /**
-     * Answers a ListIterator on the elements of this List. The elements are
-     * iterated in the same order that they occur in the List. The iteration
-     * starts at the specified location.
-     * 
-     * @param location
-     *            the index at which to start the iteration
-     * @return a ListIterator on the elements of this List
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
-     * 
-     * @see ListIterator
-     */
     @Override
     public abstract ListIterator<E> listIterator(int location);
 
-    /**
-     * Removes the object at the specified location from this List.
-     * 
-     * @param location
-     *            the index of the object to remove
-     * @return the removed object
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this List is not supported
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
-     */
     @Override
     public E remove(int location) {
         try {
@@ -166,25 +78,6 @@
         }
     }
 
-    /**
-     * Replaces the element at the specified location in this List with the
-     * specified object.
-     * 
-     * @param location
-     *            the index at which to put the specified object
-     * @param object
-     *            the object to add
-     * @return the previous element at the index
-     * 
-     * @exception UnsupportedOperationException
-     *                when replacing elements in this List is not supported
-     * @exception ClassCastException
-     *                when the class of an object is inappropriate for this List
-     * @exception IllegalArgumentException
-     *                when an object cannot be added to this List
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
-     */
     @Override
     public E set(int location, E object) {
         ListIterator<E> it = listIterator(location);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSet.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/AbstractSet.java Thu May  7 21:43:41 2009
@@ -18,8 +18,8 @@
 package java.util;
 
 /**
- * AbstractSet is an abstract implementation of the Set interface. This
- * Implementation does not support adding. A subclass must implement the
+ * An AbstractSet is an abstract implementation of the Set interface. This
+ * implementation does not support adding. A subclass must implement the
  * abstract methods iterator() and size().
  * 
  * @since 1.2
@@ -35,14 +35,14 @@
     }
 
     /**
-     * Compares the specified object to this Set and answer if they are equal.
-     * The object must be an instance of Set and contain the same objects.
+     * Compares the specified object to this Set and returns true if they are
+     * equal. The object must be an instance of Set and contain the same
+     * objects.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this Set, false
-     *         otherwise
-     * 
+     *            the object to compare with this set.
+     * @return {@code true} if the specified object is equal to this set,
+     *         {@code false} otherwise
      * @see #hashCode
      */
     @Override
@@ -63,11 +63,11 @@
     }
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
+     * Returns the hash code for this set. Two set which are equal must return
+     * the same value. This implementation calculates the hash code by adding
+     * each element's hash code.
      * 
+     * @return the hash code of this set.
      * @see #equals
      */
     @Override
@@ -82,15 +82,15 @@
     }
 
     /**
-     * Removes all occurrences in this Collection of each object in the
-     * specified Collection.
+     * Removes all occurrences in this collection which are contained in the
+     * specified collection.
      * 
      * @param collection
-     *            the Collection of objects to remove
-     * @return true if this Collection is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Collection is not supported
+     *            the collection of objects to remove.
+     * @return {@code true} if this collection was modified, {@code false}
+     *         otherwise.
+     * @throws UnsupportedOperationException
+     *                if removing from this collection is not supported.
      */
     @Override
     public boolean removeAll(Collection<?> collection) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ArrayList.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ArrayList.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ArrayList.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ArrayList.java Thu May  7 21:43:41 2009
@@ -25,9 +25,9 @@
 import java.lang.reflect.Array;
 
 /**
- * ArrayList is an implementation of List, backed by an array. All optional
- * operations are supported, adding, removing, and replacing. The elements can
- * be any objects.
+ * ArrayList is an implementation of {@link List}, backed by an array. All
+ * optional operations adding, removing, and replacing are supported. The
+ * elements can be any objects.
  * 
  * @since 1.2
  */
@@ -43,17 +43,18 @@
     private transient E[] array;
 
     /**
-     * Constructs a new instance of ArrayList with capacity for ten elements.
+     * Constructs a new instance of {@code ArrayList} with ten capacity.
      */
     public ArrayList() {
         this(10);
     }
 
     /**
-     * Constructs a new instance of ArrayList with the specified capacity.
+     * Constructs a new instance of {@code ArrayList} with the specified
+     * capacity.
      * 
      * @param capacity
-     *            the initial capacity of this ArrayList
+     *            the initial capacity of this {@code ArrayList}.
      */
     public ArrayList(int capacity) {
         if (capacity < 0) {
@@ -64,13 +65,12 @@
     }
 
     /**
-     * Constructs a new instance of ArrayList containing the elements in the
-     * specified collection. The ArrayList will have an initial capacity which
-     * is 110% of the size of the collection. The order of the elements in this
-     * ArrayList is the order they are returned by the collection iterator.
+     * Constructs a new instance of {@code ArrayList} containing the elements of
+     * the specified collection. The initial size of the {@code ArrayList} will
+     * be 10% higher than the size of the specified collection.
      * 
      * @param collection
-     *            the collection of elements to add
+     *            the collection of elements to add.
      */
     public ArrayList(Collection<? extends E> collection) {
         int size = collection.size();
@@ -87,18 +87,17 @@
     }
 
     /**
-     * Inserts the specified object into this ArrayList at the specified
+     * Inserts the specified object into this {@code ArrayList} at the specified
      * location. The object is inserted before any previous element at the
      * specified location. If the location is equal to the size of this
-     * ArrayList, the object is added at the end.
+     * {@code ArrayList}, the object is added at the end.
      * 
      * @param location
-     *            the index at which to insert
+     *            the index at which to insert the object.
      * @param object
-     *            the object to add
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     *            the object to add.
+     * @throws IndexOutOfBoundsException
+     *             when {@code location < 0 || > size()}
      */
     @Override
     public void add(int location, E object) {
@@ -135,11 +134,11 @@
     }
 
     /**
-     * Adds the specified object at the end of this ArrayList.
+     * Adds the specified object at the end of this {@code ArrayList}.
      * 
      * @param object
-     *            the object to add
-     * @return true
+     *            the object to add.
+     * @return always true
      */
     @Override
     public boolean add(E object) {
@@ -152,18 +151,18 @@
     }
 
     /**
-     * Inserts the objects in the specified Collection at the specified location
-     * in this ArrayList. The objects are added in the order they are returned
-     * from the Collection iterator.
+     * Inserts the objects in the specified collection at the specified location
+     * in this List. The objects are added in the order they are returned from
+     * the collection's iterator.
      * 
      * @param location
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param collection
-     *            the Collection of objects
-     * @return true if this ArrayList is modified, false otherwise
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || > size()</code>
+     *            the collection of objects.
+     * @return {@code true} if this {@code ArrayList} is modified, {@code false}
+     *         otherwise.
+     * @throws IndexOutOfBoundsException
+     *             when {@code location < 0 || > size()}
      */
     @Override
     public boolean addAll(int location, Collection<? extends E> collection) {
@@ -218,11 +217,12 @@
     }
 
     /**
-     * Adds the objects in the specified Collection to this ArrayList.
+     * Adds the objects in the specified collection to this {@code ArrayList}.
      * 
      * @param collection
-     *            the Collection of objects
-     * @return true if this ArrayList is modified, false otherwise
+     *            the collection of objects.
+     * @return {@code true} if this {@code ArrayList} is modified, {@code false}
+     *         otherwise.
      */
     @Override
     public boolean addAll(Collection<? extends E> collection) {
@@ -240,7 +240,7 @@
     }
 
     /**
-     * Removes all elements from this ArrayList, leaving it empty.
+     * Removes all elements from this {@code ArrayList}, leaving it empty.
      * 
      * @see #isEmpty
      * @see #size
@@ -255,11 +255,10 @@
     }
 
     /**
-     * Answers a new ArrayList with the same elements, size and capacity as this
-     * ArrayList.
-     * 
-     * @return a shallow copy of this ArrayList
+     * Returns a new {@code ArrayList} with the same elements, the same size and
+     * the same capacity as this {@code ArrayList}.
      * 
+     * @return a shallow copy of this {@code ArrayList}
      * @see java.lang.Cloneable
      */
     @Override
@@ -275,12 +274,12 @@
     }
 
     /**
-     * Searches this ArrayList for the specified object.
+     * Searches this {@code ArrayList} for the specified object.
      * 
      * @param object
-     *            the object to search for
-     * @return true if <code>object</code> is an element of this ArrayList,
-     *         false otherwise
+     *            the object to search for.
+     * @return {@code true} if {@code object} is an element of this
+     *         {@code ArrayList}, {@code false} otherwise
      */
     @Override
     public boolean contains(Object object) {
@@ -301,12 +300,11 @@
     }
 
     /**
-     * Ensures that this ArrayList can hold the specified number of elements
-     * without growing.
+     * Ensures that after this operation the {@code ArrayList} can hold the
+     * specified number of elements without further growing.
      * 
      * @param minimumCapacity
-     *            the minimum number of elements that this ArrayList will hold
-     *            before growing
+     *            the minimum capacity asked for.
      */
     public void ensureCapacity(int minimumCapacity) {
         if (array.length < minimumCapacity) {
@@ -318,16 +316,6 @@
         }
     }
 
-    /**
-     * Answers the element at the specified location in this ArrayList.
-     * 
-     * @param location
-     *            the index of the element to return
-     * @return the element at the specified index
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
-     */
     @Override
     public E get(int location) {
         if (0 <= location && location < (lastIndex - firstIndex)) {
@@ -419,14 +407,6 @@
         array = newArray;
     }
 
-    /**
-     * Searches this ArrayList for the specified object and returns the index of
-     * the first occurrence.
-     * 
-     * @param object
-     *            the object to search for
-     * @return the index of the first occurrence of the object
-     */
     @Override
     public int indexOf(Object object) {
         if (object != null) {
@@ -445,26 +425,11 @@
         return -1;
     }
 
-    /**
-     * Answers if this ArrayList has no elements, a size of zero.
-     * 
-     * @return true if this ArrayList has no elements, false otherwise
-     * 
-     * @see #size
-     */
     @Override
     public boolean isEmpty() {
         return lastIndex == firstIndex;
     }
 
-    /**
-     * Searches this ArrayList for the specified object and returns the index of
-     * the last occurrence.
-     * 
-     * @param object
-     *            the object to search for
-     * @return the index of the last occurrence of the object
-     */
     @Override
     public int lastIndexOf(Object object) {
         if (object != null) {
@@ -484,14 +449,13 @@
     }
 
     /**
-     * Removes the object at the specified location from this ArrayList.
+     * Removes the object at the specified location from this list.
      * 
      * @param location
-     *            the index of the object to remove
-     * @return the removed object
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     *            the index of the object to remove.
+     * @return the removed object.
+     * @throws IndexOutOfBoundsException
+     *             when {@code location < 0 || >= size()}
      */
     @Override
     public E remove(int location) {
@@ -528,14 +492,6 @@
         return result;
     }
 
-    /**
-     * Removes the first one of the specified object in this list, if present.
-     * 
-     * @param object
-     *            the object to removes
-     * @return true if the list contains the object
-     * @see java.util.AbstractCollection#remove(java.lang.Object)
-     */
     @Override
     public boolean remove(Object object) {
         int location = indexOf(object);
@@ -551,13 +507,11 @@
      * not including the end index.
      * 
      * @param start
-     *            the index at which to start removing
+     *            the index at which to start removing.
      * @param end
-     *            the index one past the end of the range to remove
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>start < 0, start > end</code> or
-     *                <code>end > size()</code>
+     *            the index one after the end of the range to remove.
+     * @throws IndexOutOfBoundsException
+     *             when {@code start < 0, start > end} or {@code end > size()}
      */
     @Override
     protected void removeRange(int start, int end) {
@@ -586,17 +540,16 @@
     }
 
     /**
-     * Replaces the element at the specified location in this ArrayList with the
-     * specified object.
+     * Replaces the element at the specified location in this {@code ArrayList}
+     * with the specified object.
      * 
      * @param location
-     *            the index at which to put the specified object
+     *            the index at which to put the specified object.
      * @param object
-     *            the object to add
-     * @return the previous element at the index
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     *            the object to add.
+     * @return the previous element at the index.
+     * @throws IndexOutOfBoundsException
+     *             when {@code location < 0 || >= size()}
      */
     @Override
     public E set(int location, E object) {
@@ -609,9 +562,9 @@
     }
 
     /**
-     * Answers the number of elements in this ArrayList.
+     * Returns the number of elements in this {@code ArrayList}.
      * 
-     * @return the number of elements in this ArrayList
+     * @return the number of elements in this {@code ArrayList}.
      */
     @Override
     public int size() {
@@ -619,9 +572,10 @@
     }
 
     /**
-     * Answers a new array containing all elements contained in this ArrayList.
+     * Returns a new array containing all elements contained in this
+     * {@code ArrayList}.
      * 
-     * @return an array of the elements from this ArrayList
+     * @return an array of the elements from this {@code ArrayList}
      */
     @Override
     public Object[] toArray() {
@@ -632,19 +586,19 @@
     }
 
     /**
-     * Answers an array containing all elements contained in this ArrayList. If
-     * the specified array is large enough to hold the elements, the specified
-     * array is used, otherwise an array of the same type is created. If the
-     * specified array is used and is larger than this ArrayList, the array
-     * element following the collection elements is set to null.
+     * Returns an array containing all elements contained in this
+     * {@code ArrayList}. If the specified array is large enough to hold the
+     * elements, the specified array is used, otherwise an array of the same
+     * type is created. If the specified array is used and is larger than this
+     * {@code ArrayList}, the array element following the collection elements
+     * is set to null.
      * 
      * @param contents
-     *            the array
-     * @return an array of the elements from this ArrayList
-     * 
-     * @exception ArrayStoreException
-     *                when the type of an element in this ArrayList cannot be
-     *                stored in the type of the specified array
+     *            the array.
+     * @return an array of the elements from this {@code ArrayList}.
+     * @throws ArrayStoreException
+     *             when the type of an element in this {@code ArrayList} cannot
+     *             be stored in the type of the specified array.
      */
     @Override
     @SuppressWarnings("unchecked")
@@ -662,7 +616,8 @@
     }
 
     /**
-     * Sets the capacity of this ArrayList to be the same as the size.
+     * Sets the capacity of this {@code ArrayList} to be the same as the current
+     * size.
      * 
      * @see #size
      */



Mime
View raw message