Summary

Specify the treatment of expired vs. unexpired elements in DelayQueue methods.

Problem

Some DelayQueue methods disregard unexpired elements, but the documentation does not make it sufficiently clear which ones do.

Solution

Add more javadoc to make it clear. The Queue.remove method needs javadoc for its nonstandard behavior even though it doesn't need an implementation override.

We fix the documentation to match the long-standing implementation and author intent.

Specification

 * An unbounded {@linkplain BlockingQueue blocking queue} of {@link Delayed}
 * elements, in which an element generally becomes eligible for removal when its
 * delay has expired.
 *
 * <p><a id="expired">An element is considered <em>expired</em> when its
 * {@code getDelay(TimeUnit.NANOSECONDS)} method would return a value less than
 * or equal to zero.</a>
 *
 * <p><a id="head">An element is considered the <em>head</em> of the queue if it
 * is the element with the earliest expiration time, whether in the past or the
 * future, if there is such an element.</a>
 *
 * <p><a id="expired-head">An element is considered the <em>expired head</em> of
 * the queue if it is the <em>expired</em> element with the earliest expiration
 * time in the past, if there is such an element.
 * The <em>expired head</em>, when present, is also the <em>head</em>.</a>
 *
 * <p>While this class implements the {@code BlockingQueue} interface, it
 * intentionally violates the general contract of {@code BlockingQueue}, in that
 * the following methods disregard the presence of unexpired elements and only
 * ever remove the <em>expired head</em>:
 *
 * <ul>
 * <li> {@link #poll()}
 * <li> {@link #poll(long,TimeUnit)}
 * <li> {@link #take()}
 * <li> {@link #remove()}
 * </ul>
 *
 * <p>All other methods operate on both expired and unexpired elements.
 * For example, the {@link #size()} method returns the count of all elements.
 * Method {@link #peek()} may return the (non-null) <em>head</em> even when
 * {@code take()} would block waiting for that element to expire.

     /**
-     * Retrieves and removes the head of this queue, or returns {@code null}
-     * if this queue has no elements with an expired delay.
+     * Retrieves and removes the <a href="#expired-head">expired head</a> of
+     * this queue, or returns {@code null} if this queue has no
+     * <a href="#expired">expired elements</a>.
      *
-     * @return the head of this queue, or {@code null} if this
+     * @return the <em>expired head</em> of this queue, or {@code null} if this
      *         queue has no elements with an expired delay
      */
     public E poll() {
@@ -201,10 +225,11 @@ public class DelayQueue<E extends Delayed> extends AbstractQueue<E>
     }

     /**
-     * Retrieves and removes the head of this queue, waiting if necessary
-     * until an element with an expired delay is available on this queue.
+     * Retrieves and removes the <a href="#expired-head">expired head</a> of
+     * this queue, waiting if necessary until an
+     * <a href="#expired">expired element</a> is available on this queue.
      *
-     * @return the head of this queue
+     * @return the <em>expired head</em> of this queue
      * @throws InterruptedException {@inheritDoc}
      */
     public E take() throws InterruptedException {
@@ -242,11 +267,12 @@ public class DelayQueue<E extends Delayed> extends AbstractQueue<E>
     }

     /**
-     * Retrieves and removes the head of this queue, waiting if necessary
-     * until an element with an expired delay is available on this queue,
+     * Retrieves and removes the <a href="#expired-head">expired head</a> of
+     * this queue, waiting if necessary until an
+     * <a href="#expired">expired element</a> is available on this queue,
      * or the specified wait time expires.
      *
-     * @return the head of this queue, or {@code null} if the
+     * @return the <em>expired head</em> of this queue, or {@code null} if the
      *         specified waiting time elapses before an element with
      *         an expired delay becomes available
      * @throws InterruptedException {@inheritDoc}
@@ -293,13 +319,25 @@ public class DelayQueue<E extends Delayed> extends AbstractQueue<E>
     }

     /**
-     * Retrieves, but does not remove, the head of this queue, or
-     * returns {@code null} if this queue is empty.  Unlike
-     * {@code poll}, if no expired elements are available in the queue,
-     * this method returns the element that will expire next,
-     * if one exists.
+     * Retrieves and removes the <a href="#expired-head">expired head</a> of
+     * this queue, or throws an exception if this queue has no
+     * <a href="#expired">expired elements</a>.
+     *
+     * @return the <em>expired head</em> of this queue
+     * @throws NoSuchElementException if this queue has no elements with an
+     *         expired delay
+     */
+    public E remove() {
+        return super.remove();
+    }
+
+    /**
+     * Retrieves, but does not remove, the <a href="#head">head</a> of this
+     * queue, or returns {@code null} if this queue is empty.
+     * Unlike {@code poll}, if no expired elements are available in the queue,
+     * this method returns the element that will expire next, if one exists.
      *
-     * @return the head of this queue, or {@code null} if this
+     * @return the <em>head</em> of this queue, or {@code null} if this
      *         queue is empty
      */
     public E peek() {