--- jsr166/src/jsr166y/LinkedTransferQueue.java	2009/07/30 22:45:39	1.35
+++ jsr166/src/jsr166y/LinkedTransferQueue.java	2009/08/01 21:24:01	1.43
@@ -18,7 +18,7 @@ import java.util.concurrent.locks.LockSu
 import java.util.concurrent.atomic.AtomicReference;
 
 /**
- * An unbounded {@linkplain TransferQueue} based on linked nodes.
+ * An unbounded {@link TransferQueue} based on linked nodes.
  * This queue orders elements FIFO (first-in-first-out) with respect
  * to any given producer.  The <em>head</em> of the queue is that
  * element that has been on the queue the longest time for some
@@ -294,7 +294,7 @@ public class LinkedTransferQueue<E> exte
      * @param e the comparison value for checking match
      * @param mode mode
      * @param nanos timeout value
-     * @return matched item, or s if cancelled
+     * @return matched item, or null if cancelled
      */
     private E awaitFulfill(Node<E> pred, Node<E> s, E e,
                            int mode, long nanos) {
@@ -360,7 +360,7 @@ public class LinkedTransferQueue<E> exte
         for (;;) {
             Node<E> h = head.get();
             Node<E> first = h.next;
-            if (first != null && first.next == first) { // help advance
+            if (first != null && first.get() == first) { // help advance
                 advanceHead(h, first);
                 continue;
             }
@@ -511,7 +511,7 @@ public class LinkedTransferQueue<E> exte
 
     /**
      * Inserts the specified element at the tail of this queue.
-     * As the queue is unbounded this method will never throw
+     * As the queue is unbounded, this method will never throw
      * {@link IllegalStateException} or return {@code false}.
      *
      * @return {@code true} (as specified by {@link Collection#add})
@@ -522,10 +522,12 @@ public class LinkedTransferQueue<E> exte
     }
 
     /**
-     * Transfers the specified element immediately if there exists a
-     * consumer already waiting to receive it (in {@link #take} or
-     * timed {@link #poll(Object,long,TimeUnit) poll}), otherwise
-     * returning {@code false} without enqueuing the element.
+     * Transfers the element to a waiting consumer immediately, if possible.
+     *
+     * <p>More precisely, transfers the specified element immediately
+     * if there exists a consumer already waiting to receive it (in
+     * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
+     * otherwise returning {@code false} without enqueuing the element.
      *
      * @throws NullPointerException if the specified element is null
      */
@@ -535,11 +537,14 @@ public class LinkedTransferQueue<E> exte
     }
 
     /**
-     * Inserts the specified element at the tail of this queue,
-     * waiting if necessary for the element to be received by a
-     * consumer invoking {@code take} or {@code poll}.
+     * Transfers the element to a consumer, waiting if necessary to do so.
+     *
+     * <p>More precisely, transfers the specified element immediately
+     * if there exists a consumer already waiting to receive it (in
+     * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
+     * else inserts the specified element at the tail of this queue
+     * and waits until the element is received by a consumer.
      *
-     * @throws InterruptedException {@inheritDoc}
      * @throws NullPointerException if the specified element is null
      */
     public void transfer(E e) throws InterruptedException {
@@ -551,11 +556,17 @@ public class LinkedTransferQueue<E> exte
     }
 
     /**
-     * Inserts the specified element at the tail of this queue,
-     * waiting up to the specified wait time for the element to be
-     * received by a consumer invoking {@code take} or {@code poll}.
+     * Transfers the element to a consumer if it is possible to do so
+     * before the timeout elapses.
+     *
+     * <p>More precisely, transfers the specified element immediately
+     * if there exists a consumer already waiting to receive it (in
+     * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
+     * else inserts the specified element at the tail of this queue
+     * and waits until the element is received by a consumer,
+     * returning {@code false} if the specified wait time elapses
+     * before the element can be transferred.
      *
-     * @throws InterruptedException {@inheritDoc}
      * @throws NullPointerException if the specified element is null
      */
     public boolean tryTransfer(E e, long timeout, TimeUnit unit)
@@ -576,9 +587,6 @@ public class LinkedTransferQueue<E> exte
         throw new InterruptedException();
     }
 
-    /**
-     * @throws InterruptedException {@inheritDoc}
-     */
     public E poll(long timeout, TimeUnit unit) throws InterruptedException {
         E e = xfer(null, TIMEOUT, unit.toNanos(timeout));
         if (e != null || !Thread.interrupted())
@@ -754,6 +762,11 @@ public class LinkedTransferQueue<E> exte
         }
     }
 
+    /**
+     * Returns {@code true} if this queue contains no elements.
+     *
+     * @return {@code true} if this queue contains no elements
+     */
     public boolean isEmpty() {
         for (;;) {
             Node<E> h = traversalHead();
@@ -835,6 +848,17 @@ public class LinkedTransferQueue<E> exte
         }
     }
 
+    /**
+     * Removes a single instance of the specified element from this queue,
+     * if it is present.  More formally, removes an element {@code e} such
+     * that {@code o.equals(e)}, if this queue contains one or more such
+     * elements.
+     * Returns {@code true} if this queue contained the specified element
+     * (or equivalently, if this queue changed as a result of the call).
+     *
+     * @param o element to be removed from this queue, if present
+     * @return {@code true} if this queue changed as a result of the call
+     */
     public boolean remove(Object o) {
         if (o == null)
             return false;