--- jsr166/src/main/java/util/Queue.java	2003/12/27 19:26:15	1.22
+++ jsr166/src/main/java/util/Queue.java	2005/05/02 04:19:58	1.26
@@ -8,8 +8,38 @@ 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.
+ *
+ * <p><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
@@ -107,7 +137,7 @@ public interface Queue<E> extends Collec
 
     /**
      * Retrieves and removes the head of this queue.  This method
-     * differs from the <tt>poll</tt> method in that it throws an
+     * differs from the {@link #poll} method only in that it throws an
      * exception if this queue is empty.
      *
      * @return the head of this queue.
@@ -126,7 +156,7 @@ public interface Queue<E> extends Collec
 
     /**
      * Retrieves, but does not remove, the head of this queue.  This method
-     * differs from the <tt>peek</tt> method only in that it throws an
+     * differs from the {@link #peek} method only in that it throws an
      * exception if this queue is empty.
      *
      * @return the head of this queue.