RFR: JDK-8297605 DelayQueue javadoc is confusing

[Martin Buchholz]

On Thu, 23 Feb 2023 21:20:27 GMT, Martin Buchholz <martin at openjdk.org> wrote:

>> Clarifies the distinction between expiration of the head of DelayQueue and how it relates to `poll`, `take`, and `peek`. See discussion on https://bugs.openjdk.org/browse/JDK-8297605
>> 
>> @DougLea If possible, please weigh in on whether this is in line with your thoughts on the matter.
>
> Here's my attempt:
> 
> 
>  * 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>An element is considered <em>expired</em> when its {@code
>  * getDelay(TimeUnit.NANOSECONDS)} method would return a value less than or
>  * equal to zero.
>  *
>  * <p>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.
>  *
>  * <p>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>.
>  *
>  * <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 {@code 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.

> @Martin-Buchholz Martin, how would you like to proceed with your proposed wording, would you prefer a suggested edit to this PR, do a separate PR, or otherwise? /cc @AlanBateman (any recommendation, Alan? thinking )

Talked me into it - I will dust off my github/skara skillz and make a new PR.  

I wonder if there's now a way to override javadoc for remove() without creating a new method body.

-------------

PR: https://git.openjdk.org/jdk/pull/12729