8297605: improve DelayQueue removal method javadoc

Reviewed-by: alanb

src/java.base/share/classes/java/util/concurrent/DelayQueue.java

@@ -47,18 +47,41 @@ import java.util.concurrent.locks.Condition;
 import java.util.concurrent.locks.ReentrantLock;
 
 /**
- * An unbounded {@linkplain BlockingQueue blocking queue} of
- * {@code Delayed} elements, in which an element can only be taken
- * when its delay has expired.  The <em>head</em> of the queue is that
- * {@code Delayed} element whose delay expired furthest in the
- * past.  If no delay has expired there is no head and {@code poll}
- * will return {@code null}. Expiration occurs when an element's
- * {@code getDelay(TimeUnit.NANOSECONDS)} method returns a value less
- * than or equal to zero.  Even though unexpired elements cannot be
- * removed using {@code take} or {@code poll}, they are otherwise
- * treated as normal elements. For example, the {@code size} method
- * returns the count of both expired and unexpired elements.
- * This queue does not permit null elements.
+ * 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.
+ *
+ * <p>This queue does not permit null elements.
  *
  * <p>This class and its iterator implement all of the <em>optional</em>
  * methods of the {@link Collection} and {@link Iterator} interfaces.
@@ -181,10 +204,11 @@ public class DelayQueue<E extends Delayed> extends AbstractQueue<E>
     }
 
     /**
-     * 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 head of this queue, or {@code null} if this
+     * @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 <em>head</em> of this queue, or {@code null} if this
      *         queue is empty
      */
     public E peek() {