diff --git a/src/java.base/share/classes/java/util/concurrent/AbstractExecutorService.java b/src/java.base/share/classes/java/util/concurrent/AbstractExecutorService.java
index 0d26607591d60..c249f63016309 100644
--- a/src/java.base/share/classes/java/util/concurrent/AbstractExecutorService.java
+++ b/src/java.base/share/classes/java/util/concurrent/AbstractExecutorService.java
@@ -44,16 +44,16 @@
 import java.util.Objects;
 
 /**
- * Provides default implementations of {@link ExecutorService}
- * execution methods. This class implements the {@code submit},
- * {@code invokeAny} and {@code invokeAll} methods using a
- * {@link RunnableFuture} returned by {@code newTaskFor}, which defaults
- * to the {@link FutureTask} class provided in this package.  For example,
- * the implementation of {@code submit(Runnable)} creates an
- * associated {@code RunnableFuture} that is executed and
- * returned. Subclasses may override the {@code newTaskFor} methods
- * to return {@code RunnableFuture} implementations other than
- * {@code FutureTask}.
+ * Provides default implementations of {@link ExecutorService} methods
+ * other than {@link Executor#execute}. This class implements the {@code
+ * submit}, {@code invokeAny} and {@code invokeAll} methods using a
+ * {@link RunnableFuture} returned by {@code newTaskFor}, which
+ * defaults to the {@link FutureTask} class provided in this package.
+ * For example, the implementation of {@code submit(Runnable)} creates
+ * an associated {@code RunnableFuture} that is executed and
+ * returned. Subclasses may override the {@code newTaskFor} methods to
+ * return {@code RunnableFuture} implementations other than {@code
+ * FutureTask}.
  *
  * <p><b>Extension example.</b> Here is a sketch of a class
  * that customizes {@link ThreadPoolExecutor} to use
diff --git a/src/java.base/share/classes/java/util/concurrent/CompletionStage.java b/src/java.base/share/classes/java/util/concurrent/CompletionStage.java
index 6ff31c61049cf..b43688428659e 100644
--- a/src/java.base/share/classes/java/util/concurrent/CompletionStage.java
+++ b/src/java.base/share/classes/java/util/concurrent/CompletionStage.java
@@ -43,7 +43,7 @@
 /**
  * A stage of a possibly asynchronous computation, that performs an
  * action or computes a value when another CompletionStage completes.
- * A stage completes upon termination of its computation, but this may
+ * A stage completes upon termination of its computation, which may
  * in turn trigger other dependent stages.  The functionality defined
  * in this interface takes only a few basic forms, which expand out to
  * a larger set of methods to capture a range of usage styles:
@@ -97,18 +97,25 @@
  * In all other cases, if a stage's computation terminates abruptly
  * with an (unchecked) exception or error, then all dependent stages
  * requiring its completion complete exceptionally as well, with a
- * {@link CompletionException} holding the exception as its cause.  If
- * a stage is dependent on <em>both</em> of two stages, and both
- * complete exceptionally, then the CompletionException may correspond
- * to either one of these exceptions.  If a stage is dependent on
- * <em>either</em> of two others, and only one of them completes
- * exceptionally, no guarantees are made about whether the dependent
- * stage completes normally or exceptionally. In the case of method
- * {@code whenComplete}, when the supplied action itself encounters an
- * exception, then the stage completes exceptionally with this
- * exception unless the source stage also completed exceptionally, in
- * which case the exceptional completion from the source stage is
- * given preference and propagated to the dependent stage.
+ * {@link CompletionException} holding the exception as its
+ * cause. This convention distinguishes exceptions in an action itself
+ * from those it depends on. If they are to be handled in the same
+ * way, instead catch {@link RuntimeException} (possibly inspecting
+ * the exception's {@code getCause()}).  If a stage is dependent on
+ * <em>both</em> of two stages, and both complete exceptionally, then
+ * the CompletionException may correspond to either one of these
+ * exceptions.  If a stage is dependent on <em>either</em> of two
+ * others, and only one of them completes exceptionally, no guarantees
+ * are made about whether the dependent stage completes normally or
+ * exceptionally. In the case of method {@code whenComplete}, when the
+ * supplied action itself encounters an exception, then the stage
+ * completes exceptionally with that exception unless the source stage
+ * also completed exceptionally, in which case the exceptional
+ * completion from the source stage is given preference and propagated
+ * to the dependent stage. Applications are encouraged to maintain
+ * these conventions, avoiding unnecessary nesting when rethrowing, as
+ * in {@code throw (ex instanceof CompletionException) ? ex : new
+ * CompletionException(ex)}.
  *
  * </ul>
  *
@@ -137,7 +144,7 @@
  *   }
  * }}</pre>
  *
- * <p>This interface does not define methods for initially creating,
+ * <p>The {@code CompletionStage} interface does not define methods for initially creating,
  * forcibly completing normally or exceptionally, probing completion
  * status or results, or awaiting completion of a stage.
  * Implementations of CompletionStage may provide means of achieving
@@ -145,6 +152,13 @@
  * enables interoperability among different implementations of this
  * interface by providing a common conversion type.
  *
+ * <p>Memory consistency effects: Actions in a thread prior to the
+ * submission of a computation producing a {@code CompletionStage} <a
+ * href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
+ * that computation begins. And actions taken by {@code
+ * CompletionStage x} <i>happen-before</i> actions of any dependent
+ * stage subsequent to {@code x}'s completion.
+ *
  * @param <T> the type of values the stage produces or consumes
  *
  * @author Doug Lea
@@ -153,8 +167,8 @@
 public interface CompletionStage<T> {
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * normally, is executed with this stage's result as the argument
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * normally, is executed with {@code this} stage's result as the argument
      * to the supplied function.
      *
      * <p>This method is analogous to
@@ -172,9 +186,9 @@ public interface CompletionStage<T> {
     public <U> CompletionStage<U> thenApply(Function<? super T,? extends U> fn);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * normally, is executed using this stage's default asynchronous
-     * execution facility, with this stage's result as the argument to
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * normally, is executed using {@code this} stage's default asynchronous
+     * execution facility, with {@code this} stage's result as the argument to
      * the supplied function.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -189,8 +203,8 @@ public interface CompletionStage<T> {
         (Function<? super T,? extends U> fn);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * normally, is executed using the supplied Executor, with this
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * normally, is executed using the supplied Executor, with {@code this}
      * stage's result as the argument to the supplied function.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -207,8 +221,8 @@ public interface CompletionStage<T> {
          Executor executor);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * normally, is executed with this stage's result as the argument
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * normally, is executed with {@code this} stage's result as the argument
      * to the supplied action.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -221,9 +235,9 @@ public interface CompletionStage<T> {
     public CompletionStage<Void> thenAccept(Consumer<? super T> action);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * normally, is executed using this stage's default asynchronous
-     * execution facility, with this stage's result as the argument to
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * normally, is executed using {@code this} stage's default asynchronous
+     * execution facility, with {@code this} stage's result as the argument to
      * the supplied action.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -236,8 +250,8 @@ public interface CompletionStage<T> {
     public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * normally, is executed using the supplied Executor, with this
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * normally, is executed using the supplied Executor, with {@code this}
      * stage's result as the argument to the supplied action.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -251,7 +265,7 @@ public interface CompletionStage<T> {
     public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action,
                                                  Executor executor);
     /**
-     * Returns a new CompletionStage that, when this stage completes
+     * Returns a new CompletionStage that, when {@code this} stage completes
      * normally, executes the given action.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -264,8 +278,8 @@ public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action,
     public CompletionStage<Void> thenRun(Runnable action);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * normally, executes the given action using this stage's default
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * normally, executes the given action using {@code this} stage's default
      * asynchronous execution facility.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -278,7 +292,7 @@ public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action,
     public CompletionStage<Void> thenRunAsync(Runnable action);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
+     * Returns a new CompletionStage that, when {@code this} stage completes
      * normally, executes the given action using the supplied Executor.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -293,7 +307,7 @@ public CompletionStage<Void> thenRunAsync(Runnable action,
                                               Executor executor);
 
     /**
-     * Returns a new CompletionStage that, when this and the other
+     * Returns a new CompletionStage that, when {@code this} and the other
      * given stage both complete normally, is executed with the two
      * results as arguments to the supplied function.
      *
@@ -312,8 +326,8 @@ public CompletionStage<Void> thenRunAsync(Runnable action,
          BiFunction<? super T,? super U,? extends V> fn);
 
     /**
-     * Returns a new CompletionStage that, when this and the other
-     * given stage both complete normally, is executed using this
+     * Returns a new CompletionStage that, when {@code this} and the other
+     * given stage both complete normally, is executed using {@code this}
      * stage's default asynchronous execution facility, with the two
      * results as arguments to the supplied function.
      *
@@ -332,7 +346,7 @@ public CompletionStage<Void> thenRunAsync(Runnable action,
          BiFunction<? super T,? super U,? extends V> fn);
 
     /**
-     * Returns a new CompletionStage that, when this and the other
+     * Returns a new CompletionStage that, when {@code this} and the other
      * given stage both complete normally, is executed using the
      * supplied executor, with the two results as arguments to the
      * supplied function.
@@ -354,7 +368,7 @@ public CompletionStage<Void> thenRunAsync(Runnable action,
          Executor executor);
 
     /**
-     * Returns a new CompletionStage that, when this and the other
+     * Returns a new CompletionStage that, when {@code this} and the other
      * given stage both complete normally, is executed with the two
      * results as arguments to the supplied action.
      *
@@ -372,8 +386,8 @@ public CompletionStage<Void> thenRunAsync(Runnable action,
          BiConsumer<? super T, ? super U> action);
 
     /**
-     * Returns a new CompletionStage that, when this and the other
-     * given stage both complete normally, is executed using this
+     * Returns a new CompletionStage that, when {@code this} and the other
+     * given stage both complete normally, is executed using {@code this}
      * stage's default asynchronous execution facility, with the two
      * results as arguments to the supplied action.
      *
@@ -391,7 +405,7 @@ public CompletionStage<Void> thenRunAsync(Runnable action,
          BiConsumer<? super T, ? super U> action);
 
     /**
-     * Returns a new CompletionStage that, when this and the other
+     * Returns a new CompletionStage that, when {@code this} and the other
      * given stage both complete normally, is executed using the
      * supplied executor, with the two results as arguments to the
      * supplied action.
@@ -412,7 +426,7 @@ public CompletionStage<Void> thenRunAsync(Runnable action,
          Executor executor);
 
     /**
-     * Returns a new CompletionStage that, when this and the other
+     * Returns a new CompletionStage that, when {@code this} and the other
      * given stage both complete normally, executes the given action.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -426,9 +440,9 @@ public CompletionStage<Void> thenRunAsync(Runnable action,
     public CompletionStage<Void> runAfterBoth(CompletionStage<?> other,
                                               Runnable action);
     /**
-     * Returns a new CompletionStage that, when this and the other
+     * Returns a new CompletionStage that, when {@code this} and the other
      * given stage both complete normally, executes the given action
-     * using this stage's default asynchronous execution facility.
+     * using {@code this} stage's default asynchronous execution facility.
      *
      * See the {@link CompletionStage} documentation for rules
      * covering exceptional completion.
@@ -442,7 +456,7 @@ public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
                                                    Runnable action);
 
     /**
-     * Returns a new CompletionStage that, when this and the other
+     * Returns a new CompletionStage that, when {@code this} and the other
      * given stage both complete normally, executes the given action
      * using the supplied executor.
      *
@@ -459,7 +473,7 @@ public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
                                                    Runnable action,
                                                    Executor executor);
     /**
-     * Returns a new CompletionStage that, when either this or the
+     * Returns a new CompletionStage that, when either {@code this} or the
      * other given stage complete normally, is executed with the
      * corresponding result as argument to the supplied function.
      *
@@ -477,8 +491,8 @@ public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
          Function<? super T, U> fn);
 
     /**
-     * Returns a new CompletionStage that, when either this or the
-     * other given stage complete normally, is executed using this
+     * Returns a new CompletionStage that, when either {@code this} or the
+     * other given stage complete normally, is executed using {@code this}
      * stage's default asynchronous execution facility, with the
      * corresponding result as argument to the supplied function.
      *
@@ -496,7 +510,7 @@ public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
          Function<? super T, U> fn);
 
     /**
-     * Returns a new CompletionStage that, when either this or the
+     * Returns a new CompletionStage that, when either {@code this} or the
      * other given stage complete normally, is executed using the
      * supplied executor, with the corresponding result as argument to
      * the supplied function.
@@ -517,7 +531,7 @@ public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
          Executor executor);
 
     /**
-     * Returns a new CompletionStage that, when either this or the
+     * Returns a new CompletionStage that, when either {@code this} or the
      * other given stage complete normally, is executed with the
      * corresponding result as argument to the supplied action.
      *
@@ -534,8 +548,8 @@ public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
          Consumer<? super T> action);
 
     /**
-     * Returns a new CompletionStage that, when either this or the
-     * other given stage complete normally, is executed using this
+     * Returns a new CompletionStage that, when either {@code this} or the
+     * other given stage complete normally, is executed using {@code this}
      * stage's default asynchronous execution facility, with the
      * corresponding result as argument to the supplied action.
      *
@@ -552,7 +566,7 @@ public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
          Consumer<? super T> action);
 
     /**
-     * Returns a new CompletionStage that, when either this or the
+     * Returns a new CompletionStage that, when either {@code this} or the
      * other given stage complete normally, is executed using the
      * supplied executor, with the corresponding result as argument to
      * the supplied action.
@@ -572,7 +586,7 @@ public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
          Executor executor);
 
     /**
-     * Returns a new CompletionStage that, when either this or the
+     * Returns a new CompletionStage that, when either {@code this} or the
      * other given stage complete normally, executes the given action.
      *
      * See the {@link CompletionStage} documentation for rules
@@ -587,9 +601,9 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
                                                 Runnable action);
 
     /**
-     * Returns a new CompletionStage that, when either this or the
+     * Returns a new CompletionStage that, when either {@code this} or the
      * other given stage complete normally, executes the given action
-     * using this stage's default asynchronous execution facility.
+     * using {@code this} stage's default asynchronous execution facility.
      *
      * See the {@link CompletionStage} documentation for rules
      * covering exceptional completion.
@@ -604,7 +618,7 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
          Runnable action);
 
     /**
-     * Returns a new CompletionStage that, when either this or the
+     * Returns a new CompletionStage that, when either {@code this} or the
      * other given stage complete normally, executes the given action
      * using the supplied executor.
      *
@@ -626,10 +640,10 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
      * Returns a new CompletionStage that is completed with the same
      * value as the CompletionStage returned by the given function.
      *
-     * <p>When this stage completes normally, the given function is
-     * invoked with this stage's result as the argument, returning
+     * <p>When {@code this} stage completes normally, the given function is
+     * invoked with {@code this} stage's result as the argument, returning
      * another CompletionStage.  When that stage completes normally,
-     * the CompletionStage returned by this method is completed with
+     * the CompletionStage returned is completed with
      * the same value.
      *
      * <p>To ensure progress, the supplied function must arrange
@@ -652,13 +666,13 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
     /**
      * Returns a new CompletionStage that is completed with the same
      * value as the CompletionStage returned by the given function,
-     * executed using this stage's default asynchronous execution
+     * executed using {@code this} stage's default asynchronous execution
      * facility.
      *
-     * <p>When this stage completes normally, the given function is
-     * invoked with this stage's result as the argument, returning
+     * <p>When {@code this} stage completes normally, the given function is
+     * invoked with {@code this} stage's result as the argument, returning
      * another CompletionStage.  When that stage completes normally,
-     * the CompletionStage returned by this method is completed with
+     * the CompletionStage returned is completed with
      * the same value.
      *
      * <p>To ensure progress, the supplied function must arrange
@@ -679,10 +693,10 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
      * value as the CompletionStage returned by the given function,
      * executed using the supplied Executor.
      *
-     * <p>When this stage completes normally, the given function is
-     * invoked with this stage's result as the argument, returning
+     * <p>When {@code this} stage completes normally, the given function is
+     * invoked with {@code this} stage's result as the argument, returning
      * another CompletionStage.  When that stage completes normally,
-     * the CompletionStage returned by this method is completed with
+     * the CompletionStage returned by {@code this} method is completed with
      * the same value.
      *
      * <p>To ensure progress, the supplied function must arrange
@@ -701,13 +715,13 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
          Executor executor);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * either normally or exceptionally, is executed with this stage's
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * either normally or exceptionally, is executed with {@code this} stage's
      * result and exception as arguments to the supplied function.
      *
-     * <p>When this stage is complete, the given function is invoked
+     * <p>When {@code this} stage is complete, the given function is invoked
      * with the result (or {@code null} if none) and the exception (or
-     * {@code null} if none) of this stage as arguments, and the
+     * {@code null} if none) of {@code this} stage as arguments, and the
      * function's result is used to complete the returned stage.
      *
      * @param fn the function to use to compute the value of the
@@ -719,14 +733,14 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
         (BiFunction<? super T, Throwable, ? extends U> fn);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * either normally or exceptionally, is executed using this stage's
-     * default asynchronous execution facility, with this stage's
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * either normally or exceptionally, is executed using {@code this} stage's
+     * default asynchronous execution facility, with {@code this} stage's
      * result and exception as arguments to the supplied function.
      *
-     * <p>When this stage is complete, the given function is invoked
+     * <p>When {@code this} stage is complete, the given function is invoked
      * with the result (or {@code null} if none) and the exception (or
-     * {@code null} if none) of this stage as arguments, and the
+     * {@code null} if none) of {@code this} stage as arguments, and the
      * function's result is used to complete the returned stage.
      *
      * @param fn the function to use to compute the value of the
@@ -738,14 +752,14 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
         (BiFunction<? super T, Throwable, ? extends U> fn);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
+     * Returns a new CompletionStage that, when {@code this} stage completes
      * either normally or exceptionally, is executed using the
-     * supplied executor, with this stage's result and exception as
+     * supplied executor, with {@code this} stage's result and exception as
      * arguments to the supplied function.
      *
-     * <p>When this stage is complete, the given function is invoked
+     * <p>When {@code this} stage is complete, the given function is invoked
      * with the result (or {@code null} if none) and the exception (or
-     * {@code null} if none) of this stage as arguments, and the
+     * {@code null} if none) of {@code this} stage as arguments, and the
      * function's result is used to complete the returned stage.
      *
      * @param fn the function to use to compute the value of the
@@ -760,22 +774,22 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
 
     /**
      * Returns a new CompletionStage with the same result or exception as
-     * this stage, that executes the given action when this stage completes.
+     * {@code this} stage, that executes the given action when {@code this} stage completes.
      *
-     * <p>When this stage is complete, the given action is invoked
+     * <p>When {@code this} stage is complete, the given action is invoked
      * with the result (or {@code null} if none) and the exception (or
-     * {@code null} if none) of this stage as arguments.  The returned
+     * {@code null} if none) of {@code this} stage as arguments.  The returned
      * stage is completed when the action returns.
      *
      * <p>Unlike method {@link #handle handle},
-     * this method is not designed to translate completion outcomes,
+     * method {@code whenComplete} is not designed to translate completion outcomes,
      * so the supplied action should not throw an exception. However,
-     * if it does, the following rules apply: if this stage completed
+     * if it does, the following rules apply: if {@code this} stage completed
      * normally but the supplied action throws an exception, then the
      * returned stage completes exceptionally with the supplied
-     * action's exception. Or, if this stage completed exceptionally
+     * action's exception. Or, if {@code this} stage completed exceptionally
      * and the supplied action throws an exception, then the returned
-     * stage completes exceptionally with this stage's exception.
+     * stage completes exceptionally with {@code this} stage's exception.
      *
      * @param action the action to perform
      * @return the new CompletionStage
@@ -785,23 +799,23 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
 
     /**
      * Returns a new CompletionStage with the same result or exception as
-     * this stage, that executes the given action using this stage's
-     * default asynchronous execution facility when this stage completes.
+     * {@code this} stage, that executes the given action using {@code this} stage's
+     * default asynchronous execution facility when {@code this} stage completes.
      *
-     * <p>When this stage is complete, the given action is invoked with the
+     * <p>When {@code this} stage is complete, the given action is invoked with the
      * result (or {@code null} if none) and the exception (or {@code null}
-     * if none) of this stage as arguments.  The returned stage is completed
+     * if none) of {@code this} stage as arguments.  The returned stage is completed
      * when the action returns.
      *
      * <p>Unlike method {@link #handleAsync(BiFunction) handleAsync},
-     * this method is not designed to translate completion outcomes,
+     * method {@code whenCompleteAsync} is not designed to translate completion outcomes,
      * so the supplied action should not throw an exception. However,
-     * if it does, the following rules apply: If this stage completed
+     * if it does, the following rules apply: If {@code this} stage completed
      * normally but the supplied action throws an exception, then the
      * returned stage completes exceptionally with the supplied
-     * action's exception. Or, if this stage completed exceptionally
+     * action's exception. Or, if {@code this} stage completed exceptionally
      * and the supplied action throws an exception, then the returned
-     * stage completes exceptionally with this stage's exception.
+     * stage completes exceptionally with {@code this} stage's exception.
      *
      * @param action the action to perform
      * @return the new CompletionStage
@@ -811,23 +825,23 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
 
     /**
      * Returns a new CompletionStage with the same result or exception as
-     * this stage, that executes the given action using the supplied
-     * Executor when this stage completes.
+     * {@code this} stage, that executes the given action using the supplied
+     * Executor when {@code this} stage completes.
      *
-     * <p>When this stage is complete, the given action is invoked with the
+     * <p>When {@code this} stage is complete, the given action is invoked with the
      * result (or {@code null} if none) and the exception (or {@code null}
-     * if none) of this stage as arguments.  The returned stage is completed
+     * if none) of {@code this} stage as arguments.  The returned stage is completed
      * when the action returns.
      *
      * <p>Unlike method {@link #handleAsync(BiFunction,Executor) handleAsync},
-     * this method is not designed to translate completion outcomes,
+     * method {@code whenCompleteAsync} is not designed to translate completion outcomes,
      * so the supplied action should not throw an exception. However,
-     * if it does, the following rules apply: If this stage completed
+     * if it does, the following rules apply: If {@code this} stage completed
      * normally but the supplied action throws an exception, then the
      * returned stage completes exceptionally with the supplied
-     * action's exception. Or, if this stage completed exceptionally
+     * action's exception. Or, if {@code this} stage completed exceptionally
      * and the supplied action throws an exception, then the returned
-     * stage completes exceptionally with this stage's exception.
+     * stage completes exceptionally with {@code this} stage's exception.
      *
      * @param action the action to perform
      * @param executor the executor to use for asynchronous execution
@@ -838,14 +852,14 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
          Executor executor);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * exceptionally, is executed with this stage's exception as the
-     * argument to the supplied function.  Otherwise, if this stage
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * exceptionally, is executed with {@code this} stage's exception as the
+     * argument to the supplied function.  Otherwise, if {@code this} stage
      * completes normally, then the returned stage also completes
      * normally with the same value.
      *
      * @param fn the function to use to compute the value of the
-     * returned CompletionStage if this CompletionStage completed
+     * returned CompletionStage if {@code this} CompletionStage completed
      * exceptionally
      * @return the new CompletionStage
      */
@@ -853,10 +867,10 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
         (Function<Throwable, ? extends T> fn);
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * exceptionally, is executed with this stage's exception as the
-     * argument to the supplied function, using this stage's default
-     * asynchronous execution facility.  Otherwise, if this stage
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * exceptionally, is executed with {@code this} stage's exception as the
+     * argument to the supplied function, using {@code this} stage's default
+     * asynchronous execution facility.  Otherwise, if {@code this} stage
      * completes normally, then the returned stage also completes
      * normally with the same value.
      *
@@ -865,7 +879,7 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
      * #thenCompose} for result.
      *
      * @param fn the function to use to compute the value of the
-     * returned CompletionStage if this CompletionStage completed
+     * returned CompletionStage if {@code this} CompletionStage completed
      * exceptionally
      * @return the new CompletionStage
      * @since 12
@@ -879,10 +893,10 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
     }
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
-     * exceptionally, is executed with this stage's exception as the
+     * Returns a new CompletionStage that, when {@code this} stage completes
+     * exceptionally, is executed with {@code this} stage's exception as the
      * argument to the supplied function, using the supplied Executor.
-     * Otherwise, if this stage completes normally, then the returned
+     * Otherwise, if {@code this} stage completes normally, then the returned
      * stage also completes normally with the same value.
      *
      * @implSpec The default implementation invokes {@link #handle},
@@ -890,7 +904,7 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
      * #thenCompose} for result.
      *
      * @param fn the function to use to compute the value of the
-     * returned CompletionStage if this CompletionStage completed
+     * returned CompletionStage if {@code this} CompletionStage completed
      * exceptionally
      * @param executor the executor to use for asynchronous execution
      * @return the new CompletionStage
@@ -905,16 +919,16 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
     }
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
+     * Returns a new CompletionStage that, when {@code this} stage completes
      * exceptionally, is composed using the results of the supplied
-     * function applied to this stage's exception.
+     * function applied to {@code this} stage's exception.
      *
      * @implSpec The default implementation invokes {@link #handle},
      * invoking the given function on exception, then {@link
      * #thenCompose} for result.
      *
      * @param fn the function to use to compute the returned
-     * CompletionStage if this CompletionStage completed exceptionally
+     * CompletionStage if {@code this} CompletionStage completed exceptionally
      * @return the new CompletionStage
      * @since 12
      */
@@ -927,9 +941,9 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
     }
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
+     * Returns a new CompletionStage that, when {@code this} stage completes
      * exceptionally, is composed using the results of the supplied
-     * function applied to this stage's exception, using this stage's
+     * function applied to {@code this} stage's exception, using {@code this} stage's
      * default asynchronous execution facility.
      *
      * @implSpec The default implementation invokes {@link #handle},
@@ -937,7 +951,7 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
      * #thenCompose} for result.
      *
      * @param fn the function to use to compute the returned
-     * CompletionStage if this CompletionStage completed exceptionally
+     * CompletionStage if {@code this} CompletionStage completed exceptionally
      * @return the new CompletionStage
      * @since 12
      */
@@ -951,9 +965,9 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
     }
 
     /**
-     * Returns a new CompletionStage that, when this stage completes
+     * Returns a new CompletionStage that, when {@code this} stage completes
      * exceptionally, is composed using the results of the supplied
-     * function applied to this stage's exception, using the
+     * function applied to {@code this} stage's exception, using the
      * supplied Executor.
      *
      * @implSpec The default implementation invokes {@link #handle},
@@ -961,7 +975,7 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
      * #thenCompose} for result.
      *
      * @param fn the function to use to compute the returned
-     * CompletionStage if this CompletionStage completed exceptionally
+     * CompletionStage if {@code this} CompletionStage completed exceptionally
      * @param executor the executor to use for asynchronous execution
      * @return the new CompletionStage
      * @since 12
@@ -978,9 +992,9 @@ public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
 
     /**
      * Returns a {@link CompletableFuture} maintaining the same
-     * completion properties as this stage. If this stage is already a
-     * CompletableFuture, this method may return this stage itself.
-     * Otherwise, invocation of this method may be equivalent in
+     * completion properties as {@code this} stage. If {@code this} stage is already a
+     * CompletableFuture, method {@code toCompletableFuture} may return {@code this} stage itself.
+     * Otherwise, invocation may be equivalent in
      * effect to {@code thenApply(x -> x)}, but returning an instance
      * of type {@code CompletableFuture}.
      *
diff --git a/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java b/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java
index 8734980cf808a..16f52d5839b08 100644
--- a/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java
+++ b/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java
@@ -147,7 +147,7 @@
  * <p>Like {@link Hashtable} but unlike {@link HashMap}, this class
  * does <em>not</em> allow {@code null} to be used as a key or value.
  *
- * <p>ConcurrentHashMaps support a set of sequential and parallel bulk
+ * <p id="Bulk">ConcurrentHashMaps support a set of sequential and parallel bulk
  * operations that, unlike most {@link Stream} methods, are designed
  * to be safely, and often sensibly, applied even with maps that are
  * being concurrently updated by other threads; for example, when
@@ -3704,7 +3704,7 @@ final int batchFor(long b) {
     }
 
     /**
-     * Performs the given action for each (key, value).
+     * Performs the given <a href="#Bulk"> bulk</a> action for each (key, value).
      *
      * @param parallelismThreshold the (estimated) number of elements
      * needed for this operation to be executed in parallel
@@ -3720,7 +3720,7 @@ public void forEach(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each non-null transformation
+     * Performs the given <a href="#Bulk"> bulk</a> action for each non-null transformation
      * of each (key, value).
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -3743,7 +3743,7 @@ public <U> void forEach(long parallelismThreshold,
     }
 
     /**
-     * Returns a non-null result from applying the given search
+     * Returns a non-null result from applying the given <a href="#Bulk"> bulk</a> search
      * function on each (key, value), or null if none.  Upon
      * success, further element processing is suppressed and the
      * results of any other parallel invocations of the search
@@ -3767,7 +3767,7 @@ public <U> U search(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of accumulating the given <a href="#Bulk"> bulk</a> transformation
      * of all (key, value) pairs using the given reducer to
      * combine values, or null if none.
      *
@@ -3793,7 +3793,7 @@ public <U> U reduce(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of accumulating the given <a href="#Bulk"> bulk</a> transformation
      * of all (key, value) pairs using the given reducer to
      * combine values, and the given basis as an identity value.
      *
@@ -3819,7 +3819,7 @@ public double reduceToDouble(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of accumulating the given <a href="#Bulk"> bulk</a> transformation
      * of all (key, value) pairs using the given reducer to
      * combine values, and the given basis as an identity value.
      *
@@ -3845,7 +3845,7 @@ public long reduceToLong(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of accumulating the given <a href="#Bulk"> bulk</a> transformation
      * of all (key, value) pairs using the given reducer to
      * combine values, and the given basis as an identity value.
      *
@@ -3871,7 +3871,7 @@ public int reduceToInt(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each key.
+     * Performs the given <a href="#Bulk"> bulk</a> action for each key.
      *
      * @param parallelismThreshold the (estimated) number of elements
      * needed for this operation to be executed in parallel
@@ -3887,7 +3887,7 @@ public void forEachKey(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each non-null transformation
+     * Performs the given <a href="#Bulk"> bulk</a> action for each non-null transformation
      * of each key.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -3910,7 +3910,7 @@ public <U> void forEachKey(long parallelismThreshold,
     }
 
     /**
-     * Returns a non-null result from applying the given search
+     * Returns a non-null result from applying the given <a href="#Bulk"> bulk</a> search
      * function on each key, or null if none. Upon success,
      * further element processing is suppressed and the results of
      * any other parallel invocations of the search function are
@@ -3934,7 +3934,7 @@ public <U> U searchKeys(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating all keys using the given
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating all keys using the given
      * reducer to combine values, or null if none.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -3953,7 +3953,7 @@ public K reduceKeys(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all keys using the given reducer to combine values, or
      * null if none.
      *
@@ -3979,7 +3979,7 @@ public <U> U reduceKeys(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all keys using the given reducer to combine values, and
      * the given basis as an identity value.
      *
@@ -4005,7 +4005,7 @@ public double reduceKeysToDouble(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all keys using the given reducer to combine values, and
      * the given basis as an identity value.
      *
@@ -4031,7 +4031,7 @@ public long reduceKeysToLong(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all keys using the given reducer to combine values, and
      * the given basis as an identity value.
      *
@@ -4057,7 +4057,7 @@ public int reduceKeysToInt(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each value.
+     * Performs the given <a href="#Bulk"> bulk</a> action for each value.
      *
      * @param parallelismThreshold the (estimated) number of elements
      * needed for this operation to be executed in parallel
@@ -4074,7 +4074,7 @@ public void forEachValue(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each non-null transformation
+     * Performs the given <a href="#Bulk"> bulk</a> action for each non-null transformation
      * of each value.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -4097,7 +4097,7 @@ public <U> void forEachValue(long parallelismThreshold,
     }
 
     /**
-     * Returns a non-null result from applying the given search
+     * Returns a non-null result from <a href="#Bulk"> bulk</a> applying the given search
      * function on each value, or null if none.  Upon success,
      * further element processing is suppressed and the results of
      * any other parallel invocations of the search function are
@@ -4121,7 +4121,7 @@ public <U> U searchValues(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating all values using the
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating all values using the
      * given reducer to combine values, or null if none.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -4139,7 +4139,7 @@ public V reduceValues(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all values using the given reducer to combine values, or
      * null if none.
      *
@@ -4165,7 +4165,7 @@ public <U> U reduceValues(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all values using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4191,7 +4191,7 @@ public double reduceValuesToDouble(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all values using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4217,7 +4217,7 @@ public long reduceValuesToLong(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all values using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4243,7 +4243,7 @@ public int reduceValuesToInt(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each entry.
+     * Performs the given <a href="#Bulk"> bulk</a> action for each entry.
      *
      * @param parallelismThreshold the (estimated) number of elements
      * needed for this operation to be executed in parallel
@@ -4258,7 +4258,7 @@ public void forEachEntry(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each non-null transformation
+     * Performs the given <a href="#Bulk"> bulk</a> action for each non-null transformation
      * of each entry.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -4281,7 +4281,7 @@ public <U> void forEachEntry(long parallelismThreshold,
     }
 
     /**
-     * Returns a non-null result from applying the given search
+     * Returns a non-null result from <a href="#Bulk"> bulk</a> applying the given search
      * function on each entry, or null if none.  Upon success,
      * further element processing is suppressed and the results of
      * any other parallel invocations of the search function are
@@ -4305,7 +4305,7 @@ public <U> U searchEntries(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating all entries using the
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating all entries using the
      * given reducer to combine values, or null if none.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -4323,7 +4323,7 @@ public Map.Entry<K,V> reduceEntries(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all entries using the given reducer to combine values,
      * or null if none.
      *
@@ -4349,7 +4349,7 @@ public <U> U reduceEntries(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all entries using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4375,7 +4375,7 @@ public double reduceEntriesToDouble(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all entries using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4401,7 +4401,7 @@ public long reduceEntriesToLong(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of <a href="#Bulk"> bulk</a> accumulating the given transformation
      * of all entries using the given reducer to combine values,
      * and the given basis as an identity value.
      *
diff --git a/src/java.base/share/classes/java/util/concurrent/CyclicBarrier.java b/src/java.base/share/classes/java/util/concurrent/CyclicBarrier.java
index 87e498d9c247a..ca78c25462487 100644
--- a/src/java.base/share/classes/java/util/concurrent/CyclicBarrier.java
+++ b/src/java.base/share/classes/java/util/concurrent/CyclicBarrier.java
@@ -44,7 +44,10 @@
  * useful in programs involving a fixed sized party of threads that
  * must occasionally wait for each other. The barrier is called
  * <em>cyclic</em> because it can be re-used after the waiting threads
- * are released.
+ * are released. If you need support for variable numbers of parties
+ * per cycle, alternate actions on exceptions, termination control,
+ * contention control, or status monitoring, use the more flexible
+ * {@link Phaser} class.
  *
  * <p>A {@code CyclicBarrier} supports an optional {@link Runnable} command
  * that is run once per barrier point, after the last thread in the party
diff --git a/src/java.base/share/classes/java/util/concurrent/ExecutorService.java b/src/java.base/share/classes/java/util/concurrent/ExecutorService.java
index 0d4acf8913e04..f899b56b28883 100644
--- a/src/java.base/share/classes/java/util/concurrent/ExecutorService.java
+++ b/src/java.base/share/classes/java/util/concurrent/ExecutorService.java
@@ -56,7 +56,9 @@
  *
  * <p>Method {@code submit} extends base method {@link
  * Executor#execute(Runnable)} by creating and returning a {@link Future}
- * that can be used to cancel execution and/or wait for completion.
+ * that can be used to cancel execution and/or wait for completion;
+ * also reporting exceptions that would otherwise be uncaught
+ * using method {@code execute}.
  * Methods {@code invokeAny} and {@code invokeAll} perform the most
  * commonly useful forms of bulk execution, executing a collection of
  * tasks and then waiting for at least one, or all, to
diff --git a/src/java.base/share/classes/java/util/concurrent/Executors.java b/src/java.base/share/classes/java/util/concurrent/Executors.java
index ba7c2e1efeebe..ef3d634801090 100644
--- a/src/java.base/share/classes/java/util/concurrent/Executors.java
+++ b/src/java.base/share/classes/java/util/concurrent/Executors.java
@@ -306,7 +306,7 @@ public static ScheduledExecutorService newSingleThreadScheduledExecutor(ThreadFa
     }
 
     /**
-     * Creates a thread pool that can schedule commands to run after a
+     * Creates a fixed-size thread pool that can schedule commands to run after a
      * given delay, or to execute periodically.
      * @param corePoolSize the number of threads to keep in the pool,
      * even if they are idle
@@ -318,7 +318,7 @@ public static ScheduledExecutorService newScheduledThreadPool(int corePoolSize)
     }
 
     /**
-     * Creates a thread pool that can schedule commands to run after a
+     * Creates a fixed-size thread pool that can schedule commands to run after a
      * given delay, or to execute periodically.
      * @param corePoolSize the number of threads to keep in the pool,
      * even if they are idle
diff --git a/src/java.base/share/classes/java/util/concurrent/Flow.java b/src/java.base/share/classes/java/util/concurrent/Flow.java
index 1aefaea43b0e3..16b2ba5e9d809 100644
--- a/src/java.base/share/classes/java/util/concurrent/Flow.java
+++ b/src/java.base/share/classes/java/util/concurrent/Flow.java
@@ -60,7 +60,8 @@
  * TRUE} item to a single subscriber.  Because the subscriber receives
  * only a single item, this class does not use buffering and ordering
  * control required in most implementations (for example {@link
- * SubmissionPublisher}).
+ * SubmissionPublisher}), and omits some error processing needed to
+ * fully conform to the Reactive Streams specification.
  *
  * <pre> {@code
  * class OneShotPublisher implements Publisher<Boolean> {
diff --git a/src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java b/src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
index a7821921bc911..482fe3cf80136 100644
--- a/src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
+++ b/src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
@@ -140,7 +140,7 @@
  * tasks, as well as method {@link #submitWithTimeout} to cancel tasks
  * that take too long. The scheduled functions or actions may create
  * and invoke other {@linkplain ForkJoinTask ForkJoinTasks}. Delayed
- * actions become <em>enabled</em> and behave as ordinary submitted
+ * actions become enabled for execution and behave as ordinary submitted
  * tasks when their delays elapse.  Scheduling methods return
  * {@linkplain ForkJoinTask ForkJoinTasks} that implement the {@link
  * ScheduledFuture} interface. Resource exhaustion encountered after
@@ -153,7 +153,7 @@
  * to disable all delayed tasks upon shutdown, and method {@link
  * #shutdownNow} may be used to instead unconditionally initiate pool
  * termination. Monitoring methods such as {@link #getQueuedTaskCount}
- * do not include scheduled tasks that are not yet enabled to execute,
+ * do not include scheduled tasks that are not yet enabled for execution,
  * which are reported separately by method {@link
  * #getDelayedTaskCount}.
  *
@@ -3505,7 +3505,7 @@ final <T> ScheduledForkJoinTask<T> scheduleDelayedTask(ScheduledForkJoinTask<T>
     }
 
     /**
-     * Submits a one-shot task that becomes enabled after the given
+     * Submits a one-shot task that becomes enabled for execution after the given
      * delay.  At that point it will execute unless explicitly
      * cancelled, or fail to execute (eventually reporting
      * cancellation) when encountering resource exhaustion, or the
@@ -3533,7 +3533,7 @@ public ScheduledFuture<?> schedule(Runnable command,
     }
 
     /**
-     * Submits a value-returning one-shot task that becomes enabled
+     * Submits a value-returning one-shot task that becomes enabled for execution
      * after the given delay. At that point it will execute unless
      * explicitly cancelled, or fail to execute (eventually reporting
      * cancellation) when encountering resource exhaustion, or the
@@ -3562,7 +3562,7 @@ public <V> ScheduledFuture<V> schedule(Callable<V> callable,
     }
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given period;
      * that is, executions will commence after
      * {@code initialDelay}, then {@code initialDelay + period}, then
@@ -3616,7 +3616,7 @@ public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
     }
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given delay
      * between the termination of one execution and the commencement of
      * the next.
diff --git a/src/java.base/share/classes/java/util/concurrent/Future.java b/src/java.base/share/classes/java/util/concurrent/Future.java
index c6f3036c2d28f..2ac837d72701a 100644
--- a/src/java.base/share/classes/java/util/concurrent/Future.java
+++ b/src/java.base/share/classes/java/util/concurrent/Future.java
@@ -50,6 +50,26 @@
  * declare types of the form {@code Future<?>} and
  * return {@code null} as a result of the underlying task.
  *
+ * <p>Cancellation of a Future need not abruptly terminate its
+ * computation. Method {@code cancel} causes {@code isCancelled()} to
+ * return {@code true} unless already {@code isDone()}; in either case
+ * {@code isDone()} subsequently reports {@code true}. This suppresses
+ * execution by an {@link ExecutorService} if not already started.
+ * There are several options for suppressing unnecessary computation
+ * or unblocking a running Future that will not generate a
+ * result. When task bodies are simple and short, no special attention
+ * is warranted.  Computational methods in Future-aware code bodies
+ * (for example {@link ForkJoinTask}, {@link FutureTask}) may inspect
+ * their own {@code isDone()} status before or while engaging in
+ * expensive computations. In blocking I/O or communication contexts,
+ * the optional {@code mayInterruptIfRunning} argument of {@code
+ * cancel} may be used to support conventions that tasks should
+ * unblock and exit when {@link Thread#interrupted}, whether checked
+ * inside a task body or as a response to an {@link
+ * InterruptedException}.  It is still preferable to additionally
+ * check {@code isDone()} status when possible to avoid unintended
+ * effects of other uses of {@link Thread#interrupt}.
+ *
  * <p><b>Sample Usage</b> (Note that the following classes are all
  * made-up.)
  *
diff --git a/src/java.base/share/classes/java/util/concurrent/FutureTask.java b/src/java.base/share/classes/java/util/concurrent/FutureTask.java
index b905e71aeef95..2ec976291054e 100644
--- a/src/java.base/share/classes/java/util/concurrent/FutureTask.java
+++ b/src/java.base/share/classes/java/util/concurrent/FutureTask.java
@@ -285,7 +285,9 @@ protected void done() { }
      * this future has already been set or has been cancelled.
      *
      * <p>This method is invoked internally by the {@link #run} method
-     * upon successful completion of the computation.
+     * upon successful completion of the computation. Invocation in
+     * other contexts has undefined effects. Any override of this
+     * method in subclasses should include {@code super.set(v)}.
      *
      * @param v the value
      */
diff --git a/src/java.base/share/classes/java/util/concurrent/RunnableFuture.java b/src/java.base/share/classes/java/util/concurrent/RunnableFuture.java
index b6b088ae7cd82..8585cfe108297 100644
--- a/src/java.base/share/classes/java/util/concurrent/RunnableFuture.java
+++ b/src/java.base/share/classes/java/util/concurrent/RunnableFuture.java
@@ -47,8 +47,9 @@
  */
 public interface RunnableFuture<V> extends Runnable, Future<V> {
     /**
-     * Sets this Future to the result of its computation
-     * unless it has been cancelled.
+     * Sets this Future to the result of its computation unless it has
+     * been cancelled (or has already been invoked, in which case
+     * effects are undefined).
      */
     void run();
 }
diff --git a/src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java b/src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java
index 4d63ffae4bb44..034d98687c257 100644
--- a/src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java
+++ b/src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java
@@ -40,10 +40,12 @@
  * delay, or to execute periodically.
  *
  * <p>The {@code schedule} methods create tasks with various delays
- * and return a task object that can be used to cancel or check
- * execution. The {@code scheduleAtFixedRate} and
- * {@code scheduleWithFixedDelay} methods create and execute tasks
- * that run periodically until cancelled.
+ * and return {@link ScheduledFuture} objects that can be used to cancel or check
+ * execution. When delays elapse, tasks are enabled for execution and
+ * behave in accord with other {@link ExecutorService} tasks, except
+ * that {@code scheduleAtFixedRate} and {@code scheduleWithFixedDelay}
+ * methods create and execute tasks that run periodically until
+ * cancelled.
  *
  * <p>Commands submitted using the {@link Executor#execute(Runnable)}
  * and {@link ExecutorService} {@code submit} methods are scheduled
@@ -91,7 +93,7 @@
 public interface ScheduledExecutorService extends ExecutorService {
 
     /**
-     * Submits a one-shot task that becomes enabled after the given delay.
+     * Submits a one-shot task that becomes enabled for execution after the given delay.
      *
      * @param command the task to execute
      * @param delay the time from now to delay execution
@@ -107,7 +109,7 @@ public ScheduledFuture<?> schedule(Runnable command,
                                        long delay, TimeUnit unit);
 
     /**
-     * Submits a value-returning one-shot task that becomes enabled
+     * Submits a value-returning one-shot task that becomes enabled for execution
      * after the given delay.
      *
      * @param callable the function to execute
@@ -123,7 +125,7 @@ public <V> ScheduledFuture<V> schedule(Callable<V> callable,
                                            long delay, TimeUnit unit);
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given period;
      * that is, executions will commence after
      * {@code initialDelay}, then {@code initialDelay + period}, then
@@ -167,7 +169,7 @@ public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
                                                   TimeUnit unit);
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given delay
      * between the termination of one execution and the commencement of
      * the next.
diff --git a/src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java b/src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
index 94f40ccf6f516..23398aeae2813 100644
--- a/src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
+++ b/src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
@@ -57,7 +57,7 @@
  * capabilities of {@link ThreadPoolExecutor} (which this class
  * extends) are required.
  *
- * <p>Delayed tasks execute no sooner than they are enabled, but
+ * <p>Delayed tasks execute no sooner than they are enabled for execution, but
  * without any real-time guarantees about when, after they are
  * enabled, they will commence. Tasks scheduled for exactly the same
  * execution time are enabled in first-in-first-out (FIFO) order of
@@ -568,7 +568,7 @@ public <V> ScheduledFuture<V> schedule(Callable<V> callable,
     }
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given period;
      * that is, executions will commence after
      * {@code initialDelay}, then {@code initialDelay + period}, then
@@ -621,7 +621,7 @@ public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
     }
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given delay
      * between the termination of one execution and the commencement of
      * the next.
diff --git a/src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java b/src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java
index 3a8f37466374c..f793d2bcabdf2 100644
--- a/src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java
+++ b/src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java
@@ -162,8 +162,8 @@
  *     (this.subscription = subscription).request(1);
  *   }
  *   public void onNext(S item) {
- *     subscription.request(1);
  *     submit(function.apply(item));
+ *     subscription.request(1);
  *   }
  *   public void onError(Throwable ex) { closeExceptionally(ex); }
  *   public void onComplete() { close(); }
@@ -602,9 +602,11 @@ public int offer(T item, long timeout, TimeUnit unit,
     /**
      * Unless already closed, issues {@link
      * Flow.Subscriber#onComplete() onComplete} signals to current
-     * subscribers, and disallows subsequent attempts to publish.
-     * Upon return, this method does <em>NOT</em> guarantee that all
-     * subscribers have yet completed.
+     * subscribers, and disallows subsequent attempts to publish. To
+     * ensure uniform ordering among subscribers, this method may
+     * await completion of in-progress offers.  Upon return, this
+     * method does <em>NOT</em> guarantee that all subscribers have
+     * yet completed.
      */
     public void close() {
         ReentrantLock lock = this.lock;
diff --git a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
index f02aa9f593192..d116fb9b22bcc 100644
--- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
+++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
@@ -398,6 +398,8 @@ else if (s == MICRO_SCALE)
      * @param obj the object to wait on
      * @param timeout the maximum time to wait. If less than
      * or equal to zero, do not wait at all.
+     * @throws  IllegalMonitorStateException  if the current thread is not
+     *               the owner of the object's monitor.
      * @throws InterruptedException if interrupted while waiting
      */
     public void timedWait(Object obj, long timeout)
diff --git a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java
index e01b3ec7d50f9..f947eb4f7db88 100644
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java
@@ -46,10 +46,11 @@
 
 /**
  * A reflection-based utility that enables atomic updates to
- * designated {@code volatile int} fields of designated classes.
- * This class is designed for use in atomic data structures in which
- * several fields of the same node are independently subject to atomic
- * updates.
+ * designated non-static {@code volatile int} fields of designated
+ * classes, providing a subset of the functionality of class {@link
+ * VarHandle} that should be used instead.  This class is designed for
+ * use in atomic data structures in which several fields of the same
+ * node are independently subject to atomic updates.
  *
  * <p>Note that the guarantees of the {@code compareAndSet}
  * method in this class are weaker than in other atomic classes.
diff --git a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java
index 57722f333711a..b31a8edf53a46 100644
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java
@@ -46,10 +46,11 @@
 
 /**
  * A reflection-based utility that enables atomic updates to
- * designated {@code volatile long} fields of designated classes.
- * This class is designed for use in atomic data structures in which
- * several fields of the same node are independently subject to atomic
- * updates.
+ * designated non-static {@code volatile long} fields of designated
+ * classes, providing a subset of the functionality of class {@link
+ * VarHandle} that should be used instead.  This class is designed for
+ * use in atomic data structures in which several fields of the same
+ * node are independently subject to atomic updates.
  *
  * <p>Note that the guarantees of the {@code compareAndSet}
  * method in this class are weaker than in other atomic classes.
diff --git a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
index 1c0c6d0afd070..e3ca4830d5a21 100644
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
@@ -46,11 +46,12 @@
 
 /**
  * A reflection-based utility that enables atomic updates to
- * designated {@code volatile} reference fields of designated
- * classes.  This class is designed for use in atomic data structures
- * in which several reference fields of the same node are
- * independently subject to atomic updates. For example, a tree node
- * might be declared as
+ * designated non-static {@code volatile} reference fields of
+ * designated classes, providing a subset of the functionality of
+ * class {@link VarHandle} that should be used instead.  This class
+ * may be used in atomic data structures in which several reference
+ * fields of the same node are independently subject to atomic
+ * updates. For example, a tree node might be declared as
  *
  * <pre> {@code
  * class Node {
@@ -68,6 +69,26 @@
  *   // ... and so on
  * }}</pre>
  *
+ * However, it is preferable to use {@link VarHandle}:
+ * <pre> {@code
+ * import java.lang.invoke.VarHandle;
+ * import java.lang.invoke.MethodHandles;
+ * class Node {
+ *  private volatile Node left, right;
+ *  private static final VarHandle LEFT, RIGHT;
+ *  Node getLeft() { return left; }
+ *  boolean compareAndSetLeft(Node expect, Node update) {
+ *    return LEFT.compareAndSet(this, expect, update);
+ *  }
+ *  // ... and so on
+ *  static { try {
+ *    MethodHandles.Lookup l = MethodHandles.lookup();
+ *    LEFT  = l.findVarHandle(Node.class, "left", Node.class);
+ *    RIGHT = l.findVarHandle(Node.class, "right", Node.class);
+ *   } catch (ReflectiveOperationException e) {
+ *     throw new ExceptionInInitializerError(e);
+ * }}}}</pre>
+ *
  * <p>Note that the guarantees of the {@code compareAndSet}
  * method in this class are weaker than in other atomic classes.
  * Because this class cannot ensure that all uses of the field
diff --git a/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java b/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java
index 3e0b293380f5f..536996fd27334 100644
--- a/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java
+++ b/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java
@@ -97,6 +97,10 @@
  * perform reads under read locks.  If a reader tries to acquire the
  * write lock it will never succeed.
  *
+ * <p>Note: If you do not rely on reentrancy, you may find that {@link
+ * StampedLock} offers better performance, as in: {@code ReadWriteLock
+ * lock = new StampedLock().asReadWriteLock()}.
+ *
  * <li><b>Lock downgrading</b>
  * <p>Reentrancy also allows downgrading from the write lock to a read lock,
  * by acquiring the write lock, then the read lock and then releasing the
@@ -734,11 +738,13 @@ protected ReadLock(ReentrantReadWriteLock lock) {
          * Acquires the read lock.
          *
          * <p>Acquires the read lock if the write lock is not held by
-         * another thread and returns immediately.
+         * any thread and returns immediately.
          *
-         * <p>If the write lock is held by another thread then
-         * the current thread becomes disabled for thread scheduling
-         * purposes and lies dormant until the read lock has been acquired.
+         * <p>If the write lock is held by any thread or the fairness
+         * policy prohibits acquisition of the read lock at this time,
+         * then the current thread becomes disabled for thread
+         * scheduling purposes and lies dormant until the read lock
+         * has been acquired.
          */
         public void lock() {
             sync.acquireShared(1);
@@ -749,11 +755,13 @@ public void lock() {
          * {@linkplain Thread#interrupt interrupted}.
          *
          * <p>Acquires the read lock if the write lock is not held
-         * by another thread and returns immediately.
+         * by any thread and returns immediately.
          *
-         * <p>If the write lock is held by another thread then the
-         * current thread becomes disabled for thread scheduling
-         * purposes and lies dormant until one of two things happens:
+         * <p>If the write lock is held by any thread or the fairness
+         * policy prohibits acquisition of the read lock at this time,
+         * then the current thread becomes disabled for thread
+         * scheduling purposes and lies dormant until one of two
+         * things happens:
          *
          * <ul>
          *
@@ -794,7 +802,7 @@ public void lockInterruptibly() throws InterruptedException {
          * another thread at the time of invocation.
          *
          * <p>Acquires the read lock if the write lock is not held by
-         * another thread and returns immediately with the value
+         * any thread and returns immediately with the value
          * {@code true}. Even when this lock has been set to use a
          * fair ordering policy, a call to {@code tryLock()}
          * <em>will</em> immediately acquire the read lock if it is
@@ -806,7 +814,7 @@ public void lockInterruptibly() throws InterruptedException {
          * tryLock(0, TimeUnit.SECONDS)} which is almost equivalent
          * (it also detects interruption).
          *
-         * <p>If the write lock is held by another thread then
+         * <p>If the write lock is held by any thread then
          * this method will return immediately with the value
          * {@code false}.
          *
diff --git a/src/java.base/share/classes/java/util/concurrent/package-info.java b/src/java.base/share/classes/java/util/concurrent/package-info.java
index dd0c8f79bc024..f237017799d9f 100644
--- a/src/java.base/share/classes/java/util/concurrent/package-info.java
+++ b/src/java.base/share/classes/java/util/concurrent/package-info.java
@@ -222,7 +222,9 @@
  * <li>they are guaranteed to traverse elements as they existed upon
  * construction exactly once, and may (but are not guaranteed to)
  * reflect any modifications subsequent to construction.
- * </ul>
+ * <li> These properties extend to other iteration-based
+ * operations. In particular, {@link Object#equals} is almost never
+ * useful unless both collections are known to be quiescent.  </ul>
  *
  * <h2 id="MemoryVisibility">Memory Consistency Properties</h2>
  *
