--- jsr166/src/main/java/util/Queue.java	2003/09/12 15:38:26	1.17
+++ jsr166/src/main/java/util/Queue.java	2004/12/26 20:13:57	1.24
@@ -1,15 +1,45 @@
 /*
  * Written by Doug Lea with assistance from members of JCP JSR-166
- * Expert Group and released to the public domain. Use, modify, and
- * redistribute this code in any way without acknowledgement.
+ * Expert Group and released to the public domain, as explained at
+ * http://creativecommons.org/licenses/publicdomain
  */
 
 package java.util;
 
 /**
  * A collection designed for holding elements prior to processing.
- * Besides basic {@link java.util.Collection Collection} operations, queues provide
- * additional insertion, extraction, and inspection operations.
+ * Besides basic {@link java.util.Collection Collection} operations,
+ * queues provide additional insertion, extraction, and inspection
+ * operations.  Each of these methods exists in two forms: one throws
+ * an exception if the operation fails, the other returns a special
+ * value (either <tt>null</tt> or <tt>false</tt>, depending on the
+ * operation).  The latter form of the insert operation is designed
+ * specifically for use with capacity-restricted <tt>Queue</tt>
+ * implementations; in most implementations, insert operations cannot
+ * fail.
+ *
+ * <table BORDER CELLPADDING=3 CELLSPACING=1>
+ *  <tr>
+ *    <td></td>
+ *    <td ALIGN=CENTER><em>Throws exception</em></td>
+ *    <td ALIGN=CENTER><em>Returns special value</em></td>
+ *  </tr>
+ *  <tr>
+ *    <td><b>Insert</b></td>
+ *    <td>{@link #add add(e)}</td>
+ *    <td>{@link #offer offer(e)}</td>
+ *  </tr>
+ *  <tr>
+ *    <td><b>Remove</b></td>
+ *    <td>{@link #remove remove()}</td>
+ *    <td>{@link #poll poll()}</td>
+ *  </tr>
+ *  <tr>
+ *    <td><b>Examine</b></td>
+ *    <td>{@link #element element()}</td>
+ *    <td>{@link #peek peek()}</td>
+ *  </tr>
+ * </table>
  *
  * <p>Queues typically, but do not necessarily, order elements in a
  * FIFO (first-in-first-out) manner.  Among the exceptions are
@@ -79,11 +109,12 @@ package java.util;
  * @see java.util.concurrent.PriorityBlockingQueue
  * @since 1.5
  * @author Doug Lea
+ * @param <E> the type of elements held in this collection
  */
 public interface Queue<E> extends Collection<E> {
 
     /**
-     * Inserts the specified element to this queue, if possible.  When
+     * Inserts the specified element into this queue, if possible.  When
      * using queues that may impose insertion restrictions (for
      * example capacity bounds), method <tt>offer</tt> is generally
      * preferable to method {@link Collection#add}, which can fail to
@@ -96,7 +127,8 @@ public interface Queue<E> extends Collec
     boolean offer(E o);
 
     /**
-     * Retrieves and removes the head of this queue, if it is available.
+     * Retrieves and removes the head of this queue, or <tt>null</tt>
+     * if this queue is empty.
      *
      * @return the head of this queue, or <tt>null</tt> if this
      *         queue is empty.
@@ -104,10 +136,9 @@ public interface Queue<E> extends Collec
     E poll();
 
     /**
-     * Retrieves and removes the head of this queue.
-     * This method differs
-     * from the <tt>poll</tt> method in that it throws an exception if this
-     * queue is empty.
+     * Retrieves and removes the head of this queue.  This method
+     * differs from the <tt>poll</tt> method in that it throws an
+     * exception if this queue is empty.
      *
      * @return the head of this queue.
      * @throws NoSuchElementException if this queue is empty.
@@ -115,12 +146,11 @@ public interface Queue<E> extends Collec
     E remove();
 
     /**
-     * Retrieves, but does not remove, the head of this queue.
-     * This method differs from the <tt>poll</tt>
-     * method only in that this method does not remove the head element from
-     * this queue.
+     * Retrieves, but does not remove, the head of this queue,
+     * returning <tt>null</tt> if this queue is empty.
      *
-     * @return the head of this queue, or <tt>null</tt> if this queue is empty.
+     * @return the head of this queue, or <tt>null</tt> if this queue
+     * is empty.
      */
     E peek();