RFR: 8359919: Minor java.util.concurrent doc improvements

[Doug Lea]

On Thu, 19 Jun 2025 09:36:19 GMT, Viktor Klang <vklang at openjdk.org> wrote:

>> This collects miscellaneous open issues that can be resolved with documentation updates; each indicated by adding JDK issue numbers
>
> src/java.base/share/classes/java/util/concurrent/CompletionStage.java line 103:
> 
>> 101:  * cause. This distinguishes exceptions in an action itself from those
>> 102:  * it depends on. If you want them handled in the same way, you might
>> 103:  * choose to catch {@link RuntimeException}.  If a stage is dependent
> 
> Perhaps something like the following:
> 
> Suggestion:
> 
>  * it depends on. If they are to be handled the same, instead catch {@link RuntimeException}.
>  *  If a stage is dependent
> 
> 
> 🤔

Done

> src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java line 49:
> 
>> 47: /**
>> 48:  * A reflection-based utility that enables atomic updates to
>> 49:  * designated non-static {@code volatile} reference fields of designated
> 
> Wouldn't this change also apply to the other AtomicXFieldUpdaters?

Yes. Will do. Also, as mentioned by @liach we could trap violations by throwing a better exception. But considering that people should be using VarHandles instead anyway these days, and old uses might depend on current behavior, it doesn't seem worthwhile to add? (line 338)
+            if (Modifier.isStatic(modifiers))
+                throw new IllegalArgumentException("Must not be static");

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25880#discussion_r2156718705
PR Review Comment: https://git.openjdk.org/jdk/pull/25880#discussion_r2156709501