2001-10-15 Eric Blake <ebb9@email.byu.edu>

	* java/util/Collection.java: Updated javadoc.
	* java/util/Comparator.java: Updated javadoc.
	* java/util/Enumeration.java: Updated javadoc.
	* java/util/Iterator.java: Updated javadoc.
	* java/util/List.java: Updated javadoc.
	* java/util/ListIterator.java: Updated javadoc.
	* java/util/Map.java: Updated javadoc.
	* java/util/RandomAccess.java: New file.
	* java/util/Set.java: Updated javadoc.
	* java/util/SortedMap.java: Updated javadoc.
	* java/util/SortedSet.java: Updated javadoc.

12 files changed, 1171 insertions, 283 deletions

diff --git a/ChangeLog b/ChangeLog
index edae42d7e..dc712c33f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2001-10-15  Eric Blake  <ebb9@email.byu.edu>
+
+	* java/util/Collection.java: Updated javadoc.
+	* java/util/Comparator.java: Updated javadoc.
+	* java/util/Enumeration.java: Updated javadoc.
+	* java/util/Iterator.java: Updated javadoc.
+	* java/util/List.java: Updated javadoc.
+	* java/util/ListIterator.java: Updated javadoc.
+	* java/util/Map.java: Updated javadoc.
+	* java/util/RandomAccess.java: New file.
+	* java/util/Set.java: Updated javadoc.
+	* java/util/SortedMap.java: Updated javadoc.
+	* java/util/SortedSet.java: Updated javadoc.
+
 2001-10-13  Tom Tromey  <tromey@redhat.com>
 
 	* java/lang/SecurityManager.java (SecurityManager): Now public.
diff --git a/java/util/Collection.java b/java/util/Collection.java
index b7dbb69b1..11baa30f9 100644
--- a/java/util/Collection.java
+++ b/java/util/Collection.java
@@ -1,5 +1,5 @@
 /* Collection.java -- Interface that represents a collection of objects
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -25,9 +25,6 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Maybe some more @see clauses would be helpful.
-
 package java.util;
 
 /**
@@ -57,9 +54,23 @@ package java.util;
  * and returns a collection containing the same elements (that is, creates a
  * copy of the argument using its own implementation).
  *
- * @see java.util.List
- * @see java.util.Set
- * @see java.util.AbstractCollection
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see List
+ * @see Set
+ * @see Map
+ * @see SortedSet
+ * @see SortedMap
+ * @see HashSet
+ * @see TreeSet
+ * @see ArrayList
+ * @see LinkedList
+ * @see Vector
+ * @see Collections
+ * @see Arrays
+ * @see AbstractCollection
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface Collection
 {
@@ -67,12 +78,12 @@ public interface Collection
    * Add an element to this collection.
    *
    * @param o the object to add.
-   * @returns true if the collection was modified as a result of this action.
-   * @exception UnsupportedOperationException if this collection does not
+   * @return true if the collection was modified as a result of this action.
+   * @throws UnsupportedOperationException if this collection does not
    *   support the add operation.
-   * @exception ClassCastException if o cannot be added to this collection due
+   * @throws ClassCastException if o cannot be added to this collection due
    *   to its type.
-   * @exception IllegalArgumentException if o cannot be added to this
+   * @throws IllegalArgumentException if o cannot be added to this
    *   collection for some other reason.
    */
   boolean add(Object o);
@@ -81,12 +92,12 @@ public interface Collection
    * Add the contents of a given collection to this collection.
    *
    * @param c the collection to add.
-   * @returns true if the collection was modified as a result of this action.
-   * @exception UnsupportedOperationException if this collection does not
+   * @return true if the collection was modified as a result of this action.
+   * @throws UnsupportedOperationException if this collection does not
    *   support the addAll operation.
-   * @exception ClassCastException if some element of c cannot be added to this
+   * @throws ClassCastException if some element of c cannot be added to this
    *   collection due to its type.
-   * @exception IllegalArgumentException if some element of c cannot be added
+   * @throws IllegalArgumentException if some element of c cannot be added
    *   to this collection for some other reason.
    */
   boolean addAll(Collection c);
@@ -95,7 +106,7 @@ public interface Collection
    * Clear the collection, such that a subsequent call to isEmpty() would
    * return true.
    *
-   * @exception UnsupportedOperationException if this collection does not
+   * @throws UnsupportedOperationException if this collection does not
    *   support the clear operation.
    */
   void clear();
@@ -105,7 +116,7 @@ public interface Collection
    * elements.
    *
    * @param o the element to look for.
-   * @returns true if this collection contains at least one element e such that
+   * @return true if this collection contains at least one element e such that
    *   <code>o == null ? e == null : o.equals(e)</code>.
    */
   boolean contains(Object o);
@@ -114,7 +125,7 @@ public interface Collection
    * Test whether this collection contains every element in a given collection.
    *
    * @param c the collection to test for.
-   * @returns true if for every element o in c, contains(o) would return true.
+   * @return true if for every element o in c, contains(o) would return true.
    */
   boolean containsAll(Collection c);
 
@@ -132,7 +143,7 @@ public interface Collection
    * preserve the symmetry of the relation.
    *
    * @param o the object to compare to this collection.
-   * @returns true if the o is equal to this collection.
+   * @return true if the o is equal to this collection.
    */
   boolean equals(Object o);
 
@@ -148,21 +159,21 @@ public interface Collection
    * method renders it impossible to correctly implement both Set and List, as
    * the required implementations are mutually exclusive.
    *
-   * @returns a hash code for this collection.
+   * @return a hash code for this collection.
    */
   int hashCode();
 
   /**
    * Test whether this collection is empty, that is, if size() == 0.
    *
-   * @returns true if this collection contains no elements.
+   * @return true if this collection contains no elements.
    */
   boolean isEmpty();
 
   /**
    * Obtain an Iterator over this collection.
    *
-   * @returns an Iterator over the elements of this collection, in any order.
+   * @return an Iterator over the elements of this collection, in any order.
    */
   Iterator iterator();
 
@@ -172,9 +183,9 @@ public interface Collection
    *   : o.equals(e)</code>.
    *
    * @param o the object to remove.
-   * @returns true if the collection changed as a result of this call, that is,
+   * @return true if the collection changed as a result of this call, that is,
    *   if the collection contained at least one occurrence of o.
-   * @exception UnsupportedOperationException if this collection does not
+   * @throws UnsupportedOperationException if this collection does not
    *   support the remove operation.
    */
   boolean remove(Object o);
@@ -183,8 +194,8 @@ public interface Collection
    * Remove all elements of a given collection from this collection. That is,
    * remove every element e such that c.contains(e).
    *
-   * @returns true if this collection was modified as a result of this call.
-   * @exception UnsupportedOperationException if this collection does not
+   * @return true if this collection was modified as a result of this call.
+   * @throws UnsupportedOperationException if this collection does not
    *   support the removeAll operation.
    */
   boolean removeAll(Collection c);
@@ -193,8 +204,8 @@ public interface Collection
    * Remove all elements of this collection that are not contained in a given
    * collection. That is, remove every element e such that !c.contains(e).
    *
-   * @returns true if this collection was modified as a result of this call.
-   * @exception UnsupportedOperationException if this collection does not
+   * @return true if this collection was modified as a result of this call.
+   * @throws UnsupportedOperationException if this collection does not
    *   support the retainAll operation.
    */
   boolean retainAll(Collection c);
@@ -202,14 +213,14 @@ public interface Collection
   /**
    * Get the number of elements in this collection.
    *
-   * @returns the number of elements in the collection.
+   * @return the number of elements in the collection.
    */
   int size();
 
   /**
    * Copy the current contents of this collection into an array.
    *
-   * @returns an array of type Object[] and length equal to the size of this
+   * @return an array of type Object[] and length equal to the size of this
    *   collection, containing the elements currently in this collection, in
    *   any order.
    */
@@ -227,9 +238,9 @@ public interface Collection
    * if it is known that this collection does not contain any null elements.
    *
    * @param a the array to copy this collection into.
-   * @returns an array containing the elements currently in this collection, in
+   * @return an array containing the elements currently in this collection, in
    *   any order.
-   * @exception ArrayStoreException if the type of any element of the
+   * @throws ArrayStoreException if the type of any element of the
    *   collection is not a subtype of the element type of a.
    */
   Object[] toArray(Object[] a);
diff --git a/java/util/Comparator.java b/java/util/Comparator.java
index fc61fc302..8522301ee 100644
--- a/java/util/Comparator.java
+++ b/java/util/Comparator.java
@@ -29,36 +29,67 @@ package java.util;
 
 /**
  * Interface for objects that specify an ordering between objects. The ordering
- * can be <EM>total</EM>, such that two objects only compare equal if they are
- * equal by the equals method, or <EM>partial</EM> such that this is not
- * necessarily true. For example, a case-sensitive dictionary order comparison
- * of Strings is total, but if it is case-insensitive it is partial, because
- * "abc" and "ABC" compare as equal even though "abc".equals("ABC") returns
- * false.
+ * should be <em>total</em>, such that any two objects of the correct type
+ * can be compared, and the comparison is reflexive, anti-symmetric, and
+ * transitive.  It is also recommended that the comparator be <em>consistent
+ * with equals</em>, although this is not a strict requirement. A relation
+ * is consistent with equals if these two statements always have the same
+ * results (if no exceptions occur):<br>
+ * <code>compare((Object) e1, (Object) e2) == 0</code> and
+ * <code>e1.equals((Object) e2)</code><br>
+ * Comparators that violate consistency with equals may cause strange behavior
+ * in sorted lists and sets.  For example, a case-sensitive dictionary order
+ * comparison of Strings is consistent with equals, but if it is
+ * case-insensitive it is not, because "abc" and "ABC" compare as equal even
+ * though "abc".equals("ABC") returns false.
  * <P>
  * In general, Comparators should be Serializable, because when they are passed
  * to Serializable data structures such as SortedMap or SortedSet, the entire
  * data structure will only serialize correctly if the comparator is
  * Serializable.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Comparable
+ * @see TreeMap
+ * @see TreeSet
+ * @see SortedMap
+ * @see SortedSet
+ * @see Arrays#sort(Object[], Comparator)
+ * @see java.io.Serializable
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface Comparator
 {
   /**
    * Return an integer that is negative, zero or positive depending on whether
    * the first argument is less than, equal to or greater than the second
-   * according to this ordering. This method should obey the following contract:
-   * <UL>
-   *   <LI>if compare(a, b) &lt; 0 then compare(b, a) &gt; 0</LI>
-   *   <LI>if compare(a, b) throws an exception, so does compare(b, a)</LI>
-   *   <LI>if compare(a, b) &lt; 0 and compare(b, c) &lt; 0 then compare(a, c)
-   *       &lt; 0</LI>
-   *   <LI>if a.equals(b) or both a and b are null, then compare(a, b) == 0.
-   *       The converse need not be true, but if it is, this Comparator
-   *       specifies a <EM>total</EM> ordering.</LI>
-   * </UL>
+   * according to this ordering. This method should obey the following
+   * contract:
+   * <ul>
+   *   <li>if compare(a, b) &lt; 0 then compare(b, a) &gt; 0</li>
+   *   <li>if compare(a, b) throws an exception, so does compare(b, a)</li>
+   *   <li>if compare(a, b) &lt; 0 and compare(b, c) &lt; 0 then compare(a, c)
+   *       &lt; 0</li>
+   *   <li>if compare(a, b) == 0 then compare(a, c) and compare(b, c) must
+   *       have the same sign</li
+   * </ul>
+   * To be consistent with equals, the following additional constraint is
+   * in place:
+   * <ul>
+   *   <li>if a.equals(b) or both a and b are null, then
+   *       compare(a, b) == 0.</li>
+   * </ul><p>
    *
+   * Although it is permissible for a comparator to provide an order
+   * inconsistent with equals, that should be documented.
+   *
+   * @param o1 the first object
+   * @param o2 the second object
+   * @return the comparison
    * @throws ClassCastException if the elements are not of types that can be
-   *   compared by this ordering.
+   *         compared by this ordering.
    */
   int compare(Object o1, Object o2);
 
@@ -66,8 +97,12 @@ public interface Comparator
    * Return true if the object is equal to this object.  To be
    * considered equal, the argument object must satisfy the constraints
    * of <code>Object.equals()</code>, be a Comparator, and impose the
-   * same ordering as this Comparator.
+   * same ordering as this Comparator. The default implementation
+   * inherited from Object is usually adequate.
+   *
    * @param obj The object
+   * @return true if it is a Comparator that imposes the same order
+   * @see Object#equals(Object)
    */
   boolean equals(Object obj);
 }
diff --git a/java/util/Enumeration.java b/java/util/Enumeration.java
index 66624bd3a..5bcfbee3b 100644
--- a/java/util/Enumeration.java
+++ b/java/util/Enumeration.java
@@ -42,7 +42,12 @@ package java.util;
  * be obtained by the enumeration method in class Collections.
  *
  * @author Warren Levy <warrenl@cygnus.com>
- * @date August 25, 1998.
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Iterator
+ * @see Hashtable
+ * @see Vector
+ * @since 1.0
+ * @status updated to 1.4
  */
 public interface Enumeration
 {
@@ -50,8 +55,8 @@ public interface Enumeration
    * Tests whether there are elements remaining in the enumeration.
    *
    * @return true if there is at least one more element in the enumeration,
-   *   that is, if the next call to nextElement will not throw a
-   *   NoSuchElementException.
+   *         that is, if the next call to nextElement will not throw a
+   *         NoSuchElementException.
    */
   boolean hasMoreElements();
 
@@ -59,7 +64,7 @@ public interface Enumeration
    * Obtain the next element in the enumeration.
    *
    * @return the next element in the enumeration
-   * @exception NoSuchElementException if there are no more elements
+   * @throws NoSuchElementException if there are no more elements
    */
-  Object nextElement() throws NoSuchElementException;
+  Object nextElement();
 }
diff --git a/java/util/Iterator.java b/java/util/Iterator.java
index 92620f8c0..cc68c87da 100644
--- a/java/util/Iterator.java
+++ b/java/util/Iterator.java
@@ -1,5 +1,5 @@
 /* Iterator.java -- Interface for iterating over collections
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -28,20 +28,28 @@ executable file might be covered by the GNU General Public License. */
 package java.util;
 
 /**
- * An object which iterates over a collection. An Iterator is used to return the
- * items once only, in sequence, by successive calls to the next method. It is
- * also possible to remove elements from the underlying collection by using the
- * optional remove method. Iterator is intended as a replacement for the
- * Enumeration interface of previous versions of Java, which did not have the
- * remove method and had less conveniently named methods.
+ * An object which iterates over a collection. An Iterator is used to return
+ * the items once only, in sequence, by successive calls to the next method.
+ * It is also possible to remove elements from the underlying collection by
+ * using the optional remove method. Iterator is intended as a replacement
+ * for the Enumeration interface of previous versions of Java, which did not
+ * have the remove method and had less conveniently named methods.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Collection
+ * @see ListIterator
+ * @see Enumeration
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface Iterator
 {
   /**
-   * Tests whether there are elements remaining in the collection.
+   * Tests whether there are elements remaining in the collection. In other
+   * words, calling <code>next()</code> will not throw an exception.
    *
-   * @return true if there is at least one more element in the collection,
-   *   that is, if the next call to next will not throw NoSuchElementException.
+   * @return true if there is at least one more element in the collection
    */
   boolean hasNext();
 
@@ -49,20 +57,20 @@ public interface Iterator
    * Obtain the next element in the collection.
    *
    * @return the next element in the collection
-   * @exception NoSuchElementException if there are no more elements
+   * @throws NoSuchElementException if there are no more elements
    */
   Object next();
 
   /**
-   * Remove from the underlying collection the last element returned by next.
-   * This method can be called only once after each call to next. It does not
-   * affect what will be returned by subsequent calls to next. This operation is
-   * optional, it may throw an UnsupportedOperationException.
+   * Remove from the underlying collection the last element returned by next
+   * (optional operation). This method can be called only once after each
+   * call to <code>next()</code>. It does not affect what will be returned
+   * by subsequent calls to next.
    *
-   * @exception IllegalStateException if next has not yet been called or remove
-   *   has already been called since the last call to next.
-   * @exception UnsupportedOperationException if this Iterator does not support
-   *   the remove operation.
+   * @throws IllegalStateException if next has not yet been called or remove
+   *         has already been called since the last call to next.
+   * @throws UnsupportedOperationException if this Iterator does not support
+   *         the remove operation.
    */
   void remove();
 }
diff --git a/java/util/List.java b/java/util/List.java
index e3e2617e5..25892d73c 100644
--- a/java/util/List.java
+++ b/java/util/List.java
@@ -1,5 +1,5 @@
 /* List.java -- An ordered collection which allows indexed access
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -25,131 +25,179 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Doc comment for the interface itself needs to be put into english.
-// ~ Some more @see clauses might be nice.
-
 package java.util;
 
 /**
- * [This is what this doc comment will mention:
- * ~ Additional restrictions on some methods. Others included for completeness.
- * ~ ListIterator and what it can do
- * ~ Positional and iterated access
- * ~ search (but linear time)
- * ~ be careful when containing self as an element, because equals and hashCode
- *   loop.]
+ * An ordered collection (also known as a list). This collection allows
+ * access to elements by position, as well as control on where elements
+ * are inserted. Unlike sets, duplicate elements are permitted by this
+ * general contract (if a subclass forbids duplicates, this should be
+ * documented).
+ * <p>
+ *
+ * List places additional requirements on <code>iterator</code>,
+ * <code>add</code>, <code>remove</code>, <code>equals</code>, and
+ * <code>hashCode</code>, in addition to requiring more methods. List
+ * indexing is 0-based (like arrays), although some implementations may
+ * require time proportional to the index to obtain an arbitrary element.
+ * The List interface is incompatible with Set; you cannot implement both
+ * simultaneously.
+ * <p>
+ *
+ * Lists also provide a <code>ListIterator</code> which allows bidirectional
+ * traversal and other features atop regular iterators. Lists can be
+ * searched for arbitrary elements, and allow easy insertion and removal
+ * of multiple elements in one method call.
+ * <p>
+ *
+ * Note: While lists may contain themselves as elements, this leads to
+ * undefined (usually infinite recursive) behavior for some methods like
+ * hashCode or equals.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Collection
+ * @see Set
+ * @see ArrayList
+ * @see LinkedList
+ * @see Vector
+ * @see Arrays#asList(Object[])
+ * @see Collections#nCopies(int, Object)
+ * @see Collections#EMPTY_LIST
+ * @see AbstractList
+ * @see AbstractSequentialList
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface List extends Collection
 {
   /**
-   * Insert an element into the list at a given position.
+   * Insert an element into the list at a given position (optional operation).
+   * This shifts all existing elements from that position to the end one
+   * index to the right. This version of add has no return, since it is
+   * assumed to always succeed if there is no exception.
    *
-   * @param index the location to insert the item.
-   * @param o the object to insert.
-   * @exception UnsupportedOperationException if this list does not support the
-   *   add operation.
-   * @exception IndexOutOfBoundsException if index < 0 || index > size()
-   * @exception ClassCastException if o cannot be added to this list due to its
-   *   type.
-   * @exception IllegalArgumentException if o cannot be added to this list for
-   *   some other reason.
+   * @param index the location to insert the item
+   * @param o the object to insert
+   * @throws UnsupportedOperationException if this list does not support the
+   *         add operation
+   * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
+   * @throws ClassCastException if o cannot be added to this list due to its
+   *         type
+   * @throws IllegalArgumentException if o cannot be added to this list for
+   *         some other reason
    */
   void add(int index, Object o);
 
   /**
-   * Add an element to the end of the list.
+   * Add an element to the end of the list (optional operation). If the list
+   * imposes restraints on what can be inserted, such as no null elements,
+   * this should be documented.
    *
-   * @param o the object to add.
-   * @returns true, as Collection defines this method as returning true if the
-   *   list was modified as a result of this action, and it always is for a
-   *   list.
-   * @exception UnsupportedOperationException if this list does not support the
-   *   add operation.
-   * @exception ClassCastException if o cannot be added to this list due to its
-   *   type.
-   * @exception IllegalArgumentException if o cannot be added to this list for
-   *   some other reason.
+   * @param o the object to add
+   * @return true, as defined by Collection for a modified list
+   * @throws UnsupportedOperationException if this list does not support the
+   *         add operation
+   * @throws ClassCastException if o cannot be added to this list due to its
+   *         type
+   * @throws IllegalArgumentException if o cannot be added to this list for
+   *         some other reason
    */
   boolean add(Object o);
 
   /**
-   * Insert the contents of a collection into the list at a given position.
+   * Insert the contents of a collection into the list at a given position
+   * (optional operation). Shift all elements at that position to the right
+   * by the number of elements inserted. This operation is undefined if
+   * this list is modified during the operation (for example, if you try
+   * to insert a list into itself).
    *
-   * @param index the location to insert the collection.
-   * @param c the collection to insert.
-   * @returns true if the list was modified by this action, that is, if c is
-   *   non-empty.
-   * @exception UnsupportedOperationException if this list does not support the
-   *   addAll operation.
-   * @exception IndexOutOfBoundsException if index < 0 || index > size()
-   * @exception ClassCastException if some element of c cannot be added to this
-   *   list due to its type.
-   * @exception IllegalArgumentException if some element of c cannot be added
-   *   to this list for some other reason.
+   * @param index the location to insert the collection
+   * @param c the collection to insert
+   * @return true if the list was modified by this action, that is, if c is
+   *         non-empty
+   * @throws UnsupportedOperationException if this list does not support the
+   *         addAll operation
+   * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
+   * @throws ClassCastException if some element of c cannot be added to this
+   *         list due to its type
+   * @throws IllegalArgumentException if some element of c cannot be added
+   *         to this list for some other reason
+   * @throws NullPointerException if the specified collection is null
+   * @see #add(int, Object)
    */
   boolean addAll(int index, Collection c);
 
   /**
-   * Add the contents of a collection to the end of the list.
+   * Add the contents of a collection to the end of the list (optional
+   * operation).  This operation is undefined if this list is modified
+   * during the operation (for example, if you try to insert a list into
+   * itself).
    *
-   * @param c the collection to add.
-   * @returns true if the list was modified by this action, that is, if c is
-   *   non-empty.
-   * @exception UnsupportedOperationException if this list does not support the
-   *   addAll operation.
-   * @exception ClassCastException if some element of c cannot be added to this
-   *   list due to its type.
-   * @exception IllegalArgumentException if some element of c cannot be added
-   *   to this list for some other reason.
+   * @param c the collection to add
+   * @return true if the list was modified by this action, that is, if c is
+   *         non-empty
+   * @throws UnsupportedOperationException if this list does not support the
+   *         addAll operation
+   * @throws ClassCastException if some element of c cannot be added to this
+   *         list due to its type
+   * @throws IllegalArgumentException if some element of c cannot be added
+   *         to this list for some other reason
+   * @throws NullPointerException if the specified collection is null
+   * @see #add(Object)
    */
   boolean addAll(Collection c);
 
   /**
    * Clear the list, such that a subsequent call to isEmpty() would return
-   * true.
+   * true (optional operation).
    *
-   * @exception UnsupportedOperationException if this list does not support the
-   *   clear operation.
+   * @throws UnsupportedOperationException if this list does not support the
+   *         clear operation
    */
   void clear();
 
   /**
    * Test whether this list contains a given object as one of its elements.
+   * This is defined as the existence of an element e such that
+   * <code>o == null ? e == null : o.equals(e)</code>.
    *
-   * @param o the element to look for.
-   * @returns true if this list contains an element e such that <code>o ==
-   *   null ? e == null : o.equals(e)</code>.
+   * @param o the element to look for
+   * @return true if this list contains the element
    */
   boolean contains(Object o);
 
   /**
    * Test whether this list contains every element in a given collection.
    *
-   * @param c the collection to test for.
-   * @returns true if for every element o in c, contains(o) would return true.
+   * @param c the collection to test for
+   * @return true if for every element o in c, contains(o) would return true
+   * @throws NullPointerException if the collection is null
+   * @see #contains(Object)
    */
   boolean containsAll(Collection c);
 
   /**
    * Test whether this list is equal to another object. A List is defined to be
    * equal to an object if and only if that object is also a List, and the two
-   * lists are equal. Two lists l1 and l2 are defined to be equal if and only
+   * lists have the same sequence. Two lists l1 and l2 are equal if and only
    * if <code>l1.size() == l2.size()</code>, and for every integer n between 0
    * and <code>l1.size() - 1</code> inclusive, <code>l1.get(n) == null ?
    * l2.get(n) == null : l1.get(n).equals(l2.get(n))</code>.
    *
-   * @param o the object to test for equality with this list.
-   * @returns true if o is equal to this list.
+   * @param o the object to test for equality with this list
+   * @return true if o is equal to this list
+   * @see Object#equals(Object)
+   * @see #hashCode()
    */
   boolean equals(Object o);
 
   /**
    * Get the element at a given index in this list.
    *
-   * @param index the index of the element to be returned.
-   * @returns the element at index index in this list.
-   * @exception IndexOutOfBoundsException if index < 0 || index >= size()
+   * @param index the index of the element to be returned
+   * @return the element at index index in this list
+   * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
    */
   Object get(int index);
 
@@ -159,14 +207,17 @@ public interface List extends Collection
    * <pre>
    *   hashCode = 1;
    *   Iterator i = list.iterator();
-   *   while (i.hasNext()) {
-   *     Object obj = i.next();
-   *     hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode());
-   *   }
+   *   while (i.hasNext())
+   *     {
+   *       Object obj = i.next();
+   *       hashCode = 31 * hashCode + (obj == null ? 0 : obj.hashCode());
+   *     }
    * </pre>
    * This ensures that the general contract of Object.hashCode() is adhered to.
    *
-   * @returns the hash code of this list.
+   * @return the hash code of this list
+   * @see Object#hashCode()
+   * @see #equals(Object)
    */
   int hashCode();
 
@@ -174,22 +225,23 @@ public interface List extends Collection
    * Obtain the first index at which a given object is to be found in this
    * list.
    *
-   * @returns the least integer n such that <code>o == null ? get(n) == null :
-   *   o.equals(get(n))</code>, or -1 if there is no such index.
+   * @param o the object to search for
+   * @return the least integer n such that <code>o == null ? get(n) == null :
+   *         o.equals(get(n))</code>, or -1 if there is no such index
    */
   int indexOf(Object o);
 
   /**
    * Test whether this list is empty, that is, if size() == 0.
    *
-   * @returns true if this list contains no elements.
+   * @return true if this list contains no elements
    */
   boolean isEmpty();
 
   /**
-   * Obtain an Iterator over this list.
+   * Obtain an Iterator over this list, whose sequence is the list order.
    *
-   * @returns an Iterator over the elements of this list, in order.
+   * @return an Iterator over the elements of this list, in order
    */
   Iterator iterator();
 
@@ -197,119 +249,135 @@ public interface List extends Collection
    * Obtain the last index at which a given object is to be found in this
    * list.
    *
-   * @returns the greatest integer n such that <code>o == null ? get(n) == null
-   *   : o.equals(get(n))</code>.
+   * @return the greatest integer n such that <code>o == null ? get(n) == null
+   *         : o.equals(get(n))</code>, or -1 if there is no such index
    */
   int lastIndexOf(Object o);
 
   /**
    * Obtain a ListIterator over this list, starting at the beginning.
    *
-   * @returns a ListIterator over the elements of this list, in order, starting
-   *   at the beginning.
+   * @return a ListIterator over the elements of this list, in order, starting
+   *         at the beginning
    */
   ListIterator listIterator();
 
   /**
    * Obtain a ListIterator over this list, starting at a given position.
+   * A first call to next() would return the same as get(index), and a
+   * first call to previous() would return the same as get(index - 1).
    *
    * @param index the position, between 0 and size() inclusive, to begin the
-   *   iteration from.
-   * @returns a ListIterator over the elements of this list, in order, starting
-   *   at index.
-   * @exception IndexOutOfBoundsException if index < 0 || index > size()
+   *        iteration from
+   * @return a ListIterator over the elements of this list, in order, starting
+   *         at index
+   * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
    */
   ListIterator listIterator(int index);
 
   /**
-   * Remove the element at a given position in this list.
+   * Remove the element at a given position in this list (optional operation).
+   * Shifts all remaining elements to the left to fill the gap.
    *
-   * @param index the position within the list of the object to remove.
-   * @returns the object that was removed.
-   * @exception UnsupportedOperationException if this list does not support the
-   *   remove operation.
-   * @exception IndexOutOfBoundsException if index < 0 || index > size()
+   * @param index the position within the list of the object to remove
+   * @return the object that was removed
+   * @throws UnsupportedOperationException if this list does not support the
+   *         remove operation
+   * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
    */
   Object remove(int index);
 
   /**
-   * Remove the first occurence of an object from this list. That is, remove
-   * the first element e such that <code>o == null ? e == null :
-   * o.equals(e)</code>.
+   * Remove the first occurence of an object from this list (optional
+   * operation). That is, remove the first element e such that
+   * <code>o == null ? e == null : o.equals(e)</code>.
    *
-   * @param o the object to remove.
-   * @returns true if the list changed as a result of this call, that is, if
-   *   the list contained at least one occurrence of o.
-   * @exception UnsupportedOperationException if this list does not support the
-   *   remove operation.
+   * @param o the object to remove
+   * @return true if the list changed as a result of this call, that is, if
+   *         the list contained at least one occurrence of o
+   * @throws UnsupportedOperationException if this list does not support the
+   *         remove operation
    */
   boolean remove(Object o);
 
   /**
-   * Remove all elements of a given collection from this list. That is, remove
-   * every element e such that c.contains(e).
+   * Remove all elements of a given collection from this list (optional
+   * operation). That is, remove every element e such that c.contains(e).
    *
-   * @returns true if this list was modified as a result of this call.
-   * @exception UnsupportedOperationException if this list does not support the
-   *   removeAll operation.
+   * @param c the collection to filter out
+   * @return true if this list was modified as a result of this call
+   * @throws UnsupportedOperationException if this list does not support the
+   *         removeAll operation
+   * @throws NullPointerException if the collection is null
+   * @see #remove(Object)
+   * @see #contains(Object)
    */
   boolean removeAll(Collection c);
 
   /**
    * Remove all elements of this list that are not contained in a given
-   * collection. That is, remove every element e such that !c.contains(e).
+   * collection (optional operation). That is, remove every element e such
+   * that !c.contains(e).
    *
-   * @returns true if this list was modified as a result of this call.
-   * @exception UnsupportedOperationException if this list does not support the
-   *   retainAll operation.
+   * @param c the collection to retain
+   * @return true if this list was modified as a result of this call
+   * @throws UnsupportedOperationException if this list does not support the
+   *         retainAll operation
+   * @throws NullPointerException if the collection is null
+   * @see #remove(Object)
+   * @see #contains(Object)
    */
   boolean retainAll(Collection c);
 
   /**
-   * Replace an element of this list with another object.
+   * Replace an element of this list with another object (optional operation).
    *
-   * @param index the position within this list of the element to be replaced.
-   * @param o the object to replace it with.
-   * @returns the object that was replaced.
-   * @exception UnsupportedOperationException if this list does not support the
-   *   set operation.
-   * @exception IndexOutOfBoundsException if index < 0 || index >= size()
-   * @exception ClassCastException if o cannot be added to this list due to its
-   *   type.
-   * @exception IllegalArgumentException if o cannot be added to this list for
-   *   some other reason.
+   * @param index the position within this list of the element to be replaced
+   * @param o the object to replace it with
+   * @return the object that was replaced
+   * @throws UnsupportedOperationException if this list does not support the
+   *         set operation
+   * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
+   * @throws ClassCastException if o cannot be added to this list due to its
+   *         type
+   * @throws IllegalArgumentException if o cannot be added to this list for
+   *         some other reason
    */
   Object set(int index, Object o);
 
   /**
-   * Get the number of elements in this list.
+   * Get the number of elements in this list. If the list contains more
+   * than Integer.MAX_VALUE elements, return Integer.MAX_VALUE.
    *
-   * @returns the number of elements in the list.
+   * @return the number of elements in the list
    */
   int size();
 
   /**
    * Obtain a List view of a subsection of this list, from fromIndex
-   * (inclusive) to toIndex (exclusive). The returned list should be modifiable
-   * if and only if this list is modifiable. Changes to the returned list
-   * should be reflected in this list. If this list is structurally modified in
+   * (inclusive) to toIndex (exclusive). If the two indices are equal, the
+   * sublist is empty. The returned list should be modifiable if and only
+   * if this list is modifiable. Changes to the returned list should be
+   * reflected in this list. If this list is structurally modified in
    * any way other than through the returned list, the result of any subsequent
    * operations on the returned list is undefined.
    *
    * @param fromIndex the index that the returned list should start from
-   *    (inclusive).
-   * @param toIndex the index that the returned list should go to (exclusive).
-   * @returns a List backed by a subsection of this list.
-   * @exception IndexOutOfBoundsException if fromIndex < 0 || toIndex > size()
-   *   || fromIndex > toIndex.
+   *        (inclusive)
+   * @param toIndex the index that the returned list should go to (exclusive)
+   * @return a List backed by a subsection of this list
+   * @throws IndexOutOfBoundsException if fromIndex &lt; 0
+   *         || toIndex &gt; size() || fromIndex &gt; toIndex
+   * @throws IllegalArgumentException if fromIndex &gt; toIndex (according to
+   *         AbstractList). Don't you love Sun's inconsistent specifications?
    */
   List subList(int fromIndex, int toIndex);
 
   /**
    * Copy the current contents of this list into an array.
    *
-   * @returns an array of type Object[] and length equal to the length of this
-   *   list, containing the elements currently in this list, in order.
+   * @return an array of type Object[] and length equal to the length of this
+   *         list, containing the elements currently in this list, in order
    */
   Object[] toArray();
 
@@ -323,11 +391,12 @@ public interface List extends Collection
    * Note: The fact that the following element is set to null is only useful
    * if it is known that this list does not contain any null elements.
    *
-   * @param a the array to copy this list into.
-   * @returns an array containing the elements currently in this list, in
-   *    order.
-   * @exception ArrayStoreException if the type of any element of the
-   *   collection is not a subtype of the element type of a.
+   * @param a the array to copy this list into
+   * @return an array containing the elements currently in this list, in
+   *         order
+   * @throws ArrayStoreException if the type of any element of the
+   *         collection is not a subtype of the element type of a
+   * @throws NullPointerException if the specified array is null
    */
   Object[] toArray(Object[] a);
 }
diff --git a/java/util/ListIterator.java b/java/util/ListIterator.java
index 8a8d2c74e..92f49371a 100644
--- a/java/util/ListIterator.java
+++ b/java/util/ListIterator.java
@@ -1,5 +1,5 @@
 /* ListIterator.java -- Extended Iterator for iterating over ordered lists
-   Copyright (C) 1998, 1999 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -32,116 +32,128 @@ package java.util;
  * elements may be accessed in forward or reverse order, elements may be
  * replaced as well as removed, and new elements may be inserted, during the
  * traversal of the list.
+ * <p>
+ *
+ * A list with n elements provides n+1 iterator positions (the front, the end,
+ * or between two elements). Note that <code>remove</code> and <code>set</code>
+ * operate on the last element returned, whether it was by <code>next</code>
+ * or <code>previous</code>.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Collection
+ * @see List
+ * @see Iterator
+ * @see Enumeration
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface ListIterator extends Iterator
 {
   /**
    * Tests whether there are elements remaining in the list in the forward
-   * direction.
+   * direction. In other words, next() will not fail with a
+   * NoSuchElementException.
    *
-   * @return true if there is at least one more element in the list in the
-   *   forward direction, that is, if the next call to next will not throw
-   *   NoSuchElementException.
+   * @return true if the list continues in the forward direction
    */
   boolean hasNext();
 
   /**
    * Tests whether there are elements remaining in the list in the reverse
-   * direction.
+   * direction. In other words, previous() will not fail with a
+   * NoSuchElementException.
    *
-   * @return true if there is at least one more element in the list in the
-   *   reverse direction, that is, if the next call to previous will not throw
-   *   NoSuchElementException.
+   * @return true if the list continues in the reverse direction
    */
   boolean hasPrevious();
 
   /**
    * Obtain the next element in the list in the forward direction. Repeated
-   * calls to next may be used to iterate over the entire list, or calls to next
-   * and previous may be used together to go forwards and backwards. Alternating
-   * calls to next and previous will return the same element.
+   * calls to next may be used to iterate over the entire list, or calls to
+   * next and previous may be used together to go forwards and backwards.
+   * Alternating calls to next and previous will return the same element.
    *
    * @return the next element in the list in the forward direction
-   * @exception NoSuchElementException if there are no more elements
+   * @throws NoSuchElementException if there are no more elements
    */
   Object next();
 
   /**
    * Obtain the next element in the list in the reverse direction. Repeated
-   * calls to previous may be used to iterate backwards over the entire list, or
-   * calls to next and previous may be used together to go forwards and
+   * calls to previous may be used to iterate backwards over the entire list,
+   * or calls to next and previous may be used together to go forwards and
    * backwards. Alternating calls to next and previous will return the same
    * element.
    *
    * @return the next element in the list in the reverse direction
-   * @exception NoSuchElementException if there are no more elements
+   * @throws NoSuchElementException if there are no more elements
    */
   Object previous();
 
   /**
    * Find the index of the element that would be returned by a call to next.
+   * If hasNext() returns false, this returns the list size.
    *
-   * @return the index of the element that would be returned by a call to next,
-   *   or list.size() if the iterator is at the end of the list.
+   * @return the index of the element that would be returned by next()
    */
   int nextIndex();
 
   /**
-   * Find the index of the element that would be returned by a call to previous.
+   * Find the index of the element that would be returned by a call to
+   * previous. If hasPrevious() returns false, this returns -1.
    *
-   * @return the index of the element that would be returned by a call to
-   *   previous, or -1 if the iterator is at the beginning of the list.
+   * @return the index of the element that would be returned by previous()
    */
   int previousIndex();
 
   /**
-   * Insert an element into the list at the current position of the iterator.
-   * The element is inserted in between the element that would be returned by
-   * previous and the element that would be returned by next. After the
-   * insertion, a subsequent call to next is unaffected, but a call to
-   * previous returns the item that was added. This operation is optional, it
-   * may throw an UnsupportedOperationException.
+   * Insert an element into the list at the current position of the iterator
+   * (optional operation). The element is inserted in between the element that
+   * would be returned by previous and the element that would be returned by
+   * next. After the insertion, a subsequent call to next is unaffected, but
+   * a call to previous returns the item that was added. The values returned
+   * by nextIndex() and previousIndex() are incremented.
    *
    * @param o the object to insert into the list
-   * @exception ClassCastException the object is of a type which cannot be added
-   *   to this list
-   * @exception IllegalArgumentException some other aspect of the object stops
-   *   it being added to this list
-   * @exception UnsupportedOperationException if this ListIterator does not
-   *   support the add operation
+   * @throws ClassCastException the object is of a type which cannot be added
+   *         to this list
+   * @throws IllegalArgumentException some other aspect of the object stops
+   *         it being added to this list
+   * @throws UnsupportedOperationException if this ListIterator does not
+   *         support the add operation
    */
   void add(Object o);
 
   /**
    * Remove from the list the element last returned by a call to next or
-   * previous. This method may only be called if neither add nor remove have
-   * been called since the last call to next or previous. This operation is
-   * optional, it may throw an UnsupportedOperationException.
+   * previous (optional operation). This method may only be called if neither
+   * add nor remove have been called since the last call to next or previous.
    *
-   * @exception IllegalStateException if neither next or previous have been
-   *   called, or if add or remove has been called since the last call to next
-   *   or previous.
-   * @exception UnsupportedOperationException if this ListIterator does not
-   *   support the remove operation.
+   * @throws IllegalStateException if neither next or previous have been
+   *         called, or if add or remove has been called since the last call
+   *         to next or previous
+   * @throws UnsupportedOperationException if this ListIterator does not
+   *         support the remove operation
    */
   void remove();
 
   /**
    * Replace the element last returned by a call to next or previous with a
-   * given object. This method may only be called if neither add nor remove have
-   * been called since the last call to next or previous. This operation is
-   * optional, it may throw an UnsupportedOperationException.
+   * given object (optional operation). This method may only be called if
+   * neither add nor remove have been called since the last call to next or
+   * previous.
    *
    * @param o the object to replace the element with
-   * @exception ClassCastException the object is of a type which cannot be added
-   *   to this list
-   * @exception IllegalArgumentException some other aspect of the object stops
-   *   it being added to this list
-   * @exception IllegalStateException if neither next or previous have been
-   *   called, or if add or remove has been called since the last call to next
-   *   or previous.
-   * @exception UnsupportedOperationException if this ListIterator does not
-   *   support the set operation.
+   * @throws ClassCastException the object is of a type which cannot be added
+   *         to this list
+   * @throws IllegalArgumentException some other aspect of the object stops
+   *         it being added to this list
+   * @throws IllegalStateException if neither next or previous have been
+   *         called, or if add or remove has been called since the last call
+   *         to next or previous
+   * @throws UnsupportedOperationException if this ListIterator does not
+   *         support the set operation
    */
   void set(Object o);
 }
diff --git a/java/util/Map.java b/java/util/Map.java
index b1d432697..2cd22b32e 100644
--- a/java/util/Map.java
+++ b/java/util/Map.java
@@ -1,5 +1,6 @@
-/* Map.java -- An object that maps keys to values
-   Copyright (C) 1998 Free Software Foundation, Inc.
+/* Map.java: interface Map -- An object that maps keys to values
+             interface Map.Entry -- an Entry in a Map
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -25,34 +26,293 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Doc comments for everything.
-
 package java.util;
 
+/**
+ * An object that maps keys onto values. Keys cannot be duplicated. This
+ * interface replaces the obsolete {@link Dictionary} abstract class.
+ * <p>
+ *
+ * The map has three collection views, which are backed by the map
+ * (modifications on one show up on the other): a set of keys, a collection
+ * of values, and a set of key-value mappings. Some maps have a guaranteed
+ * order, but not all do.
+ * <p>
+ *
+ * Note: Be careful about using mutable keys.  Behavior is unspecified if
+ * a key's comparison behavior is changed after the fact.  As a corollary
+ * to this rule, don't use a Map as one of its own keys or values, as it makes
+ * hashCode and equals have undefined behavior.
+ * <p>
+ *
+ * All maps are recommended to provide a no argument constructor, which builds
+ * an empty map, and one that accepts a Map parameter and copies the mappings
+ * (usually by putAll), to create an equivalent map.  Unfortunately, Java
+ * cannot enforce these suggestions.
+ * <p>
+ *
+ * The map may be unmodifiable, in which case unsupported operations will
+ * throw an UnsupportedOperationException.  Note that some operations may be
+ * safe, such as putAll(m) where m is empty, even if the operation would
+ * normally fail with a non-empty argument.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see HashMap
+ * @see TreeMap
+ * @see Hashtable
+ * @see SortedMap
+ * @see Collection
+ * @see Set
+ * @since 1.2
+ * @status updated to 1.4
+ */
 public interface Map
 {
+  /**
+   * Remove all entries from this Map (optional operation).
+   *
+   * @throws UnsupportedOperationException if clear is not supported
+   */
   public void clear();
+
+  /**
+   * Returns true if this contains a mapping for the given key.
+   *
+   * @param key the key to search for
+   * @return true if the map contains the key
+   * @throws ClassCastException if the key is of an inappropriate type
+   * @throws NullPointerException if key is <code>null</code> but the map
+   *         does not permit null keys
+   */
   public boolean containsKey(Object key);
+
+  /**
+   * Returns true if this contains at least one mapping with the given value.
+   * In other words, returns true if a value v exists where
+   * <code>(value == null ? v == null : value.equals(v))</code>. This usually
+   * requires linear time.
+   *
+   * @param value the value to search for
+   * @return true if the map contains the value
+   */
   public boolean containsValue(Object value);
+
+  /**
+   * Returns a set view of the mappings in this Map.  Each element in the
+   * set is a Map.Entry.  The set is backed by the map, so that changes in
+   * one show up in the other.  Modifications made while an iterator is
+   * in progress cause undefined behavior.  If the set supports removal,
+   * these methods remove the underlying mapping from the map:
+   * <code>Iterator.remove</code>, <code>Set.remove</code>,
+   * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
+   * Element addition, via <code>add</code> or <code>addAll</code>, is
+   * not supported via this set.
+   *
+   * @return the set view of all mapping entries
+   * @see Map.Entry
+   */
   public Set entrySet();
+
+  /**
+   * Compares the specified object with this map for equality. Returns
+   * <code>true</code> if the other object is a Map with the same mappings,
+   * that is,<br>
+   * <code>o instanceof Map && entrySet().equals(((Map) o).entrySet();</code>
+   * This allows comparison of maps, regardless of implementation.
+   *
+   * @param o the object to be compared
+   * @return true if the object equals this map
+   * @see Set#equals(Object)
+   */
   public boolean equals(Object o);
+
+  /**
+   * Returns the value mapped by the given key. Returns <code>null</code> if
+   * there is no mapping.  However, in Maps that accept null values, you
+   * must rely on <code>containsKey</code> to determine if a mapping exists.
+   *
+   * @param key the key to look up
+   * @return the value associated with the key, or null if key not in map
+   * @throws ClassCastException if the key is an inappropriate type
+   * @throws NullPointerException if this map does not accept null keys
+   * @see #containsKey(Object)
+   */
   public Object get(Object key);
+
+  /**
+   * Associates the given key to the given value (optional operation). If the
+   * map already contains the key, its value is replaced. Be aware that in
+   * a map that permits <code>null</code> values, a null return does not
+   * always imply that the mapping was created.
+   *
+   * @param key the key to map
+   * @param value the value to be mapped
+   * @return the previous value of the key, or null if there was no mapping
+   * @throws UnsupportedOperationException if the operation is not supported
+   * @throws ClassCastException if the key or value is of the wrong type
+   * @throws IllegalArgumentException if something about this key or value
+   *         prevents it from existing in this map
+   * @throws NullPointerException if the map forbids null keys or values
+   * @see #containsKey(Object)
+   */
   public Object put(Object key, Object value);
+
+  /**
+   * Returns the hash code for this map. This is the sum of all hashcodes
+   * for each Map.Entry object in entrySet.  This allows comparison of maps,
+   * regardless of implementation, and satisfies the contract of
+   * Object.hashCode.
+   *
+   * @return the hash code
+   * @see Map.Entry#hashCode()
+   */
   public int hashCode();
+
+  /**
+   * Returns true if the map contains no mappings.
+   *
+   * @return true if the map is empty
+   */
   public boolean isEmpty();
+
+  /**
+   * Returns a set view of the keys in this Map.  The set is backed by the
+   * map, so that changes in one show up in the other.  Modifications made
+   * while an iterator is in progress cause undefined behavior.  If the set
+   * supports removal, these methods remove the underlying mapping from
+   * the map: <code>Iterator.remove</code>, <code>Set.remove</code>,
+   * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
+   * Element addition, via <code>add</code> or <code>addAll</code>, is
+   * not supported via this set.
+   *
+   * @return the set view of all keys
+   */
   public Set keySet();
+
+  /**
+   * Copies all entries of the given map to this one (optional operation). If
+   * the map already contains a key, its value is replaced.
+   *
+   * @param m the mapping to load into this map
+   * @throws UnsupportedOperationException if the operation is not supported
+   * @throws ClassCastException if a key or value is of the wrong type
+   * @throws IllegalArgumentException if something about a key or value
+   *         prevents it from existing in this map
+   * @throws NullPointerException if the map forbids null keys or values, or
+   *         if <code>m</code> is null.
+   * @see #put(Object, Object)
+   */
   public void putAll(Map m);
+
+  /**
+   * Removes the mapping for this key if present (optional operation). If
+   * the key is not present, this returns null. Note that maps which permit
+   * null values may also return null if the key was removed.
+   *
+   * @param key the key to remove
+   * @return the value the key mapped to, or null if not present
+   * @throws UnsupportedOperationException if deletion is unsupported
+   */
   public Object remove(Object o);
+
+  /**
+   * Returns the number of key-value mappings in the map. If there are more
+   * than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE.
+   *
+   * @return the number of mappings
+   */
   public int size();
+
+  /**
+   * Returns a collection (or bag) view of the values in this Map.  The
+   * collection is backed by the map, so that changes in one show up in
+   * the other.  Modifications made while an iterator is in progress cause
+   * undefined behavior.  If the collection supports removal, these methods
+   * remove the underlying mapping from the map: <code>Iterator.remove</code>,
+   * <code>Collection.remove</code>, <code>removeAll</code>,
+   * <code>retainAll</code>, and <code>clear</code>. Element addition, via
+   * <code>add</code> or <code>addAll</code>, is not supported via this
+   * collection.
+   *
+   * @return the collection view of all values
+   */
   public Collection values();
 
+  /**
+   * A map entry (key-value pair). The Map.entrySet() method returns a set
+   * view of these objects; there is no other valid way to come across them.
+   * These objects are only valid for the duration of an iteration; in other
+   * words, if you mess with one after modifying the map, you are asking
+   * for undefined behavior.
+   *
+   * @author Original author unknown
+   * @author Eric Blake <ebb9@email.byu.edu>
+   * @see Map
+   * @see Map#entrySet()
+   * @since 1.2
+   * @status updated to 1.4
+   */
   public static interface Entry
   {
+    /**
+     * Get the key corresponding to this entry.
+     *
+     * @return the key
+     */
     public Object getKey();
+
+    /**
+     * Get the value corresponding to this entry. If you already called
+     * Iterator.remove(), this is undefined.
+     *
+     * @return the value
+     */
     public Object getValue();
+
+    /**
+     * Replaces the value with the specified object (optional operation).
+     * This writes through to the map, and is undefined if you already
+     * called Iterator.remove().
+     *
+     * @param value the new value to store
+     * @return the old value
+     * @throws UnsupportedOperationException if the operation is not supported
+     * @throws ClassCastException if the value is of the wrong type
+     * @throws IllegalArgumentException if something about the value
+     *         prevents it from existing in this map
+     * @throws NullPointerException if the map forbids null values
+     */
     public Object setValue(Object value);
+
+    /**
+     * Returns the hash code of the entry.  This is defined as the exclusive-or
+     * of the hashcodes of the key and value (using 0 for null). In other
+     * words, this must be:
+     * <pre>
+     *  (getKey() == null ? 0 : getKey().hashCode()) ^
+     *  (getValue() == null ? 0 : getValue().hashCode())
+     * </pre>
+     *
+     * @return the hash code
+     */
     public int hashCode();
+
+    /**
+     * Compares the specified object with this entry. Returns true only if
+     * the object is a mapping of identical key and value. In other words,
+     * this must be:
+     * <pre>
+     * (o instanceof Map.Entry)
+     * && (getKey() == null ? ((HashMap) o).getKey() == null
+     *                      : getKey().equals(((HashMap) o).getKey()))
+     * && (getValue() == null ? ((HashMap) o).getValue() == null
+     *                        : getValue().equals(((HashMap) o).getValue()))
+     * </pre>
+     *
+     * @param o the object to compare
+     * @return true if it is equal
+     */
     public boolean equals(Object o);
   }
 }
diff --git a/java/util/RandomAccess.java b/java/util/RandomAccess.java
new file mode 100644
index 000000000..dd2b14016
--- /dev/null
+++ b/java/util/RandomAccess.java
@@ -0,0 +1,53 @@
+/* RandomAccess.java -- A tagging interface that lists can use to tailor
+   operations to the correct algorithm
+   Copyright (C) 2001 Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
+
+
+package java.util;
+
+/**
+ * Marker interface used to inform <code>List</code> implementations that
+ * they support fast (usually constant time) random access. This allows
+ * generic list algorithms to tailor their behavior based on the list
+ * type.
+ * <p>
+ *
+ * For example, some sorts are n*log(n) on an array, but decay to quadratic
+ * time on a linked list.  As a rule of thumb, this interface should be
+ * used is this loop:<br>
+ * <code>for (int i = 0, n = list.size(); i &lt; n; i++) list.get(i);</code>
+ * <br>runs faster than this loop:<br>
+ * <code>for (Iterator i = list.iterator(); i.hasNext(); ) i.next();</code>
+ *
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see List
+ * @since 1.4
+ * @status updated to 1.4
+ */
+public interface RandomAccess
+{
+  // Tagging interface only.
+}
diff --git a/java/util/Set.java b/java/util/Set.java
index 3c8c09be3..c22228c21 100644
--- a/java/util/Set.java
+++ b/java/util/Set.java
@@ -1,5 +1,5 @@
 /* Set.java -- A collection that prohibits duplicates
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -25,25 +25,208 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Doc comments for everything.
-
 package java.util;
 
+/**
+ * A collection that contains no duplicates. In other words, for two set
+ * elements e1 and e2, <code>e1.equals(e2)</code> returns false. There
+ * are additional stipulations on <code>add</code>, <code>equals</code>
+ * and <code>hashCode</code>, as well as the requirements that constructors
+ * do not permit duplicate elements. The Set interface is incompatible with
+ * List; you cannot implement both simultaneously.
+ * <p>
+ *
+ * Note: Be careful about using mutable objects in sets.  In particular,
+ * if a mutable object changes to become equal to another set element, you
+ * have violated the contract.  As a special case of this, a Set is not
+ * allowed to be an element of itself, without risking undefined behavior.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Collection
+ * @see List
+ * @see SortedSet
+ * @see HashSet
+ * @see TreeSet
+ * @see LinkedHashSet
+ * @see AbstractSet
+ * @see Collections#singleton(Object)
+ * @see Collections#EMPTY_SET
+ * @since 1.2
+ * @status updated to 1.4
+ */
 public interface Set extends Collection
 {
+  /**
+   * Adds the specified element to the set if it is not already present
+   * (optional operation). In particular, the comparison algorithm is
+   * <code>o == null ? e == null : o.equals(e)</code>. Sets need not permit
+   * all values, and may document what exceptions will be thrown if
+   * a value is not permitted.
+   *
+   * @param o the object to add
+   * @return true if the object was not previously in the set
+   * @throws UnsupportedOperationException if this operation is not allowed
+   * @throws ClassCastException if the class of o prevents it from being added
+   * @throws IllegalArgumentException if some aspect of o prevents it from
+   *         being added
+   * @throws NullPointerException if null is not permitted in this set
+   */
   boolean add(Object o);
+
+  /**
+   * Adds all of the elements of the given collection to this set (optional
+   * operation). If the argument is also a Set, this returns the mathematical
+   * <i>union</i> of the two. The behavior is unspecified if the set is
+   * modified while this is taking place.
+   *
+   * @param c the collection to add
+   * @return true if the set changed as a result
+   * @throws UnsupportedOperationException if this operation is not allowed
+   * @throws ClassCastException if the class of an element prevents it from
+   *         being added
+   * @throws IllegalArgumentException if something about an element prevents
+   *         it from being added
+   * @throws NullPointerException if null is not permitted in this set, or
+   *         if the argument c is null
+   * @see #add(Object)
+   */
   boolean addAll(Collection c);
+
+  /**
+   * Removes all elements from this set (optional operation). This set will
+   * be empty afterwords, unless an exception occurs.
+   *
+   * @throws UnsupportedOperationException if this operation is not allowed
+   */
   void clear();
+
+  /**
+   * Returns true if the set contains the specified element. In other words,
+   * this looks for <code>o == null ? e == null : o.equals(e)</code>.
+   *
+   * @param o the object to look for
+   * @return true if it is found in the set
+   */
   boolean contains(Object o);
+
+  /**
+   * Returns true if this set contains all elements in the specified
+   * collection. If the argument is also a set, this is the <i>subset</i>
+   * relationship.
+   *
+   * @param c the collection to check membership in
+   * @return true if all elements in this set are in c
+   * @throws NullPointerException if c is null
+   * @see #contains(Object)
+   */
   boolean containsAll(Collection c);
+
+  /**
+   * Compares the specified object to this for equality. For sets, the object
+   * must be a set, the two must have the same size, and every element in
+   * one must be in the other.
+   *
+   * @param o the object to compare to
+   * @return true if it is an equal set
+   */
   boolean equals(Object o);
+
+  /**
+   * Returns the hash code for this set. In order to satisfy the contract of
+   * equals, this is the sum of the hashcode of all elements in the set.
+   *
+   * @return the sum of the hashcodes of all set elements
+   */
   int hashCode();
+
+  /**
+   * Returns true if the set contains no elements.
+   *
+   * @return true if the set is empty
+   */
   boolean isEmpty();
+
+  /**
+   * Returns an iterator over the set.  The iterator has no specific order,
+   * unless further specified.
+   *
+   * @return a set iterator
+   */
   Iterator iterator();
+
+  /**
+   * Removes the specified element from this set (optional operation). If
+   * an element e exists, <code>o == null ? e == null : o.equals(e)</code>,
+   * it is removed from the set.
+   *
+   * @param o the object to remove
+   * @return true if the set changed (an object was removed)
+   * @throws UnsupportedOperationException if this operation is not allowed
+   */
   boolean remove(Object o);
+
+  /**
+   * Removes from this set all elements contained in the specified collection
+   * (optional operation). If the argument is a set, this returns the
+   * <i>asymmetric set difference</i> of the two sets.
+   *
+   * @param c the collection to remove from this set
+   * @return true if this set changed as a result
+   * @throws UnsupportedOperationException if this operation is not allowed
+   * @throws NullPointerException if c is null
+   * @see #remove(Object)
+   */
   boolean removeAll(Collection c);
+
+  /**
+   * Retains only the elements in this set that are also in the specified
+   * collection (optional operation). If the argument is also a set, this
+   * performs the <i>intersection</i> of the two sets.
+   *
+   * @param c the collection to keep
+   * @return true if this set was modified
+   * @throws UnsupportedOperationException if this operation is not allowed
+   * @throws NullPointerException if c is null
+   * @see #remove(Object)
+   */
   boolean retainAll(Collection c);
+
+  /**
+   * Returns the number of elements in the set. If there are more
+   * than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE. This is
+   * the <i>cardinality</i> of the set.
+   *
+   * @return the number of elements
+   */
   int size();
+
+  /**
+   * Returns an array containing the elements of this set. If the set
+   * makes a guarantee about iteration order, the array has the same
+   * order. The array is distinct from the set; modifying one does not
+   * affect the other.
+   *
+   * @return an array of this set's elements
+   * @see #toArray(Object[])
+   */
   Object[] toArray();
+
+  /**
+   * Returns an array containing the elements of this set, of the same runtime
+   * type of the argument. If the given set is large enough, it is reused,
+   * and null is inserted in the first unused slot. Otherwise, reflection
+   * is used to build a new array. If the set makes a guarantee about iteration
+   * order, the array has the same order. The array is distinct from the set;
+   * modifying one does not affect the other.
+   *
+   * @param a the array to determine the return type; if it is big enough
+   *        it is used and returned
+   * @return an array holding the elements of the set
+   * @throws ArrayStoreException if the runtime type of a is not a supertype
+   *         of all elements in the set
+   * @throws NullPointerException if a is null
+   * @see #toArray()
+   */
+  Object[] toArray(Object[] a);
 }
diff --git a/java/util/SortedMap.java b/java/util/SortedMap.java
index 2de57a175..5be6c19d9 100644
--- a/java/util/SortedMap.java
+++ b/java/util/SortedMap.java
@@ -1,5 +1,5 @@
 /* SortedMap.java -- A map that makes guarantees about the order of its keys
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -25,17 +25,135 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Doc comments for everything.
-
 package java.util;
 
+/**
+ * A map which guarantees its key's iteration order. The entries in the
+ * map are related by the <i>natural ordering</i> of the keys if they
+ * are Comparable, or by the provided Comparator.  Additional operations
+ * take advantage of the sorted nature of the map.
+ * <p>
+ *
+ * All keys entered in the map must be mutually comparable; in other words,
+ * <code>k1.compareTo(k2)</code> or <code>comparator.compare(k1, k2)</code>
+ * must not throw a ClassCastException. The ordering must be <i>consistent
+ * with equals</i> (see {@link Comparator} for this definition), if the
+ * map is to obey the general contract of the Map interface.  If not,
+ * the results are well-defined, but probably not what you wanted.
+ * <p>
+ *
+ * It is recommended that all implementing classes provide four constructors:
+ * 1) one that takes no arguments and builds an empty map sorted by natural
+ * order of the keys; 2) one that takes a Comparator for the sorting order;
+ * 3) one that takes a Map and sorts according to the natural order of its
+ * keys; and 4) one that takes a SortedMap and sorts by the same comparator.
+ * Unfortunately, the Java language does not provide a way to enforce this.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Map
+ * @see TreeMap
+ * @see SortedSet
+ * @see Comparable
+ * @see Comparator
+ * @see Collection
+ * @see ClassCastException
+ * @since 1.2
+ * @status updated to 1.4
+ */
 public interface SortedMap extends Map
 {
+  /**
+   * Returns the comparator used in sorting this map, or null if it is
+   * the keys' natural ordering.
+   *
+   * @return the sorting comparator
+   */
   Comparator comparator();
+
+  /**
+   * Returns the first (lowest sorted) key in the map.
+   *
+   * @return the first key
+   */
   Object firstKey();
+
+  /**
+   * Returns a view of the portion of the map strictly less than toKey. The
+   * view is backed by this map, so changes in one show up in the other.
+   * The submap supports all optional operations of the original.
+   * <p>
+   *
+   * The returned map throws an IllegalArgumentException any time a key is
+   * used which is out of the range of toKey. Note that the endpoint is not
+   * included; if you want the endpoint, pass the successor object in to
+   * toKey.  For example, for Strings, you can request
+   * <code>headMap(limit + "\0")</code>.
+   *
+   * @param toKey the exclusive upper range of the submap
+   * @return the submap
+   * @throws ClassCastException if toKey is not comparable to the map contents
+   * @throws IllegalArgumentException if this is a subMap, and toKey is out
+   *         of range
+   * @throws NullPointerException if toKey is null but the map does not allow
+   *         null keys
+   */
   SortedMap headMap(Object toKey);
+
+  /**
+   * Returns the last (highest sorted) key in the map.
+   *
+   * @return the last key
+   */
   Object lastKey();
+
+  /**
+   * Returns a view of the portion of the map greater than or equal to
+   * fromKey, and strictly less than toKey. The view is backed by this map,
+   * so changes in one show up in the other. The submap supports all
+   * optional operations of the original.
+   * <p>
+   *
+   * The returned map throws an IllegalArgumentException any time a key is
+   * used which is out of the range of fromKey and toKey. Note that the
+   * lower endpoint is included, but the upper is not; if you want to
+   * change the inclusion or exclusion of an endpoint, pass the successor
+   * object in instead.  For example, for Strings, you can request
+   * <code>subMap(lowlimit + "\0", highlimit + "\0")</code> to reverse
+   * the inclusiveness of both endpoints.
+   *
+   * @param fromKey the inclusive lower range of the submap
+   * @param toKey the exclusive upper range of the submap
+   * @return the submap
+   * @throws ClassCastException if fromKey or toKey is not comparable to
+   *         the map contents
+   * @throws IllegalArgumentException if this is a subMap, and fromKey or
+   *         toKey is out of range
+   * @throws NullPointerException if fromKey or toKey is null but the map
+   *         does not allow null keys
+   */
   SortedMap subMap(Object fromKey, Object toKey);
+
+  /**
+   * Returns a view of the portion of the map greater than or equal to
+   * fromKey. The view is backed by this map, so changes in one show up
+   * in the other. The submap supports all optional operations of the original.
+   * <p>
+   *
+   * The returned map throws an IllegalArgumentException any time a key is
+   * used which is out of the range of fromKey. Note that the endpoint is
+   * included; if you do not want the endpoint, pass the successor object in
+   * to fromKey.  For example, for Strings, you can request
+   * <code>tailMap(limit + "\0")</code>.
+   *
+   * @param fromKey the inclusive lower range of the submap
+   * @return the submap
+   * @throws ClassCastException if fromKey is not comparable to the map
+   *         contents
+   * @throws IllegalArgumentException if this is a subMap, and fromKey is out
+   *         of range
+   * @throws NullPointerException if fromKey is null but the map does not allow
+   *         null keys
+   */
   SortedMap tailMap(Object fromKey);
 }
diff --git a/java/util/SortedSet.java b/java/util/SortedSet.java
index f72dd66ef..ea39811dd 100644
--- a/java/util/SortedSet.java
+++ b/java/util/SortedSet.java
@@ -1,6 +1,6 @@
-/* SortedSet.java -- A set that makes guarantees about the order of its 
+/* SortedSet.java -- A set that makes guarantees about the order of its
    elements
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -26,17 +26,137 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Doc comments for everything.
-
 package java.util;
 
+/**
+ * A set which guarantees its iteration order. The elements in the set
+ * are related by the <i>natural ordering</i> if they are Comparable, or
+ * by the provided Comparator.  Additional operations take advantage of
+ * the sorted nature of the set.
+ * <p>
+ *
+ * All elements entered in the set must be mutually comparable; in other words,
+ * <code>k1.compareTo(k2)</code> or <code>comparator.compare(k1, k2)</code>
+ * must not throw a ClassCastException. The ordering must be <i>consistent
+ * with equals</i> (see {@link Comparator} for this definition), if the
+ * map is to obey the general contract of the Set interface.  If not,
+ * the results are well-defined, but probably not what you wanted.
+ * <p>
+ *
+ * It is recommended that all implementing classes provide four constructors:
+ * 1) one that takes no arguments and builds an empty set sorted by natural
+ * order of the elements; 2) one that takes a Comparator for the sorting order;
+ * 3) one that takes a Set and sorts according to the natural order of its
+ * elements; and 4) one that takes a SortedSet and sorts by the same
+ * comparator. Unfortunately, the Java language does not provide a way to
+ * enforce this.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Set
+ * @see TreeSet
+ * @see SortedMap
+ * @see Collection
+ * @see Comparable
+ * @see Comparator
+ * @see ClassCastException
+ * @since 1.2
+ * @status updated to 1.4
+ */
 public interface SortedSet extends Set
 {
+  /**
+   * Returns the comparator used in sorting this set, or null if it is
+   * the elements' natural ordering.
+   *
+   * @return the sorting comparator
+   */
   Comparator comparator();
+
+  /**
+   * Returns the first (lowest sorted) element in the map.
+   *
+   * @return the first element
+   */
   Object first();
+
+  /**
+   * Returns a view of the portion of the set strictly less than toElement. The
+   * view is backed by this set, so changes in one show up in the other.
+   * The subset supports all optional operations of the original.
+   * <p>
+   *
+   * The returned set throws an IllegalArgumentException any time an element is
+   * used which is out of the range of toElement. Note that the endpoint is not
+   * included; if you want the endpoint, pass the successor object in to
+   * toElement.  For example, for Strings, you can request
+   * <code>headSet(limit + "\0")</code>.
+   *
+   * @param toElement the exclusive upper range of the subset
+   * @return the subset
+   * @throws ClassCastException if toElement is not comparable to the set
+   *         contents
+   * @throws IllegalArgumentException if this is a subSet, and toElement is out
+   *         of range
+   * @throws NullPointerException if toElement is null but the map does not
+   *         allow null elements
+   */
   SortedSet headSet(Object toElement);
+
+  /**
+   * Returns the last (highest sorted) element in the map.
+   *
+   * @return the last element
+   */
   Object last();
+
+  /**
+   * Returns a view of the portion of the set greater than or equal to
+   * fromElement, and strictly less than toElement. The view is backed by
+   * this set, so changes in one show up in the other. The subset supports all
+   * optional operations of the original.
+   * <p>
+   *
+   * The returned set throws an IllegalArgumentException any time an element is
+   * used which is out of the range of fromElement and toElement. Note that the
+   * lower endpoint is included, but the upper is not; if you want to
+   * change the inclusion or exclusion of an endpoint, pass the successor
+   * object in instead.  For example, for Strings, you can request
+   * <code>subSet(lowlimit + "\0", highlimit + "\0")</code> to reverse
+   * the inclusiveness of both endpoints.
+   *
+   * @param fromElement the inclusive lower range of the subset
+   * @param toElement the exclusive upper range of the subset
+   * @return the subset
+   * @throws ClassCastException if fromElement or toElement is not comparable
+   *         to the set contents
+   * @throws IllegalArgumentException if this is a subSet, and fromElement or
+   *         toElement is out of range
+   * @throws NullPointerException if fromElement or toElement is null but the
+   *         set does not allow null elements
+   */
   SortedSet subSet(Object fromElement, Object toElement);
+
+  /**
+   * Returns a view of the portion of the set greater than or equal to
+   * fromElement. The view is backed by this set, so changes in one show up
+   * in the other. The subset supports all optional operations of the original.
+   * <p>
+   *
+   * The returned set throws an IllegalArgumentException any time an element is
+   * used which is out of the range of fromElement. Note that the endpoint is
+   * included; if you do not want the endpoint, pass the successor object in
+   * to fromElement.  For example, for Strings, you can request
+   * <code>tailSet(limit + "\0")</code>.
+   *
+   * @param fromElement the inclusive lower range of the subset
+   * @return the subset
+   * @throws ClassCastException if fromElement is not comparable to the set
+   *         contents
+   * @throws IllegalArgumentException if this is a subSet, and fromElement is
+   *         out of range
+   * @throws NullPointerException if fromElement is null but the set does not
+   *         allow null elements
+   */
   SortedSet tailSet(Object fromElement);
 }