JavaDocs overhaul

Author: pivovarit

vavr/src/main/java/io/vavr/concurrent/Future.java

@@ -27,76 +27,78 @@
 import static io.vavr.concurrent.Future.DEFAULT_EXECUTOR;
 
 /**
- * A Promise is a write-once wrapper around a read-only Future which can complete the underlying Future with a value
- * or an exception.
+ * A {@code Promise} is a write-once container for a read-only {@code Future}, allowing the underlying {@code Future}
+ * to be completed with a value or an exception.
  * <p>
- * The underlying {@code Executor} is used to execute asynchronous handlers, e.g. via
+ * The associated {@code Executor} is used to run asynchronous handlers, for example, via
  * {@code promise.future().onComplete(...)}.
  *
  * <h2>Creation</h2>
  * <p>
- * Promise offers static factory methods to create new promises which hasn't been fulfilled yet:
+ * {@code Promise} provides static factory methods to create new promises:
  * <ul>
- * <li>create new promises: {@link Promise#make()}</li>
+ *   <li>Unfulfilled promises: {@link Promise#make()}</li>
+ *   <li>Already completed promises:
+ *     <ul>
+ *       <li>{@link #failed(Throwable)}</li>
+ *       <li>{@link #fromTry(Try)}</li>
+ *       <li>{@link #successful(Object)}</li>
+ *     </ul>
+ *   </li>
  * </ul>
- * And we may create new promises that are already finished:
- * <ul>
- * <li>{@link #failed(Throwable)}</li>
- * <li>{@link #fromTry(Try)}</li>
- * <li>{@link #successful(Object)}</li>
- * </ul>
- * All the static factory methods mentioned above have additional versions which take an {@link Executor} as
- * argument. This gives us more control over thread creation and thread pool sizes.
+ * All factory methods also have variants that accept an {@link Executor}, allowing finer control over
+ * thread usage and thread pool configuration.
  *
  * <h3>One-shot API</h3>
  * <p>
- * The main purpose of a {@code Promise} is to complete its underlying {@code Future}. When only a single {@code Thread}
- * will eventually complete the {@code Promise}, we use one of these methods. Calls will throw if the {@code Promise} is already
- * completed.
+ * When a single {@code Thread} is responsible for completing the {@code Promise}, use one of the following methods.
+ * Calls will throw an exception if the {@code Promise} has already been completed:
  * <ul>
- * <li>{@link #complete(Try)}</li>
- * <li>{@link #completeWith(Future)}</li>
- * <li>{@link #failure(Throwable)}</li>
- * <li>{@link #success(Object)}</li>
+ *   <li>{@link #complete(Try)}</li>
+ *   <li>{@link #completeWith(Future)}</li>
+ *   <li>{@link #failure(Throwable)}</li>
+ *   <li>{@link #success(Object)}</li>
  * </ul>
  *
- * <h3>API for competing threads</h3>
+ * <h3>API for concurrent completion</h3>
  * <p>
- * When multiple {@code Thread}s may complete our {@code Promise}, we typically use one of these methods. Calls will
- * gracefully return {@code false} if the {@code Promise} is already completed.
+ * When multiple {@code Thread}s may attempt to complete the {@code Promise}, use one of the following "try" methods.
+ * Calls will return {@code false} if the {@code Promise} is already completed:
  * <ul>
- * <li>{@link #tryComplete(Try)}</li>
- * <li>{@link #tryCompleteWith(Future)}</li>
- * <li>{@link #tryFailure(Throwable)}</li>
- * <li>{@link #trySuccess(Object)}</li>
+ *   <li>{@link #tryComplete(Try)}</li>
+ *   <li>{@link #tryCompleteWith(Future)}</li>
+ *   <li>{@link #tryFailure(Throwable)}</li>
+ *   <li>{@link #trySuccess(Object)}</li>
  * </ul>
  *
- * @param <T> The result type of the underlying {@code Future}.
+ * @param <T> the type of the value that completes the underlying {@code Future}
  * @author Daniel Dietrich
  */
 public interface Promise<T> {
 
     /**
-     * Creates a failed {@code Promise}, backed by the {@link Future#DEFAULT_EXECUTOR}.
+     * Creates a {@code Promise} that is already completed with a failure, using the 
+     * {@link Future#DEFAULT_EXECUTOR} for asynchronous operations.
      *
-     * @param exception The reason why it failed.
-     * @param <T>       The value type of a successful result.
-     * @return A failed {@code Promise}.
-     * @throws NullPointerException if exception is null
+     * @param exception the cause of the failure
+     * @param <T>       the type of the value that would have been returned on success
+     * @return a {@code Promise} completed with the given failure
+     * @throws NullPointerException if {@code exception} is null
      */
     static <T> Promise<T> failed(Throwable exception) {
         Objects.requireNonNull(exception, "exception is null");
         return failed(DEFAULT_EXECUTOR, exception);
     }
 
     /**
-     * Creates a failed {@code Promise}, backed by the given {@link Executor}.
+     * Creates a {@code Promise} that is already completed with a failure, using the specified {@link Executor}
+     * for asynchronous operations.
      *
-     * @param executor An {@code Executor} passed to the underlying {@link Future}.
-     * @param exception       The reason why it failed.
-     * @param <T>             The value type of a successful result.
-     * @return A failed {@code Promise}.
-     * @throws NullPointerException if executor or exception is null
+     * @param executor  the {@code Executor} used by the underlying {@link Future}
+     * @param exception the cause of the failure
+     * @param <T>       the type of the value that would have been returned on success
+     * @return a {@code Promise} completed with the given failure
+     * @throws NullPointerException if {@code executor} or {@code exception} is null
      */
     static <T> Promise<T> failed(Executor executor, Throwable exception) {
         Objects.requireNonNull(executor, "executor is null");
@@ -105,25 +107,27 @@ static <T> Promise<T> failed(Executor executor, Throwable exception) {
     }
 
     /**
-     * Creates a {@code Promise} from a {@link Try}, backed by the {@link Future#DEFAULT_EXECUTOR}.
+     * Creates a {@code Promise} from the given {@link Try}, using the {@link Future#DEFAULT_EXECUTOR}
+     * for asynchronous operations.
      *
-     * @param result The result.
-     * @param <T>    The value type of a successful result.
-     * @return A completed {@code Promise} which contains either a {@code Success} or a {@code Failure}.
-     * @throws NullPointerException if result is null
+     * @param result the {@code Try} representing a success or failure
+     * @param <T>    the type of the value in case of success
+     * @return a {@code Promise} already completed with the given {@code Try} result
+     * @throws NullPointerException if {@code result} is null
      */
     static <T> Promise<T> fromTry(Try<? extends T> result) {
         return fromTry(DEFAULT_EXECUTOR, result);
     }
 
     /**
-     * Creates a {@code Promise} from a {@link Try}, backed by the given {@link Executor}.
+     * Creates a {@code Promise} from the given {@link Try}, using the specified {@link Executor}
+     * for asynchronous operations.
      *
-     * @param executor An {@code Executor} passed to the underlying {@link Future}.
-     * @param result          The result.
-     * @param <T>             The value type of a successful result.
-     * @return A completed {@code Promise} which contains either a {@code Success} or a {@code Failure}.
-     * @throws NullPointerException if executor or result is null
+     * @param executor the {@code Executor} used by the underlying {@link Future}
+     * @param result   the {@code Try} representing a success or failure
+     * @param <T>      the type of the value in case of success
+     * @return a {@code Promise} already completed with the given {@code Try} result
+     * @throws NullPointerException if {@code executor} or {@code result} is null
      */
     static <T> Promise<T> fromTry(Executor executor, Try<? extends T> result) {
         Objects.requireNonNull(executor, "executor is null");
@@ -132,62 +136,64 @@ static <T> Promise<T> fromTry(Executor executor, Try<? extends T> result) {
     }
 
     /**
-     * Makes a {@code Promise} that isn't fulfilled yet, backed by the {@link Future#DEFAULT_EXECUTOR}.
-     * {@link ForkJoinPool#commonPool()}.
+     * Creates a new {@code Promise} that is not yet completed, using the {@link Future#DEFAULT_EXECUTOR}
+     * (typically {@link ForkJoinPool#commonPool()}) for asynchronous operations.
      *
-     * @param <T> Result type of the {@code Promise}.
-     * @return A new {@code Promise}.
+     * @param <T> the type of the value that will complete the {@code Promise}
+     * @return a new, uncompleted {@code Promise}
      */
     static <T> Promise<T> make() {
         return make(DEFAULT_EXECUTOR);
     }
 
     /**
-     * Makes a {@code Promise} that isn't fulfilled yet, backed by the given {@link Executor}.
+     * Creates a new {@code Promise} that is not yet completed, using the specified {@link Executor}
+     * for asynchronous operations.
      *
-     * @param executor An {@code Executor} passed to the underlying {@link Future}.
-     * @param <T>             Result type of the {@code Promise}.
-     * @return A new {@code Promise}.
-     * @throws NullPointerException if executor is null
+     * @param executor the {@code Executor} used by the underlying {@link Future}
+     * @param <T>      the type of the value that will complete the {@code Promise}
+     * @return a new, uncompleted {@code Promise}
+     * @throws NullPointerException if {@code executor} is null
      */
     static <T> Promise<T> make(Executor executor) {
         Objects.requireNonNull(executor, "executor is null");
         return new PromiseImpl<>(FutureImpl.of(executor));
     }
 
     /**
-     * Narrows a widened {@code Promise<? extends T>} to {@code Promise<T>}
-     * by performing a type-safe cast. This is eligible because immutable/read-only
-     * collections are covariant.
+     * Narrows a {@code Promise<? extends T>} to {@code Promise<T>} through a type-safe cast. 
+     * This is safe because immutable or read-only collections are covariant.
      *
-     * @param promise A {@code Promise}.
-     * @param <T>     Component type of the {@code Promise}.
-     * @return the given {@code promise} instance as narrowed type {@code Promise<T>}.
+     * @param promise the {@code Promise} to narrow
+     * @param <T>     the component type of the {@code Promise}
+     * @return the same {@code promise} instance, cast to {@code Promise<T>}
      */
     @SuppressWarnings("unchecked")
     static <T> Promise<T> narrow(Promise<? extends T> promise) {
         return (Promise<T>) promise;
     }
 
     /**
-     * Creates a succeeded {@code Promise}, backed by the {@link Future#DEFAULT_EXECUTOR}.
+     * Creates a {@code Promise} that is already completed successfully, using the 
+     * {@link Future#DEFAULT_EXECUTOR} for asynchronous operations.
      *
-     * @param result The result.
-     * @param <T>    The value type of a successful result.
-     * @return A succeeded {@code Promise}.
+     * @param result the value of the successful result
+     * @param <T>    the type of the value
+     * @return a {@code Promise} already completed with the given result
      */
     static <T> Promise<T> successful(T result) {
         return successful(DEFAULT_EXECUTOR, result);
     }
 
     /**
-     * Creates a succeeded {@code Promise}, backed by the given {@link Executor}.
+     * Creates a {@code Promise} that is already completed successfully, using the specified {@link Executor}
+     * for asynchronous operations.
      *
-     * @param executor An {@code Executor} passed to the underlying {@link Future}.
-     * @param result          The result.
-     * @param <T>             The value type of a successful result.
-     * @return A succeeded {@code Promise}.
-     * @throws NullPointerException if executor is null
+     * @param executor the {@code Executor} used by the underlying {@link Future}
+     * @param result   the value of the successful result
+     * @param <T>      the type of the value
+     * @return a {@code Promise} already completed with the given result
+     * @throws NullPointerException if {@code executor} is null
      */
     static <T> Promise<T> successful(Executor executor, T result) {
         Objects.requireNonNull(executor, "executor is null");
@@ -197,7 +203,7 @@ static <T> Promise<T> successful(Executor executor, T result) {
     /**
      * Returns the {@link Executor} used by the underlying {@link Future} of this {@code Promise}.
      *
-     * @return The underlying {@code Executor}.
+     * @return the {@code Executor} associated with this {@code Promise}
      */
     default Executor executor() {
         return executorService();
@@ -218,16 +224,16 @@ default Executor executor() {
     ExecutorService executorService();
 
     /**
-     * Returns the underlying {@link Future} of this {@code Promise}.
+     * Returns the underlying {@link Future} associated with this {@code Promise}.
      *
-     * @return The {@code Future}.
+     * @return the underlying {@code Future}
      */
     Future<T> future();
 
     /**
-     * Checks if this {@code Promise} is completed, i.e. has a value.
+     * Checks whether this {@code Promise} has been completed, either successfully or with a failure.
      *
-     * @return true, if the computation successfully finished or failed, false otherwise.
+     * @return {@code true} if the {@code Promise} is completed, {@code false} otherwise
      */
     default boolean isCompleted() {
         return future().isCompleted();
@@ -236,9 +242,9 @@ default boolean isCompleted() {
     /**
      * Completes this {@code Promise} with the given {@code value}.
      *
-     * @param value Either a {@link Try.Success} containing the result or a {@link Try.Failure} containing an exception.
-     * @return This {@code Promise}.
-     * @throws IllegalStateException if this {@code Promise} has already been completed.
+     * @param value a {@link Try.Success} containing the result or a {@link Try.Failure} containing an exception
+     * @return this {@code Promise}
+     * @throws IllegalStateException if this {@code Promise} has already been completed
      */
     default Promise<T> complete(Try<? extends T> value) {
         if (tryComplete(value)) {
@@ -249,72 +255,75 @@ default Promise<T> complete(Try<? extends T> value) {
     }
 
     /**
-     * Attempts to completes this {@code Promise} with the given {@code value}.
+     * Attempts to complete this {@code Promise} with the given {@code value}.
      *
-     * @param value Either a {@link Try.Success} containing the result or a {@link Try.Failure} containing an exception.
-     * @return {@code false} if this {@code Promise} has already been completed, {@code true} otherwise.
-     * @throws IllegalStateException if this {@code Promise} has already been completed.
+     * @param value a {@link Try.Success} containing the result or a {@link Try.Failure} containing an exception
+     * @return {@code true} if the {@code Promise} was completed successfully, 
+     *         {@code false} if it was already completed
      */
     boolean tryComplete(Try<? extends T> value);
 
     /**
-     * Completes this {@code Promise} with the given {@code Future}, once that {@code Future} is completed.
+     * Completes this {@code Promise} with the result of the given {@code Future} once it is completed.
      *
-     * @param other Another {@code Future} to react on.
-     * @return This {@code Promise}.
+     * @param other the {@code Future} whose result or failure will complete this {@code Promise}
+     * @return this {@code Promise}
      */
     default Promise<T> completeWith(Future<? extends T> other) {
         return tryCompleteWith(other);
     }
 
     /**
-     * Attempts to complete this {@code Promise} with the specified {@code Future}, once that {@code Future} is completed.
+     * Attempts to complete this {@code Promise} with the result of the given {@code Future} once it is completed.
      *
-     * @param other Another {@code Future} to react on.
-     * @return This {@code Promise}.
+     * @param other the {@code Future} whose result or failure may complete this {@code Promise}
+     * @return {@code true} if this {@code Promise} was completed by {@code other}, 
+     *         {@code false} if it was already completed
      */
     default Promise<T> tryCompleteWith(Future<? extends T> other) {
         other.onComplete(this::tryComplete);
         return this;
     }
 
     /**
-     * Completes this {@code Promise} with the given {@code value}.
+     * Completes this {@code Promise} with the given value.
      *
-     * @param value A value.
-     * @return This {@code Promise}.
-     * @throws IllegalStateException if this {@code Promise} has already been completed.
+     * @param value the value to complete this {@code Promise} with
+     * @return this {@code Promise}
+     * @throws IllegalStateException if this {@code Promise} has already been completed
      */
     default Promise<T> success(T value) {
         return complete(Try.success(value));
     }
 
     /**
-     * Completes this {@code Promise} with the given {@code value}.
+     * Attempts to complete this {@code Promise} with the given value.
      *
-     * @param value A value.
-     * @return {@code false} if this {@code Promise} has already been completed, {@code true} otherwise.
+     * @param value the value to complete this {@code Promise} with
+     * @return {@code true} if the {@code Promise} was completed successfully, 
+     *         {@code false} if it was already completed
      */
     default boolean trySuccess(T value) {
         return tryComplete(Try.success(value));
     }
 
     /**
-     * Completes this {@code Promise} with the given {@code exception}.
+     * Completes this {@code Promise} with the given exception.
      *
-     * @param exception An exception.
-     * @return This {@code Promise}.
-     * @throws IllegalStateException if this {@code Promise} has already been completed.
+     * @param exception the exception to complete this {@code Promise} with
+     * @return this {@code Promise}
+     * @throws IllegalStateException if this {@code Promise} has already been completed
      */
     default Promise<T> failure(Throwable exception) {
         return complete(Try.failure(exception));
     }
 
     /**
-     * Completes this {@code Promise} with the given {@code exception}.
+     * Attempts to complete this {@code Promise} with the given exception.
      *
-     * @param exception An exception.
-     * @return {@code false} if this {@code Promise} has already been completed, {@code true} otherwise.
+     * @param exception the exception to complete this {@code Promise} with
+     * @return {@code true} if the {@code Promise} was completed successfully, 
+     *         {@code false} if it was already completed
      */
     default boolean tryFailure(Throwable exception) {
         return tryComplete(Try.failure(exception));