RFR: JDK-8297605 DelayQueue javadoc is confusing

[Martin Buchholz]

On Thu, 23 Feb 2023 15:36:48 GMT, Viktor Klang <duke 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.

I like extending this approach as follows:
- define "head"
- define "expired head"
- make it clear that some methods operate on all elements (regardless of their expiration status), some only on expired elements.
- ensure that all public methods have an overriding javadoc that makes the distinction clear.  e.g. currently remove() needs such an overriding javadoc.
(writing good spec is hard work!)

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

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