--- jsr166/src/main/java/util/Queue.java	2004/11/21 01:40:39	1.23
+++ jsr166/src/main/java/util/Queue.java	2005/05/02 08:35:49	1.27
@@ -8,32 +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. The names
- * of the operations vary with their policies:
+ * 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>
+ * <p><table BORDER CELLPADDING=3 CELLSPACING=1>
  *  <tr>
- *    <td><em>Operation</em></td>
- *    <td ALIGN=CENTER><em>Attempt</em></td>
- *    <td ALIGN=CENTER><em>Throw</em></td>
+ *    <td></td>
+ *    <td ALIGN=CENTER><em>Throws exception</em></td>
+ *    <td ALIGN=CENTER><em>Returns special value</em></td>
  *  </tr>
  *  <tr>
- *    <td><em>insert</em></td>
- *    <td>offer(x)</td>
- *    <td>add(x)</td>
+ *    <td><b>Insert</b></td>
+ *    <td>{@link #add add(e)}</td>
+ *    <td>{@link #offer offer(e)}</td>
  *  </tr>
  *  <tr>
- *    <td><em>extract</em></td>
- *    <td>poll()</td>
- *    <td>remove()</td>
+ *    <td><b>Remove</b></td>
+ *    <td>{@link #remove remove()}</td>
+ *    <td>{@link #poll poll()}</td>
  *  </tr>
  *  <tr>
- *    <td><em>inspect</em></td>
- *    <td>peek()</td>
- *    <td>element()</td>
+ *    <td><b>Examine</b></td>
+ *    <td>{@link #element element()}</td>
+ *    <td>{@link #peek peek()}</td>
  *  </tr>
- *</table>
+ * </table>
  *
  * <p>Queues typically, but do not necessarily, order elements in a
  * FIFO (first-in-first-out) manner.  Among the exceptions are
@@ -114,11 +120,11 @@ public interface Queue<E> extends Collec
      * preferable to method {@link Collection#add}, which can fail to
      * insert an element only by throwing an exception.
      *
-     * @param o the element to insert.
+     * @param e the element to insert.
      * @return <tt>true</tt> if it was possible to add the element to
      * this queue, else <tt>false</tt>
      */
-    boolean offer(E o);
+    boolean offer(E e);
 
     /**
      * Retrieves and removes the head of this queue, or <tt>null</tt>
@@ -131,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.
@@ -150,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.