harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772785 [7/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/LinkedHashMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashMap.java Thu May  7 21:43:41 2009
@@ -18,18 +18,34 @@
 package java.util;
 
 /**
- * LinkedHashMap is a variant on HashMap. Its entries are kept in a
+ * LinkedHashMap is a variant of HashMap. Its entries are kept in a
  * doubly-linked list. The iteration order is, by default, the order in which
- * keys were inserted.
+ * keys were inserted. Reinserting an already existing key doesn't change the
+ * order. A key is existing if a call to {@code containsKey} would return true.
  * <p>
- * If the three argument constructor is used, and <code>order</code> is
- * specified as <code>true</code>, the iteration would be in the order that
- * entries were accessed. The access order gets affected by put(), get(),
- * putAll() operations, but not by operations on the collection views.
+ * If the three argument constructor is used, and {@code order} is specified as
+ * {@code true}, the iteration will be in the order that entries were accessed.
+ * The access order gets affected by put(), get(), putAll() operations, but not
+ * by operations on the collection views.
  * <p>
- * Null elements are allowed, and all the optional Map operations are supported.
+ * Null elements are allowed, and all the optional map operations are supported.
  * <p>
- * 
+ * <b>Note:</b> The implementation of {@code LinkedHashMap} is not synchronized.
+ * If one thread of several threads accessing an instance modifies the map
+ * structurally, access to the map needs to be synchronized. For
+ * insertion-ordered instances a structural modification is an operation that
+ * removes or adds an entry. Access-ordered instances also are structurally
+ * modified by put(), get() and putAll() since these methods change the order of
+ * the entries. Changes in the value of an entry are not structural changes.
+ * <p>
+ * The Iterator that can be created by calling the {@code iterator} method
+ * throws a {@code ConcurrentModificationException} if the map is structurally
+ * changed while an iterator is used to iterate over the elements. Only the
+ * {@code remove} method that is provided by the iterator allows for removal of
+ * elements during iteration. It is not possible to guarantee that this
+ * mechanism works in all cases of unsynchronized concurrent modification. It
+ * should only be used for debugging purposes.
+ *
  * @since 1.4
  */
 public class LinkedHashMap<K, V> extends HashMap<K, V> {
@@ -41,7 +57,7 @@
     transient private LinkedHashMapEntry<K, V> head, tail;
 
     /**
-     * Constructs a new empty instance of LinkedHashMap.
+     * Constructs a new empty {@code LinkedHashMap} instance.
      */
     public LinkedHashMap() {
         super();
@@ -50,10 +66,13 @@
     }
 
     /**
-     * Constructor with specified size.
+     * Constructs a new {@code LinkedHashMap} instance with the specified
+     * capacity.
      * 
      * @param s
-     *            Size of LinkedHashMap required
+     *            the initial capacity of this map.
+     * @throws IllegalArgumentException
+     *                if the capacity is less than zero.
      */
     public LinkedHashMap(int s) {
         super(s);
@@ -62,12 +81,16 @@
     }
 
     /**
-     * Constructor with specified size and load factor.
+     * Constructs a new {@code LinkedHashMap} instance with the specified
+     * capacity and load factor.
      * 
      * @param s
-     *            Size of LinkedHashMap required
+     *            the initial capacity of this map.
      * @param lf
-     *            Load factor
+     *            the initial load factor.
+     * @throws IllegalArgumentException
+     *             when the capacity is less than zero or the load factor is
+     *             less or equal to zero.
      */
     public LinkedHashMap(int s, float lf) {
         super(s, lf);
@@ -77,15 +100,21 @@
     }
 
     /**
-     * Constructor with specified size, load factor and access order
+     * Constructs a new {@code LinkedHashMap} instance with the specified
+     * capacity, load factor and a flag specifying the ordering behavior.
      * 
      * @param s
-     *            Size of LinkedHashmap required
+     *            the initial capacity of this hash map.
      * @param lf
-     *            Load factor
+     *            the initial load factor.
      * @param order
-     *            If true indicates that traversal order should begin with most
-     *            recently accessed
+     *            {@code true} if the ordering should be done based on the last
+     *            access (from least-recently accessed to most-recently
+     *            accessed), and {@code false} if the ordering should be the
+     *            order in which the entries were inserted.
+     * @throws IllegalArgumentException
+     *             when the capacity is less than zero or the load factor is
+     *             less or equal to zero.
      */
     public LinkedHashMap(int s, float lf, boolean order) {
         super(s, lf);
@@ -95,10 +124,11 @@
     }
 
     /**
-     * Constructor with input map
+     * Constructs a new {@code LinkedHashMap} instance containing the mappings
+     * from the specified map. The order of the elements is preserved.
      * 
      * @param m
-     *            Input map
+     *            the mappings to add.
      */
     public LinkedHashMap(Map<? extends K, ? extends V> m) {
         accessOrder = false;
@@ -246,14 +276,6 @@
         }
     }
 
-    /**
-     * Searches this map for the specified value.
-     * 
-     * @param value
-     *            the object to search for
-     * @return true if <code>value</code> is a value of this HashMap, false
-     *         otherwise
-     */
     @Override
     public boolean containsValue(Object value) {
         LinkedHashMapEntry<K, V> entry = head;
@@ -288,11 +310,12 @@
     }
 
     /**
-     * Retrieve the map value corresponding to the given key.
+     * Returns the value of the mapping with the specified key.
      * 
      * @param key
-     *            Key value
-     * @return mapped value or null if the key is not in the map
+     *            the key.
+     * @return the value of the mapping with the specified key, or {@code null}
+     *         if no mapping for the specified key is found.
      */
     @Override
     public V get(Object key) {
@@ -345,14 +368,14 @@
     }
 
     /**
-     * Set the mapped value for the given key to the given value.
+     * Maps the specified key to the specified value.
      * 
      * @param key
-     *            Key value
+     *            the key.
      * @param value
-     *            New mapped value
-     * @return The old value if the key was already in the map or null
-     *         otherwise.
+     *            the value.
+     * @return the value of any previous mapping with the specified key or
+     *         {@code null} if there was no such mapping.
      */
     @Override
     public V put(K key, V value) {
@@ -462,11 +485,11 @@
     }
 
     /**
-     * Answers a Set of the mappings contained in this HashMap. Each element in
-     * the set is a Map.Entry. The set is backed by this HashMap so changes to
-     * one are reflected by the other. The set does not support adding.
+     * 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 the mappings
+     * @return a set of the mappings.
      */
     @Override
     public Set<Map.Entry<K, V>> entrySet() {
@@ -474,11 +497,11 @@
     }
 
     /**
-     * Answers a Set of the keys contained in this HashMap. The set is backed by
-     * this HashMap 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 set does not
+     * support adding.
      * 
-     * @return a Set of the keys
+     * @return a set of the keys.
      */
     @Override
     public Set<K> keySet() {
@@ -518,11 +541,23 @@
     }
 
     /**
-     * Answers a Collection of the values contained in this HashMap. The
-     * collection is backed by this HashMap so changes to one are reflected by
-     * the other. The collection does not support adding.
-     * 
-     * @return a Collection of the values
+     * 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.
+     * <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 size method
+     * wraps the map's size method and the 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, since no
+     * synchronization is performed.
+     *
+     * @return a collection of the values contained in this map.
      */
     @Override
     public Collection<V> values() {
@@ -553,12 +588,12 @@
     }
 
     /**
-     * Remove the entry corresponding to the given key.
+     * Removes the mapping with the specified key from this map.
      * 
      * @param key
-     *            the key
-     * @return the value associated with the key or null if the key was no in
-     *         the map
+     *            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.
      */
     @Override
     public V remove(Object key) {
@@ -585,17 +620,18 @@
      * This method is queried from the put and putAll methods to check if the
      * eldest member of the map should be deleted before adding the new member.
      * If this map was created with accessOrder = true, then the result of
-     * removeEldesrEntry is assumed to be false.
+     * removeEldestEntry is assumed to be false.
      * 
      * @param eldest
-     * @return true if the eldest member should be removed
+     *            the entry to check if it should be removed.
+     * @return {@code true} if the eldest member should be removed.
      */
     protected boolean removeEldestEntry(Map.Entry<K, V> eldest) {
         return false;
     }
 
     /**
-     * Removes all mappings from this HashMap, leaving it empty.
+     * Removes all elements from this map, leaving it empty.
      * 
      * @see #isEmpty()
      * @see #size()

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashSet.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashSet.java Thu May  7 21:43:41 2009
@@ -20,7 +20,7 @@
 import java.io.Serializable;
 
 /**
- * LinkedHashSet is a variant on HashSet. Its entries are kept in a
+ * LinkedHashSet is a variant of HashSet. Its entries are kept in a
  * doubly-linked list. The iteration order is the order in which entries were
  * inserted.
  * <p>
@@ -28,8 +28,8 @@
  * <p>
  * Like HashSet, LinkedHashSet is not thread safe, so access by multiple threads
  * must be synchronized by an external mechanism such as
- * Collections.synchronizedSet.
- * 
+ * {@link Collections#synchronizedSet(Set)}.
+ *
  * @since 1.4
  */
 public class LinkedHashSet<E> extends HashSet<E> implements Set<E>, Cloneable,
@@ -38,41 +38,42 @@
     private static final long serialVersionUID = -2851667679971038690L;
 
     /**
-     * Constructs a new empty instance of LinkedHashSet.
+     * Constructs a new empty instance of {@code LinkedHashSet}.
      */
     public LinkedHashSet() {
         super(new LinkedHashMap<E, HashSet<E>>());
     }
 
     /**
-     * Constructs a new instance of LinkedHashSet with the specified capacity.
+     * Constructs a new instance of {@code LinkedHashSet} with the specified
+     * capacity.
      * 
      * @param capacity
-     *            the initial capacity of this HashSet
+     *            the initial capacity of this {@code LinkedHashSet}.
      */
     public LinkedHashSet(int capacity) {
         super(new LinkedHashMap<E, HashSet<E>>(capacity));
     }
 
     /**
-     * Constructs a new instance of LinkedHashSet with the specified capacity
-     * and load factor.
+     * Constructs a new instance of {@code LinkedHashSet} with the specified
+     * capacity and load factor.
      * 
      * @param capacity
-     *            the initial capacity
+     *            the initial capacity.
      * @param loadFactor
-     *            the initial load factor
+     *            the initial load factor.
      */
     public LinkedHashSet(int capacity, float loadFactor) {
         super(new LinkedHashMap<E, HashSet<E>>(capacity, loadFactor));
     }
 
     /**
-     * Constructs a new instance of LinkedHashSet containing the unique elements
-     * in the specified collection.
+     * Constructs a new instance of {@code LinkedHashSet} containing the unique
+     * elements in the specified collection.
      * 
      * @param collection
-     *            the collection of elements to add
+     *            the collection of elements to add.
      */
     public LinkedHashSet(Collection<? extends E> collection) {
         super(new LinkedHashMap<E, HashSet<E>>(collection.size() < 6 ? 11

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedList.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedList.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedList.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedList.java Thu May  7 21:43:41 2009
@@ -25,7 +25,7 @@
 
 /**
  * LinkedList is an implementation of List, backed by a linked list. All
- * optional operations are supported, adding, removing and replacing. The
+ * optional operations (adding, removing and replacing) are supported. The
  * elements can be any objects.
  * 
  * @since 1.2
@@ -176,8 +176,7 @@
     }
 
     /**
-     * Constructs a new empty instance of LinkedList.
-     * 
+     * Constructs a new empty instance of {@code LinkedList}.
      */
     public LinkedList() {
         voidLink = new Link<E>(null, null, null);
@@ -186,13 +185,13 @@
     }
 
     /**
-     * Constructs a new instance of <code>LinkedList</code> that holds all of
-     * the elements contained in the supplied <code>collection</code>
-     * argument. The order of the elements in this new <code>LinkedList</code>
-     * will be determined by the iteration order of <code>collection</code>.
+     * Constructs a new instance of {@code LinkedList} that holds all of the
+     * elements contained in the specified {@code collection}. The order of the
+     * elements in this new {@code LinkedList} will be determined by the
+     * iteration order of {@code collection}.
      * 
      * @param collection
-     *            the collection of elements to add
+     *            the collection of elements to add.
      */
     public LinkedList(Collection<? extends E> collection) {
         this();
@@ -200,18 +199,17 @@
     }
 
     /**
-     * Inserts the specified object into this LinkedList 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
-     * LinkedList, the object is added at the end.
+     * Inserts the specified object into this {@code LinkedList} 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
+     * {@code LinkedList}, the object is added at the end.
      * 
      * @param location
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param object
-     *            the object to add
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     *            the object to add.
+     * @throws IndexOutOfBoundsException
+     *             if {@code location < 0 || >= size()}
      */
     @Override
     public void add(int location, E object) {
@@ -238,11 +236,11 @@
     }
 
     /**
-     * Adds the specified object at the end of this LinkedList.
+     * Adds the specified object at the end of this {@code LinkedList}.
      * 
      * @param object
-     *            the object to add
-     * @return true
+     *            the object to add.
+     * @return always true
      */
     @Override
     public boolean add(E object) {
@@ -257,18 +255,22 @@
     }
 
     /**
-     * Inserts the objects in the specified Collection at the specified location
-     * in this LinkedList. The objects are added in the order they are returned
-     * from the <code>Collection</code> iterator.
+     * Inserts the objects in the specified collection at the specified location
+     * in this {@code LinkedList}. 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 LinkedList is modified, false otherwise
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || > size()</code>
+     *            the collection of objects
+     * @return {@code true} if this {@code LinkedList} is modified,
+     *         {@code false} otherwise.
+     * @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()}
      */
     @Override
     public boolean addAll(int location, Collection<? extends E> collection) {
@@ -306,11 +308,12 @@
     }
 
     /**
-     * Adds the objects in the specified Collection to this LinkedList.
+     * Adds the objects in the specified Collection to this {@code LinkedList}.
      * 
      * @param collection
-     *            the Collection of objects
-     * @return true if this LinkedList is modified, false otherwise
+     *            the collection of objects.
+     * @return {@code true} if this {@code LinkedList} is modified,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean addAll(Collection<? extends E> collection) {
@@ -335,10 +338,10 @@
     }
 
     /**
-     * Adds the specified object at the beginning of this LinkedList.
+     * Adds the specified object at the beginning of this {@code LinkedList}.
      * 
      * @param object
-     *            the object to add
+     *            the object to add.
      */
     public void addFirst(E object) {
         Link<E> oldFirst = voidLink.next;
@@ -350,10 +353,10 @@
     }
 
     /**
-     * Adds the specified object at the end of this LinkedList.
+     * Adds the specified object at the end of this {@code LinkedList}.
      * 
      * @param object
-     *            the object to add
+     *            the object to add.
      */
     public void addLast(E object) {
         Link<E> oldLast = voidLink.previous;
@@ -365,7 +368,7 @@
     }
 
     /**
-     * Removes all elements from this LinkedList, leaving it empty.
+     * Removes all elements from this {@code LinkedList}, leaving it empty.
      * 
      * @see List#isEmpty
      * @see #size
@@ -381,11 +384,10 @@
     }
 
     /**
-     * Answers a new LinkedList with the same elements and size as this
-     * LinkedList.
-     * 
-     * @return a shallow copy of this LinkedList
+     * Returns a new {@code LinkedList} with the same elements and size as this
+     * {@code LinkedList}.
      * 
+     * @return a shallow copy of this {@code LinkedList}.
      * @see java.lang.Cloneable
      */
     @SuppressWarnings("unchecked")
@@ -405,12 +407,12 @@
     }
 
     /**
-     * Searches this LinkedList for the specified object.
+     * Searches this {@code LinkedList} for the specified object.
      * 
      * @param object
-     *            the object to search for
-     * @return true if <code>object</code> is an element of this LinkedList,
-     *         false otherwise
+     *            the object to search for.
+     * @return {@code true} if {@code object} is an element of this
+     *         {@code LinkedList}, {@code false} otherwise
      */
     @Override
     public boolean contains(Object object) {
@@ -452,12 +454,11 @@
     }
 
     /**
-     * Answers the first element in this LinkedList.
-     * 
-     * @return the first element
+     * Returns the first element in this {@code LinkedList}.
      * 
-     * @exception NoSuchElementException
-     *                when this LinkedList is empty
+     * @return the first element.
+     * @throws NoSuchElementException
+     *             if this {@code LinkedList} is empty.
      */
     public E getFirst() {
         Link<E> first = voidLink.next;
@@ -468,12 +469,11 @@
     }
 
     /**
-     * Answers the last element in this LinkedList.
+     * Returns the last element in this {@code LinkedList}.
      * 
      * @return the last element
-     * 
-     * @exception NoSuchElementException
-     *                when this LinkedList is empty
+     * @throws NoSuchElementException
+     *             if this {@code LinkedList} is empty
      */
     public E getLast() {
         Link<E> last = voidLink.previous;
@@ -483,14 +483,6 @@
         throw new NoSuchElementException();
     }
 
-    /**
-     * Searches this LinkedList 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) {
         int pos = 0;
@@ -516,12 +508,13 @@
     }
 
     /**
-     * Searches this LinkedList for the specified object and returns the index
-     * of the last occurrence.
+     * Searches this {@code LinkedList} 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
+     * @return the index of the last occurrence of the object, or -1 if it was
+     *         not found.
      */
     @Override
     public int lastIndexOf(Object object) {
@@ -548,17 +541,15 @@
     }
 
     /**
-     * Answers a ListIterator on the elements of this LinkedList. The elements
-     * are iterated in the same order that they occur in the LinkedList. The
-     * iteration starts at the specified location.
+     * Returns a ListIterator on the elements of this {@code LinkedList}. The
+     * elements are iterated in the same order that they occur in the
+     * {@code LinkedList}. 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 LinkedList
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
-     * 
+     * @return a ListIterator on the elements of this {@code LinkedList}
+     * @throws IndexOutOfBoundsException
+     *             if {@code location < 0 || >= size()}
      * @see ListIterator
      */
     @Override
@@ -567,14 +558,13 @@
     }
 
     /**
-     * Removes the object at the specified location from this LinkedList.
+     * Removes the object at the specified location from this {@code LinkedList}.
      * 
      * @param location
      *            the index of the object to remove
      * @return the removed object
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>location < 0 || >= size()</code>
+     * @throws IndexOutOfBoundsException
+     *             if {@code location < 0 || >= size()}
      */
     @Override
     public E remove(int location) {
@@ -625,12 +615,11 @@
     }
 
     /**
-     * Removes the first object from this LinkedList.
-     * 
-     * @return the removed object
+     * Removes the first object from this {@code LinkedList}.
      * 
-     * @exception NoSuchElementException
-     *                when this LinkedList is empty
+     * @return the removed object.
+     * @throws NoSuchElementException
+     *             if this {@code LinkedList} is empty.
      */
     public E removeFirst() {
         Link<E> first = voidLink.next;
@@ -646,12 +635,11 @@
     }
 
     /**
-     * Removes the last object from this LinkedList.
-     * 
-     * @return the removed object
+     * Removes the last object from this {@code LinkedList}.
      * 
-     * @exception NoSuchElementException
-     *                when this LinkedList is empty
+     * @return the removed object.
+     * @throws NoSuchElementException
+     *             if this {@code LinkedList} is empty.
      */
     public E removeLast() {
         Link<E> last = voidLink.previous;
@@ -667,17 +655,20 @@
     }
 
     /**
-     * Replaces the element at the specified location in this LinkedList with
-     * the specified object.
+     * Replaces the element at the specified location in this {@code LinkedList}
+     * 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 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()}
      */
     @Override
     public E set(int location, E object) {
@@ -700,9 +691,9 @@
     }
 
     /**
-     * Answers the number of elements in this LinkedList.
+     * Returns the number of elements in this {@code LinkedList}.
      * 
-     * @return the number of elements in this LinkedList
+     * @return the number of elements in this {@code LinkedList}.
      */
     @Override
     public int size() {
@@ -732,9 +723,10 @@
     }
 
     /**
-     * Answers a new array containing all elements contained in this LinkedList.
+     * Returns a new array containing all elements contained in this
+     * {@code LinkedList}.
      * 
-     * @return an array of the elements from this LinkedList
+     * @return an array of the elements from this {@code LinkedList}.
      */
     @Override
     public Object[] toArray() {
@@ -749,19 +741,19 @@
     }
 
     /**
-     * Answers an array containing all elements contained in this LinkedList. 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 LinkedList, the array
-     * element following the collection elements is set to null.
+     * Returns an array containing all elements contained in this
+     * {@code LinkedList}. 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 LinkedList}, the array element following the collection elements
+     * is set to null.
      * 
      * @param contents
-     *            the array
-     * @return an array of the elements from this LinkedList
-     * 
-     * @exception ArrayStoreException
-     *                when the type of an element in this LinkedList cannot be
-     *                stored in the type of the specified array
+     *            the array.
+     * @return an array of the elements from this {@code LinkedList}.
+     * @throws ArrayStoreException
+     *             if the type of an element in this {@code LinkedList} cannot
+     *             be stored in the type of the specified array.
      */
     @Override
     @SuppressWarnings("unchecked")

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/List.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/List.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/List.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/List.java Thu May  7 21:43:41 2009
@@ -17,339 +17,337 @@
 
 package java.util;
 
+
 /**
- * List is a collection which maintains an ordering for its elements. Every
- * element in the list has an index.
+ * A {@code List} is a collection which maintains an ordering for its elements. Every
+ * element in the {@code List} has an index. Each element can thus be accessed by its
+ * index, with the first index being zero. Normally, {@code List}s allow duplicate
+ * elements, as compared to Sets, where elements have to be unique.
  */
 public interface List<E> extends Collection<E> {
-
     /**
-     * Inserts the specified object into this Vector 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.
+     * Inserts the specified object into this {@code List} at the specified location.
+     * The object is inserted before the current element at the specified
+     * location. If the location is equal to the size of this {@code List}, the object
+     * is added at the end. If the location is smaller than the size of this
+     * {@code List}, then all elements beyond the specified location are moved by one
+     * position towards the end of the {@code List}.
      * 
      * @param location
-     *            the index at which to insert
+     *            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>
+     *            the object to add.
+     * @throws UnsupportedOperationException
+     *                if adding to this {@code List} is not supported.
+     * @throws ClassCastException
+     *                if the class of the object is inappropriate for this
+     *                {@code List}.
+     * @throws IllegalArgumentException
+     *                if the object cannot be added to this {@code List}.
+     * @throws IndexOutOfBoundsException
+     *                if {@code location < 0 || location > size()}
      */
     public void add(int location, E object);
 
     /**
-     * Adds the specified object at the end of this List.
+     * Adds the specified object at the end of this {@code List}.
      * 
      * @param object
-     *            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
-     *                List
-     * @exception IllegalArgumentException
-     *                when the object cannot be added to this List
+     *            the object to add.
+     * @return always true.
+     * @throws UnsupportedOperationException
+     *                if adding to this {@code List} is not supported.
+     * @throws ClassCastException
+     *                if the class of the object is inappropriate for this
+     *                {@code List}.
+     * @throws IllegalArgumentException
+     *                if the object cannot be added to this {@code List}.
      */
     public boolean add(E 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.
+     * Inserts the objects in the specified collection at the specified location
+     * in this {@code 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 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>
+     *            the collection of objects to be inserted.
+     * @return true if this {@code List} has been modified through the insertion, false
+     *         otherwise (i.e. if the passed collection was empty).
+     * @throws UnsupportedOperationException
+     *                if adding to this {@code List} is not supported.
+     * @throws ClassCastException
+     *                if the class of an object is inappropriate for this
+     *                {@code List}.
+     * @throws IllegalArgumentException
+     *                if an object cannot be added to this {@code List}.
+     * @throws IndexOutOfBoundsException
+     *                if {@code location < 0 || > size()}
      */
     public boolean addAll(int location, Collection<? extends E> collection);
 
     /**
-     * Adds the objects in the specified Collection to the end of this List. The
-     * objects are added in the order they are returned from the Collection
-     * iterator.
+     * Adds the objects in the specified collection to the end of this {@code List}. The
+     * objects are added in the order in which they are returned from the
+     * collection's iterator.
      * 
      * @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
+     *            the collection of objects.
+     * @return {@code true} if this {@code List} is modified, {@code false} otherwise
+     *         (i.e. if the passed collection was empty).
+     * @throws UnsupportedOperationException
+     *                if adding to this {@code List} is not supported.
+     * @throws ClassCastException
+     *                if the class of an object is inappropriate for this
+     *                {@code List}.
+     * @throws IllegalArgumentException
+     *                if an object cannot be added to this {@code List}.
      */
     public boolean addAll(Collection<? extends E> collection);
 
     /**
-     * Removes all elements from this List, leaving it empty.
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this List is not supported
+     * Removes all elements from this {@code List}, leaving it empty.
      * 
+     * @throws UnsupportedOperationException
+     *                if removing from this {@code List} is not supported.
      * @see #isEmpty
      * @see #size
      */
     public void clear();
 
     /**
-     * Searches this List for the specified object.
+     * Tests whether this {@code List} contains the specified object.
      * 
      * @param object
-     *            the object to search for
-     * @return true if object is an element of this List, false otherwise
+     *            the object to search for.
+     * @return {@code true} if object is an element of this {@code List}, {@code false}
+     *         otherwise
      */
     public boolean contains(Object object);
 
     /**
-     * Searches this List for all objects in the specified Collection.
+     * Tests whether this {@code List} contains all objects contained in the
+     * specified collection.
      * 
      * @param collection
-     *            the Collection of objects
-     * @return true if all objects in the specified Collection are elements of
-     *         this List, false otherwise
+     *            the collection of objects
+     * @return {@code true} if all objects in the specified collection are
+     *         elements of this {@code List}, {@code false} otherwise.
      */
     public boolean containsAll(Collection<?> collection);
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
-     * the <em>same</em> object using a class specific comparison.
+     * Compares the given object with the {@code List}, and returns true if they
+     * represent the <em>same</em> object using a class specific comparison. For
+     * {@code List}s, this means that they contain the same elements in exactly the same
+     * order.
      * 
      * @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 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
      */
     public boolean equals(Object object);
 
     /**
-     * Answers the element at the specified location in this List.
+     * Returns the element at the specified location in this {@code 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>
+     *            the index of the element to return.
+     * @return the element at the specified location.
+     * @throws IndexOutOfBoundsException
+     *                if {@code location < 0 || >= size()}
      */
     public E get(int location);
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
+     * Returns the hash code for this {@code List}. It is calculated by taking each
+     * element' hashcode and its position in the {@code List} into account.
      * 
-     * @return the receiver's hash
-     * 
-     * @see #equals
+     * @return the hash code of the {@code List}.
      */
     public int hashCode();
 
     /**
-     * Searches this List for the specified object and returns the index of the
+     * Searches this {@code 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 the
+     *         object was not found.
      */
     public int indexOf(Object object);
 
     /**
-     * Answers if this List has no elements, a size of zero.
-     * 
-     * @return true if this List has no elements, false otherwise
+     * Returns whether this {@code List} contains no elements.
      * 
+     * @return {@code true} if this {@code List} has no elements, {@code false}
+     *         otherwise.
      * @see #size
      */
     public boolean isEmpty();
 
     /**
-     * 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 {@code List}. The elements are
+     * iterated in the same order as they occur in the {@code List}.
      * 
+     * @return an iterator on the elements of this {@code List}.
      * @see Iterator
      */
     public Iterator<E> iterator();
 
     /**
-     * Searches this List for the specified object and returns the index of the
+     * Searches this {@code 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);
 
     /**
-     * Answers a ListIterator on the elements of this List. The elements are
-     * iterated in the same order that they occur in the List.
+     * Returns a {@code List} iterator on the elements of this {@code List}. The elements are
+     * iterated in the same order that they occur in the {@code List}.
      * 
-     * @return a ListIterator on the elements of this List
+     * @return a {@code List} iterator on the elements of this {@code List}
      * 
      * @see ListIterator
      */
     public ListIterator<E> listIterator();
 
     /**
-     * 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 {@code List}. The elements are
+     * iterated in the same order as they occur in the {@code 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 list iterator on the elements of this {@code List}.
+     * @throws IndexOutOfBoundsException
+     *                if {@code location < 0 || location > size()}
      * @see ListIterator
      */
     public ListIterator<E> listIterator(int location);
 
     /**
-     * Removes the object at the specified location from this List.
+     * Removes the object at the specified location from this {@code 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 {@code List} is not supported.
+     * @throws IndexOutOfBoundsException
+     *                if {@code location < 0 || >= size()}
      */
     public E remove(int location);
 
     /**
-     * Removes the first occurrence of the specified object from this List.
+     * Removes the first occurrence of the specified object from this {@code List}.
      * 
      * @param object
-     *            the object to remove
-     * @return true if this List is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this List is not supported
+     *            the object to remove.
+     * @return true if this {@code List} was modified by this operation, false
+     *         otherwise.
+     * @throws UnsupportedOperationException
+     *                if removing from this {@code List} is not supported.
      */
     public boolean remove(Object object);
 
     /**
-     * Removes all occurrences in this List of each object in the specified
-     * Collection.
+     * Removes all occurrences in this {@code List} of each object in the specified
+     * collection.
      * 
      * @param collection
-     *            the Collection of objects to remove
-     * @return true if this List is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this List is not supported
+     *            the collection of objects to remove.
+     * @return {@code true} if this {@code List} is modified, {@code false} otherwise.
+     * @throws UnsupportedOperationException
+     *                if removing from this {@code List} is not supported.
      */
     public boolean removeAll(Collection<?> collection);
 
     /**
-     * Removes all objects from this List that are not contained in the
-     * specified Collection.
+     * Removes all objects from this {@code List} that are not contained in the
+     * specified collection.
      * 
      * @param collection
-     *            the Collection of objects to retain
-     * @return true if this List is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this List is not supported
+     *            the collection of objects to retain.
+     * @return {@code true} if this {@code List} is modified, {@code false} otherwise.
+     * @throws UnsupportedOperationException
+     *                if removing from this {@code List} is not supported.
      */
     public boolean retainAll(Collection<?> collection);
 
     /**
-     * Replaces the element at the specified location in this List with the
-     * specified object.
+     * Replaces the element at the specified location in this {@code List} with the
+     * specified object. This operation does not change the size of the {@code List}.
      * 
      * @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 insert.
+     * @return the previous element at the index.
+     * @throws UnsupportedOperationException
+     *                if replacing elements in this {@code List} is not supported.
+     * @throws ClassCastException
+     *                if the class of an object is inappropriate for this
+     *                {@code List}.
+     * @throws IllegalArgumentException
+     *                if an object cannot be added to this {@code List}.
+     * @throws IndexOutOfBoundsException
+     *                if {@code location < 0 || >= size()}
      */
     public E set(int location, E object);
 
     /**
-     * Answers the number of elements in this List.
+     * Returns the number of elements in this {@code List}.
      * 
-     * @return the number of elements in this List
+     * @return the number of elements in this {@code List}.
      */
     public int size();
 
     /**
-     * Answers a List of the specified portion of this List from the start index
-     * to one less than the end index. The returned List is backed by this list
-     * so changes to one are reflected by the other.
+     * Returns a {@code List} of the specified portion of this {@code List} from the given start
+     * index to the end index minus one. The returned {@code List} is backed by this
+     * {@code List} so changes to it are reflected by the other.
      * 
      * @param start
-     *            the index at which to start the sublist
+     *            the index at which to start the sublist.
      * @param end
-     *            the index one past the end of the sublist
-     * @return a List of a portion of this List
-     * 
-     * @exception IndexOutOfBoundsException
-     *                when <code>start < 0, start > end</code> or
-     *                <code>end > size()</code>
+     *            the index one past the end of the sublist.
+     * @return a list of a portion of this {@code List}.
+     * @throws IndexOutOfBoundsException
+     *                if {@code start < 0, start > end} or {@code end >
+     *                size()}
      */
     public List<E> subList(int start, int end);
 
     /**
-     * Answers an array containing all elements contained in this List.
+     * Returns an array containing all elements contained in this {@code List}.
      * 
-     * @return an array of the elements from this List
+     * @return an array of the elements from this {@code List}.
      */
     public Object[] toArray();
 
     /**
-     * Answers an array containing all elements contained in this List. If the
+     * Returns an array containing all elements contained in this {@code List}. 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 List, the array element following
+     * array is used and is larger than this {@code List}, the array element following
      * the collection elements is set to null.
      * 
      * @param array
-     *            the array
-     * @return an array of the elements from this List
-     * 
-     * @exception ArrayStoreException
-     *                when the type of an element in this List cannot be stored
-     *                in the type of the specified array
+     *            the array.
+     * @return an array of the elements from this {@code List}.
+     * @throws ArrayStoreException
+     *                if the type of an element in this {@code List} cannot be stored
+     *                in the type of the specified array.
      */
     public <T> T[] toArray(T[] array);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListIterator.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListIterator.java Thu May  7 21:43:41 2009
@@ -17,127 +17,116 @@
 
 package java.util;
 
+
 /**
  * An ListIterator is used to sequence over a List of objects. ListIterator can
- * move backwards or forwards through the List.
+ * move backwards or forwards through the list.
  */
 public interface ListIterator<E> extends Iterator<E> {
-
+    
     /**
-     * Inserts the specified object into the list between <code>next</code>
-     * and <code>previous</code>. The object inserted will be the previous
-     * object.
+     * Inserts the specified object into the list between {@code next} and
+     * {@code previous}. The object inserted will be the previous object.
      * 
      * @param object
-     *            the object to insert
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding is not supported by the list being iterated
-     * @exception ClassCastException
-     *                when the class of the object is inappropriate for the list
-     * @exception IllegalArgumentException
-     *                when the object cannot be added to the list
+     *            the object to insert.
+     * @throws UnsupportedOperationException
+     *             if adding is not supported by the list being iterated.
+     * @throws ClassCastException
+     *             if the class of the object is inappropriate for the list.
+     * @throws IllegalArgumentException
+     *             if the object cannot be added to the list.
      */
     void add(E object);
 
     /**
-     * Answers if there are more elements to iterate.
-     * 
-     * @return true if there are more elements, false otherwise
+     * Returns whether there are more elements to iterate.
      * 
+     * @return {@code true} if there are more elements, {@code false} otherwise.
      * @see #next
      */
     public boolean hasNext();
 
     /**
-     * Answers if there are previous elements to iterate.
-     * 
-     * @return true if there are previous elements, false otherwise
+     * Returns whether there are previous elements to iterate.
      * 
+     * @return {@code true} if there are previous elements, {@code false}
+     *         otherwise.
      * @see #previous
      */
     public boolean hasPrevious();
 
     /**
-     * Answers the next object in the iteration.
-     * 
-     * @return the next object
-     * 
-     * @exception NoSuchElementException
-     *                when there are no more elements
+     * Returns the next object in the iteration.
      * 
+     * @return the next object.
+     * @throws NoSuchElementException
+     *             if there are no more elements.
      * @see #hasNext
      */
     public E next();
 
     /**
-     * Answers the index of the next object in the iteration.
-     * 
-     * @return the index of the next object
-     * 
-     * @exception NoSuchElementException
-     *                when there are no more elements
+     * Returns the index of the next object in the iteration.
      * 
+     * @return the index of the next object, or the size of the list if the
+     *         iterator is at the end.
+     * @throws NoSuchElementException
+     *             if there are no more elements.
      * @see #next
      */
     public int nextIndex();
 
     /**
-     * Answers the previous object in the iteration.
-     * 
-     * @return the previous object
-     * 
-     * @exception NoSuchElementException
-     *                when there are no previous elements
+     * Returns the previous object in the iteration.
      * 
+     * @return the previous object.
+     * @throws NoSuchElementException
+     *             if there are no previous elements.
      * @see #hasPrevious
      */
     public E previous();
 
     /**
-     * Answers the index of the previous object in the iteration.
-     * 
-     * @return the index of the previous object
-     * 
-     * @exception NoSuchElementException
-     *                when there are no previous elements
+     * Returns the index of the previous object in the iteration.
      * 
+     * @return the index of the previous object, or -1 if the iterator is at the
+     *         beginning.
+     * @throws NoSuchElementException
+     *             if there are no previous elements.
      * @see #previous
      */
     public int previousIndex();
 
     /**
-     * Removes the last object returned by <code>next</code> or
-     * <code>previous</code> from the list.
+     * Removes the last object returned by {@code next} or {@code previous} from
+     * the list.
      * 
-     * @exception UnsupportedOperationException
-     *                when removing is not supported by the list being iterated
-     * @exception IllegalStateException
-     *                when <code>next</code> or <code>previous</code> have
-     *                not been called, or <code>remove</code> or
-     *                <code>add</code> have already been called after the last
-     *                call to <code>next</code> or <code>previous</code>
+     * @throws UnsupportedOperationException
+     *             if removing is not supported by the list being iterated.
+     * @throws IllegalStateException
+     *             if {@code next} or {@code previous} have not been called, or
+     *             {@code remove} or {@code add} have already been called after
+     *             the last call to {@code next} or {@code previous}.
      */
     public void remove();
 
     /**
-     * Replaces the last object returned by <code>next</code> or
-     * <code>previous</code> with the specified object.
+     * Replaces the last object returned by {@code next} or {@code previous}
+     * with the specified object.
      * 
      * @param object
-     *            the object to add
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding is not supported by the list being iterated
-     * @exception ClassCastException
-     *                when the class of the object is inappropriate for the list
-     * @exception IllegalArgumentException
-     *                when the object cannot be added to the list
-     * @exception IllegalStateException
-     *                when <code>next</code> or <code>previous</code> have
-     *                not been called, or <code>remove</code> or
-     *                <code>add</code> have already been called after the last
-     *                call to <code>next</code> or <code>previous</code>
+     *            the object to set.
+     * @throws UnsupportedOperationException
+     *             if setting is not supported by the list being iterated
+     * @throws ClassCastException
+     *             if the class of the object is inappropriate for the list.
+     * @throws IllegalArgumentException
+     *             if the object cannot be added to the list.
+     * @throws IllegalStateException
+     *             if {@code next} or {@code previous} have not been called, or
+     *             {@code remove} or {@code add} have already been called after
+     *             the last call to {@code next} or {@code previous}.
      */
     void set(E object);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListResourceBundle.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListResourceBundle.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListResourceBundle.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListResourceBundle.java Thu May  7 21:43:41 2009
@@ -18,8 +18,8 @@
 package java.util;
 
 /**
- * ListResourceBundle is the abstract superclass of classes which provide
- * resources by implementing the <code>getContents()</code> method to return
+ * {@code ListResourceBundle} is the abstract superclass of classes which provide
+ * resources by implementing the {@code getContents()} method to return
  * the list of resources.
  * 
  * @see ResourceBundle
@@ -36,18 +36,19 @@
     }
 
     /**
-     * Answers an Object array which contains the resources of this
-     * ListResourceBundle. Each element in the array is an array of two
-     * elements, the first is the resource key and the second is the resource.
+     * Returns an {@code Object} array which contains the resources of this
+     * {@code ListResourceBundle}. Each element in the array is an array of two
+     * elements, the first is the resource key string and the second is the
+     * resource.
      * 
-     * @return a Object array containing the resources
+     * @return a {@code Object} array containing the resources.
      */
     protected abstract Object[][] getContents();
 
     /**
-     * Answers the names of the resources contained in this ListResourceBundle.
+     * Returns the names of the resources contained in this {@code ListResourceBundle}.
      * 
-     * @return an Enumeration of the resource names
+     * @return an {@code Enumeration} of the resource names.
      */
     @Override
     public Enumeration<String> getKeys() {
@@ -109,14 +110,6 @@
         }
     }
 
-    /**
-     * Answers the named resource from this ResourceBundle, or null if the
-     * resource is not found.
-     * 
-     * @param key
-     *            the name of the resource
-     * @return the resource object
-     */
     @Override
     public final Object handleGetObject(String key) {
         initializeTable();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Locale.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Locale.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Locale.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Locale.java Thu May  7 21:43:41 2009
@@ -32,7 +32,7 @@
 import com.ibm.icu.util.ULocale;
 
 /**
- * Locale represents a language/country/variant combination. It is an identifier
+ * {@code Locale} represents a language/country/variant combination. It is an identifier
  * which dictates particular conventions for the presentation of information.
  * The language codes are two letter lowercase codes as defined by ISO-639. The
  * country codes are three letter uppercase codes as defined by ISO-3166. The
@@ -185,36 +185,40 @@
 	}
 
     /**
-     * Constructs a new Locale using the specified language.
+     * Constructs a new {@code Locale} using the specified language.
      * 
      * @param language
-     * 
+     *            the language this {@code Locale} represents.
      */
     public Locale(String language) {
         this(language, "", ""); //$NON-NLS-1$//$NON-NLS-2$
     }
 
     /**
-     * Constructs a new Locale using the specified language and country codes.
+     * Constructs a new {@code Locale} using the specified language and country codes.
      * 
      * @param language
+     *            the language this {@code Locale} represents.
      * @param country
-     * 
+     *            the country this {@code Locale} represents.
      */
     public Locale(String language, String country) {
         this(language, country, ""); //$NON-NLS-1$
     }
 
     /**
-     * Constructs a new Locale using the specified language, country, and
+     * Constructs a new {@code Locale} using the specified language, country, and
      * variant codes.
      * 
      * @param language
+     *            the language this {@code Locale} represents.
      * @param country
+     *            the country this {@code Locale} represents.
      * @param variant
+     *            the variant this {@code Locale} represents.
      * @throws NullPointerException
-     *             if <code>language</code>, <code>country</code> or
-     *             <code>variant</code> is <code>null</code>.
+     *             if {@code language}, {@code country}, or
+     *             {@code variant} is {@code null}.
      */
     public Locale(String language, String country, String variant) {
         if (language == null || country == null || variant == null) {
@@ -246,11 +250,10 @@
     }
 
     /**
-     * Answers a new Locale with the same language, country and variant codes as
-     * this Locale.
-     * 
-     * @return a shallow copy of this Locale
+     * Returns a new {@code Locale} with the same language, country and variant codes as
+     * this {@code Locale}.
      * 
+     * @return a shallow copy of this {@code Locale}.
      * @see java.lang.Cloneable
      */
     @Override
@@ -263,15 +266,14 @@
     }
 
     /**
-     * Compares the specified object to this Locale and answer if they are
-     * equal. The object must be an instance of Locale and have the same
+     * Compares the specified object to this {@code Locale} and returns whether they are
+     * equal. The object must be an instance of {@code Locale} and have the same
      * language, country and variant.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this Locale, false
-     *         otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this {@code Locale},
+     *         {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -374,9 +376,10 @@
     }
 
 	/**
-	 * Gets the list of installed Locales.
-	 * 
-	 * @return an array of Locale
+     * Gets the list of installed {@code Locale}. At least a {@code Locale} that is equal to
+     * {@code Locale.US} must be contained in this array.
+     *
+     * @return an array of {@code Locale}s.
 	 */
 	public static Locale[] getAvailableLocales() {
 		ULocale[] ulocales =  ULocale.getAvailableLocales();
@@ -388,76 +391,77 @@
 	}
 
     /**
-     * Gets the country code for this Locale.
+     * Gets the country code for this {@code Locale} or an empty string of no country
+     * was set.
      * 
-     * @return a country code
+     * @return a country code.
      */
     public String getCountry() {
         return countryCode;
     }
 
     /**
-     * Gets the default Locale.
+     * Gets the default {@code Locale}.
      * 
-     * @return the default Locale
+     * @return the default {@code Locale}.
      */
     public static Locale getDefault() {
         return defaultLocale;
     }
 
     /**
-     * Gets the full country name in the default Locale for the country code of
-     * this Locale. If there is no matching country name, the country code is
+     * Gets the full country name in the default {@code Locale} for the country code of
+     * this {@code Locale}. If there is no matching country name, the country code is
      * returned.
      * 
-     * @return a country name
+     * @return a country name.
      */
     public final String getDisplayCountry() {
         return getDisplayCountry(getDefault());
     }
 
-	/**
-	 * Gets the full country name in the specified Locale for the country code
-	 * of this Locale. If there is no matching country name, the country code is
-	 * returned.
-	 * 
-	 * @param locale
-	 *            the Locale
-	 * @return a country name
-	 */
+    /**
+     * Gets the full country name in the specified {@code Locale} for the country code
+     * of this {@code Locale}. If there is no matching country name, the country code is
+     * returned.
+     *
+     * @param locale
+     *            the {@code Locale} for which the display name is retrieved.
+     * @return a country name.
+     */
 	public String getDisplayCountry(Locale locale) {
 		return ULocale.forLocale(this).getDisplayCountry(ULocale.forLocale(locale));
 	}
 
     /**
-     * Gets the full language name in the default Locale for the language code
-     * of this Locale. If there is no matching language name, the language code
+     * Gets the full language name in the default {@code Locale} for the language code
+     * of this {@code Locale}. If there is no matching language name, the language code
      * is returned.
      * 
-     * @return a language name
+     * @return a language name.
      */
     public final String getDisplayLanguage() {
         return getDisplayLanguage(getDefault());
     }
 
-	/**
-	 * Gets the full language name in the specified Locale for the language code
-	 * of this Locale. If there is no matching language name, the language code
-	 * is returned.
-	 * 
-	 * @param locale
-	 *            the Locale
-	 * @return a language name
-	 */
+    /**
+     * Gets the full language name in the specified {@code Locale} for the language code
+     * of this {@code Locale}. If there is no matching language name, the language code
+     * is returned.
+     *
+     * @param locale
+     *            the {@code Locale} for which the display name is retrieved.
+     * @return a language name.
+     */
 	public String getDisplayLanguage(Locale locale) {
         return ULocale.forLocale(this).getDisplayLanguage(ULocale.forLocale(locale));
 	}
 
     /**
-     * Gets the full language, country, and variant names in the default Locale
-     * for the codes of this Locale.
+     * Gets the full language, country, and variant names in the default {@code Locale}
+     * for the codes of this {@code Locale}.
      * 
-     * @return a Locale name
+     * @return a {@code Locale} name.
      */
     public final String getDisplayName() {
         return getDisplayName(getDefault());
@@ -465,11 +469,11 @@
 
     /**
      * Gets the full language, country, and variant names in the specified
-     * Locale for the codes of this Locale.
+     * Locale for the codes of this {@code Locale}.
      * 
      * @param locale
-     *            the Locale
-     * @return a Locale name
+     *            the {@code Locale} for which the display name is retrieved.
+     * @return a {@code Locale} name.
      */
     public String getDisplayName(Locale locale) {
         int count = 0;
@@ -501,99 +505,98 @@
     }
 
     /**
-     * Gets the full variant name in the default Locale for the variant code of
-     * this Locale. If there is no matching variant name, the variant code is
+     * Gets the full variant name in the default {@code Locale} for the variant code of
+     * this {@code Locale}. If there is no matching variant name, the variant code is
      * returned.
      * 
-     * @return a variant name
+     * @return a variant name.
      */
     public final String getDisplayVariant() {
         return getDisplayVariant(getDefault());
     }
 
-	/**
-	 * Gets the full variant name in the specified Locale for the variant code
-	 * of this Locale. If there is no matching variant name, the variant code is
-	 * returned.
-	 * 
-	 * @param locale
-	 *            the Locale
-	 * @return a variant name
-	 */
+    /**
+     * Gets the full variant name in the specified {@code Locale} for the variant code
+     * of this {@code Locale}. If there is no matching variant name, the variant code is
+     * returned.
+     *
+     * @param locale
+     *            the {@code Locale} for which the display name is retrieved.
+     * @return a variant name.
+     */
 	public String getDisplayVariant(Locale locale) {
         return ULocale.forLocale(this).getDisplayVariant(ULocale.forLocale(locale));
 	}
 
-	/**
-	 * Gets the three letter ISO country code which corresponds to the country
-	 * code for this Locale.
-	 * 
-	 * @return a three letter ISO language code
-	 * 
-	 * @exception MissingResourceException
-	 *                when there is no matching three letter ISO country code
-	 */
+    /**
+     * Gets the three letter ISO country code which corresponds to the country
+     * code for this {@code Locale}.
+     *
+     * @return a three letter ISO language code.
+     * @throws MissingResourceException
+     *                if there is no matching three letter ISO country code.
+     */
 	public String getISO3Country() throws MissingResourceException {
         return ULocale.forLocale(this).getISO3Country();
 	}
 
-	/**
-	 * Gets the three letter ISO language code which corresponds to the language
-	 * code for this Locale.
-	 * 
-	 * @return a three letter ISO language code
-	 * 
-	 * @exception MissingResourceException
-	 *                when there is no matching three letter ISO language code
-	 */
+    /**
+     * Gets the three letter ISO language code which corresponds to the language
+     * code for this {@code Locale}.
+     *
+     * @return a three letter ISO language code.
+     * @throws MissingResourceException
+     *                if there is no matching three letter ISO language code.
+     */
 	public String getISO3Language() throws MissingResourceException {
         return ULocale.forLocale(this).getISO3Language();
 	}
 
     /**
      * Gets the list of two letter ISO country codes which can be used as the
-     * country code for a Locale.
+     * country code for a {@code Locale}.
      * 
-     * @return an array of String
+     * @return an array of strings.
      */
     public static String[] getISOCountries() {
         return ULocale.getISOCountries();
     }
 
-	/**
-	 * Gets the list of two letter ISO language codes which can be used as the
-	 * language code for a Locale.
-	 * 
-	 * @return an array of String
-	 */
+    /**
+     * Gets the list of two letter ISO language codes which can be used as the
+     * language code for a {@code Locale}.
+     *
+     * @return an array of strings.
+     */
 	public static String[] getISOLanguages() {
         return ULocale.getISOLanguages();
 	}
 
     /**
-     * Gets the language code for this Locale.
+     * Gets the language code for this {@code Locale} or the empty string of no language
+     * was set.
      * 
-     * @return a language code
+     * @return a language code.
      */
     public String getLanguage() {
         return languageCode;
     }
 
     /**
-     * Gets the variant code for this Locale.
+     * Gets the variant code for this {@code Locale} or an empty {@code String} of no variant
+     * was set.
      * 
-     * @return a variant code
+     * @return a variant code.
      */
     public String getVariant() {
         return variantCode;
     }
 
     /**
-     * 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 an integer hash code for the receiver. Objects which are equal
+     * return the same value for this method.
      * 
+     * @return the receiver's hash.
      * @see #equals
      */
     @Override
@@ -603,14 +606,13 @@
     }
 
     /**
-     * Sets the default Locale to the specified Locale.
+     * Sets the default {@code Locale} to the specified {@code Locale}.
      * 
      * @param locale
-     *            the new default Locale
-     * 
-     * @exception SecurityException
-     *                when there is a security manager which does not allow this
-     *                operation
+     *            the new default {@code Locale}.
+     * @throws SecurityException
+     *                if there is a {@code SecurityManager} in place which does not allow this
+     *                operation.
      */
     public synchronized static void setDefault(Locale locale) {
         if (locale != null) {
@@ -625,9 +627,17 @@
     }
 
     /**
-     * Answers the string representation of this Locale.
-     * 
-     * @return the string representation of this Locale
+     * Returns the string representation of this {@code Locale}. It consists of the
+     * language followed by the country and at the end the variant. They are
+     * separated by underscores. If the language is missing the string begins
+     * with an underscore. If the country is missing there are 2 underscores
+     * between the language and the variant. the variant alone canot be defined
+     * without a language and/or a country (in this case this method would
+     * return the empty string).
+     *
+     * Examples: "en", "en_US", "_US", "en__POSIX", "en_US_POSIX"
+     *
+     * @return the string representation of this {@code Locale}.
      */
     @Override
     public final String toString() {



Mime
View raw message