--- jsr166/src/main/java/util/AbstractQueue.java	2003/07/28 04:11:54	1.6
+++ jsr166/src/main/java/util/AbstractQueue.java	2003/07/31 07:18:02	1.9
@@ -7,25 +7,62 @@
 package java.util;
 
 /**
- * AbstractQueue provides default implementations of add, remove, and
- * element based on offer, poll, and peek, respectively but that throw
- * exceptions instead of indicating failure via false or null returns.
- * The provided implementations all assume that the base implementation
+ * <tt>AbstractQueue</tt> provides default implementations of 
+ * {@link #add add}, {@link #remove remove}, and {@link #element element} 
+ * based on 
+ * {@link #offer offer}, {@link #poll poll}, and {@link #peek peek}, 
+ * respectively but that 
+ * throw exceptions instead of indicating failure via <tt>false</tt> or 
+ * <tt>null</tt> returns.
+ * <p>The provided implementations all assume that the base implementation
  * does <em>not</em> allow <tt>null</tt> elements.
  * @since 1.5
  * @author Doug Lea
  */
-
-public abstract class AbstractQueue<E> extends AbstractCollection<E> implements Queue<E> {
-
-    public boolean add(E x) {
-        if (offer(x))
+public abstract class AbstractQueue<E> 
+    extends AbstractCollection<E> 
+    implements Queue<E> {
+
+    // note that optional methods are not optional here or in our subclasses,
+    // so we redefine each optional method to document that it is not optional
+    // We also inherit, or define, all necessary @throws comments
+
+    /**
+     * Adds the specified element to this queue.
+     * @return <tt>true</tt> (as per the general contract of 
+     * <tt>Collection.add</tt>).
+     *
+     * @throws NullPointerException if the element is null
+     */
+    public boolean add(E o) {
+        if (offer(o))
             return true;
         else
             throw new IllegalStateException("Queue full");
     }
 
-    public E remove() throws NoSuchElementException {
+    /**
+     * Adds all of the elements in the specified collection to this queue.
+     * The behavior of this operation is undefined if
+     * the specified collection is modified while the operation is in
+     * progress.  (This implies that the behavior of this call is undefined if
+     * the specified collection is this queue, and this queue is nonempty.)
+     * <p>
+     * This implementation iterates over the specified collection, and adds
+     * each object returned by the iterator to this collection, in turn.
+     *
+     * @param c collection whose elements are to be added to this queue
+     * @return <tt>true</tt> if this collection changed as a result of the
+     *         call.
+     * @throws NullPointerException if <tt>c</tt> is <tt>null</tt>
+     * 
+     */
+    boolean addAll(Collection<? extends E> c) {
+        return super.addAll(c);
+    }
+
+    /** @throws NoSuchElementException {@inheritDoc} */
+    public E remove() {
         E x = poll();
         if (x != null)
             return x;
@@ -33,7 +70,8 @@ public abstract class AbstractQueue<E> e
             throw new NoSuchElementException();
     }
 
-    public E element() throws NoSuchElementException {
+    /** @throws NoSuchElementException {@inheritDoc} */
+    public E element() {
         E x = peek();
         if (x != null)
             return x;
@@ -41,12 +79,18 @@ public abstract class AbstractQueue<E> e
             throw new NoSuchElementException();
     }
 
+    /**
+     * Removes all of the elements from this collection.
+     * The collection will be empty after this call returns.
+     * <p>This implementation repeatedly invokes {@link #poll poll} until it
+     * returns <tt>null</tt>.
+     */
     public void clear() {
         while (poll() != null)
             ;
     }
 
-    // why is this here? Won't Collection declare this itself??? - David
+    // XXX Remove this redundant declaration, pending response from Neal Gafter.
     public abstract Iterator<E> iterator();
 }