RFR: 8359919: Minor java.util.concurrent doc improvements [v8]

[Doug Lea]

On Fri, 20 Jun 2025 12:10:42 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Doug Lea has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Adding JDK-8333172 to doc improvements
>
> src/java.base/share/classes/java/util/concurrent/TimeUnit.java line 402:
> 
>> 400:      * or equal to zero, do not wait at all.
>> 401:      * @throws  IllegalMonitorStateException  if the current thread is not
>> 402:      *               the owner of this object's monitor.
> 
> This should probably use "the object's monitor" rather than "the object's monitor" as "this" is the TimeUnit instance.

thanks. Done.

> src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java line 86:
> 
>> 84:  *   }
>> 85:  *   // ... and so on
>> 86:  * }}</pre>
> 
> I wonder if this should be convert to a `{@snippet ..}` and have it handle the checked exceptions thrown by findVarHandle. I'm just thinking of someone seeing VarHandle usage for first time, then reporting a bug that the example doesn't compile.

I made it compilable, in the lest ugly way I could think of. Not sure if either or both should now be snippets? @pavelrappo any thoughts?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25880#discussion_r2159051166
PR Review Comment: https://git.openjdk.org/jdk/pull/25880#discussion_r2159049484