Collection.java, [...]: Added additional exceptions to documentation.

2004-08-01  Andrew John Hughes  <gnu_andrew@member.fsf.org>

	* java/util/Collection.java, java/util/List.java,
	java/util/Map.java, java/util/Set.java,
	java/util/SortedMap.java, java/util/SortedSet.java:
	Added additional exceptions to documentation.

From-SVN: r85403

7 files changed, 111 insertions, 6 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index a08c386..2897329 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,3 +1,10 @@
+2004-08-01  Andrew John Hughes  <gnu_andrew@member.fsf.org>
+
+	* java/util/Collection.java, java/util/List.java,
+	java/util/Map.java, java/util/Set.java,
+	java/util/SortedMap.java, java/util/SortedSet.java:
+	Added additional exceptions to documentation.
+
 2004-08-01  Danny Smith  <dannysmith@users.sourceforge.net>
 
 	PR libgcj/16814
diff --git a/libjava/java/util/Collection.java b/libjava/java/util/Collection.java
index 977c603..6ec9c4e 100644
--- a/libjava/java/util/Collection.java
+++ b/libjava/java/util/Collection.java
@@ -94,6 +94,8 @@ public interface Collection
    *   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.
    */
@@ -108,6 +110,9 @@ public interface Collection
    *   support the addAll operation.
    * @throws ClassCastException if some element of c cannot be added to this
    *   collection due to its type.
+   * @throws NullPointerException if some element of c is null and this
+   *   collection does not support the addition of null values.
+   * @throws NullPointerException if c itself is null.
    * @throws IllegalArgumentException if some element of c cannot be added
    *   to this collection for some other reason.
    */
@@ -129,6 +134,10 @@ public interface Collection
    * @param o the element to look for.
    * @return true 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.
    */
   boolean contains(Object o);
 
@@ -137,6 +146,11 @@ public interface Collection
    *
    * @param c the collection to test for.
    * @return true if for every element o in c, contains(o) would return true.
+   * @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 null values.
+   * @throws NullPointerException if c itself is null.
    */
   boolean containsAll(Collection c);
 
@@ -198,6 +212,10 @@ public interface Collection
    *   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.
    */
   boolean remove(Object o);
 
@@ -208,6 +226,11 @@ public interface Collection
    * @return true 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.
    */
   boolean removeAll(Collection c);
 
@@ -218,6 +241,11 @@ public interface Collection
    * @return true if this collection was modified as a result of this call.
    * @throws UnsupportedOperationException if this collection does not
    *   support the retainAll 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 retaining null values.
+   * @throws NullPointerException if c itself is null.
    */
   boolean retainAll(Collection c);
 
diff --git a/libjava/java/util/List.java b/libjava/java/util/List.java
index 22a6b83..0f7f409 100644
--- a/libjava/java/util/List.java
+++ b/libjava/java/util/List.java
@@ -97,6 +97,8 @@ public interface List extends Collection
    *         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.
    */
   void add(int index, Object o);
 
@@ -113,6 +115,8 @@ public interface List extends Collection
    *         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.
    */
   boolean add(Object o);
 
@@ -134,6 +138,8 @@ public interface List extends Collection
    *         list due to its type
    * @throws IllegalArgumentException if some element of c cannot be added
    *         to this list for some other reason
+   * @throws NullPointerException if some element of c is null and this list
+   *         doesn't support the addition of null values.
    * @throws NullPointerException if the specified collection is null
    * @see #add(int, Object)
    */
@@ -155,6 +161,8 @@ public interface List extends Collection
    * @throws IllegalArgumentException if some element of c cannot be added
    *         to this list for some other reason
    * @throws NullPointerException if the specified collection is null
+   * @throws NullPointerException if some element of c is null and this list
+   *         doesn't support the addition of null values.
    * @see #add(Object)
    */
   boolean addAll(Collection c);
@@ -175,6 +183,10 @@ public interface List extends Collection
    *
    * @param o the element to look for
    * @return true if this list contains the element
+   * @throws ClassCastException if the type of o is not a valid type
+   *         for this list.
+   * @throws NullPointerException if o is null and the list doesn't
+   *         support null values.
    */
   boolean contains(Object o);
 
@@ -184,6 +196,10 @@ public interface List extends Collection
    * @param c the collection to test for
    * @return true if for every element o in c, contains(o) would return true
    * @throws NullPointerException if the collection is null
+   * @throws ClassCastException if the type of any element in c is not a valid
+   *         type for this list.
+   * @throws NullPointerException if some element of c is null and this
+   *         list does not support null values.
    * @see #contains(Object)
    */
   boolean containsAll(Collection c);
@@ -240,7 +256,11 @@ while (i.hasNext())
    *
    * @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
+   *         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.
    */
   int indexOf(Object o);
 
@@ -263,7 +283,11 @@ while (i.hasNext())
    * 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
+   *         : 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.
    */
   int lastIndexOf(Object o);
 
@@ -310,6 +334,10 @@ while (i.hasNext())
    *         the list contained at least one occurrence of o
    * @throws UnsupportedOperationException if this list does not support the
    *         remove operation
+   * @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 removing null values.
    */
   boolean remove(Object o);
 
@@ -322,6 +350,10 @@ while (i.hasNext())
    * @throws UnsupportedOperationException if this list does not support the
    *         removeAll operation
    * @throws NullPointerException if the collection is null
+   * @throws ClassCastException if the type of any element in c is not a valid
+   *         type for this list.
+   * @throws NullPointerException if some element of c is null and this
+   *         list does not support removing null values.
    * @see #remove(Object)
    * @see #contains(Object)
    */
@@ -337,6 +369,10 @@ while (i.hasNext())
    * @throws UnsupportedOperationException if this list does not support the
    *         retainAll operation
    * @throws NullPointerException if the collection is null
+   * @throws ClassCastException if the type of any element in c is not a valid
+   *         type for this list.
+   * @throws NullPointerException if some element of c is null and this
+   *         list does not support retaining null values.
    * @see #remove(Object)
    * @see #contains(Object)
    */
@@ -355,6 +391,8 @@ while (i.hasNext())
    *         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.
    */
   Object set(int index, Object o);
 
@@ -381,8 +419,6 @@ while (i.hasNext())
    * @return a List backed by a subsection of this list
    * @throws IndexOutOfBoundsException if fromIndex &lt; 0
    *         || toIndex &gt; size() || fromIndex &gt; toIndex
-   * @throws IllegalArgumentException if fromIndex &gt; toIndex (according to
-   *         AbstractList). Don't you love Sun's inconsistent specifications?
    */
   List subList(int fromIndex, int toIndex);
 
diff --git a/libjava/java/util/Map.java b/libjava/java/util/Map.java
index f7643f9..75658da 100644
--- a/libjava/java/util/Map.java
+++ b/libjava/java/util/Map.java
@@ -106,6 +106,10 @@ public interface Map
    *
    * @param value the value to search for
    * @return true 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.
    */
   boolean containsValue(Object value);
 
@@ -164,7 +168,8 @@ public interface Map
    * @throws ClassCastException if the key or value is of the wrong type
    * @throws IllegalArgumentException if something about this key or value
    *         prevents it from existing in this map
-   * @throws NullPointerException if the map forbids null keys or values
+   * @throws NullPointerException if either the key or the value is null,
+   *         and the map forbids null keys or values
    * @see #containsKey(Object)
    */
   Object put(Object key, Object value);
@@ -224,8 +229,12 @@ public interface Map
    * @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.
    */
-  Object remove(Object o);
+  Object remove(Object key);
 
   /**
    * Returns the number of key-value mappings in the map. If there are more
diff --git a/libjava/java/util/Set.java b/libjava/java/util/Set.java
index 8a3290f..eb4df3e 100644
--- a/libjava/java/util/Set.java
+++ b/libjava/java/util/Set.java
@@ -118,6 +118,10 @@ public interface Set extends Collection
    *
    * @param o the object to look for
    * @return true if it is found in the set
+   * @throws ClassCastException if the type of o is not a valid type
+   *         for this set.
+   * @throws NullPointerException if o is null and this set doesn't
+   *         support null values.
    */
   boolean contains(Object o);
 
@@ -129,6 +133,10 @@ public interface Set extends Collection
    * @param c the collection to check membership in
    * @return true if all elements in this set are in c
    * @throws NullPointerException if c is null
+   * @throws ClassCastException if the type of any element in c is not
+   *         a valid type for this set.
+   * @throws NullPointerException if some element of c is null and this
+   *         set doesn't support null values.
    * @see #contains(Object)
    */
   boolean containsAll(Collection c);
@@ -148,6 +156,7 @@ public interface Set extends Collection
    * equals, this is the sum of the hashcode of all elements in the set.
    *
    * @return the sum of the hashcodes of all set elements
+   * @see #equals(Object)
    */
   int hashCode();
 
@@ -174,6 +183,10 @@ public interface Set extends Collection
    * @param o the object to remove
    * @return true if the set changed (an object was removed)
    * @throws UnsupportedOperationException if this operation is not allowed
+   * @throws ClassCastException if the type of o is not a valid type
+   *         for this set.
+   * @throws NullPointerException if o is null and this set doesn't allow
+   *         the removal of a null value.
    */
   boolean remove(Object o);
 
@@ -186,6 +199,10 @@ public interface Set extends Collection
    * @return true if this set changed as a result
    * @throws UnsupportedOperationException if this operation is not allowed
    * @throws NullPointerException if c is null
+   * @throws ClassCastException if the type of any element in c is not
+   *         a valid type for this set.
+   * @throws NullPointerException if some element of c is null and this
+   *         set doesn't support removing null values.
    * @see #remove(Object)
    */
   boolean removeAll(Collection c);
@@ -199,6 +216,10 @@ public interface Set extends Collection
    * @return true if this set was modified
    * @throws UnsupportedOperationException if this operation is not allowed
    * @throws NullPointerException if c is null
+   * @throws ClassCastException if the type of any element in c is not
+   *         a valid type for this set.
+   * @throws NullPointerException if some element of c is null and this
+   *         set doesn't support retaining null values.
    * @see #remove(Object)
    */
   boolean retainAll(Collection c);
diff --git a/libjava/java/util/SortedMap.java b/libjava/java/util/SortedMap.java
index 2ae36f9..742524e 100644
--- a/libjava/java/util/SortedMap.java
+++ b/libjava/java/util/SortedMap.java
@@ -86,6 +86,7 @@ public interface SortedMap extends Map
    * Returns the first (lowest sorted) key in the map.
    *
    * @return the first key
+   * @throws NoSuchElementException if this map is empty.
    */
   Object firstKey();
 
@@ -115,6 +116,7 @@ public interface SortedMap extends Map
    * Returns the last (highest sorted) key in the map.
    *
    * @return the last key
+   * @throws NoSuchElementException if this map is empty.
    */
   Object lastKey();
 
diff --git a/libjava/java/util/SortedSet.java b/libjava/java/util/SortedSet.java
index 401edb9..81dff0c 100644
--- a/libjava/java/util/SortedSet.java
+++ b/libjava/java/util/SortedSet.java
@@ -88,6 +88,7 @@ public interface SortedSet extends Set
    * Returns the first (lowest sorted) element in the map.
    *
    * @return the first element
+   * @throws NoSuchElementException if the set is empty.
    */
   Object first();
 
@@ -118,6 +119,7 @@ public interface SortedSet extends Set
    * Returns the last (highest sorted) element in the map.
    *
    * @return the last element
+   * @throws NoSuchElementException if the set is empty.
    */
   Object last();