2004-11-07 Andrew John Hughes <gnu_andrew@member.fsf.org>

       * java/util/Collections.java
       Added documentation.
       * java/util/SortedMap.java
       Clarified some method examples.
       * java/util/SortedSet.java
       Clarified some method examples.

From-SVN: r90227

4 files changed, 1827 insertions, 38 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index 8a5a54c..2521bf0 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,5 +1,14 @@
 2004-11-07  Andrew John Hughes <gnu_andrew@member.fsf.org>
 
+	* java/util/Collections.java
+	Added documentation.
+	* java/util/SortedMap.java
+	Clarified some method examples.
+	* java/util/SortedSet.java
+	Clarified some method examples.
+
+2004-11-07  Andrew John Hughes <gnu_andrew@member.fsf.org>
+
 	* java/util/Currency.java
 	Documented variables and methods more fully.
 	Caches the currency instances, so that a request
diff --git a/libjava/java/util/Collections.java b/libjava/java/util/Collections.java
index 5ae4b40..6da8429 100644
--- a/libjava/java/util/Collections.java
+++ b/libjava/java/util/Collections.java
@@ -75,7 +75,7 @@ public class Collections
   /**
    * Constant used to decide cutoff for when a non-RandomAccess list should
    * be treated as sequential-access. Basically, quadratic behavior is
-   * acceptible for small lists when the overhead is so small in the first
+   * acceptable for small lists when the overhead is so small in the first
    * place. I arbitrarily set it to 16, so it may need some tuning.
    */
   private static final int LARGE_LIST_SIZE = 16;
@@ -88,7 +88,7 @@ public class Collections
    * and exceeds a large (unspecified) size should be sequential.
    *
    * @param l the list to check
-   * @return true if it should be treated as sequential-access
+   * @return <code>true</code> if it should be treated as sequential-access
    */
   private static boolean isSequential(List l)
   {
@@ -131,6 +131,7 @@ public class Collections
 
     /**
      * The size: always 0!
+     * @return 0.
      */
     public int size()
     {
@@ -139,6 +140,7 @@ public class Collections
 
     /**
      * Returns an iterator that does not iterate.
+     * @return A non-iterating iterator.
      */
     // This is really cheating! I think it's perfectly valid, though.
     public Iterator iterator()
@@ -150,6 +152,8 @@ public class Collections
     // advantage by not allocating unnecessary iterators in AbstractSet.
     /**
      * The empty set never contains anything.
+     * @param o The object to search for.
+     * @return <code>false</code>.
      */
     public boolean contains(Object o)
     {
@@ -158,6 +162,9 @@ public class Collections
 
     /**
      * This is true only if the given collection is also empty.
+     * @param c The collection of objects which are to be compared
+     *          against the members of this set.
+     * @return <code>true</code> if c is empty.
      */
     public boolean containsAll(Collection c)
     {
@@ -166,6 +173,8 @@ public class Collections
 
     /**
      * Equal only if the other set is empty.
+     * @param o The object to compare with this set.
+     * @return <code>true</code> if o is an empty instance of <code>Set</code>.
      */
     public boolean equals(Object o)
     {
@@ -174,6 +183,7 @@ public class Collections
 
     /**
      * The hashcode is always 0.
+     * @return 0.
      */
     public int hashCode()
     {
@@ -181,7 +191,9 @@ public class Collections
     }
 
     /**
-     * Always succeeds with false result.
+     * Always succeeds with a <code>false</code> result.
+     * @param o The object to remove.
+     * @return <code>false</code>.
      */
     public boolean remove(Object o)
     {
@@ -189,7 +201,10 @@ public class Collections
     }
 
     /**
-     * Always succeeds with false result.
+     * Always succeeds with a <code>false</code> result.
+     * @param c The collection of objects which should
+     *          all be removed from this set.
+     * @return <code>false</code>.
      */
     public boolean removeAll(Collection c)
     {
@@ -197,7 +212,10 @@ public class Collections
     }
 
     /**
-     * Always succeeds with false result.
+     * Always succeeds with a <code>false</code> result.
+     * @param c The collection of objects which should
+     *          all be retained within this set.
+     * @return <code>false</code>.
      */
     public boolean retainAll(Collection c)
     {
@@ -206,6 +224,7 @@ public class Collections
 
     /**
      * The array is always empty.
+     * @return A new array with a size of 0.
      */
     public Object[] toArray()
     {
@@ -214,6 +233,9 @@ public class Collections
 
     /**
      * We don't even need to use reflection!
+     * @param a An existing array, which can be empty.
+     * @return The original array with any existing
+     *         initial element set to null.
      */
     public Object[] toArray(Object[] a)
     {
@@ -224,6 +246,8 @@ public class Collections
 
     /**
      * The string never changes.
+     *
+     * @return the string "[]".
      */
     public String toString()
     {
@@ -261,6 +285,7 @@ public class Collections
 
     /**
      * The size is always 0.
+     * @return 0.
      */
     public int size()
     {
@@ -268,7 +293,13 @@ public class Collections
     }
 
     /**
-     * No matter the index, it is out of bounds.
+     * No matter the index, it is out of bounds.  This
+     * method never returns, throwing an exception instead.
+     *
+     * @param index The index of the element to retrieve.
+     * @return the object at the specified index.
+     * @throws IndexOutofBoundsException as any given index
+     *         is outside the bounds of an empty array.
      */
     public Object get(int index)
     {
@@ -279,6 +310,8 @@ public class Collections
     // advantage by not allocating unnecessary iterators in AbstractList.
     /**
      * Never contains anything.
+     * @param o The object to search for.
+     * @return <code>false</code>.
      */
     public boolean contains(Object o)
     {
@@ -287,6 +320,9 @@ public class Collections
 
     /**
      * This is true only if the given collection is also empty.
+     * @param c The collection of objects, which should be compared
+     *          against the members of this list.
+     * @return <code>true</code> if c is also empty. 
      */
     public boolean containsAll(Collection c)
     {
@@ -294,7 +330,10 @@ public class Collections
     }
 
     /**
-     * Equal only if the other set is empty.
+     * Equal only if the other list is empty.
+     * @param o The object to compare against this list.
+     * @return <code>true</code> if o is also an empty instance of
+     *         <code>List</code>.
      */
     public boolean equals(Object o)
     {
@@ -303,6 +342,7 @@ public class Collections
 
     /**
      * The hashcode is always 1.
+     * @return 1.
      */
     public int hashCode()
     {
@@ -311,6 +351,8 @@ public class Collections
 
     /**
      * Returns -1.
+     * @param o The object to search for.
+     * @return -1.
      */
     public int indexOf(Object o)
     {
@@ -319,6 +361,8 @@ public class Collections
 
     /**
      * Returns -1.
+     * @param o The object to search for.
+     * @return -1.
      */
     public int lastIndexOf(Object o)
     {
@@ -326,7 +370,9 @@ public class Collections
     }
 
     /**
-     * Always succeeds with false result.
+     * Always succeeds with <code>false</code> result.
+     * @param o The object to remove.
+     * @return -1.
      */
     public boolean remove(Object o)
     {
@@ -334,7 +380,10 @@ public class Collections
     }
 
     /**
-     * Always succeeds with false result.
+     * Always succeeds with <code>false</code> result.
+     * @param c The collection of objects which should
+     *          all be removed from this list.
+     * @return <code>false</code>.
      */
     public boolean removeAll(Collection c)
     {
@@ -342,7 +391,10 @@ public class Collections
     }
 
     /**
-     * Always succeeds with false result.
+     * Always succeeds with <code>false</code> result.
+     * @param c The collection of objects which should
+     *          all be retained within this list.
+     * @return <code>false</code>.
      */
     public boolean retainAll(Collection c)
     {
@@ -351,6 +403,7 @@ public class Collections
 
     /**
      * The array is always empty.
+     * @return A new array with a size of 0.
      */
     public Object[] toArray()
     {
@@ -359,6 +412,9 @@ public class Collections
 
     /**
      * We don't even need to use reflection!
+     * @param a An existing array, which can be empty.
+     * @return The original array with any existing
+     *         initial element set to null.
      */
     public Object[] toArray(Object[] a)
     {
@@ -369,6 +425,8 @@ public class Collections
 
     /**
      * The string never changes.
+     *
+     * @return the string "[]".
      */
     public String toString()
     {
@@ -405,6 +463,7 @@ public class Collections
 
     /**
      * There are no entries.
+     * @return The empty set.
      */
     public Set entrySet()
     {
@@ -415,6 +474,8 @@ public class Collections
     // advantage by not allocating unnecessary iterators in AbstractMap.
     /**
      * No entries!
+     * @param key The key to search for.
+     * @return <code>false</code>.
      */
     public boolean containsKey(Object key)
     {
@@ -423,6 +484,8 @@ public class Collections
 
     /**
      * No entries!
+     * @param value The value to search for.
+     * @return <code>false</code>.
      */
     public boolean containsValue(Object value)
     {
@@ -431,6 +494,9 @@ public class Collections
 
     /**
      * Equal to all empty maps.
+     * @param o The object o to compare against this map.
+     * @return <code>true</code> if o is also an empty instance of
+     *         <code>Map</code>.
      */
     public boolean equals(Object o)
     {
@@ -439,6 +505,8 @@ public class Collections
 
     /**
      * No mappings, so this returns null.
+     * @param o The key of the object to retrieve.
+     * @return null. 
      */
     public Object get(Object o)
     {
@@ -447,6 +515,7 @@ public class Collections
 
     /**
      * The hashcode is always 0.
+     * @return 0.
      */
     public int hashCode()
     {
@@ -455,6 +524,7 @@ public class Collections
 
     /**
      * No entries.
+     * @return The empty set.
      */
     public Set keySet()
     {
@@ -463,6 +533,8 @@ public class Collections
 
     /**
      * Remove always succeeds, with null result.
+     * @param o The key of the mapping to remove.
+     * @return null, as there is never a mapping for o.
      */
     public Object remove(Object o)
     {
@@ -471,6 +543,7 @@ public class Collections
 
     /**
      * Size is always 0.
+     * @return 0.
      */
     public int size()
     {
@@ -480,6 +553,7 @@ public class Collections
     /**
      * No entries. Technically, EMPTY_SET, while more specific than a general
      * Collection, will work. Besides, that's what the JDK uses!
+     * @return The empty set.
      */
     public Collection values()
     {
@@ -488,6 +562,8 @@ public class Collections
 
     /**
      * The string never changes.
+     *
+     * @return the string "[]".
      */
     public String toString()
     {
@@ -664,10 +740,24 @@ public class Collections
     final Iterator i = c.iterator();
     return new Enumeration()
     {
+      /**
+       * Returns <code>true</code> if there are more elements to
+       * be enumerated.
+       *
+       * @return The result of <code>hasNext()</code>
+       *         called on the underlying iterator.
+       */
       public final boolean hasMoreElements()
       {
 	return i.hasNext();
       }
+
+      /**
+       * Returns the next element to be enumerated.
+       *
+       * @return The result of <code>next()</code>
+       *         called on the underlying iterator.
+       */
       public final Object nextElement()
       {
 	return i.next();
@@ -907,6 +997,7 @@ public class Collections
 
     /**
      * The size is fixed.
+     * @return The size of the list.
      */
     public int size()
     {
@@ -915,6 +1006,9 @@ public class Collections
 
     /**
      * The same element is returned.
+     * @param index The index of the element to be returned (irrelevant
+     *        as the list contains only copies of <code>element</code>).
+     * @return The element used by this list.
      */
     public Object get(int index)
     {
@@ -927,6 +1021,8 @@ public class Collections
     // advantage by not allocating unnecessary iterators in AbstractList.
     /**
      * This list only contains one element.
+     * @param o The object to search for.
+     * @return <code>true</code> if o is the element used by this list.
      */
     public boolean contains(Object o)
     {
@@ -935,6 +1031,8 @@ public class Collections
 
     /**
      * The index is either 0 or -1.
+     * @param o The object to find the index of.
+     * @return 0 if <code>o == element</code>, -1 if not.
      */
     public int indexOf(Object o)
     {
@@ -943,6 +1041,9 @@ public class Collections
 
     /**
      * The index is either n-1 or -1.
+     * @param o The object to find the last index of.
+     * @return The last index in the list if <code>o == element</code>,
+     *         -1 if not.
      */
     public int lastIndexOf(Object o)
     {
@@ -951,6 +1052,11 @@ public class Collections
 
     /**
      * A subList is just another CopiesList.
+     * @param from The starting bound of the sublist.
+     * @param to The ending bound of the sublist.
+     * @return A list of copies containing <code>from - to</code>
+     *         elements, all of which are equal to the element
+     *         used by this list.
      */
     public List subList(int from, int to)
     {
@@ -961,6 +1067,8 @@ public class Collections
 
     /**
      * The array is easy.
+     * @return An array of size n filled with copies of
+     *         the element used by this list.
      */
     public Object[] toArray()
     {
@@ -971,6 +1079,7 @@ public class Collections
 
     /**
      * The string is easy to generate.
+     * @return A string representation of the list.
      */
     public String toString()
     {
@@ -990,12 +1099,12 @@ public class Collections
    * @param list the list to iterate over
    * @param oldval the element to replace
    * @param newval the new value for the element
-   * @return true if a replacement occurred
+   * @return <code>true</code> if a replacement occurred.
    * @throws UnsupportedOperationException if the list iterator does not allow
    *         for the set operation
-   * @throws ClassCastException newval is of a type which cannot be added
+   * @throws ClassCastException if newval is of a type which cannot be added
    *         to the list
-   * @throws IllegalArgumentException some other aspect of newval stops
+   * @throws IllegalArgumentException if some other aspect of newval stops
    *         it being added to the list
    * @since 1.4
    */
@@ -1303,6 +1412,7 @@ public class Collections
 
     /**
      * The size: always 1!
+     * @return 1.
      */
     public int size()
     {
@@ -1316,13 +1426,30 @@ public class Collections
     {
       return new Iterator()
       {
+	/**
+	 * Flag to indicate whether or not the element has
+	 * been retrieved.
+	 */
         private boolean hasNext = true;
 
+	/**
+	 * Returns <code>true</code> if elements still remain to be
+	 * iterated through.
+	 *
+	 * @return <code>true</code> if the element has not yet been returned.
+	 */
         public boolean hasNext()
         {
           return hasNext;
         }
 
+	/**
+	 * Returns the element.
+	 *
+	 * @return The element used by this singleton.
+	 * @throws NoSuchElementException if the object
+	 *         has already been retrieved.
+	 */ 
         public Object next()
         {
           if (hasNext)
@@ -1334,6 +1461,15 @@ public class Collections
             throw new NoSuchElementException();
         }
 
+	/**
+	 * Removes the element from the singleton.
+	 * As this set is immutable, this will always
+	 * throw an exception.
+	 *
+	 * @throws UnsupportedOperationException as the
+	 *         singleton set doesn't support
+	 *         <code>remove()</code>.
+	 */
         public void remove()
         {
           throw new UnsupportedOperationException();
@@ -1345,6 +1481,9 @@ public class Collections
     // advantage by not allocating unnecessary iterators in AbstractSet.
     /**
      * The set only contains one element.
+     *
+     * @param o The object to search for.
+     * @return <code>true</code> if o == the element of the singleton.
      */
     public boolean contains(Object o)
     {
@@ -1353,6 +1492,10 @@ public class Collections
 
     /**
      * This is true if the other collection only contains the element.
+     *
+     * @param c A collection to compare against this singleton.
+     * @return <code>true</code> if c only contains either no elements or
+     *         elements equal to the element in this singleton.
      */
     public boolean containsAll(Collection c)
     {
@@ -1366,6 +1509,8 @@ public class Collections
 
     /**
      * The hash is just that of the element.
+     * 
+     * @return The hashcode of the element.
      */
     public int hashCode()
     {
@@ -1374,6 +1519,8 @@ public class Collections
 
     /**
      * Returning an array is simple.
+     *
+     * @return An array containing the element.
      */
     public Object[] toArray()
     {
@@ -1382,6 +1529,9 @@ public class Collections
 
     /**
      * Obvious string.
+     *
+     * @return The string surrounded by enclosing
+     *         square brackets.
      */
     public String toString()
     {
@@ -1435,6 +1585,7 @@ public class Collections
 
     /**
      * The size: always 1!
+     * @return 1.
      */
     public int size()
     {
@@ -1443,6 +1594,12 @@ public class Collections
 
     /**
      * Only index 0 is valid.
+     * @param index The index of the element
+     *        to retrieve.
+     * @return The singleton's element if the
+     *         index is 0.
+     * @throws IndexOutOfBoundsException if
+     *         index is not 0.
      */
     public Object get(int index)
     {
@@ -1455,6 +1612,9 @@ public class Collections
     // advantage by not allocating unnecessary iterators in AbstractList.
     /**
      * The set only contains one element.
+     *
+     * @param o The object to search for.
+     * @return <code>true</code> if o == the singleton element.
      */
     public boolean contains(Object o)
     {
@@ -1463,6 +1623,10 @@ public class Collections
 
     /**
      * This is true if the other collection only contains the element.
+     *
+     * @param c A collection to compare against this singleton.
+     * @return <code>true</code> if c only contains either no elements or
+     *         elements equal to the element in this singleton.
      */
     public boolean containsAll(Collection c)
     {
@@ -1476,6 +1640,9 @@ public class Collections
 
     /**
      * Speed up the hashcode computation.
+     *
+     * @return The hashcode of the list, based
+     *         on the hashcode of the singleton element.
      */
     public int hashCode()
     {
@@ -1484,6 +1651,9 @@ public class Collections
 
     /**
      * Either the list has it or not.
+     *
+     * @param o The object to find the first index of.
+     * @return 0 if o is the singleton element, -1 if not.
      */
     public int indexOf(Object o)
     {
@@ -1492,6 +1662,9 @@ public class Collections
 
     /**
      * Either the list has it or not.
+     *
+     * @param o The object to find the last index of.
+     * @return 0 if o is the singleton element, -1 if not.
      */
     public int lastIndexOf(Object o)
     {
@@ -1500,6 +1673,14 @@ public class Collections
 
     /**
      * Sublists are limited in scope.
+     * 
+     * @param from The starting bound for the sublist.
+     * @param to The ending bound for the sublist.
+     * @return Either an empty list if both bounds are
+     *         0 or 1, or this list if the bounds are 0 and 1.
+     * @throws IllegalArgumentException if <code>from > to</code>
+     * @throws IndexOutOfBoundsException if either bound is greater
+     *         than 1.
      */
     public List subList(int from, int to)
     {
@@ -1514,6 +1695,8 @@ public class Collections
 
     /**
      * Returning an array is simple.
+     *
+     * @return An array containing the element.
      */
     public Object[] toArray()
     {
@@ -1522,6 +1705,9 @@ public class Collections
 
     /**
      * Obvious string.
+     *
+     * @return The string surrounded by enclosing
+     *         square brackets. 
      */
     public String toString()
     {
@@ -1588,12 +1774,23 @@ public class Collections
 
     /**
      * There is a single immutable entry.
+     *
+     * @return A singleton containing the map entry.
      */
     public Set entrySet()
     {
       if (entries == null)
         entries = singleton(new AbstractMap.BasicMapEntry(k, v)
         {
+	  /**
+	   * Sets the value of the map entry to the supplied value.
+	   * An exception is always thrown, as the map is immutable.
+	   *
+	   * @param o The new value.
+	   * @return The old value.
+	   * @throws UnsupportedOperationException as setting the value
+	   *         is not supported.
+	   */
           public Object setValue(Object o)
           {
             throw new UnsupportedOperationException();
@@ -1606,6 +1803,10 @@ public class Collections
     // advantage by not allocating unnecessary iterators in AbstractMap.
     /**
      * Single entry.
+     *
+     * @param key The key to look for.
+     * @return <code>true</code> if the key is the same as the one used by
+     *         this map.
      */
     public boolean containsKey(Object key)
     {
@@ -1614,6 +1815,10 @@ public class Collections
 
     /**
      * Single entry.
+     *
+     * @param value The value to look for.
+     * @return <code>true</code> if the value is the same as the one used by
+     *         this map.
      */
     public boolean containsValue(Object value)
     {
@@ -1622,6 +1827,10 @@ public class Collections
 
     /**
      * Single entry.
+     *
+     * @param key The key of the value to be retrieved.
+     * @return The singleton value if the key is the same as the
+     *         singleton key, null otherwise.
      */
     public Object get(Object key)
     {
@@ -1630,6 +1839,9 @@ public class Collections
 
     /**
      * Calculate the hashcode directly.
+     *
+     * @return The hashcode computed from the singleton key
+     *         and the singleton value.
      */
     public int hashCode()
     {
@@ -1638,6 +1850,8 @@ public class Collections
 
     /**
      * Return the keyset.
+     *
+     * @return A singleton containing the key.
      */
     public Set keySet()
     {
@@ -1648,6 +1862,8 @@ public class Collections
 
     /**
      * The size: always 1!
+     *
+     * @return 1.
      */
     public int size()
     {
@@ -1657,6 +1873,8 @@ public class Collections
     /**
      * Return the values. Technically, a singleton, while more specific than
      * a general Collection, will work. Besides, that's what the JDK uses!
+     *
+     * @return A singleton containing the value.
      */
     public Collection values()
     {
@@ -1667,6 +1885,9 @@ public class Collections
 
     /**
      * Obvious string.
+     *
+     * @return A string containing the string representations of the key
+     *         and its associated value.
      */
     public String toString()
     {
@@ -1827,6 +2048,22 @@ public class Collections
       mutex = sync;
     }
 
+    /**
+     * Adds the object to the underlying collection, first
+     * obtaining a lock on the mutex.
+     *
+     * @param o The object to add.
+     * @return <code>true</code> if the collection was modified as a result
+     *         of this action.
+     * @throws UnsupportedOperationException if this collection does not
+     *         support the add operation.
+     * @throws ClassCastException if o cannot be added to this collection due
+     *         to its type.
+     * @throws NullPointerException if o is null and this collection doesn't
+     *         support the addition of null values.
+     * @throws IllegalArgumentException if o cannot be added to this
+     *         collection for some other reason.
+     */
     public boolean add(Object o)
     {
       synchronized (mutex)
@@ -1835,6 +2072,23 @@ public class Collections
         }
     }
 
+    /**
+     * Adds the objects in col to the underlying collection, first
+     * obtaining a lock on the mutex.
+     *
+     * @param col The collection to take the new objects from.
+     * @return <code>true</code> if the collection was modified as a result
+     *          of this action.
+     * @throws UnsupportedOperationException if this collection does not
+     *         support the addAll operation.
+     * @throws ClassCastException if some element of col cannot be added to this
+     *         collection due to its type.
+     * @throws NullPointerException if some element of col is null and this
+     *         collection does not support the addition of null values.
+     * @throws NullPointerException if col itself is null.
+     * @throws IllegalArgumentException if some element of col cannot be added
+     *         to this collection for some other reason.
+     */
     public boolean addAll(Collection col)
     {
       synchronized (mutex)
@@ -1843,6 +2097,13 @@ public class Collections
         }
     }
 
+    /**
+     * Removes all objects from the underlying collection,
+     * first obtaining a lock on the mutex.
+     *
+     * @throws UnsupportedOperationException if this collection does not
+     *         support the clear operation.
+     */
     public void clear()
     {
       synchronized (mutex)
@@ -1851,6 +2112,18 @@ public class Collections
         }
     }
 
+    /**
+     * Checks for the existence of o within the underlying
+     * collection, first obtaining a lock on the mutex.
+     *
+     * @param o the element to look for.
+     * @return <code>true</code> if this collection contains at least one
+     *         element e such that <code>o == null ? e == null : o.equals(e)</code>.
+     * @throws ClassCastException if the type of o is not a valid type for this
+     *         collection.
+     * @throws NullPointerException if o is null and this collection doesn't
+     *         support null values.
+     */
     public boolean contains(Object o)
     {
       synchronized (mutex)
@@ -1859,6 +2132,20 @@ public class Collections
         }
     }
 
+    /**
+     * Checks for the existence of each object in cl
+     * within the underlying collection, first obtaining
+     * a lock on the mutex.
+     *
+     * @param cl the collection to test for.
+     * @return <code>true</code> if for every element o in c, contains(o)
+     *         would return <code>true</code>.
+     * @throws ClassCastException if the type of any element in cl is not a valid
+     *         type for this collection.
+     * @throws NullPointerException if some element of cl is null and this
+     *         collection does not support null values.
+     * @throws NullPointerException if cl itself is null.
+     */
     public boolean containsAll(Collection c1)
     {
       synchronized (mutex)
@@ -1867,6 +2154,13 @@ public class Collections
         }
     }
 
+    /**
+     * Returns <code>true</code> if there are no objects in the underlying
+     * collection.  A lock on the mutex is obtained before the
+     * check is performed.
+     *
+     * @return <code>true</code> if this collection contains no elements.
+     */
     public boolean isEmpty()
     {
       synchronized (mutex)
@@ -1875,6 +2169,14 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a synchronized iterator wrapper around the underlying
+     * collection's iterator.  A lock on the mutex is obtained before
+     * retrieving the collection's iterator.
+     *
+     * @return An iterator over the elements in the underlying collection,
+     *         which returns each element in any order.
+     */
     public Iterator iterator()
     {
       synchronized (mutex)
@@ -1883,6 +2185,20 @@ public class Collections
         }
     }
 
+    /**
+     * Removes the specified object from the underlying collection,
+     * first obtaining a lock on the mutex.
+     *
+     * @param o The object to remove.
+     * @return <code>true</code> if the collection changed as a result of this call, that is,
+     *         if the collection contained at least one occurrence of o.
+     * @throws UnsupportedOperationException if this collection does not
+     *         support the remove operation.
+     * @throws ClassCastException if the type of o is not a valid type
+     *         for this collection.
+     * @throws NullPointerException if o is null and the collection doesn't
+     *         support null values.
+     */
     public boolean remove(Object o)
     {
       synchronized (mutex)
@@ -1891,6 +2207,22 @@ public class Collections
         }
     }
 
+    /**
+     * Removes all elements, e, of the underlying
+     * collection for which <code>col.contains(e)</code>
+     * returns <code>true</code>.  A lock on the mutex is obtained
+     * before the operation proceeds.
+     *
+     * @param col The collection of objects to be removed.
+     * @return <code>true</code> if this collection was modified as a result of this call.
+     * @throws UnsupportedOperationException if this collection does not
+     *   support the removeAll operation.
+     * @throws ClassCastException if the type of any element in c is not a valid
+     *   type for this collection.
+     * @throws NullPointerException if some element of c is null and this
+     *   collection does not support removing null values.
+     * @throws NullPointerException if c itself is null.
+     */
     public boolean removeAll(Collection col)
     {
       synchronized (mutex)
@@ -1899,6 +2231,23 @@ public class Collections
         }
     }
 
+    /**
+     * Retains all elements, e, of the underlying
+     * collection for which <code>col.contains(e)</code>
+     * returns <code>true</code>.  That is, every element that doesn't
+     * exist in col is removed.  A lock on the mutex is obtained
+     * before the operation proceeds.
+     *
+     * @param col The collection of objects to be removed.
+     * @return <code>true</code> if this collection was modified as a result of this call.
+     * @throws UnsupportedOperationException if this collection does not
+     *   support the removeAll operation.
+     * @throws ClassCastException if the type of any element in c is not a valid
+     *   type for this collection.
+     * @throws NullPointerException if some element of c is null and this
+     *   collection does not support removing null values.
+     * @throws NullPointerException if c itself is null.
+     */
     public boolean retainAll(Collection col)
     {
       synchronized (mutex)
@@ -1907,6 +2256,13 @@ public class Collections
         }
     }
 
+    /**
+     * Retrieves the size of the underlying collection.
+     * A lock on the mutex is obtained before the collection
+     * is accessed.
+     *
+     * @return The size of the collection.
+     */
     public int size()
     {
       synchronized (mutex)
@@ -1915,6 +2271,14 @@ public class Collections
         }
     }
 
+    /**
+     * Returns an array containing each object within the underlying
+     * collection.  A lock is obtained on the mutex before the collection
+     * is accessed.
+     *
+     * @return An array of objects, matching the collection in size.  The
+     *         elements occur in any order.
+     */
     public Object[] toArray()
     {
       synchronized (mutex)
@@ -1923,6 +2287,23 @@ public class Collections
         }
     }
 
+    /**
+     * Copies the elements in the underlying collection to the supplied
+     * array.  If <code>a.length < size()</code>, a new array of the
+     * same run-time type is created, with a size equal to that of
+     * the collection.  If <code>a.length > size()</code>, then the
+     * elements from 0 to <code>size() - 1</code> contain the elements
+     * from this collection.  The following element is set to null
+     * to indicate the end of the collection objects.  However, this
+     * only makes a difference if null is not a permitted value within
+     * the collection.
+     * Before the copying takes place, a lock is obtained on the mutex.
+     *
+     * @param a An array to copy elements to.
+     * @return An array containing the elements of the underlying collection.
+     * @throws ArrayStoreException if the type of any element of the
+     *         collection is not a subtype of the element type of a.
+     */
     public Object[] toArray(Object[] a)
     {
       synchronized (mutex)
@@ -1931,6 +2312,12 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a string representation of the underlying collection.
+     * A lock is obtained on the mutex before the string is created.
+     *
+     * @return A string representation of the collection.
+     */
     public String toString()
     {
       synchronized (mutex)
@@ -1970,6 +2357,13 @@ public class Collections
       mutex = sync;
     }
 
+    /**
+     * Retrieves the next object in the underlying collection.
+     * A lock is obtained on the mutex before the collection is accessed.
+     * 
+     * @return The next object in the collection.
+     * @throws NoSuchElementException if there are no more elements
+     */
     public Object next()
     {
       synchronized (mutex)
@@ -1978,6 +2372,14 @@ public class Collections
         }
     }
 
+    /**
+     * Returns <code>true</code> if objects can still be retrieved from the iterator
+     * using <code>next()</code>.  A lock is obtained on the mutex before
+     * the collection is accessed.
+     *
+     * @return <code>true</code> if at least one element is still to be returned by
+     *         <code>next()</code>.
+     */
     public boolean hasNext()
     {
       synchronized (mutex)
@@ -1986,6 +2388,21 @@ public class Collections
         }
     }
 
+    /**
+     * Removes the object that was last returned by <code>next()</code>
+     * from the underlying collection.  Only one call to this method is
+     * allowed per call to the <code>next()</code> method, and it does
+     * not affect the value that will be returned by <code>next()</code>.
+     * Thus, if element n was retrieved from the collection by
+     * <code>next()</code>, it is this element that gets removed.
+     * Regardless of whether this takes place or not, element n+1 is
+     * still returned on the subsequent <code>next()</code> call.
+     *
+     * @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.
+     */
     public void remove()
     {
       synchronized (mutex)
@@ -2073,6 +2490,25 @@ public class Collections
       list = l;
     }
 
+  /**
+   * Insert an element into the underlying 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.  Before the
+   * addition takes place, a lock is obtained on the mutex.
+   *
+   * @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
+   * @throws NullPointerException if o is null and this list doesn't support
+   *         the addition of null values.
+   */
     public void add(int index, Object o)
     {
       synchronized (mutex)
@@ -2081,6 +2517,23 @@ public class Collections
         }
     }
 
+  /**
+   * Add an element to the end of the underlying list (optional operation).
+   * If the list imposes restraints on what can be inserted, such as no null
+   * elements, this should be documented.  A lock is obtained on the mutex before
+   * any of the elements are added.
+   *
+   * @param o the object to add
+   * @return <code>true</code>, 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
+   * @throws NullPointerException if o is null and this list doesn't support
+   *         the addition of null values.
+   */
     public boolean addAll(int index, Collection c)
     {
       synchronized (mutex)
@@ -2089,6 +2542,18 @@ public class Collections
         }
     }
 
+   /**
+    * Tests whether the underlying list is equal to the supplied object.
+    * The object is deemed to be equal if it is also a <code>List</code>
+    * of equal size and with the same elements (i.e. each element, e1,
+    * in list, l1, and each element, e2, in l2, must return <code>true</code> for
+    * <code>e1 == null ? e2 == null : e1.equals(e2)</code>.  Before the
+    * comparison is made, a lock is obtained on the mutex.
+    *
+    * @param o The object to test for equality with the underlying list.
+    * @return <code>true</code> if o is equal to the underlying list under the above
+    *         definition.
+    */
     public boolean equals(Object o)
     {
       synchronized (mutex)
@@ -2097,6 +2562,14 @@ public class Collections
         }
     }
 
+    /**
+     * Retrieves the object at the specified index.  A lock
+     * is obtained on the mutex before the list is accessed.
+     *
+     * @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()
+     */
     public Object get(int index)
     {
       synchronized (mutex)
@@ -2105,6 +2578,15 @@ public class Collections
         }
     }
 
+    /**
+     * Obtains a hashcode for the underlying list, first obtaining
+     * a lock on the mutex.  The calculation of the hashcode is
+     * detailed in the documentation for the <code>List</code>
+     * interface.
+     *
+     * @return The hashcode of the underlying list.
+     * @see List#hashCode()
+     */
     public int hashCode()
     {
       synchronized (mutex)
@@ -2113,6 +2595,20 @@ public class Collections
         }
     }
 
+    /**
+     * Obtain the first index at which a given object is to be found in the
+     * underlying list.  A lock is obtained on the mutex before the list is
+     * accessed.
+     *
+     * @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.
+     * @throws ClassCastException if the type of o is not a valid
+     *         type for this list.
+     * @throws NullPointerException if o is null and this
+     *         list does not support null values.
+     */
+
     public int indexOf(Object o)
     {
       synchronized (mutex)
@@ -2121,6 +2617,18 @@ public class Collections
         }
     }
 
+    /**
+     * Obtain the last index at which a given object is to be found in this
+     * underlying list.  A lock is obtained on the mutex before the list
+     * is accessed.
+     *
+     * @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.
+     * @throws ClassCastException if the type of o is not a valid
+     *         type for this list.
+     * @throws NullPointerException if o is null and this
+     *         list does not support null values.
+     */
     public int lastIndexOf(Object o)
     {
       synchronized (mutex)
@@ -2129,6 +2637,16 @@ public class Collections
         }
     }
 
+    /**
+     * Retrieves a synchronized wrapper around the underlying list's
+     * list iterator.  A lock is obtained on the mutex before the
+     * list iterator is retrieved.
+     *
+     * @return A list iterator over the elements in the underlying list.
+     *         The list iterator allows additional list-specific operations
+     *         to be performed, in addition to those supplied by the
+     *         standard iterator.
+     */
     public ListIterator listIterator()
     {
       synchronized (mutex)
@@ -2137,6 +2655,23 @@ public class Collections
         }
     }
 
+    /**
+     * Retrieves a synchronized wrapper around the underlying list's
+     * list iterator.  A lock is obtained on the mutex before the
+     * list iterator is retrieved.  The iterator starts at the
+     * index supplied, leading to the element at that index being
+     * the first one returned by <code>next()</code>.  Calling
+     * <code>previous()</code> from this initial position returns
+     * index - 1.
+     *
+     * @param index the position, between 0 and size() inclusive, to begin the
+     *        iteration from
+     * @return A list iterator over the elements in the underlying list.
+     *         The list iterator allows additional list-specific operations
+     *         to be performed, in addition to those supplied by the
+     *         standard iterator.
+     * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
+     */
     public ListIterator listIterator(int index)
     {
       synchronized (mutex)
@@ -2145,6 +2680,17 @@ public class Collections
         }
     }
 
+    /**
+     * Remove the element at a given position in the underlying list (optional
+     * operation).  All remaining elements are shifted to the left to fill the gap.
+     * A lock on the mutex is obtained before the element is removed.
+     *
+     * @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()
+     */
     public Object remove(int index)
     {
       synchronized (mutex)
@@ -2153,6 +2699,24 @@ public class Collections
         }
     }
 
+  /**
+   * Replace an element of the underlying list with another object (optional
+   * operation).  A lock is obtained on the mutex before the element is
+   * replaced.
+   *
+   * @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
+   * @throws NullPointerException if o is null and this
+   *         list does not support null values.
+   */
     public Object set(int index, Object o)
     {
       synchronized (mutex)
@@ -2161,6 +2725,24 @@ public class Collections
         }
     }
 
+    /**
+     * Obtain a List view of a subsection of the underlying list, from fromIndex
+     * (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.  A lock is obtained
+     * on the mutex before the creation of the sublist.  The returned list
+     * is also synchronized, using the same mutex.
+     *
+     * @param fromIndex the index that the returned list should start from
+     *        (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
+     */
     public List subList(int fromIndex, int toIndex)
     {
       synchronized (mutex)
@@ -2206,6 +2788,25 @@ public class Collections
       super(sync, l);
     }
 
+    /**
+     * Obtain a List view of a subsection of the underlying list, from fromIndex
+     * (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.    A lock is obtained
+     * on the mutex before the creation of the sublist.  The returned list
+     * is also synchronized, using the same mutex.  Random accessibility
+     * is also extended to the new list.
+     *
+     * @param fromIndex the index that the returned list should start from
+     *        (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
+     */
     public List subList(int fromIndex, int toIndex)
     {
       synchronized (mutex)
@@ -2243,6 +2844,24 @@ public class Collections
       this.li = li;
     }
 
+    /**
+     * Insert an element into the underlying list at the current position of
+     * the iterator (optional operation). The element is inserted in between
+     * the element that would be returned by <code>previous()</code> and the
+     * element that would be returned by <code>next()</code>. 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.  A lock is obtained
+     * on the mutex before the addition takes place.
+     *
+     * @param o the object to insert into the list
+     * @throws ClassCastException if the object is of a type which cannot be added
+     *         to this list.
+     * @throws IllegalArgumentException if some other aspect of the object stops
+     *         it being added to this list.
+     * @throws UnsupportedOperationException if this ListIterator does not
+     *         support the add operation.
+     */
     public void add(Object o)
     {
       synchronized (mutex)
@@ -2250,6 +2869,15 @@ public class Collections
           li.add(o);
         }
     }
+
+    /**
+     * Tests whether there are elements remaining in the underlying list
+     * in the reverse direction. In other words, <code>previous()</code>
+     * will not fail with a NoSuchElementException.  A lock is obtained
+     * on the mutex before the check takes place.
+     *
+     * @return <code>true</code> if the list continues in the reverse direction
+     */
     public boolean hasPrevious()
     {
       synchronized (mutex)
@@ -2258,6 +2886,14 @@ public class Collections
         }
     }
 
+    /**
+      * Find the index of the element that would be returned by a call to
+      * <code>next()</code>.  If hasNext() returns <code>false</code>, this
+      * returns the list size.  A lock is obtained on the mutex before the
+      * query takes place.
+      *
+      * @return the index of the element that would be returned by next()
+      */
     public int nextIndex()
     {
       synchronized (mutex)
@@ -2266,6 +2902,16 @@ public class Collections
         }
     }
 
+    /**
+     * Obtain the previous element from the underlying list. 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
+     * backwards. Alternating calls to next and previous will return the same
+     * element.  A lock is obtained on the mutex before the object is retrieved.
+     *
+     * @return the next element in the list in the reverse direction
+     * @throws NoSuchElementException if there are no more elements
+     */
     public Object previous()
     {
       synchronized (mutex)
@@ -2274,6 +2920,13 @@ public class Collections
         }
     }
 
+    /**
+     * Find the index of the element that would be returned by a call to
+     * previous. If hasPrevious() returns <code>false</code>, this returns -1.
+     * A lock is obtained on the mutex before the query takes place.
+     *
+     * @return the index of the element that would be returned by previous()
+     */
     public int previousIndex()
     {
       synchronized (mutex)
@@ -2282,6 +2935,25 @@ public class Collections
         }
     }
 
+    /**
+     * Replace the element last returned by a call to <code>next()</code> or
+     * <code>previous()</code> with a given object (optional operation).  This
+     * method may only be called if neither <code>add()</code> nor
+     * <code>remove()</code> have been called since the last call to
+     * <code>next()</code> or <code>previous</code>.  A lock is obtained
+     * on the mutex before the list is modified.
+     *
+     * @param o the object to replace the element with
+     * @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
+     */
     public void set(Object o)
     {
       synchronized (mutex)
@@ -2388,6 +3060,12 @@ public class Collections
       mutex = sync;
     }
 
+    /**
+     * Clears all the entries from the underlying map.  A lock is obtained
+     * on the mutex before the map is cleared.
+     *
+     * @throws UnsupportedOperationException if clear is not supported
+     */
     public void clear()
     {
       synchronized (mutex)
@@ -2396,6 +3074,16 @@ public class Collections
         }
     }
 
+    /**
+     * Returns <code>true</code> if the underlying map contains a entry for the given key.
+     * A lock is obtained on the mutex before the map is queried.
+     *
+     * @param key the key to search for.
+     * @return <code>true</code> if the underlying 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)
     {
       synchronized (mutex)
@@ -2404,6 +3092,20 @@ public class Collections
         }
     }
 
+  /**
+   * Returns <code>true</code> if the underlying map contains at least one entry with the
+   * given value.  In other words, returns <code>true</code> if a value v exists where
+   * <code>(value == null ? v == null : value.equals(v))</code>. This usually
+   * requires linear time.  A lock is obtained on the mutex before the map
+   * is queried.
+   *
+   * @param value the value to search for
+   * @return <code>true</code> if the map contains the value
+   * @throws ClassCastException if the type of the value is not a valid type
+   *         for this map.
+   * @throws NullPointerException if the value is null and the map doesn't
+   *         support null values.
+   */
     public boolean containsValue(Object value)
     {
       synchronized (mutex)
@@ -2426,6 +3128,15 @@ public class Collections
         {
           e = (Map.Entry) o;
         }
+
+	/**
+	 * Returns <code>true</code> if the object, o, implements <code>Map.Entry</code>
+	 * with the same key and value as the underlying entry.  A lock is
+	 * obtained on the mutex before the comparison takes place.
+	 *
+	 * @param o The object to compare with this entry.
+	 * @return <code>true</code> if o is equivalent to the underlying map entry.
+	 */
         public boolean equals(Object o)
         {
           synchronized (mutex)
@@ -2433,6 +3144,13 @@ public class Collections
               return e.equals(o);
             }
         }
+
+	/**
+	 * Returns the key used in the underlying map entry.  A lock is obtained
+	 * on the mutex before the key is retrieved.
+	 *
+	 * @return The key of the underlying map entry.
+	 */
         public Object getKey()
         {
           synchronized (mutex)
@@ -2440,6 +3158,13 @@ public class Collections
               return e.getKey();
             }
         }
+
+	/**
+	 * Returns the value used in the underlying map entry.  A lock is obtained
+	 * on the mutex before the value is retrieved.
+	 *
+	 * @return The value of the underlying map entry.
+	 */
         public Object getValue()
         {
           synchronized (mutex)
@@ -2447,6 +3172,16 @@ public class Collections
               return e.getValue();
             }
         }
+
+	/**
+	 * Computes the hash code for the underlying map entry.
+	 * This computation is described in the documentation for the
+	 * <code>Map</code> interface.  A lock is obtained on the mutex
+	 * before the underlying map is accessed.
+	 *
+	 * @return The hash code of the underlying map entry.
+	 * @see Map#hashCode()
+	 */
         public int hashCode()
         {
           synchronized (mutex)
@@ -2454,6 +3189,23 @@ public class Collections
               return e.hashCode();
             }
         }
+
+	/**
+	 * Replaces the value in the underlying map entry with the specified
+	 * object (optional operation).  A lock is obtained on the mutex
+	 * before the map is altered.  The map entry, in turn, will alter
+	 * the underlying map object.  The operation is undefined if the
+	 * <code>remove()</code> method of the iterator has been called
+	 * beforehand.
+	 *
+	 * @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)
         {
           synchronized (mutex)
@@ -2461,6 +3213,13 @@ public class Collections
               return e.setValue(value);
             }
         }
+
+	/**
+	 * Returns a textual representation of the underlying map entry.
+	 * A lock is obtained on the mutex before the entry is accessed.
+	 *
+	 * @return The contents of the map entry in <code>String</code> form.
+	 */
         public String toString()
         {
           synchronized (mutex)
@@ -2476,12 +3235,28 @@ public class Collections
           {
             entries = new SynchronizedSet(mutex, m.entrySet())
             {
-              public Iterator iterator()
+	      /**
+	       * Returns an iterator over the set.  The iterator has no specific order,
+	       * unless further specified.  A lock is obtained on the set's mutex
+	       * before the iterator is created.  The created iterator is also
+	       * thread-safe.
+	       *
+	       * @return A synchronized set iterator.
+	       */
+	      public Iterator iterator()
               {
                 synchronized (super.mutex)
                   {
                     return new SynchronizedIterator(super.mutex, c.iterator())
                     {
+		      /**
+		       * Retrieves the next map entry from the iterator.
+		       * A lock is obtained on the iterator's mutex before
+		       * the entry is created.  The new map entry is enclosed in
+		       * a thread-safe wrapper.
+		       *
+		       * @return A synchronized map entry.
+		       */
                       public Object next()
                       {
                         synchronized (super.mutex)
@@ -2497,6 +3272,16 @@ public class Collections
       return entries;
     }
 
+    /**
+     * Returns <code>true</code> if the object, o, is also an instance
+     * of <code>Map</code> and contains an equivalent
+     * entry set to that of the underlying map.  A lock
+     * is obtained on the mutex before the objects are
+     * compared.
+     *
+     * @param o The object to compare.
+     * @return <code>true</code> if o and the underlying map are equivalent.
+     */
     public boolean equals(Object o)
     {
       synchronized (mutex)
@@ -2505,6 +3290,21 @@ public class Collections
         }
     }
 
+    /**
+     * Returns the value associated with the given key, or null
+     * if no such mapping exists.  An ambiguity exists with maps
+     * that accept null values as a return value of null could
+     * be due to a non-existent mapping or simply a null value
+     * for that key.  To resolve this, <code>containsKey</code>
+     * should be used.  A lock is obtained on the mutex before
+     * the value is retrieved from the underlying map.
+     *
+     * @param key The key of the required mapping.
+     * @return The value associated with the given key, or
+     *         null if no such mapping exists.
+     * @throws ClassCastException if the key is an inappropriate type.
+     * @throws NullPointerException if this map does not accept null keys.
+     */
     public Object get(Object key)
     {
       synchronized (mutex)
@@ -2513,6 +3313,13 @@ public class Collections
         }
     }
 
+    /**
+     * Calculates the hash code of the underlying map as the
+     * sum of the hash codes of all entries.  A lock is obtained
+     * on the mutex before the hash code is computed.
+     *
+     * @return The hash code of the underlying map.
+     */
     public int hashCode()
     {
       synchronized (mutex)
@@ -2521,6 +3328,12 @@ public class Collections
         }
     }
 
+    /**
+     * Returns <code>true</code> if the underlying map contains no entries.
+     * A lock is obtained on the mutex before the map is examined.
+     *
+     * @return <code>true</code> if the map is empty.
+     */
     public boolean isEmpty()
     {
       synchronized (mutex)
@@ -2529,6 +3342,19 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a thread-safe set view of the keys in the underlying 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.  A lock is obtained
+     * on the mutex before the set is created.
+     *
+     * @return A synchronized set containing the keys of the underlying map.
+     */
     public Set keySet()
     {
       if (keys == null)
@@ -2539,6 +3365,24 @@ public class Collections
       return keys;
     }
 
+    /**
+     * Associates the given key to the given value (optional operation). If the
+     * underlying 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.  A lock is obtained on the mutex
+     * before the modification is made.
+     *
+     * @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 either the key or the value is null,
+     *         and the map forbids null keys or values
+     * @see #containsKey(Object)
+     */
     public Object put(Object key, Object value)
     {
       synchronized (mutex)
@@ -2547,6 +3391,20 @@ public class Collections
         }
     }
 
+    /**
+     * Copies all entries of the given map to the underlying one (optional
+     * operation). If the map already contains a key, its value is replaced.
+     * A lock is obtained on the mutex before the operation proceeds.
+     *
+     * @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 map)
     {
       synchronized (mutex)
@@ -2555,6 +3413,21 @@ public class Collections
         }
     }
 
+    /**
+     * Removes the mapping for the key, o, 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.  A prior
+     * <code>containsKey()</code> check is required to avoid this ambiguity.
+     * Before the mapping is removed, a lock is obtained on the mutex.
+     *
+     * @param key the key to remove
+     * @return the value the key mapped to, or null if not present
+     * @throws UnsupportedOperationException if deletion is unsupported
+     * @throws NullPointerException if the key is null and this map doesn't
+     *         support null keys.
+     * @throws ClassCastException if the type of the key is not a valid type
+     *         for this map.
+     */
     public Object remove(Object o)
     {
       synchronized (mutex)
@@ -2563,6 +3436,14 @@ public class Collections
         }
     }
 
+    /**
+     * Retrieves the size of the underlying map.  A lock
+     * is obtained on the mutex before access takes place.
+     * Maps with a size greater than <code>Integer.MAX_VALUE</code>
+     * return <code>Integer.MAX_VALUE</code> instead.
+     *
+     * @return The size of the underlying map.
+     */
     public int size()
     {
       synchronized (mutex)
@@ -2571,6 +3452,13 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a textual representation of the underlying
+     * map.  A lock is obtained on the mutex before the map
+     * is accessed.
+     *
+     * @return The map in <code>String</code> form.
+     */
     public String toString()
     {
       synchronized (mutex)
@@ -2579,6 +3467,20 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a synchronized collection view of the values in the underlying
+     * 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.  A lock is obtained on the mutex before the collection
+     * is created.
+     * 
+     * @return the collection of all values in the underlying map.
+     */
     public Collection values()
     {
       if (values == null)
@@ -2655,6 +3557,16 @@ public class Collections
       super(sync, s);
     }
 
+    /**
+     * Returns <code>true</code> if the object, o, is a <code>Set</code>
+     * of the same size as the underlying set, and contains
+     * each element, e, which occurs in the underlying set.
+     * A lock is obtained on the mutex before the comparison
+     * takes place.
+     *
+     * @param o The object to compare against.
+     * @return <code>true</code> if o is an equivalent set.
+     */
     public boolean equals(Object o)
     {
       synchronized (mutex)
@@ -2663,6 +3575,14 @@ public class Collections
         }
     }
 
+    /**
+     * Computes the hash code for the underlying set as the
+     * sum of the hash code of all elements within the set.
+     * A lock is obtained on the mutex before the computation
+     * occurs.
+     *
+     * @return The hash code for the underlying set.
+     */
     public int hashCode()
     {
       synchronized (mutex)
@@ -2750,6 +3670,13 @@ public class Collections
       this.sm = sm;
     }
 
+    /**
+     * Returns the comparator used in sorting the underlying map, or null if
+     * it is the keys' natural ordering.  A lock is obtained on the mutex
+     * before the comparator is retrieved.
+     *
+     * @return the sorting comparator.
+     */
     public Comparator comparator()
     {
       synchronized (mutex)
@@ -2758,6 +3685,13 @@ public class Collections
         }
     }
 
+    /**
+     * Returns the first, lowest sorted, key from the underlying map.
+     * A lock is obtained on the mutex before the map is accessed.
+     *
+     * @return the first key.
+     * @throws NoSuchElementException if this map is empty.
+     */
     public Object firstKey()
     {
       synchronized (mutex)
@@ -2766,6 +3700,25 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a submap containing the keys from the first
+     * key (as returned by <code>firstKey()</code>) to
+     * the key before that specified.  The submap supports all
+     * operations supported by the underlying map and all actions
+     * taking place on the submap are also reflected in the underlying
+     * map.  A lock is obtained on the mutex prior to submap creation.
+     * This operation is equivalent to <code>subMap(firstKey(), toKey)</code>.
+     * The submap retains the thread-safe status of this map.
+     *
+     * @param toKey the exclusive upper range of the submap.
+     * @return a submap from <code>firstKey()</code> to the
+     *         the key preceding toKey.
+     * @throws ClassCastException if toKey is not comparable to the underlying
+     *         map's contents.
+     * @throws IllegalArgumentException if toKey is outside the map's range.
+     * @throws NullPointerException if toKey is null. but the map does not allow
+     *         null keys.
+     */
     public SortedMap headMap(Object toKey)
     {
       synchronized (mutex)
@@ -2774,6 +3727,13 @@ public class Collections
         }
     }
 
+    /**
+     * Returns the last, highest sorted, key from the underlying map.
+     * A lock is obtained on the mutex before the map is accessed.
+     *
+     * @return the last key.
+     * @throws NoSuchElementException if this map is empty.
+     */
     public Object lastKey()
     {
       synchronized (mutex)
@@ -2782,6 +3742,24 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a submap containing the keys from fromKey to
+     * the key before toKey.  The submap supports all
+     * operations supported by the underlying map and all actions
+     * taking place on the submap are also reflected in the underlying
+     * map.  A lock is obtained on the mutex prior to submap creation.
+     * The submap retains the thread-safe status of this map.
+     *
+     * @param fromKey the inclusive lower range of the submap.
+     * @param toKey the exclusive upper range of the submap.
+     * @return a submap from fromKey to the key preceding toKey.
+     * @throws ClassCastException if fromKey or toKey is not comparable
+     *         to the underlying map's contents.
+     * @throws IllegalArgumentException if fromKey or toKey is outside the map's
+     *         range.
+     * @throws NullPointerException if fromKey or toKey is null. but the map does
+     *         not allow  null keys.
+     */
     public SortedMap subMap(Object fromKey, Object toKey)
     {
       synchronized (mutex)
@@ -2790,6 +3768,22 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a submap containing all the keys from fromKey onwards.
+     * The submap supports all operations supported by the underlying
+     * map and all actions taking place on the submap are also reflected
+     * in the underlying map.  A lock is obtained on the mutex prior to
+     * submap creation.  The submap retains the thread-safe status of
+     * this map.
+     *
+     * @param fromKey the inclusive lower range of the submap.
+     * @return a submap from fromKey to <code>lastKey()</code>.
+     * @throws ClassCastException if fromKey is not comparable to the underlying
+     *         map's contents.
+     * @throws IllegalArgumentException if fromKey is outside the map's range.
+     * @throws NullPointerException if fromKey is null. but the map does not allow
+     *         null keys.
+     */
     public SortedMap tailMap(Object fromKey)
     {
       synchronized (mutex)
@@ -2872,6 +3866,13 @@ public class Collections
       this.ss = ss;
     }
 
+    /**
+     * Returns the comparator used in sorting the underlying set, or null if
+     * it is the elements' natural ordering.  A lock is obtained on the mutex
+     * before the comparator is retrieved.
+     *
+     * @return the sorting comparator.
+     */
     public Comparator comparator()
     {
       synchronized (mutex)
@@ -2880,6 +3881,13 @@ public class Collections
         }
     }
 
+    /**
+     * Returns the first, lowest sorted, element from the underlying set.
+     * A lock is obtained on the mutex before the set is accessed.
+     *
+     * @return the first element.
+     * @throws NoSuchElementException if this set is empty.
+     */
     public Object first()
     {
       synchronized (mutex)
@@ -2888,6 +3896,25 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a subset containing the element from the first
+     * element (as returned by <code>first()</code>) to
+     * the element before that specified.  The subset supports all
+     * operations supported by the underlying set and all actions
+     * taking place on the subset are also reflected in the underlying
+     * set.  A lock is obtained on the mutex prior to subset creation.
+     * This operation is equivalent to <code>subSet(first(), toElement)</code>.
+     * The subset retains the thread-safe status of this set.
+     *
+     * @param toElement the exclusive upper range of the subset.
+     * @return a subset from <code>first()</code> to the
+     *         the element preceding toElement.
+     * @throws ClassCastException if toElement is not comparable to the underlying
+     *         set's contents.
+     * @throws IllegalArgumentException if toElement is outside the set's range.
+     * @throws NullPointerException if toElement is null. but the set does not allow
+     *         null elements.
+     */
     public SortedSet headSet(Object toElement)
     {
       synchronized (mutex)
@@ -2896,6 +3923,13 @@ public class Collections
         }
     }
 
+    /**
+     * Returns the last, highest sorted, element from the underlying set.
+     * A lock is obtained on the mutex before the set is accessed.
+     *
+     * @return the last element.
+     * @throws NoSuchElementException if this set is empty.
+     */
     public Object last()
     {
       synchronized (mutex)
@@ -2904,6 +3938,24 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a subset containing the elements from fromElement to
+     * the element before toElement.  The subset supports all
+     * operations supported by the underlying set and all actions
+     * taking place on the subset are also reflected in the underlying
+     * set.  A lock is obtained on the mutex prior to subset creation.
+     * The subset retains the thread-safe status of this set.
+     *
+     * @param fromElement the inclusive lower range of the subset.
+     * @param toElement the exclusive upper range of the subset.
+     * @return a subset from fromElement to the element preceding toElement.
+     * @throws ClassCastException if fromElement or toElement is not comparable
+     *         to the underlying set's contents.
+     * @throws IllegalArgumentException if fromElement or toElement is outside the set's
+     *         range.
+     * @throws NullPointerException if fromElement or toElement is null. but the set does
+     *         not allow null elements.
+     */
     public SortedSet subSet(Object fromElement, Object toElement)
     {
       synchronized (mutex)
@@ -2913,6 +3965,22 @@ public class Collections
         }
     }
 
+    /**
+     * Returns a subset containing all the elements from fromElement onwards.
+     * The subset supports all operations supported by the underlying
+     * set and all actions taking place on the subset are also reflected
+     * in the underlying set.  A lock is obtained on the mutex prior to
+     * subset creation.  The subset retains the thread-safe status of
+     * this set.
+     *
+     * @param fromElement the inclusive lower range of the subset.
+     * @return a subset from fromElement to <code>last()</code>.
+     * @throws ClassCastException if fromElement is not comparable to the underlying
+     *         set's contents.
+     * @throws IllegalArgumentException if fromElement is outside the set's range.
+     * @throws NullPointerException if fromElement is null. but the set does not allow
+     *         null elements.
+     */
     public SortedSet tailSet(Object fromElement)
     {
       synchronized (mutex)
@@ -2927,7 +3995,9 @@ public class Collections
    * Returns an unmodifiable view of the given collection. This allows
    * "read-only" access, although changes in the backing collection show up
    * in this view. Attempts to modify the collection directly or via iterators
-   * will fail with {@link UnsupportedOperationException}.
+   * will fail with {@link UnsupportedOperationException}.  Although this view
+   * prevents changes to the structure of the collection and its elements, the values
+   * referenced by the objects in the collection can still be modified.
    * <p>
    *
    * Since the collection might be a List or a Set, and those have incompatible
@@ -2977,71 +4047,199 @@ public class Collections
         throw new NullPointerException();
     }
 
+    /**
+     * Blocks the addition of elements to the underlying collection.
+     * This method never returns, throwing an exception instead.
+     *
+     * @param o the object to add.
+     * @return <code>true</code> if the collection was modified as a result of this action.
+     * @throws UnsupportedOperationException as an unmodifiable collection does not
+     *         support the add operation.
+     */
     public boolean add(Object o)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Blocks the addition of a collection of elements to the underlying
+     * collection.  This method never returns, throwing an exception instead.
+     *
+     * @param c the collection to add.
+     * @return <code>true</code> if the collection was modified as a result of this action.
+     * @throws UnsupportedOperationException as an unmodifiable collection does not
+     *         support the <code>addAll</code> operation.
+     */
     public boolean addAll(Collection c)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Blocks the clearing of the underlying collection.  This method never
+     * returns, throwing an exception instead.
+     *
+     * @throws UnsupportedOperationException as an unmodifiable collection does
+     *         not support the <code>clear()</code> operation.
+     */
     public void clear()
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Test whether the underlying collection contains a given object as one of its
+     * elements.
+     *
+     * @param o the element to look for.
+     * @return <code>true</code> if the underlying collection contains at least
+     *         one element e such that
+     *         <code>o == null ? e == null : o.equals(e)</code>.
+     * @throws ClassCastException if the type of o is not a valid type for the
+     *         underlying collection.
+     * @throws NullPointerException if o is null and the underlying collection
+     *         doesn't support null values.
+     */
     public boolean contains(Object o)
     {
       return c.contains(o);
     }
 
+    /**
+     * Test whether the underlying collection contains every element in a given
+     * collection.
+     *
+     * @param c the collection to test for.
+     * @return <code>true</code> if for every element o in c, contains(o) would
+     *         return <code>true</code>.
+     * @throws ClassCastException if the type of any element in c is not a valid
+     *   type for the underlying collection.
+     * @throws NullPointerException if some element of c is null and the underlying
+     *   collection does not support null values.
+     * @throws NullPointerException if c itself is null.
+     */
     public boolean containsAll(Collection c1)
     {
       return c.containsAll(c1);
     }
 
+    /**
+     * Tests whether the underlying collection is empty, that is,
+     * if size() == 0.
+     *
+     * @return <code>true</code> if this collection contains no elements.
+     */
     public boolean isEmpty()
     {
       return c.isEmpty();
     }
 
+    /**
+     * Obtain an Iterator over the underlying collection, which maintains
+     * its unmodifiable nature.
+     *
+     * @return an UnmodifiableIterator over the elements of the underlying
+     *         collection, in any order.
+     */
     public Iterator iterator()
     {
       return new UnmodifiableIterator(c.iterator());
     }
 
+    /**
+     * Blocks the removal of an object from the underlying collection.
+     * This method never returns, throwing an exception instead.
+     *
+     * @param o The object to remove.
+     * @return <code>true</code> if the object was removed (i.e. the underlying
+     *         collection returned 1 or more instances of o).
+     * @throws UnsupportedOperationException as an unmodifiable collection
+     *         does not support the <code>remove()</code> operation.
+     */
     public boolean remove(Object o)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Blocks the removal of a collection of objects from the underlying
+     * collection.  This method never returns, throwing an exception
+     * instead.
+     *
+     * @param c The collection of objects to remove.
+     * @return <code>true</code> if the collection was modified.
+     * @throws UnsupportedOperationException as an unmodifiable collection
+     *         does not support the <code>removeAll()</code> operation.
+     */
     public boolean removeAll(Collection c)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Blocks the removal of all elements from the underlying collection,
+     * except those in the supplied collection.  This method never returns,
+     * throwing an exception instead.
+     *
+     * @param c The collection of objects to retain.
+     * @return <code>true</code> if the collection was modified.
+     * @throws UnsupportedOperationException as an unmodifiable collection
+     *         does not support the <code>retainAll()</code> operation.
+     */
     public boolean retainAll(Collection c)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Retrieves the number of elements in the underlying collection.
+     *
+     * @return the number of elements in the collection.
+     */
     public int size()
     {
       return c.size();
     }
 
+    /**
+     * Copy the current contents of the underlying collection into an array.
+     *
+     * @return an array of type Object[] with a length equal to the size of the
+     *         underlying collection and containing the elements currently in
+     *         the underlying collection, in any order.
+     */
     public Object[] toArray()
     {
       return c.toArray();
     }
 
+    /**
+     * Copy the current contents of the underlying collection into an array.  If
+     * the array passed as an argument has length less than the size of the
+     * underlying collection, an array of the same run-time type as a, with a length
+     * equal to the size of the underlying collection, is allocated using reflection.
+     * Otherwise, a itself is used.  The elements of the underlying collection are
+     * copied into it, and if there is space in the array, the following element is
+     * set to null. The resultant array is returned.
+     * Note: The fact that the following element is set to null is only useful
+     * if it is known that this collection does not contain any null elements.
+     *
+     * @param a the array to copy this collection into.
+     * @return an array containing the elements currently in the underlying
+     *         collection, in any order.
+     * @throws ArrayStoreException if the type of any element of the
+     *         collection is not a subtype of the element type of a.
+     */
     public Object[] toArray(Object[] a)
     {
       return c.toArray(a);
     }
 
+    /**
+     * A textual representation of the unmodifiable collection.
+     *
+     * @return The unmodifiable collection in the form of a <code>String</code>.
+     */
     public String toString()
     {
       return c.toString();
@@ -3070,16 +4268,37 @@ public class Collections
       this.i = i;
     }
 
+    /**
+     * Obtains the next element in the underlying collection.
+     *
+     * @return the next element in the collection.
+     * @throws NoSuchElementException if there are no more elements.
+     */
     public Object next()
     {
       return i.next();
     }
-
+    /**
+     * Tests whether there are still elements to be retrieved from the
+     * underlying collection by <code>next()</code>.  When this method
+     * returns <code>true</code>, an exception will not be thrown on calling
+     * <code>next()</code>.
+     *
+     * @return <code>true</code> if there is at least one more element in the underlying
+     *         collection.
+     */
     public boolean hasNext()
     {
       return i.hasNext();
     }
 
+    /**
+     * Blocks the removal of elements from the underlying collection by the
+     * iterator.
+     *
+     * @throws UnsupportedOperationException as an unmodifiable collection
+     *         does not support the removal of elements by its iterator.
+     */
     public void remove()
     {
       throw new UnsupportedOperationException();
@@ -3091,6 +4310,9 @@ public class Collections
    * "read-only" access, although changes in the backing list show up
    * in this view. Attempts to modify the list directly, via iterators, or
    * via sublists, will fail with {@link UnsupportedOperationException}.
+   * Although this view prevents changes to the structure of the list and
+   * its elements, the values referenced by the objects in the list can
+   * still be modified.   
    * <p>
    *
    * The returned List implements Serializable, but can only be serialized if
@@ -3143,61 +4365,184 @@ public class Collections
       list = l;
     }
 
+    /**
+     * Blocks the addition of an element to the underlying
+     * list at a specific index.  This method never returns,
+     * throwing an exception instead.
+     *
+     * @param index The index at which to place the new element.
+     * @param o the object to add.
+     * @throws UnsupportedOperationException as an unmodifiable
+     *         list doesn't support the <code>add()</code> operation.
+     */
     public void add(int index, Object o)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Blocks the addition of a collection of elements to the
+     * underlying list at a specific index.  This method never
+     * returns, throwing an exception instead.
+     *
+     * @param index The index at which to place the new element.
+     * @param c the collections of objects to add.
+     * @throws UnsupportedOperationException as an unmodifiable
+     *         list doesn't support the <code>addAll()</code> operation.
+     */
     public boolean addAll(int index, Collection c)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Returns <code>true</code> if the object, o, is an instance of
+     * <code>List</code> with the same size and elements
+     * as the underlying list.
+     *
+     * @param o The object to compare.
+     * @return <code>true</code> if o is equivalent to the underlying list.
+     */
     public boolean equals(Object o)
     {
       return list.equals(o);
     }
 
+    /**
+     * Retrieves the element at a given index in the underlying list.
+     *
+     * @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()
+     */
     public Object get(int index)
     {
       return list.get(index);
     }
 
+    /**
+     * Computes the hash code for the underlying list.
+     * The exact computation is described in the documentation
+     * of the <code>List</code> interface.
+     *
+     * @return The hash code of the underlying list.
+     * @see List#hashCode()
+     */
     public int hashCode()
     {
       return list.hashCode();
     }
 
+    /**
+     * Obtain the first index at which a given object is to be found in the
+     * underlying list.
+     *
+     * @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.
+     * @throws ClassCastException if the type of o is not a valid
+     *         type for the underlying list.
+     * @throws NullPointerException if o is null and the underlying
+     *         list does not support null values.
+     */
     public int indexOf(Object o)
     {
       return list.indexOf(o);
     }
 
+    /**
+     * Obtain the last index at which a given object is to be found in the
+     * underlying list.
+     *
+     * @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.
+     * @throws ClassCastException if the type of o is not a valid
+     *         type for the underlying list.
+     * @throws NullPointerException if o is null and the underlying
+     *         list does not support null values.
+     */
     public int lastIndexOf(Object o)
     {
       return list.lastIndexOf(o);
     }
 
+  /**
+   * Obtains a list iterator over the underlying list, starting at the beginning
+   * and maintaining the unmodifiable nature of this list.
+   *
+   * @return a <code>UnmodifiableListIterator</code> over the elements of the
+   *         underlying list, in order, starting at the beginning.
+   */
     public ListIterator listIterator()
     {
       return new UnmodifiableListIterator(list.listIterator());
     }
 
+  /**
+   * Obtains a list iterator over the underlying list, starting at the specified
+   * index and maintaining the unmodifiable nature of this list.  An initial call
+   * to <code>next()</code> will retrieve the element at the specified index,
+   * and an initial call to <code>previous()</code> will retrieve the element
+   * at index - 1.
+   *
+   *
+   * @param index the position, between 0 and size() inclusive, to begin the
+   *        iteration from.
+   * @return a <code>UnmodifiableListIterator</code> over the elements of the
+   *         underlying list, in order, starting at the specified index.
+   * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
+   */
     public ListIterator listIterator(int index)
     {
       return new UnmodifiableListIterator(list.listIterator(index));
     }
 
+    /**
+     * Blocks the removal of the element at the specified index.
+     * This method never returns, throwing an exception instead.
+     *
+     * @param index The index of the element to remove.
+     * @return the removed element.
+     * @throws UnsupportedOperationException as an unmodifiable
+     *         list does not support the <code>remove()</code>
+     *         operation.
+     */
     public Object remove(int index)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Blocks the replacement of the element at the specified index.
+     * This method never returns, throwing an exception instead.
+     *
+     * @param index The index of the element to replace.
+     * @param o The new object to place at the specified index.
+     * @return the replaced element.
+     * @throws UnsupportedOperationException as an unmodifiable
+     *         list does not support the <code>set()</code>
+     *         operation.
+     */
     public Object set(int index, Object o)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Obtain a List view of a subsection of the underlying list, from
+     * fromIndex (inclusive) to toIndex (exclusive). If the two indices
+     * are equal, the sublist is empty. The returned list will be
+     * unmodifiable, like this list.  Changes to the elements of the
+     * returned list will be reflected in the underlying list. No structural
+     * modifications can take place in either list.
+     *
+     * @param fromIndex the index that the returned list should start from
+     *        (inclusive).
+     * @param toIndex the index that the returned list should go to (exclusive).
+     * @return a List backed by a subsection of the underlying list.
+     * @throws IndexOutOfBoundsException if fromIndex &lt; 0
+     *         || toIndex &gt; size() || fromIndex &gt; toIndex.
+     */
     public List subList(int fromIndex, int toIndex)
     {
       return unmodifiableList(list.subList(fromIndex, toIndex));
@@ -3254,31 +4599,77 @@ public class Collections
       this.li = li;
     }
 
+    /**
+     * Blocks the addition of an object to the list underlying this iterator.
+     * This method never returns, throwing an exception instead.
+     *
+     * @param o The object to add.
+     * @throws UnsupportedOperationException as the iterator of an unmodifiable
+     *         list does not support the <code>add()</code> operation.
+     */
     public void add(Object o)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Tests whether there are still elements to be retrieved from the
+     * underlying collection by <code>previous()</code>.  When this method
+     * returns <code>true</code>, an exception will not be thrown on calling
+     * <code>previous()</code>.
+     *
+     * @return <code>true</code> if there is at least one more element prior to the
+     *         current position in the underlying list.
+     */
     public boolean hasPrevious()
     {
       return li.hasPrevious();
     }
 
+    /**
+     * Find the index of the element that would be returned by a call to next.
+     * If <code>hasNext()</code> returns <code>false</code>, this returns the list size.
+     *
+     * @return the index of the element that would be returned by
+     *         <code>next()</code>.
+     */
     public int nextIndex()
     {
       return li.nextIndex();
     }
 
+    /**
+     * Obtains the previous element in the underlying list.
+     *
+     * @return the previous element in the list.
+     * @throws NoSuchElementException if there are no more prior elements.
+     */
     public Object previous()
     {
       return li.previous();
     }
 
+    /**
+     * Find the index of the element that would be returned by a call to
+     * previous. If <code>hasPrevious()</code> returns <code>false</code>,
+     * this returns -1.
+     *
+     * @return the index of the element that would be returned by
+     *         <code>previous()</code>.
+     */
     public int previousIndex()
     {
       return li.previousIndex();
     }
 
+    /**
+     * Blocks the replacement of an element in the list underlying this
+     * iterator.  This method never returns, throwing an exception instead.
+     *
+     * @param o The new object to replace the existing one.
+     * @throws UnsupportedOperationException as the iterator of an unmodifiable
+     *         list does not support the <code>set()</code> operation.
+     */
     public void set(Object o)
     {
       throw new UnsupportedOperationException();
@@ -3290,6 +4681,9 @@ public class Collections
    * access, although changes in the backing map show up in this view.
    * Attempts to modify the map directly, or via collection views or their
    * iterators will fail with {@link UnsupportedOperationException}.
+   * Although this view prevents changes to the structure of the map and its
+   * entries, the values referenced by the objects in the map can still be
+   * modified.   
    * <p>
    *
    * The returned Map implements Serializable, but can only be serialized if
@@ -3350,21 +4744,62 @@ public class Collections
         throw new NullPointerException();
     }
 
+    /**
+     * Blocks the clearing of entries from the underlying map.
+     * This method never returns, throwing an exception instead.
+     *
+     * @throws UnsupportedOperationException as an unmodifiable
+     *         map does not support the <code>clear()</code> operation.
+     */
     public void clear()
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Returns <code>true</code> if the underlying map contains a mapping for
+     * the given key.
+     *
+     * @param key the key to search for
+     * @return <code>true</code> 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)
     {
       return m.containsKey(key);
     }
 
+    /**
+     * Returns <code>true</code> if the underlying map contains at least one mapping with
+     * the given value.  In other words, it returns <code>true</code> 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 <code>true</code> if the map contains the value
+     * @throws ClassCastException if the type of the value is not a valid type
+     *         for this map.
+     * @throws NullPointerException if the value is null and the map doesn't
+     *         support null values.
+     */
     public boolean containsValue(Object value)
     {
       return m.containsValue(value);
     }
 
+    /**
+     * Returns a unmodifiable set view of the entries in the underlying map.
+     * Each element in the set is a unmodifiable variant of <code>Map.Entry</code>.
+     * 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.  These modifications are again limited to the values of
+     * the objects.
+     *
+     * @return the unmodifiable set view of all mapping entries.
+     * @see Map.Entry
+     */
     public Set entrySet()
     {
       if (entries == null)
@@ -3400,31 +4835,82 @@ public class Collections
       {
         return new UnmodifiableIterator(c.iterator())
 	{
+	  /**
+	   * Obtains the next element from the underlying set of
+	   * map entries.
+	   *
+	   * @return the next element in the collection.
+	   * @throws NoSuchElementException if there are no more elements.
+	   */
           public Object next()
           {
             final Map.Entry e = (Map.Entry) super.next();
             return new Map.Entry()
 	    {
+	      /**
+	       * Returns <code>true</code> if the object, o, is also a map entry with an
+	       * identical key and value.
+	       *
+	       * @param o the object to compare.
+	       * @return <code>true</code> if o is an equivalent map entry.
+	       */
               public boolean equals(Object o)
               {
                 return e.equals(o);
               }
+	      
+	      /**
+	       * Returns the key of this map entry.
+	       *
+	       * @return the key.
+	       */
               public Object getKey()
               {
                 return e.getKey();
               }
+
+	      /**
+	       * Returns the value of this map entry.
+	       *
+	       * @return the value.
+	       */
               public Object getValue()
               {
                 return e.getValue();
               }
+
+	      /**
+	       * Computes the hash code of this map entry.
+	       * The computation is described in the <code>Map</code>
+	       * interface documentation.
+	       *
+	       * @return the hash code of this entry.
+	       * @see Map#hashCode()
+	       */
               public int hashCode()
               {
                 return e.hashCode();
               }
+
+	      /**
+	       * Blocks the alteration of the value of this map entry.
+	       * This method never returns, throwing an exception instead.
+	       *
+	       * @param value The new value.
+	       * @throws UnsupportedOperationException as an unmodifiable
+	       *         map entry does not support the <code>setValue()</code>
+	       *         operation.
+	       */
               public Object setValue(Object value)
               {
                 throw new UnsupportedOperationException();
               }
+
+	      /**
+	       * Returns a textual representation of the map entry.
+	       *
+	       * @return The map entry as a <code>String</code>.
+	       */
               public String toString()
               {
                 return e.toString();
@@ -3435,31 +4921,82 @@ public class Collections
       }
     } // class UnmodifiableEntrySet
 
+    /**
+     * Returns <code>true</code> if the object, o, is also an instance
+     * of <code>Map</code> with an equal set of map entries.
+     *
+     * @param o The object to compare.
+     * @return <code>true</code> if o is an equivalent map.
+     */
     public boolean equals(Object o)
     {
       return m.equals(o);
     }
 
+    /**
+     * Returns the value associated with the supplied key or
+     * null if no such mapping exists.  An ambiguity can occur
+     * if null values are accepted by the underlying map.
+     * In this case, <code>containsKey()</code> can be used
+     * to separate the two possible cases of a null result.
+     *
+     * @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)
     {
       return m.get(key);
     }
 
+    /**
+     * Blocks the addition of a new entry to the underlying map.
+     * This method never returns, throwing an exception instead.
+     *
+     * @param key The new key.
+     * @param value The new value.
+     * @return the previous value of the key, or null if there was no mapping.
+     * @throws UnsupportedOperationException as an unmodifiable
+     *         map does not support the <code>put()</code> operation.
+     */
     public Object put(Object key, Object value)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Computes the hash code for the underlying map, as the sum
+     * of the hash codes of all entries.
+     *
+     * @return The hash code of the underlying map.
+     * @see Map.Entry#hashCode()
+     */
     public int hashCode()
     {
       return m.hashCode();
     }
 
+    /**
+     * Returns <code>true</code> if the underlying map contains no entries.
+     *
+     * @return <code>true</code> if the map is empty.
+     */
     public boolean isEmpty()
     {
       return m.isEmpty();
     }
 
+    /**
+     * Returns a unmodifiable set view of the keys in the underlying 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.  These modifications are again limited to the values of
+     * the keys.
+     *
+     * @return the set view of all keys.
+     */
     public Set keySet()
     {
       if (keys == null)
@@ -3467,26 +5004,68 @@ public class Collections
       return keys;
     }
 
+    /**
+     * Blocks the addition of the entries in the supplied map.
+     * This method never returns, throwing an exception instead.
+     *
+     * @param m The map, the entries of which should be added
+     *          to the underlying map.
+     * @throws UnsupportedOperationException as an unmodifiable
+     *         map does not support the <code>putAll</code> operation.
+     */
     public void putAll(Map m)
     {
       throw new UnsupportedOperationException();
     }
 
+    /**
+     * Blocks the removal of an entry from the map.
+     * This method never returns, throwing an exception instead.
+     *
+     * @param o The key of the entry to remove.
+     * @return The value the key was associated with, or null
+     *         if no such mapping existed.  Null is also returned
+     *         if the removed entry had a null key.
+     * @throws UnsupportedOperationException as an unmodifiable
+     *         map does not support the <code>remove</code> operation.
+     */
     public Object remove(Object o)
     {
       throw new UnsupportedOperationException();
     }
 
+
+    /**
+     * Returns the number of key-value mappings in the underlying map.
+     * If there are more than Integer.MAX_VALUE mappings, Integer.MAX_VALUE
+     * is returned.
+     *
+     * @return the number of mappings.
+     */
     public int size()
     {
       return m.size();
     }
 
+    /**
+     * Returns a textual representation of the map.
+     *
+     * @return The map in the form of a <code>String</code>.
+     */
     public String toString()
     {
       return m.toString();
     }
 
+    /**
+     * Returns a unmodifiable collection view of the values in the underlying 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.  These modifications are again limited to the values of
+     * the keys.
+     *
+     * @return the collection view of all values.
+     */
     public Collection values()
     {
       if (values == null)
@@ -3500,6 +5079,9 @@ public class Collections
    * "read-only" access, although changes in the backing set show up
    * in this view. Attempts to modify the set directly or via iterators
    * will fail with {@link UnsupportedOperationException}.
+   * Although this view prevents changes to the structure of the set and its
+   * entries, the values referenced by the objects in the set can still be
+   * modified.   
    * <p>
    *
    * The returned Set implements Serializable, but can only be serialized if
@@ -3538,11 +5120,23 @@ public class Collections
       super(s);
     }
 
+    /**
+     * Returns <code>true</code> if the object, o, is also an instance of
+     * <code>Set</code> of the same size and with the same entries.
+     *
+     * @return <code>true</code> if o is an equivalent set.
+     */
     public boolean equals(Object o)
     {
       return c.equals(o);
     }
 
+    /**
+     * Computes the hash code of this set, as the sum of the
+     * hash codes of all elements within the set.
+     *
+     * @return the hash code of the set.
+     */ 
     public int hashCode()
     {
       return c.hashCode();
@@ -3554,6 +5148,9 @@ public class Collections
    * "read-only" access, although changes in the backing map show up in this
    * view. Attempts to modify the map directly, via subviews, via collection
    * views, or iterators, will fail with {@link UnsupportedOperationException}.
+   * Although this view prevents changes to the structure of the map and its
+   * entries, the values referenced by the objects in the map can still be
+   * modified.   
    * <p>
    *
    * The returned SortedMap implements Serializable, but can only be
@@ -3600,31 +5197,119 @@ public class Collections
       this.sm = sm;
     }
 
+    /**
+     * Returns the comparator used in sorting the underlying map,
+     * or null if it is the keys' natural ordering.
+     *
+     * @return the sorting comparator.
+     */
     public Comparator comparator()
     {
       return sm.comparator();
     }
 
+    /**
+     * Returns the first (lowest sorted) key in the map.
+     *
+     * @return the first key.
+     * @throws NoSuchElementException if this map is empty.
+     */
     public Object firstKey()
     {
       return sm.firstKey();
     }
 
+    /**
+     * Returns a unmodifiable view of the portion of the map strictly less
+     * than toKey. The view is backed by the underlying map, so changes in
+     * one show up in the other.  The submap supports all optional operations
+     * of the original.  This operation is equivalent to
+     * <code>subMap(firstKey(), toKey)</code>.
+     * <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, toKey,
+     * is not included; if you want this value to be included, pass its successor
+     * object in to toKey.  For example, for Integers, you could request
+     * <code>headMap(new Integer(limit.intValue() + 1))</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.
+     */
     public SortedMap headMap(Object toKey)
     {
       return new UnmodifiableSortedMap(sm.headMap(toKey));
     }
 
+    /**
+     * Returns the last (highest sorted) key in the map.
+     *
+     * @return the last key.
+     * @throws NoSuchElementException if this map is empty.
+     */
     public Object lastKey()
     {
       return sm.lastKey();
     }
 
+    /**
+     * Returns a unmodifiable view of the portion of the map greater than or
+     * equal to fromKey, and strictly less than toKey. The view is backed by
+     * the underlying 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 its successor
+     * object in instead.  For example, for Integers, you could request
+     * <code>subMap(new Integer(lowlimit.intValue() + 1),
+     * new Integer(highlimit.intValue() + 1))</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.
+     */
     public SortedMap subMap(Object fromKey, Object toKey)
     {
       return new UnmodifiableSortedMap(sm.subMap(fromKey, toKey));
     }
 
+    /**
+     * Returns a unmodifiable view of the portion of the map greater than or
+     * equal to fromKey. The view is backed by the underlying 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, fromKey, is
+     * included; if you do not want this value to be included, pass its successor object in
+     * to fromKey.  For example, for Integers, you could request
+     * <code>tailMap(new Integer(limit.intValue() + 1))</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
+     */
     public SortedMap tailMap(Object fromKey)
     {
       return new UnmodifiableSortedMap(sm.tailMap(fromKey));
@@ -3636,6 +5321,9 @@ public class Collections
    * "read-only" access, although changes in the backing set show up
    * in this view. Attempts to modify the set directly, via subsets, or via
    * iterators, will fail with {@link UnsupportedOperationException}.
+   * Although this view prevents changes to the structure of the set and its
+   * entries, the values referenced by the objects in the set can still be
+   * modified.   
    * <p>
    *
    * The returns SortedSet implements Serializable, but can only be
@@ -3682,31 +5370,121 @@ public class Collections
       this.ss = ss;
     }
 
+    /**
+     * Returns the comparator used in sorting the underlying set,
+     * or null if it is the elements' natural ordering.
+     *
+     * @return the sorting comparator
+     */
     public Comparator comparator()
     {
       return ss.comparator();
     }
 
+    /**
+     * Returns the first (lowest sorted) element in the underlying
+     * set.
+     *
+     * @return the first element.
+     * @throws NoSuchElementException if the set is empty.
+     */
     public Object first()
     {
       return ss.first();
     }
 
+    /**
+     * Returns a unmodifiable view of the portion of the set strictly
+     * less than toElement. The view is backed by the underlying set,
+     * so changes in one show up in the other.  The subset supports
+     * all optional operations of the original.  This operation
+     * is equivalent to <code>subSet(first(), toElement)</code>.
+     * <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, toElement,
+     * is not included; if you want this value included, pass its successor object in to
+     * toElement.  For example, for Integers, you could request
+     * <code>headSet(new Integer(limit.intValue() + 1))</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 set does not
+     *         allow null elements.
+     */
     public SortedSet headSet(Object toElement)
     {
       return new UnmodifiableSortedSet(ss.headSet(toElement));
     }
 
+    /**
+     * Returns the last (highest sorted) element in the underlying
+     * set.
+     *
+     * @return the last element.
+     * @throws NoSuchElementException if the set is empty.
+     */
     public Object last()
     {
       return ss.last();
     }
 
+    /**
+     * Returns a unmodifiable view of the portion of the set greater than or
+     * equal to fromElement, and strictly less than toElement. The view is backed by
+     * the underlying 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 its successor
+     * object in instead.  For example, for Integers, you can request
+     * <code>subSet(new Integer(lowlimit.intValue() + 1),
+     * new Integer(highlimit.intValue() + 1))</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.
+     */
     public SortedSet subSet(Object fromElement, Object toElement)
     {
       return new UnmodifiableSortedSet(ss.subSet(fromElement, toElement));
     }
 
+    /**
+     * Returns a unmodifiable view of the portion of the set greater than or equal to
+     * fromElement. The view is backed by the underlying 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,
+     * fromElement, is included; if you do not want this value to be included, pass its
+     * successor object in to fromElement.  For example, for Integers, you could request
+     * <code>tailSet(new Integer(limit.intValue() + 1))</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.
+     */
     public SortedSet tailSet(Object fromElement)
     {
       return new UnmodifiableSortedSet(ss.tailSet(fromElement));
diff --git a/libjava/java/util/SortedMap.java b/libjava/java/util/SortedMap.java
index 742524e..1d2d5a3 100644
--- a/libjava/java/util/SortedMap.java
+++ b/libjava/java/util/SortedMap.java
@@ -97,10 +97,10 @@ public interface SortedMap extends Map
    * <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>.
+   * used which is out of the range of toKey. Note that the endpoint, toKey,
+   * is not included; if you want this value to be included, pass its successor
+   * object in to toKey.  For example, for Integers, you could request
+   * <code>headMap(new Integer(limit.intValue() + 1))</code>.
    *
    * @param toKey the exclusive upper range of the submap
    * @return the submap
@@ -130,9 +130,10 @@ public interface SortedMap extends Map
    * 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
+   * change the inclusion or exclusion of an endpoint, pass its successor
+   * object in instead.  For example, for Integers, you could request
+   * <code>subMap(new Integer(lowlimit.intValue() + 1),
+   * new Integer(highlimit.intValue() + 1))</code> to reverse
    * the inclusiveness of both endpoints.
    *
    * @param fromKey the inclusive lower range of the submap
@@ -154,10 +155,10 @@ public interface SortedMap extends Map
    * <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>.
+   * used which is out of the range of fromKey. Note that the endpoint, fromKey, is
+   * included; if you do not want this value to be included, pass its successor object in
+   * to fromKey.  For example, for Integers, you could request
+   * <code>tailMap(new Integer(limit.intValue() + 1))</code>.
    *
    * @param fromKey the inclusive lower range of the submap
    * @return the submap
diff --git a/libjava/java/util/SortedSet.java b/libjava/java/util/SortedSet.java
index 415e95f..8cdbe87 100644
--- a/libjava/java/util/SortedSet.java
+++ b/libjava/java/util/SortedSet.java
@@ -99,10 +99,10 @@ public interface SortedSet extends Set
    * <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>.
+   * used which is out of the range of toElement. Note that the endpoint, toElement,
+   * is not included; if you want this value included, pass its successor object in to
+   * toElement.  For example, for Integers, you could request
+   * <code>headSet(new Integer(limit.intValue() + 1))</code>.
    *
    * @param toElement the exclusive upper range of the subset
    * @return the subset
@@ -133,9 +133,10 @@ public interface SortedSet extends Set
    * 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
+   * change the inclusion or exclusion of an endpoint, pass its successor
+   * object in instead.  For example, for Integers, you can request
+   * <code>subSet(new Integer(lowlimit.intValue() + 1),
+   * new Integer(highlimit.intValue() + 1))</code> to reverse
    * the inclusiveness of both endpoints.
    *
    * @param fromElement the inclusive lower range of the subset
@@ -157,10 +158,10 @@ public interface SortedSet extends Set
    * <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>.
+   * used which is out of the range of fromElement. Note that the endpoint,
+   * fromElement, is included; if you do not want this value to be included, pass its
+   * successor object in to fromElement.  For example, for Integers, you could request
+   * <code>tailSet(new Integer(limit.intValue() + 1))</code>.
    *
    * @param fromElement the inclusive lower range of the subset
    * @return the subset