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

[Viktor Klang]

On Wed, 18 Jun 2025 17:51:20 GMT, Doug Lea <dl 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


🤔

src/java.base/share/classes/java/util/concurrent/CompletionStage.java line 153:

> 151:  * <p>Memory consistency effects: Actions in a thread prior to the
> 152:  * submission of a computation producing a {@code CompletionStage}
> 153:  * <i>happen-before</I> that computation begins. And actions taken by

Suggestion:

 * <i>happen-before</i> that computation begins. And actions taken by

src/java.base/share/classes/java/util/concurrent/CompletionStage.java line 155:

> 153:  * <i>happen-before</I> that computation begins. And actions taken by
> 154:  * a {@code CompletionStage} <i>happen-before</i> actions of any
> 155:  * dependent stage subsequent to its completion.

I found "its" ambiguous in that sentence, does it mean:

Suggestion:

 * dependent stage subsequent to that stage's completion.


🤔

src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java line 166:

> 164:  *   public void onNext(S item) {
> 165:  *     submit(function.apply(item));
> 166:  *     subscription.request(1);

👍

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?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25880#discussion_r2156580467
PR Review Comment: https://git.openjdk.org/jdk/pull/25880#discussion_r2156585287
PR Review Comment: https://git.openjdk.org/jdk/pull/25880#discussion_r2156590878
PR Review Comment: https://git.openjdk.org/jdk/pull/25880#discussion_r2156627931
PR Review Comment: https://git.openjdk.org/jdk/pull/25880#discussion_r2156630586