diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index caeee074e..5f9d31c2d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -193,7 +193,7 @@ Note: Detailed information about performing a release can be found in the SCM se
 
 ### Branching Model
 
-We following a simple git workflow/branching model:
+We follow a simple git workflow/branching model:
 
 ```
                          master
diff --git a/vavr/src/main/java/io/vavr/CheckedConsumer.java b/vavr/src/main/java/io/vavr/CheckedConsumer.java
index fc43db2e1..5a7bdcdf8 100644
--- a/vavr/src/main/java/io/vavr/CheckedConsumer.java
+++ b/vavr/src/main/java/io/vavr/CheckedConsumer.java
@@ -24,30 +24,31 @@
 import static io.vavr.CheckedConsumerModule.sneakyThrow;
 
 /**
- * A consumer that may throw, equivalent to {@linkplain java.util.function.Consumer}.
+ * A {@linkplain java.util.function.Consumer} that is allowed to throw checked exceptions.
  *
- * @param <T> the value type supplied to this consumer.
+ * @param <T> the type of the input to the consumer
  */
 @FunctionalInterface
 public interface CheckedConsumer<T> {
 
     /**
-     * Creates a {@code CheckedConsumer}.
+     * Creates a {@code CheckedConsumer} from the given method reference or lambda.
      *
+     * <p>Example usage:</p>
      * <pre>{@code
      * final CheckedConsumer<Value> checkedConsumer = CheckedConsumer.of(Value::stdout);
      * final Consumer<Value> consumer = checkedConsumer.unchecked();
      *
-     * // prints "Hi" on the console
+     * // prints "Hi" to the console
      * consumer.accept(CharSeq.of("Hi!"));
      *
-     * // throws
+     * // may throw an exception
      * consumer.accept(null);
      * }</pre>
      *
-     * @param methodReference (typically) a method reference, e.g. {@code Type::method}
-     * @param <T> type of values that are accepted by the consumer
-     * @return a new {@code CheckedConsumer}
+     * @param methodReference typically a method reference, e.g. {@code Type::method}
+     * @param <T> the type of values accepted by the consumer
+     * @return a new {@code CheckedConsumer} wrapping the given method reference
      * @see CheckedFunction1#of(CheckedFunction1)
      */
     static <T> CheckedConsumer<T> of(CheckedConsumer<T> methodReference) {
@@ -55,18 +56,18 @@ static <T> CheckedConsumer<T> of(CheckedConsumer<T> methodReference) {
     }
 
     /**
-     * Performs side-effects.
+     * Performs an action on the given value, potentially causing side-effects.
      *
-     * @param t a value of type {@code T}
-     * @throws Throwable if an error occurs
+     * @param t the input value of type {@code T}
+     * @throws Throwable if an error occurs during execution
      */
     void accept(T t) throws Throwable;
 
     /**
-     * Returns a chained {@code CheckedConsumer} that first executes {@code this.accept(t)}
-     * and then {@code after.accept(t)}, for a given {@code t} of type {@code T}.
+     * Returns a composed {@code CheckedConsumer} that performs, in sequence, 
+     * {@code this.accept(t)} followed by {@code after.accept(t)} for the same input {@code t}.
      *
-     * @param after the action that will be executed after this action
+     * @param after the action to execute after this action
      * @return a new {@code CheckedConsumer} that chains {@code this} and {@code after}
      * @throws NullPointerException if {@code after} is null
      */
@@ -76,9 +77,10 @@ default CheckedConsumer<T> andThen(CheckedConsumer<? super T> after) {
     }
 
     /**
-     * Returns an unchecked {@link Consumer} that will <em>sneaky throw</em> if an exceptions occurs when accepting a value.
+     * Returns an unchecked {@link Consumer} that <em>sneakily throws</em> any exception 
+     * encountered while accepting a value.
      *
-     * @return a new {@link Consumer} that throws a {@code Throwable}.
+     * @return a {@link Consumer} that may throw any {@link Throwable} without declaring it
      */
     default Consumer<T> unchecked() {
         return t -> {
diff --git a/vavr/src/main/java/io/vavr/CheckedPredicate.java b/vavr/src/main/java/io/vavr/CheckedPredicate.java
index f2f9633b1..88d17e793 100644
--- a/vavr/src/main/java/io/vavr/CheckedPredicate.java
+++ b/vavr/src/main/java/io/vavr/CheckedPredicate.java
@@ -23,7 +23,7 @@
 import static io.vavr.CheckedPredicateModule.sneakyThrow;
 
 /**
- * A {@linkplain java.util.function.Predicate} which may throw.
+ * A {@linkplain java.util.function.Predicate} that is allowed to throw checked exceptions.
  *
  * @param <T> the type of the input to the predicate
  */
@@ -31,22 +31,23 @@
 public interface CheckedPredicate<T> {
 
     /**
-     * Creates a {@code CheckedPredicate}.
+     * Creates a {@code CheckedPredicate} from the given method reference or lambda.
      *
+     * <p>Example usage:</p>
      * <pre>{@code
      * final CheckedPredicate<Boolean> checkedPredicate = CheckedPredicate.of(Boolean::booleanValue);
      * final Predicate<Boolean> predicate = checkedPredicate.unchecked();
      *
-     * // = true
+     * // returns true
      * predicate.test(Boolean.TRUE);
      *
-     * // throws
+     * // may throw an exception
      * predicate.test(null);
      * }</pre>
      *
-     * @param methodReference (typically) a method reference, e.g. {@code Type::method}
-     * @param <T> type of values that are tested by the predicate
-     * @return a new {@code CheckedPredicate}
+     * @param methodReference typically a method reference, e.g. {@code Type::method}
+     * @param <T> the type of values tested by the predicate
+     * @return a new {@code CheckedPredicate} wrapping the given method reference
      * @see CheckedFunction1#of(CheckedFunction1)
      */
     static <T> CheckedPredicate<T> of(CheckedPredicate<T> methodReference) {
@@ -57,24 +58,25 @@ static <T> CheckedPredicate<T> of(CheckedPredicate<T> methodReference) {
      * Evaluates this predicate on the given argument.
      *
      * @param t the input argument
-     * @return {@code true} if the input argument matches the predicate, otherwise {@code false}
-     * @throws Throwable if an error occurs
+     * @return {@code true} if the argument satisfies the predicate, {@code false} otherwise
+     * @throws Throwable if an error occurs during evaluation
      */
     boolean test(T t) throws Throwable;
 
     /**
-     * Negates this predicate.
+     * Returns a predicate that represents the logical negation of this predicate.
      *
-     * @return A new CheckedPredicate.
+     * @return a new {@code CheckedPredicate} representing the negated condition
      */
     default CheckedPredicate<T> negate() {
         return t -> !test(t);
     }
 
     /**
-     * Returns an unchecked {@link Predicate} that will <em>sneaky throw</em> if an exceptions occurs when testing a value.
+     * Returns an unchecked {@link Predicate} that <em>sneakily throws</em> any exception 
+     * encountered when testing a value.
      *
-     * @return a new {@link Predicate} that throws a {@code Throwable}.
+     * @return a {@link Predicate} that may throw any {@link Throwable} without declaring it
      */
     default Predicate<T> unchecked() {
         return t -> {
diff --git a/vavr/src/main/java/io/vavr/CheckedRunnable.java b/vavr/src/main/java/io/vavr/CheckedRunnable.java
index 41715f3bf..f197d1671 100644
--- a/vavr/src/main/java/io/vavr/CheckedRunnable.java
+++ b/vavr/src/main/java/io/vavr/CheckedRunnable.java
@@ -21,28 +21,29 @@
 import static io.vavr.CheckedRunnableModule.sneakyThrow;
 
 /**
- * A {@linkplain Runnable} which may throw.
+ * A {@linkplain Runnable} that is allowed to throw checked exceptions.
  */
 @FunctionalInterface
 public interface CheckedRunnable {
 
     /**
-     * Creates a {@code CheckedRunnable}.
+     * Creates a {@code CheckedRunnable} from the given method reference or lambda.
      *
+     * <p>Example usage:</p>
      * <pre>{@code
      * // class Evil { static void sideEffect() { ... } }
      * final CheckedRunnable checkedRunnable = CheckedRunnable.of(Evil::sideEffect);
      * final Runnable runnable = checkedRunnable.unchecked();
      *
-     * // may or may not perform a side-effect while not throwing
+     * // may or may not perform the side-effect without throwing checked exceptions
      * runnable.run();
      *
-     * // may or may not perform a side-effect while throwing
+     * // may or may not perform the side-effect while potentially throwing
      * runnable.run();
      * }</pre>
      *
-     * @param methodReference (typically) a method reference, e.g. {@code Type::method}
-     * @return a new {@code CheckedRunnable}
+     * @param methodReference typically a method reference, e.g. {@code Type::method}
+     * @return a new {@code CheckedRunnable} wrapping the given method reference
      * @see CheckedFunction1#of(CheckedFunction1)
      */
     static CheckedRunnable of(CheckedRunnable methodReference) {
@@ -50,16 +51,18 @@ static CheckedRunnable of(CheckedRunnable methodReference) {
     }
 
     /**
-     * Performs side-effects.
+     * Executes the action, potentially performing side-effects.
      *
-     * @throws Throwable if an error occurs
+     * @throws Throwable if an error occurs during execution
      */
+
     void run() throws Throwable;
 
     /**
-     * Returns an unchecked {@link Runnable} that will <em>sneaky throw</em> if an exceptions occurs when running the unit of work.
+     * Returns an unchecked {@link Runnable} that <em>sneakily throws</em> any exception 
+     * encountered during execution of this unit of work.
      *
-     * @return a new {@link Runnable} that throws a {@code Throwable}.
+     * @return a {@link Runnable} that may throw any {@link Throwable} without declaring it
      */
     default Runnable unchecked() {
         return () -> {
diff --git a/vavr/src/main/java/io/vavr/Lazy.java b/vavr/src/main/java/io/vavr/Lazy.java
index 4f15373cc..b2ee2051b 100644
--- a/vavr/src/main/java/io/vavr/Lazy.java
+++ b/vavr/src/main/java/io/vavr/Lazy.java
@@ -35,28 +35,29 @@
 import java.util.function.Supplier;
 
 /**
- * Represents a lazy evaluated value. Compared to a Supplier, Lazy is memoizing, i.e. it evaluates only once and
- * therefore is referential transparent.
+ * Represents a lazily evaluated value. Unlike a standard {@link java.util.function.Supplier}, 
+ * {@code Lazy} is memoizing: the computation is performed at most once, ensuring referential transparency.
  *
- * <pre>
- * <code>
+ * <p>This type behaves more like a <em>Functor</em> than a <em>Monad</em>: it represents a value rather than capturing
+ * a specific state. Therefore, it does not provide operations like {@code flatMap} or {@code orElse}.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre><code>
  * final Lazy&lt;Double&gt; l = Lazy.of(Math::random);
- * l.isEvaluated(); // = false
- * l.get();         // = 0.123 (random generated)
- * l.isEvaluated(); // = true
- * l.get();         // = 0.123 (memoized)
- * </code>
- * </pre>
+ * l.isEvaluated(); // false
+ * double value = l.get(); // evaluates and returns a random number, e.g., 0.123
+ * l.isEvaluated(); // true
+ * double memoizedValue = l.get(); // returns the same value as before, e.g., 0.123
+ * </code></pre>
  *
- * Example of creating a <em>real</em> lazy value (works only with interfaces):
+ * <p>Creating a <em>truly lazy</em> value for an interface type:</p>
+ * <pre><code>
+ * final CharSequence chars = Lazy.val(() -&gt; "Yay!", CharSequence.class);
+ * </code></pre>
  *
- * <pre><code>final CharSequence chars = Lazy.val(() -&gt; "Yay!", CharSequence.class);</code></pre>
- * 
- * @param <T> The type of the lazy evaluated value 
+ * @param <T> the type of the lazily evaluated value
  * @author Daniel Dietrich
  */
-// DEV-NOTE: No flatMap and orElse because this more like a Functor than a Monad.
-//           It represents a value rather than capturing a specific state.
 public final class Lazy<T> implements Value<T>, Supplier<T>, Serializable {
 
     private static final long serialVersionUID = 1L;
@@ -74,13 +75,12 @@ private Lazy(Supplier<? extends T> supplier) {
     }
 
     /**
-     * Narrows a widened {@code Lazy<? extends T>} to {@code Lazy<T>}
-     * by performing a type-safe cast. This is eligible because immutable/read-only
-     * collections are covariant.
+     * Narrows a {@code Lazy<? extends T>} to {@code Lazy<T>} via a type-safe cast.
+     * This is safe because immutable or read-only collections are covariant.
      *
-     * @param lazy A {@code Lazy}.
-     * @param <T>  Component type of the {@code Lazy}.
-     * @return the given {@code lazy} instance as narrowed type {@code Lazy<T>}.
+     * @param lazy the {@code Lazy} instance to narrow
+     * @param <T>  the type of the value
+     * @return the given {@code lazy} instance as a {@code Lazy<T>}
      */
     @SuppressWarnings("unchecked")
     public static <T> Lazy<T> narrow(Lazy<? extends T> lazy) {
@@ -88,12 +88,12 @@ public static <T> Lazy<T> narrow(Lazy<? extends T> lazy) {
     }
 
     /**
-     * Creates a {@code Lazy} that requests its value from a given {@code Supplier}. The supplier is asked only once,
-     * the value is memoized.
+     * Creates a {@code Lazy} instance that obtains its value from the given {@code Supplier}.
+     * The supplier is invoked at most once, and the result is cached for subsequent calls.
      *
-     * @param <T>      type of the lazy value
-     * @param supplier A supplier
-     * @return A new instance of Lazy
+     * @param <T>      the type of the lazy value
+     * @param supplier the supplier providing the value
+     * @return a new {@code Lazy} instance
      */
     @SuppressWarnings("unchecked")
     public static <T> Lazy<T> of(Supplier<? extends T> supplier) {
@@ -106,13 +106,15 @@ public static <T> Lazy<T> of(Supplier<? extends T> supplier) {
     }
 
     /**
-     * Reduces many {@code Lazy} values into a single {@code Lazy} by transforming an
-     * {@code Iterable<Lazy<? extends T>>} into a {@code Lazy<Seq<T>>}.
+     * Combines multiple {@code Lazy} instances into a single {@code Lazy} containing a sequence of their evaluated values.
+     *
+     * <p>Transforms an {@code Iterable<Lazy<? extends T>>} into a {@code Lazy<Seq<T>>}, evaluating each value lazily
+     * when the resulting {@code Lazy} is accessed.</p>
      *
-     * @param <T>    Type of the lazy values.
-     * @param values An iterable of lazy values.
-     * @return A lazy sequence of values.
-     * @throws NullPointerException if values is null
+     * @param <T>    the type of the lazy values
+     * @param values an {@code Iterable} of lazy values
+     * @return a {@code Lazy} containing a sequence of the evaluated values
+     * @throws NullPointerException if {@code values} is null
      */
     @SuppressWarnings("Convert2MethodRef") // TODO should be fixed in JDK 9 and Idea
     public static <T> Lazy<Seq<T>> sequence(Iterable<? extends Lazy<? extends T>> values) {
@@ -121,13 +123,13 @@ public static <T> Lazy<Seq<T>> sequence(Iterable<? extends Lazy<? extends T>> va
     }
 
     /**
-     * Creates a real _lazy value_ of type {@code T}, backed by a {@linkplain java.lang.reflect.Proxy} which delegates
-     * to a {@code Lazy} instance.
+     * Creates a true <em>lazy value</em> of type {@code T}, implemented using a {@linkplain java.lang.reflect.Proxy}
+     * that delegates to a {@code Lazy} instance.
      *
-     * @param supplier A supplier
-     * @param type     An interface
-     * @param <T>      type of the lazy value
-     * @return A new instance of T
+     * @param supplier the supplier providing the value when needed
+     * @param type     the interface class that the proxy should implement
+     * @param <T>      the type of the lazy value
+     * @return a new proxy instance of type {@code T} that evaluates lazily
      */
     @GwtIncompatible("reflection is not supported")
     @SuppressWarnings("unchecked")
@@ -148,10 +150,10 @@ public Option<T> filter(Predicate<? super T> predicate) {
     }
 
     /**
-     * Evaluates this lazy value and caches it, when called the first time.
-     * On subsequent calls, returns the cached value.
+     * Evaluates this lazy value on the first call and caches the result.
+     * Subsequent calls return the cached value without recomputation.
      *
-     * @return the lazy evaluated value
+     * @return the evaluated value
      */
     @Override
     public T get() {
@@ -173,9 +175,9 @@ private T computeValue() {
     }
 
     /**
-     * A {@code Lazy}'s value is computed synchronously.
+     * Indicates that this {@code Lazy} value is computed synchronously.
      *
-     * @return false
+     * @return {@code false}
      */
     @Override
     public boolean isAsync() {
@@ -188,21 +190,21 @@ public boolean isEmpty() {
     }
 
     /**
-     * Checks, if this lazy value is evaluated.
-     * <p>
-     * Note: A value is internally evaluated (once) by calling {@link #get()}.
+     * Checks whether this lazy value has been evaluated.
+     *
+     * <p>Note: The value is evaluated internally (at most once) when {@link #get()} is called.</p>
      *
-     * @return true, if the value is evaluated, false otherwise.
-     * @throws UnsupportedOperationException if this value is undefined
+     * @return {@code true} if the value has been evaluated, {@code false} otherwise
+     * @throws UnsupportedOperationException if this lazy value is undefined
      */
     public boolean isEvaluated() {
         return supplier == null;
     }
 
     /**
-     * A {@code Lazy}'s value is computed lazily.
+     * Indicates that this {@code Lazy} value is computed lazily.
      *
-     * @return true
+     * @return {@code true}
      */
     @Override
     public boolean isLazy() {
@@ -241,11 +243,12 @@ public Lazy<T> peek(Consumer<? super T> action) {
     }
 
     /**
-     * Transforms this {@code Lazy}.
+     * Applies a transformation function to the value contained in this {@code Lazy}, producing a new {@code Lazy} instance
+     * of the transformed value.
      *
-     * @param f   A transformation
-     * @param <U> Type of transformation result
-     * @return An instance of type {@code U}
+     * @param f   the function to transform the value
+     * @param <U> the type of the result of the transformation
+     * @return a new {@code Lazy} instance containing the transformed value
      * @throws NullPointerException if {@code f} is null
      */
     public <U> U transform(Function<? super Lazy<T>, ? extends U> f) {
@@ -274,10 +277,10 @@ public String toString() {
     }
 
     /**
-     * Ensures that the value is evaluated before serialization.
+     * Forces the lazy value to be evaluated before it is serialized.
      *
-     * @param s An object serialization stream.
-     * @throws java.io.IOException If an error occurs writing to the stream.
+     * @param s the object output stream to write to
+     * @throws java.io.IOException if an I/O error occurs during serialization
      */
     @GwtIncompatible("The Java serialization protocol is explicitly not supported")
     private void writeObject(ObjectOutputStream s) throws IOException {
diff --git a/vavr/src/main/java/io/vavr/Memoized.java b/vavr/src/main/java/io/vavr/Memoized.java
index 160c074ff..24cd5db7b 100644
--- a/vavr/src/main/java/io/vavr/Memoized.java
+++ b/vavr/src/main/java/io/vavr/Memoized.java
@@ -1,7 +1,4 @@
 package io.vavr;
 
-/**
- * INTERNAL. Zero abstract method (ZAM) / tagging interface.
- */
 interface Memoized {
 }
diff --git a/vavr/src/main/java/io/vavr/PartialFunction.java b/vavr/src/main/java/io/vavr/PartialFunction.java
index 899eb448f..80c33e456 100644
--- a/vavr/src/main/java/io/vavr/PartialFunction.java
+++ b/vavr/src/main/java/io/vavr/PartialFunction.java
@@ -22,18 +22,19 @@
 import java.util.function.Function;
 
 /**
- * Represents a partial function T -&gt; R that is not necessarily defined for all input values of type T.
- * The caller is responsible for calling the method isDefinedAt() before this function is applied to the value.
- * <p>
- * If the function <em>is not defined</em> for a specific value, apply() may produce an arbitrary result.
- * More specifically it is not guaranteed that the function will throw an exception.
- * <p>
- * If the function <em>is defined</em> for a specific value, apply() may still throw an exception.
+ * Represents a partial function {@code T -> R} that may not be defined for all input values of type {@code T}.
+ * The caller is responsible for checking {@link #isDefinedAt(Object)} before applying this function.
  *
- * @param <T> type of the function input, called <em>domain</em> of the function
- * @param <R> type of the function output, called <em>codomain</em> of the function
+ * <p>If the function <em>is not defined</em> for a given value, {@link #apply(Object)} may produce an arbitrary result.
+ * There is no guarantee that an exception will be thrown in this case.</p>
+ *
+ * <p>If the function <em>is defined</em> for a given value, {@link #apply(Object)} may still throw an exception during execution.</p>
+ *
+ * @param <T> the type of the function input (the <em>domain</em>)
+ * @param <R> the type of the function output (the <em>codomain</em>)
  * @author Daniel Dietrich
  */
+
 public interface PartialFunction<T, R> extends Function1<T, R> {
 
     /**
@@ -42,14 +43,16 @@ public interface PartialFunction<T, R> extends Function1<T, R> {
     long serialVersionUID = 1L;
 
     /**
-     * Unlifts a {@code totalFunction} that returns an {@code Option} result into a partial function.
-     * The total function should be side effect free because it might be invoked twice: when checking if the
-     * unlifted partial function is defined at a value and when applying the partial function to a value.
+     * Converts (or "unlifts") a {@code totalFunction} that returns an {@code Option} into a partial function.
+     * <p>
+     * The provided {@code totalFunction} should be side-effect-free, because it may be invoked twice:
+     * once when checking if the resulting partial function is defined at a value, and once when applying
+     * the partial function to that value.
      *
-     * @param totalFunction the function returning an {@code Option} result.
-     * @param <T> type of the function input, called <em>domain</em> of the function
-     * @param <R> type of the function output, called <em>codomain</em> of the function
-     * @return a partial function that is not necessarily defined for all input values of type T.
+     * @param totalFunction the function returning an {@code Option} result
+     * @param <T> the type of the function input (the <em>domain</em>)
+     * @param <R> the type of the function output (the <em>codomain</em>)
+     * @return a partial function that is defined only for inputs for which the {@code totalFunction} returns a defined {@code Option}
      */
     static <T, R> PartialFunction<T, R> unlift(Function<? super T, ? extends Option<? extends R>> totalFunction) {
         return new PartialFunction<T, R>() {
@@ -70,14 +73,14 @@ public boolean isDefinedAt(T value) {
     }
 
     /**
-     * Factory method for creating a partial function that maps a given {@code Value} to its underlying value.
-     * The partial function is defined for an input {@code Value} if and only if the input {@code Value} is not
-     * empty. If the input {@code Value} is not empty, the partial function will return the underlying value of
-     * the input {@code Value}.
+     * Creates a partial function that maps a given {@code Value} to its underlying value.
+     * <p>
+     * The resulting partial function is defined for an input {@code Value} if and only if the {@code Value} is not empty.
+     * For defined inputs, the partial function returns the underlying value contained in the {@code Value}.
      *
-     * @param <T> type of the underlying value of the input {@code Value}.
-     * @param <V> type of the function input, called <em>domain</em> of the function
-     * @return a partial function that maps a {@code Value} to its underlying value.
+     * @param <T> the type of the underlying value
+     * @param <V> the type of the input {@code Value} (the <em>domain</em> of the function)
+     * @return a partial function that maps a non-empty {@code Value} to its underlying value
      */
     static <T, V extends Value<T>> PartialFunction<V, T> getIfDefined() {
         return new PartialFunction<V, T>() {
@@ -100,25 +103,26 @@ public boolean isDefinedAt(V v) {
     /**
      * Applies this function to the given argument and returns the result.
      *
-     * @param t the argument
-     * @return the result of function application
-     *
+     * @param t the input argument
+     * @return the result of applying this function to the input
      */
     R apply(T t);
 
     /**
-     * Tests if a value is contained in the function's domain.
+     * Tests whether a value is contained in the function's domain.
      *
-     * @param value a potential function argument
-     * @return true, if the given value is contained in the function's domain, false otherwise
+     * @param value a potential input to the function
+     * @return {@code true} if the given value is contained in the function's domain, {@code false} otherwise
      */
     boolean isDefinedAt(T value);
 
     /**
      * Lifts this partial function into a total function that returns an {@code Option} result.
      *
-     * @return a function that applies arguments to this function and returns {@code Some(result)}
-     *         if the function is defined for the given arguments, and {@code None} otherwise.
+     * <p>The resulting function applies an argument to this partial function and returns
+     * {@code Some(result)} if the function is defined for that argument, or {@code None} if it is not defined.</p>
+     *
+     * @return a total function that returns an {@code Option} containing the result if defined, or {@code None} otherwise
      */
     default Function1<T, Option<R>> lift() {
         return t -> Option.when(isDefinedAt(t), () -> apply(t));
diff --git a/vavr/src/main/java/io/vavr/Predicates.java b/vavr/src/main/java/io/vavr/Predicates.java
index 486c47cfb..d22bb8f8a 100644
--- a/vavr/src/main/java/io/vavr/Predicates.java
+++ b/vavr/src/main/java/io/vavr/Predicates.java
@@ -35,24 +35,26 @@ private Predicates() {
     }
 
     /**
-     * A combinator that checks if <strong>all</strong> of the given {@code predicates} are satisfied.
-     * <p>
-     * By definition {@code allOf} is satisfied if the given {@code predicates} are empty.
+     * Returns a predicate that is satisfied only when <strong>all</strong> of the provided {@code predicates}
+     * return {@code true} for a given input.
+     *
+     * <p>If no predicates are supplied, the resulting predicate always evaluates to {@code true}.</p>
      *
      * <pre>{@code
      * Predicate<Integer> isGreaterThanOne = i -> i > 1;
      * Predicate<Integer> isGreaterThanTwo = i -> i > 2;
+     *
      * allOf().test(0);                                   // true
      * allOf(isGreaterThanOne, isGreaterThanTwo).test(3); // true
      * allOf(isGreaterThanOne, isGreaterThanTwo).test(2); // false
      * }</pre>
      *
-     * @param predicates An array of predicates
-     * @param <T>        closure over tested object types
-     * @return A new {@code Predicate}
+     * @param predicates the predicates to combine
+     * @param <T> the input type
+     * @return a predicate representing the logical conjunction of all given predicates
      * @throws NullPointerException if {@code predicates} is null
      */
-    @SuppressWarnings({ "unchecked", "varargs" })
+    @SuppressWarnings({"varargs" })
     @SafeVarargs
     public static <T> Predicate<T> allOf(Predicate<T>... predicates) {
         Objects.requireNonNull(predicates, "predicates is null");
@@ -60,23 +62,27 @@ public static <T> Predicate<T> allOf(Predicate<T>... predicates) {
     }
 
     /**
-     * A combinator that checks if <strong>at least one</strong> of the given {@code predicates} is satisfies.
+     * Returns a predicate that is satisfied if <strong>at least one</strong> of the provided {@code predicates}
+     * returns {@code true} for a given input.
+     *
+     * <p>If no predicates are supplied, the resulting predicate always evaluates to {@code false}.</p>
      *
      * <pre>{@code
      * Predicate<Integer> isGreaterThanOne = i -> i > 1;
      * Predicate<Integer> isGreaterThanTwo = i -> i > 2;
+     *
      * anyOf().test(0);                                   // false
      * anyOf(isGreaterThanOne, isGreaterThanTwo).test(3); // true
      * anyOf(isGreaterThanOne, isGreaterThanTwo).test(2); // true
      * anyOf(isGreaterThanOne, isGreaterThanTwo).test(1); // false
      * }</pre>
-     * 
-     * @param predicates An array of predicates
-     * @param <T>        closure over tested object types
-     * @return A new {@code Predicate}
+     *
+     * @param predicates the predicates to combine
+     * @param <T> the input type
+     * @return a predicate representing the logical disjunction of all given predicates
      * @throws NullPointerException if {@code predicates} is null
      */
-    @SuppressWarnings({ "unchecked", "varargs" })
+    @SuppressWarnings({"varargs" })
     @SafeVarargs
     public static <T> Predicate<T> anyOf(Predicate<T>... predicates) {
         Objects.requireNonNull(predicates, "predicates is null");
@@ -84,18 +90,23 @@ public static <T> Predicate<T> anyOf(Predicate<T>... predicates) {
     }
 
     /**
-     * A combinator that checks if <strong>one or more</strong> elements of an {@code Iterable} satisfy the {@code predicate}.
+     * Returns a predicate that checks if <strong>at least one</strong> element in an {@code Iterable}
+     * satisfies the given {@code predicate}.
+     *
+     * <p>If the {@code Iterable} is empty, the resulting predicate evaluates to {@code false}.</p>
      *
      * <pre>{@code
      * Predicate<Integer> isGreaterThanOne = i -> i > 1;
      * Predicate<Iterable<Integer>> existsGreaterThanOne = exists(isGreaterThanOne);
+     *
      * existsGreaterThanOne.test(List.of(0, 1, 2)); // true
      * existsGreaterThanOne.test(List.of(0, 1));    // false
+     * existsGreaterThanOne.test(Collections.emptyList()); // false
      * }</pre>
-     * 
-     * @param predicate A {@code Predicate} that tests elements of type {@code T}
-     * @param <T>        tested object type
-     * @return A new {@code Predicate}
+     *
+     * @param predicate the predicate to test elements against
+     * @param <T> the type of elements in the {@code Iterable}
+     * @return a predicate that evaluates to {@code true} if any element satisfies {@code predicate}
      * @throws NullPointerException if {@code predicate} is null
      */
     public static <T> Predicate<Iterable<T>> exists(Predicate<? super T> predicate) {
@@ -104,18 +115,23 @@ public static <T> Predicate<Iterable<T>> exists(Predicate<? super T> predicate)
     }
 
     /**
-     * A combinator that checks if <strong>all</strong> elements of an {@code Iterable} satisfy the {@code predicate}.
+     * Returns a predicate that checks if <strong>all</strong> elements in an {@code Iterable}
+     * satisfy the given {@code predicate}.
+     *
+     * <p>If the {@code Iterable} is empty, the resulting predicate evaluates to {@code true}.</p>
      *
      * <pre>{@code
      * Predicate<Integer> isGreaterThanOne = i -> i > 1;
      * Predicate<Iterable<Integer>> forAllGreaterThanOne = forAll(isGreaterThanOne);
+     *
      * forAllGreaterThanOne.test(List.of(0, 1, 2)); // false
      * forAllGreaterThanOne.test(List.of(2, 3, 4)); // true
+     * forAllGreaterThanOne.test(Collections.emptyList()); // true
      * }</pre>
      *
-     * @param predicate A {@code Predicate} that tests elements of type {@code T}
-     * @param <T>        tested object type
-     * @return A new {@code Predicate}
+     * @param predicate the predicate to test elements against
+     * @param <T> the type of elements in the {@code Iterable}
+     * @return a predicate that evaluates to {@code true} only if all elements satisfy {@code predicate}
      * @throws NullPointerException if {@code predicate} is null
      */
     public static <T> Predicate<Iterable<T>> forAll(Predicate<? super T> predicate) {
@@ -124,17 +140,18 @@ public static <T> Predicate<Iterable<T>> forAll(Predicate<? super T> predicate)
     }
 
     /**
-     * Creates a {@code Predicate} that tests, if an object is instance of the specified {@code type}.
+     * Returns a {@code Predicate} that tests whether an object is an instance of the specified {@code type}.
      *
      * <pre>{@code
      * Predicate<Object> instanceOfNumber = instanceOf(Number.class);
+     *
      * instanceOfNumber.test(1);    // true
      * instanceOfNumber.test("1");  // false
      * }</pre>
      *
-     * @param type A type
-     * @param <T>  tested object type
-     * @return A new {@code Predicate}
+     * @param type the class to test instances against
+     * @param <T> the type of objects being tested
+     * @return a predicate that evaluates to {@code true} if the object is an instance of {@code type}
      * @throws NullPointerException if {@code type} is null
      */
     // DEV-NOTE: We need Class<? extends T> instead of Class<T>, see {@link TryTest#shouldRecoverSuccessUsingCase()}
@@ -145,39 +162,43 @@ public static <T> Predicate<T> instanceOf(Class<? extends T> type) {
     }
 
     /**
-     * Creates a {@code Predicate} that tests, if an object is equal to the specified {@code value} using
-     * {@link Objects#equals(Object, Object)} for comparison.
+     * Returns a {@code Predicate} that tests whether an object is equal to the specified {@code value},
+     * using {@link Objects#equals(Object, Object)} for comparison.
      *
      * <pre>{@code
      * Predicate<Integer> isOne = is(1);
+     *
      * isOne.test(1); // true
      * isOne.test(2); // false
+     * isOne.test(null); // false
      * }</pre>
      *
-     * @param value A value, may be null
-     * @param <T>   tested object type
-     * @return A new {@code Predicate}
+     * @param value the value to compare against; may be {@code null}
+     * @param <T> the type of object being tested
+     * @return a predicate that evaluates to {@code true} if the tested object equals {@code value}
      */
     public static <T> Predicate<T> is(T value) {
         return obj -> Objects.equals(obj, value);
     }
 
     /**
-     * Creates a {@code Predicate} that tests, if an object is equal to at least one of the specified {@code values}
+     * Returns a {@code Predicate} that tests whether an object is equal to at least one of the specified {@code values},
      * using {@link Objects#equals(Object, Object)} for comparison.
      *
      * <pre>{@code
      * Predicate<Integer> isIn = isIn(1, 2, 3);
+     *
      * isIn.test(1); // true
      * isIn.test(0); // false
+     * isIn.test(null); // false
      * }</pre>
      *
-     * @param values an array of values of type T
-     * @param <T>    closure over tested object types
-     * @return A new {@code Predicate}
+     * @param values the values to compare against; may not be {@code null}
+     * @param <T> the type of objects being tested
+     * @return a predicate that evaluates to {@code true} if the tested object equals any of the specified {@code values}
      * @throws NullPointerException if {@code values} is null
      */
-    @SuppressWarnings({ "unchecked", "varargs" })
+    @SuppressWarnings({"varargs" })
     @SafeVarargs
     public static <T> Predicate<T> isIn(T... values) {
         Objects.requireNonNull(values, "values is null");
@@ -185,56 +206,60 @@ public static <T> Predicate<T> isIn(T... values) {
     }
 
     /**
-     * Creates a {@code Predicate} that tests, if an object is not null
+     * Returns a {@code Predicate} that tests whether an object is not {@code null}.
      *
      * <pre>{@code
      * Predicate<Integer> isNotNull = isNotNull();
+     *
      * isNotNull.test(0);    // true
      * isNotNull.test(null); // false
      * }</pre>
      *
-     * @param <T> tested object type
-     * @return A new {@code Predicate}
+     * @param <T> the type of object being tested
+     * @return a predicate that evaluates to {@code true} if the tested object is not {@code null}
      */
     public static <T> Predicate<T> isNotNull() {
         return Objects::nonNull;
     }
 
     /**
-     * Creates a {@code Predicate} that tests, if an object is null
+     * Returns a {@code Predicate} that tests whether an object is {@code null}.
      *
      * <pre>{@code
      * Predicate<Integer> isNull = isNull();
+     *
      * isNull.test(null); // true
      * isNull.test(0);    // false
      * }</pre>
      *
-     * @param <T> tested object type
-     * @return A new {@code Predicate}
+     * @param <T> the type of object being tested
+     * @return a predicate that evaluates to {@code true} if the tested object is {@code null}
      */
     public static <T> Predicate<T> isNull() {
         return Objects::isNull;
     }
 
     /**
-     * A combinator that checks if <strong>none</strong> of the given {@code predicates} is satisfied.
-     * <p>
-     * Naturally {@code noneOf} is satisfied if the given {@code predicates} are empty.
+     * Returns a predicate that is satisfied if <strong>none</strong> of the provided {@code predicates}
+     * return {@code true} for a given input.
+     *
+     * <p>If no predicates are supplied, the resulting predicate always evaluates to {@code true}.</p>
      *
      * <pre>{@code
      * Predicate<Integer> isGreaterThanOne = i -> i > 1;
      * Predicate<Integer> isGreaterThanTwo = i -> i > 2;
+     *
      * noneOf().test(0);                                   // true
      * noneOf(isGreaterThanOne, isGreaterThanTwo).test(1); // true
      * noneOf(isGreaterThanOne, isGreaterThanTwo).test(2); // false
      * }</pre>
      *
-     * @param predicates An array of predicates
-     * @param <T>        closure over tested object types
-     * @return A new {@code Predicate}
+     * @param predicates the predicates to combine
+     * @param <T> the input type
+     * @return a predicate that evaluates to {@code true} only if all predicates return {@code false}
      * @throws NullPointerException if {@code predicates} is null
      */
-    @SuppressWarnings({ "unchecked", "varargs" })
+    @SuppressWarnings({"varargs" })
     @SafeVarargs
     public static <T> Predicate<T> noneOf(Predicate<T>... predicates) {
         Objects.requireNonNull(predicates, "predicates is null");
@@ -242,23 +267,23 @@ public static <T> Predicate<T> noneOf(Predicate<T>... predicates) {
     }
 
     /**
-     * Negates a given {@code Predicate}.
+     * Returns a predicate that negates the result of the given {@code predicate}.
      *
      * <pre>{@code
-     * // negates a method reference
+     * // Negates a method reference
      * Predicate<String> isNotNull1 = not(Objects::isNull);
      * isNotNull1.test("");   // true
      * isNotNull1.test(null); // false
      *
-     * // negates a predicate instance
+     * // Negates a predicate instance
      * Predicate<String> isNotNull2 = not(Predicates.isNull());
      * isNotNull2.test("");   // true
      * isNotNull2.test(null); // false
      * }</pre>
      *
-     * @param predicate A {@code Predicate} that tests elements of type {@code T}
-     * @param <T>       tested object type
-     * @return A new {@code Predicate}
+     * @param predicate the predicate to negate
+     * @param <T> the type of objects being tested
+     * @return a predicate that evaluates to {@code true} if the original predicate evaluates to {@code false}, and vice versa
      * @throws NullPointerException if {@code predicate} is null
      */
     @SuppressWarnings("unchecked")
@@ -266,5 +291,4 @@ public static <T> Predicate<T> not(Predicate<? super T> predicate) {
         Objects.requireNonNull(predicate, "predicate is null");
         return (Predicate<T>) predicate.negate();
     }
-
 }
diff --git a/vavr/src/main/java/io/vavr/Value.java b/vavr/src/main/java/io/vavr/Value.java
index 1895f592f..b7536ef6e 100644
--- a/vavr/src/main/java/io/vavr/Value.java
+++ b/vavr/src/main/java/io/vavr/Value.java
@@ -53,12 +53,12 @@
 import static io.vavr.API.*;
 
 /**
- * Functional programming is all about values and transformation of values using functions. The {@code Value}
- * type reflects the values in a functional setting. It can be seen as the result of a partial function application.
- * Hence the result may be undefined. If a value is undefined, we say it is empty.
+ * Represents a value in a functional programming context. A {@code Value} models the outcome of a computation
+ * that may or may not produce a result, similar to the result of a partially applied function.
  * <p>
- * How the empty state is interpreted depends on the context, i.e. it may be <em>undefined</em>, <em>failed</em>,
- * <em>no elements</em>, etc.
+ * A {@code Value} may be present or absent. When absent, it is considered <em>empty</em>. The meaning of the
+ * empty state depends on the concrete implementation and usage context - it may represent an undefined value,
+ * a failed computation, or the absence of elements.
  * <p>
  * Basic operations:
  *
diff --git a/vavr/src/main/java/io/vavr/concurrent/Future.java b/vavr/src/main/java/io/vavr/concurrent/Future.java
index c830df4ac..c106bcabd 100644
--- a/vavr/src/main/java/io/vavr/concurrent/Future.java
+++ b/vavr/src/main/java/io/vavr/concurrent/Future.java
@@ -35,23 +35,25 @@
 import java.util.function.*;
 
 /**
- * A Future is a computation result that becomes available at some point. All operations provided are non-blocking.
- * <p>
- * The underlying {@code Executor} is used to execute asynchronous handlers, e.g. via
- * {@code onComplete(...)}.
- * <p>
- * A Future has two states: pending and completed.
+ * Represents the result of an asynchronous computation that becomes available at some point in the future.
+ * All operations provided by this {@code Future} are non-blocking.
+ *
+ * <p>The underlying {@link java.util.concurrent.Executor} is used to execute asynchronous handlers, for example via
+ * {@code onComplete(...)}.</p>
+ *
+ * <p>A {@code Future} has two states:</p>
  * <ul>
- * <li>Pending: The computation is ongoing. Only a pending future may be completed or cancelled.</li>
- * <li>Completed: The computation finished successfully with a result, failed with an exception or was cancelled.</li>
+ *     <li><strong>Pending:</strong> The computation is ongoing. Only a pending future may be completed or cancelled.</li>
+ *     <li><strong>Completed:</strong> The computation has finished, either successfully with a result, with an exception, or via cancellation.</li>
  * </ul>
- * Callbacks may be registered on a Future at each point of time. These actions are performed as soon as the Future
- * is completed. An action which is registered on a completed Future is immediately performed. The action may run on
- * a separate Thread, depending on the underlying Executor. Actions which are registered on a cancelled
- * Future are performed with the failed result.
  *
- * @param <T> Type of the computation result.
- * @author Daniel Dietrich
+ * <p>Callbacks may be registered on a {@code Future} at any time. These callbacks are executed as soon as the
+ * {@code Future} completes. If a callback is registered on a completed {@code Future}, it is executed immediately.
+ * Execution may occur on a separate thread, depending on the underlying {@code Executor}. Callbacks registered
+ * on a cancelled {@code Future} are executed with the failed result.</p>
+ *
+ * @param <T> the type of the computation result
+ * @author Daniel Dietrich, Grzegorz Piwowarek
  */
 @SuppressWarnings("deprecation")
 public interface Future<T> extends Value<T> {
@@ -80,7 +82,7 @@ public interface Future<T> extends Value<T> {
      * @see ForkJoinPool#awaitQuiescence(long, TimeUnit)
      * @deprecated Will be removed in Vavr 1.0. Use {@link #DEFAULT_EXECUTOR instead}.
      */
-    @Deprecated
+    @Deprecated()
     ExecutorService DEFAULT_EXECUTOR_SERVICE = ForkJoinPool.commonPool();
 
     /**
@@ -109,12 +111,13 @@ public interface Future<T> extends Value<T> {
     Executor DEFAULT_EXECUTOR = DEFAULT_EXECUTOR_SERVICE;
 
     /**
-     * Creates a failed {@code Future} with the given {@code exception}, backed by the {@link #DEFAULT_EXECUTOR}.
+     * Creates a failed {@code Future} with the given {@code exception}, using the {@link #DEFAULT_EXECUTOR}
+     * to execute callbacks.
      *
-     * @param exception The reason why it failed.
-     * @param <T>       The value type of a successful result.
-     * @return A failed {@code Future}.
-     * @throws NullPointerException if exception is null
+     * @param exception the exception that caused the failure
+     * @param <T>       the type of a successful result
+     * @return a failed {@code Future} containing the given exception
+     * @throws NullPointerException if {@code exception} is null
      */
     static <T> Future<T> failed(Throwable exception) {
         Objects.requireNonNull(exception, "exception is null");
@@ -122,13 +125,13 @@ static <T> Future<T> failed(Throwable exception) {
     }
 
     /**
-     * Creates a failed {@code Future} with the given {@code exception}, backed by the given {@link Executor}.
+     * Creates a failed {@code Future} with the given {@code exception}, executing callbacks using the specified {@link Executor}.
      *
-     * @param executor  An {@link Executor}.
-     * @param exception The reason why it failed.
-     * @param <T>       The value type of a successful result.
-     * @return A failed {@code Future}.
-     * @throws NullPointerException if executor or exception is null
+     * @param executor  the {@link Executor} to run asynchronous handlers
+     * @param exception the exception that caused the failure
+     * @param <T>       the type of a successful result
+     * @return a failed {@code Future} containing the given exception
+     * @throws NullPointerException if {@code executor} or {@code exception} is null
      */
     static <T> Future<T> failed(Executor executor, Throwable exception) {
         Objects.requireNonNull(executor, "executor is null");
@@ -137,33 +140,33 @@ static <T> Future<T> failed(Executor executor, Throwable exception) {
     }
 
     /**
-     * Returns a {@code Future} that eventually succeeds with the first result of the given {@code Future}s which
-     * matches the given {@code predicate}. If no result matches, the {@code Future} will contain {@link Option.None}.
-     * <p>
-     * The returned {@code Future} is backed by the {@link #DEFAULT_EXECUTOR}.
+     * Returns a {@code Future} that completes with the first result of the given {@code futures}
+     * that satisfies the specified {@code predicate}. If no result matches, the {@code Future} will contain {@link Option.None}.
      *
-     * @param futures   An iterable of futures.
-     * @param predicate A predicate that tests successful future results.
-     * @param <T>       Result type of the futures.
-     * @return A Future of an {@link Option} of the first result of the given {@code futures} that satisfies the given {@code predicate}.
-     * @throws NullPointerException if one of the arguments is null
+     * <p>The returned {@code Future} uses the {@link #DEFAULT_EXECUTOR} to execute callbacks.</p>
+     *
+     * @param futures   an iterable of futures to inspect
+     * @param predicate a predicate to test successful future results
+     * @param <T>       the type of the future results
+     * @return a {@code Future} of an {@link Option} containing the first matching result, or {@link Option.None} if none match
+     * @throws NullPointerException if {@code futures} or {@code predicate} is null
      */
     static <T> Future<Option<T>> find(Iterable<? extends Future<? extends T>> futures, Predicate<? super T> predicate) {
         return find(DEFAULT_EXECUTOR, futures, predicate);
     }
 
     /**
-     * Returns a {@code Future} that eventually succeeds with the first result of the given {@code Future}s which
-     * matches the given {@code predicate}. If no result matches, the {@code Future} will contain {@link Option.None}.
-     * <p>
-     * The returned {@code Future} is backed by the given {@link Executor}.
+     * Returns a {@code Future} that completes with the first result of the given {@code futures}
+     * that satisfies the specified {@code predicate}. If no result matches, the {@code Future} will contain {@link Option.None}.
+     *
+     * <p>The returned {@code Future} executes using the provided {@link Executor}.</p>
      *
-     * @param executor  An {@link Executor}.
-     * @param futures   An iterable of futures.
-     * @param predicate A predicate that tests successful future results.
-     * @param <T>       Result type of the futures.
-     * @return A Future of an {@link Option} of the first result of the given {@code futures} that satisfies the given {@code predicate}.
-     * @throws NullPointerException if one of the arguments is null
+     * @param executor  the {@link Executor} to run asynchronous handlers
+     * @param futures   an iterable of futures to inspect
+     * @param predicate a predicate to test successful future results
+     * @param <T>       the type of the future results
+     * @return a {@code Future} of an {@link Option} containing the first matching result, or {@link Option.None} if none match
+     * @throws NullPointerException if any argument is null
      */
     static <T> Future<Option<T>> find(Executor executor, Iterable<? extends Future<? extends T>> futures, Predicate<? super T> predicate) {
         Objects.requireNonNull(executor, "executor is null");
@@ -202,27 +205,27 @@ static <T> Future<Option<T>> find(Executor executor, Iterable<? extends Future<?
     }
 
     /**
-     * Returns a new {@code Future} that will contain the result of the first of the given futures that is completed,
-     * backed by the {@link #DEFAULT_EXECUTOR}.
+     * Returns a new {@code Future} that completes with the result of the first future in the given iterable
+     * that completes, using the {@link #DEFAULT_EXECUTOR}.
      *
-     * @param futures An iterable of futures.
-     * @param <T>     The result type.
-     * @return A new {@code Future}.
-     * @throws NullPointerException if futures is null
+     * @param futures an iterable of futures to observe
+     * @param <T>     the type of the future results
+     * @return a new {@code Future} containing the result of the first completed future
+     * @throws NullPointerException if {@code futures} is null
      */
     static <T> Future<T> firstCompletedOf(Iterable<? extends Future<? extends T>> futures) {
         return firstCompletedOf(DEFAULT_EXECUTOR, futures);
     }
 
     /**
-     * Returns a new {@code Future} that will contain the result of the first of the given futures that is completed,
-     * backed by the given {@link Executor}.
+     * Returns a new {@code Future} that completes with the result of the first future in the given iterable
+     * that completes, using the specified {@link Executor}.
      *
-     * @param executor An {@link Executor}.
-     * @param futures  An iterable of futures.
-     * @param <T>      The result type.
-     * @return A new {@code Future}.
-     * @throws NullPointerException if executor or futures is null
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param futures  an iterable of futures to observe
+     * @param <T>      the type of the future results
+     * @return a new {@code Future} containing the result of the first completed future
+     * @throws NullPointerException if {@code executor} or {@code futures} is null
      */
     static <T> Future<T> firstCompletedOf(Executor executor, Iterable<? extends Future<? extends T>> futures) {
         Objects.requireNonNull(executor, "executor is null");
@@ -231,37 +234,37 @@ static <T> Future<T> firstCompletedOf(Executor executor, Iterable<? extends Futu
     }
 
     /**
-     * Returns a Future which contains the result of the fold of the given future values. If any future or the fold
-     * fail, the result is a failure.
-     * <p>
-     * The resulting {@code Future} is backed by the {@link #DEFAULT_EXECUTOR}.
+     * Returns a {@code Future} that contains the result of folding the given future values.
+     * If any future fails or the fold operation throws an exception, the resulting {@code Future} will also fail.
+     *
+     * <p>The resulting {@code Future} executes using the {@link #DEFAULT_EXECUTOR}.</p>
      *
-     * @param futures An iterable of futures.
-     * @param zero    The zero element of the fold.
-     * @param f       The fold operation.
-     * @param <T>     The result type of the given {@code Futures}.
-     * @param <U>     The fold result type.
-     * @return A new {@code Future} that will contain the fold result.
-     * @throws NullPointerException if futures or f is null.
+     * @param futures an iterable of futures to fold
+     * @param zero    the initial value for the fold
+     * @param f       the fold operation
+     * @param <T>     the type of the values in the given futures
+     * @param <U>     the result type of the fold
+     * @return a new {@code Future} containing the fold result
+     * @throws NullPointerException if {@code futures} or {@code f} is null
      */
     static <T, U> Future<U> fold(Iterable<? extends Future<? extends T>> futures, U zero, BiFunction<? super U, ? super T, ? extends U> f) {
         return fold(DEFAULT_EXECUTOR, futures, zero, f);
     }
 
     /**
-     * Returns a Future which contains the result of the fold of the given future values. If any future or the fold
-     * fail, the result is a failure.
-     * <p>
-     * The resulting {@code Future} is backed by the given {@link Executor}.
+     * Returns a {@code Future} containing the result of folding the given future values.
+     * If any future fails or the fold operation throws an exception, the resulting {@code Future} will also fail.
+     *
+     * <p>The resulting {@code Future} executes using the specified {@link Executor}.</p>
      *
-     * @param executor An {@link Executor}.
-     * @param futures  An iterable of futures.
-     * @param zero     The zero element of the fold.
-     * @param f        The fold operation.
-     * @param <T>      The result type of the given {@code Futures}.
-     * @param <U>      The fold result type.
-     * @return A new {@code Future} that will contain the fold result.
-     * @throws NullPointerException if executor, futures or f is null.
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param futures  an iterable of futures to fold
+     * @param zero     the initial value for the fold
+     * @param f        the fold operation
+     * @param <T>      the type of the values in the given futures
+     * @param <U>      the result type of the fold
+     * @return a new {@code Future} containing the fold result
+     * @throws NullPointerException if {@code executor}, {@code futures}, or {@code f} is null
      */
     static <T, U> Future<U> fold(Executor executor, Iterable<? extends Future<? extends T>> futures, U zero, BiFunction<? super U, ? super T, ? extends U> f) {
         Objects.requireNonNull(executor, "executor is null");
@@ -275,12 +278,13 @@ static <T, U> Future<U> fold(Executor executor, Iterable<? extends Future<? exte
     }
 
     /**
-     * Creates a {@code Future} with the given java.util.concurrent.Future, backed by the {@link #DEFAULT_EXECUTOR}
+     * Creates a {@code Future} that wraps the given {@link java.util.concurrent.Future},
+     * executing callbacks on the {@link #DEFAULT_EXECUTOR}.
      *
-     * @param future A {@link java.util.concurrent.Future}
-     * @param <T>    Result type of the Future
-     * @return A new {@code Future} wrapping the result of the Java future
-     * @throws NullPointerException if future is null
+     * @param future the {@link java.util.concurrent.Future} to wrap
+     * @param <T>    the result type of the future
+     * @return a new {@code Future} containing the result of the given Java future
+     * @throws NullPointerException if {@code future} is null
      */
     static <T> Future<T> fromJavaFuture(java.util.concurrent.Future<T> future) {
         Objects.requireNonNull(future, "future is null");
@@ -288,13 +292,14 @@ static <T> Future<T> fromJavaFuture(java.util.concurrent.Future<T> future) {
     }
 
     /**
-     * Creates a {@code Future} with the given java.util.concurrent.Future, backed by given {@link Executor}
+     * Creates a {@code Future} that wraps the given {@link java.util.concurrent.Future},
+     * executing callbacks using the specified {@link Executor}.
      *
-     * @param executor An {@link Executor}.
-     * @param future   A {@link java.util.concurrent.Future}.
-     * @param <T>      Result type of the Future
-     * @return A new {@code Future} wrapping the result of the Java future
-     * @throws NullPointerException if executor or future is null
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param future   the {@link java.util.concurrent.Future} to wrap
+     * @param <T>      the result type of the future
+     * @return a new {@code Future} containing the result of the given Java future
+     * @throws NullPointerException if {@code executor} or {@code future} is null
      */
     static <T> Future<T> fromJavaFuture(Executor executor, java.util.concurrent.Future<T> future) {
         Objects.requireNonNull(executor, "executor is null");
@@ -303,12 +308,13 @@ static <T> Future<T> fromJavaFuture(Executor executor, java.util.concurrent.Futu
     }
 
     /**
-     * Creates a {@code Future} with the given {@link java.util.concurrent.CompletableFuture}, backed by the {@link #DEFAULT_EXECUTOR}
+     * Creates a {@code Future} that wraps the given {@link java.util.concurrent.CompletableFuture},
+     * using the {@link #DEFAULT_EXECUTOR} for executing callbacks.
      *
-     * @param future A {@link java.util.concurrent.CompletableFuture}
-     * @param <T>    Result type of the Future
-     * @return A new {@code Future} wrapping the result of the {@link java.util.concurrent.CompletableFuture}
-     * @throws NullPointerException if future is null
+     * @param future the {@link java.util.concurrent.CompletableFuture} to wrap
+     * @param <T>    the result type of the future
+     * @return a new {@code Future} containing the result of the given {@link java.util.concurrent.CompletableFuture}
+     * @throws NullPointerException if {@code future} is null
      */
     @GwtIncompatible
     static <T> Future<T> fromCompletableFuture(CompletableFuture<T> future) {
@@ -316,13 +322,14 @@ static <T> Future<T> fromCompletableFuture(CompletableFuture<T> future) {
     }
 
     /**
-     * Creates a {@code Future} with the given {@link java.util.concurrent.CompletableFuture}, backed by given {@link Executor}
+     * Creates a {@code Future} that wraps the given {@link java.util.concurrent.CompletableFuture},
+     * executing callbacks using the specified {@link Executor}.
      *
-     * @param executor An {@link Executor}.
-     * @param future   A {@link java.util.concurrent.CompletableFuture}.
-     * @param <T>      Result type of the Future
-     * @return A new {@code Future} wrapping the result of the {@link java.util.concurrent.CompletableFuture}
-     * @throws NullPointerException if executor or future is null
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param future   the {@link java.util.concurrent.CompletableFuture} to wrap
+     * @param <T>      the result type of the future
+     * @return a new {@code Future} containing the result of the given {@link java.util.concurrent.CompletableFuture}
+     * @throws NullPointerException if {@code executor} or {@code future} is null
      */
     @GwtIncompatible
     static <T> Future<T> fromCompletableFuture(Executor executor, CompletableFuture<T> future) {
@@ -338,25 +345,25 @@ static <T> Future<T> fromCompletableFuture(Executor executor, CompletableFuture<
     }
 
     /**
-     * Creates a {@code Future} from a {@link Try}, backed by the {@link #DEFAULT_EXECUTOR}.
+     * Creates a {@code Future} from a {@link Try}, using the {@link #DEFAULT_EXECUTOR}.
      *
-     * @param result The result.
-     * @param <T>    The value type of a successful result.
-     * @return A completed {@code Future} which contains either a {@code Success} or a {@code Failure}.
-     * @throws NullPointerException if result is null
+     * @param result the {@link Try} result to wrap
+     * @param <T>    the type of a successful result
+     * @return a completed {@code Future} containing either a {@code Success} or a {@code Failure}
+     * @throws NullPointerException if {@code result} is null
      */
     static <T> Future<T> fromTry(Try<? extends T> result) {
         return fromTry(DEFAULT_EXECUTOR, result);
     }
 
     /**
-     * Creates a {@code Future} from a {@link Try}, backed by the given {@link Executor}.
+     * Creates a {@code Future} from a {@link Try}, executing callbacks using the specified {@link Executor}.
      *
-     * @param executor An {@link Executor}.
-     * @param result   The result.
-     * @param <T>      The value type of a successful result.
-     * @return A completed {@code Future} which contains either a {@code Success} or a {@code Failure}.
-     * @throws NullPointerException if executor or result is null
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param result   the {@link Try} result to wrap
+     * @param <T>      the type of successful result
+     * @return a completed {@code Future} containing either a {@code Success} or a {@code Failure}
+     * @throws NullPointerException if {@code executor} or {@code result} is null
      */
     static <T> Future<T> fromTry(Executor executor, Try<? extends T> result) {
         Objects.requireNonNull(executor, "executor is null");
@@ -365,13 +372,12 @@ static <T> Future<T> fromTry(Executor executor, Try<? extends T> result) {
     }
 
     /**
-     * Narrows a widened {@code Future<? extends T>} to {@code Future<T>}
-     * by performing a type-safe cast. This is eligible because immutable/read-only
-     * collections are covariant.
+     * Narrows a {@code Future<? extends T>} to {@code Future<T>} via a type-safe cast.
+     * This is safe because immutable or read-only collections are covariant.
      *
-     * @param future A {@code Future}.
-     * @param <T>    Component type of the {@code Future}.
-     * @return the given {@code future} instance as narrowed type {@code Future<T>}.
+     * @param future the {@code Future} to narrow
+     * @param <T>    the type of the value contained in the future
+     * @return the given {@code future} instance as a {@code Future<T>}
      */
     @SuppressWarnings("unchecked")
     static <T> Future<T> narrow(Future<? extends T> future) {
@@ -379,13 +385,13 @@ static <T> Future<T> narrow(Future<? extends T> future) {
     }
 
     /**
-     * Starts an asynchronous computation, backed by the {@link #DEFAULT_EXECUTOR}.
+     * Starts an asynchronous computation using the {@link #DEFAULT_EXECUTOR}.
      *
-     * @param computation A computation.
-     * @param <T>      Type of the computation result.
-     * @return A new Future instance
-     * @throws NullPointerException if computation is null.
-     * @deprecated Will be removed. Use {@code Future.of(supplier::get)} instead of {@code Future.ofSupplier(supplier)}.
+     * @param computation the computation to execute asynchronously
+     * @param <T>         the type of the computation result
+     * @return a new {@code Future} containing the result of the computation
+     * @throws NullPointerException if {@code computation} is null
+     * @deprecated This method will be removed. Use {@code Future.of(supplier::get)} instead of {@code Future.ofSupplier(supplier)}.
      */
     @Deprecated
     static <T> Future<T> ofSupplier(Supplier<? extends T> computation) {
@@ -473,25 +479,25 @@ static Future<Void> runRunnable(Executor executor, Runnable computation) {
     }
 
     /**
-     * Starts an asynchronous computation, backed by the {@link #DEFAULT_EXECUTOR}.
+     * Starts an asynchronous computation using the {@link #DEFAULT_EXECUTOR}.
      *
-     * @param computation A computation.
-     * @param <T>         Type of the computation result.
-     * @return A new Future instance.
-     * @throws NullPointerException if computation is null.
+     * @param computation the computation to execute asynchronously
+     * @param <T>         the type of the computation result
+     * @return a new {@code Future} containing the result of the computation
+     * @throws NullPointerException if {@code computation} is null
      */
     static <T> Future<T> of(CheckedFunction0<? extends T> computation) {
         return of(DEFAULT_EXECUTOR, computation);
     }
 
     /**
-     * Starts an asynchronous computation, backed by the given {@link Executor}.
+     * Starts an asynchronous computation using the specified {@link Executor}.
      *
-     * @param executor    An {@link Executor}.
-     * @param computation A computation.
-     * @param <T>         Type of the computation result.
-     * @return A new Future instance.
-     * @throws NullPointerException if one of executor or computation is null.
+     * @param executor    the {@link Executor} to run asynchronous handlers
+     * @param computation the computation to execute asynchronously
+     * @param <T>         the type of the computation result
+     * @return a new {@code Future} containing the result of the computation
+     * @throws NullPointerException if {@code executor} or {@code computation} is null
      */
     static <T> Future<T> of(Executor executor, CheckedFunction0<? extends T> computation) {
         Objects.requireNonNull(executor, "executor is null");
@@ -577,33 +583,35 @@ static <T> Future<T> run(Executor executor, Task<? extends T> task) {
     }
 
     /**
-     * Returns a Future which contains the reduce result of the given future values. The zero is the result of the
-     * first future that completes. If any future or the reduce operation fail, the result is a failure.
-     * <p>
-     * The resulting {@code Future} is backed by the {@link #DEFAULT_EXECUTOR}.
+     * Returns a {@code Future} containing the result of reducing the given future values.
+     * The first completed future serves as the initial (zero) value.
+     * If any future or the reduce operation fails, the resulting {@code Future} will also fail.
      *
-     * @param futures An iterable of futures.
-     * @param f       The reduce operation.
-     * @param <T>     The result type of the given {@code Futures}.
-     * @return A new {@code Future} that will contain the reduce result.
-     * @throws NullPointerException if executor, futures or f is null.
+     * <p>The resulting {@code Future} executes using the {@link #DEFAULT_EXECUTOR}.</p>
+     *
+     * @param futures an iterable of futures to reduce
+     * @param f       the reduce operation
+     * @param <T>     the type of the values in the given futures
+     * @return a new {@code Future} containing the reduce result
+     * @throws NullPointerException if {@code futures} or {@code f} is null
      */
     static <T> Future<T> reduce(Iterable<? extends Future<? extends T>> futures, BiFunction<? super T, ? super T, ? extends T> f) {
         return reduce(DEFAULT_EXECUTOR, futures, f);
     }
 
     /**
-     * Returns a Future which contains the reduce result of the given future values. The zero is the result of the
-     * first future that completes. If any future or the reduce operation fail, the result is a failure.
-     * <p>
-     * The resulting {@code Future} is backed by the given {@link Executor}.
+     * Returns a {@code Future} containing the result of reducing the given future values.
+     * The first completed future serves as the initial (zero) value.
+     * If any future or the reduce operation fails, the resulting {@code Future} will also fail.
      *
-     * @param executor An {@link Executor}.
-     * @param futures  An iterable of futures.
-     * @param f        The reduce operation.
-     * @param <T>      The result type of the given {@code Futures}.
-     * @return A new {@code Future} that will contain the reduce result.
-     * @throws NullPointerException if executor, futures or f is null.
+     * <p>The resulting {@code Future} executes using the specified {@link Executor}.</p>
+     *
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param futures  an iterable of futures to reduce
+     * @param f        the reduce operation
+     * @param <T>      the type of the values in the given futures
+     * @return a new {@code Future} containing the reduce result
+     * @throws NullPointerException if {@code executor}, {@code futures}, or {@code f} is null
      */
     static <T> Future<T> reduce(Executor executor, Iterable<? extends Future<? extends T>> futures, BiFunction<? super T, ? super T, ? extends T> f) {
         Objects.requireNonNull(executor, "executor is null");
@@ -617,24 +625,25 @@ static <T> Future<T> reduce(Executor executor, Iterable<? extends Future<? exten
     }
 
     /**
-     * Runs an asynchronous computation, backed by the {@link #DEFAULT_EXECUTOR}.
+     * Runs an asynchronous computation using the {@link #DEFAULT_EXECUTOR}.
      *
-     * @param unit A unit of work.
-     * @return A new Future instance which results in nothing.
-     * @throws NullPointerException if unit is null.
+     * @param unit a unit of work to execute asynchronously
+     * @return a new {@code Future} representing the completion of the computation, with no result
+     * @throws NullPointerException if {@code unit} is null
      */
     static Future<Void> run(CheckedRunnable unit) {
         return run(DEFAULT_EXECUTOR, unit);
     }
 
     /**
-     * Starts an asynchronous computation, backed by the given {@link Executor}.
+     * Starts an asynchronous computation using the specified {@link Executor}.
      *
-     * @param executor An {@link Executor}.
-     * @param unit     A unit of work.
-     * @return A new Future instance which results in nothing.
-     * @throws NullPointerException if one of executor or unit is null.
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param unit     a unit of work to execute asynchronously
+     * @return a new {@code Future} representing the completion of the computation, with no result
+     * @throws NullPointerException if {@code executor} or {@code unit} is null
      */
+
     static Future<Void> run(Executor executor, CheckedRunnable unit) {
         Objects.requireNonNull(executor, "executor is null");
         Objects.requireNonNull(unit, "unit is null");
@@ -645,54 +654,58 @@ static Future<Void> run(Executor executor, CheckedRunnable unit) {
     }
 
     /**
-     * Reduces many {@code Future}s into a single {@code Future} by transforming an
+     * Reduces multiple {@code Future} instances into a single {@code Future} by transforming an
      * {@code Iterable<Future<? extends T>>} into a {@code Future<Seq<T>>}.
-     * <p>
-     * The resulting {@code Future} is backed by the {@link #DEFAULT_EXECUTOR}.
+     *
+     * <p>The resulting {@code Future} executes using the {@link #DEFAULT_EXECUTOR}.</p>
      *
      * <ul>
-     * <li>
-     * If all of the given Futures succeed, sequence() succeeds too:
-     * <pre><code>// = Future(Success(Seq(1, 2)))
+     *     <li>
+     *         If all given futures succeed, the resulting future also succeeds:
+     *         <pre><code>
+     * // = Future(Success(Seq(1, 2)))
      * sequence(
      *     List.of(
-     *         Future.of(() -&gt; 1),
-     *         Future.of(() -&gt; 2)
+     *         Future.of(() -> 1),
+     *         Future.of(() -> 2)
      *     )
-     * );</code></pre>
-     * </li>
-     * <li>
-     * If a given Future fails, sequence() fails too:
-     * <pre><code>// = Future(Failure(Error)))
+     * );
+     *         </code></pre>
+     *     </li>
+     *     <li>
+     *         If any given future fails, the resulting future fails as well:
+     *         <pre><code>
+     * // = Future(Failure(Error))
      * sequence(
      *     List.of(
-     *         Future.of(() -&gt; 1),
-     *         Future.of(() -&gt; { throw new Error(); }
+     *         Future.of(() -> 1),
+     *         Future.of(() -> { throw new Error(); })
      *     )
-     * );</code></pre>
-     * </li>
+     * );
+     *         </code></pre>
+     *     </li>
      * </ul>
      *
-     * @param futures An {@code Iterable} of {@code Future}s.
-     * @param <T>     Result type of the futures.
-     * @return A {@code Future} of a {@link Seq} of results.
-     * @throws NullPointerException if futures is null.
+     * @param futures an {@code Iterable} of {@code Future}s
+     * @param <T>     the result type of the futures
+     * @return a {@code Future} containing a {@link Seq} of results
+     * @throws NullPointerException if {@code futures} is null
      */
     static <T> Future<Seq<T>> sequence(Iterable<? extends Future<? extends T>> futures) {
         return sequence(DEFAULT_EXECUTOR, futures);
     }
 
     /**
-     * Reduces many {@code Future}s into a single {@code Future} by transforming an
+     * Reduces multiple {@code Future} instances into a single {@code Future} by transforming an
      * {@code Iterable<Future<? extends T>>} into a {@code Future<Seq<T>>}.
-     * <p>
-     * The resulting {@code Future} is backed by the given {@link Executor}.
      *
-     * @param executor An {@link Executor}.
-     * @param futures  An {@code Iterable} of {@code Future}s.
-     * @param <T>      Result type of the futures.
-     * @return A {@code Future} of a {@link Seq} of results.
-     * @throws NullPointerException if executor or futures is null.
+     * <p>The resulting {@code Future} executes using the specified {@link Executor}.</p>
+     *
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param futures  an {@code Iterable} of {@code Future}s to reduce
+     * @param <T>      the result type of the futures
+     * @return a {@code Future} containing a {@link Seq} of results
+     * @throws NullPointerException if {@code executor} or {@code futures} is null
      */
     static <T> Future<Seq<T>> sequence(Executor executor, Iterable<? extends Future<? extends T>> futures) {
         Objects.requireNonNull(executor, "executor is null");
@@ -704,24 +717,25 @@ static <T> Future<Seq<T>> sequence(Executor executor, Iterable<? extends Future<
     }
 
     /**
-     * Creates a succeeded {@code Future}, backed by the {@link #DEFAULT_EXECUTOR}.
+     * Creates a succeeded {@code Future} with the given result, using the {@link #DEFAULT_EXECUTOR}
+     * to execute callbacks.
      *
-     * @param result The result.
-     * @param <T>    The value type of a successful result.
-     * @return A succeeded {@code Future}.
+     * @param result the successful result
+     * @param <T>    the type of the result
+     * @return a succeeded {@code Future} containing the given result
      */
     static <T> Future<T> successful(T result) {
         return successful(DEFAULT_EXECUTOR, result);
     }
 
     /**
-     * Creates a succeeded {@code Future}, backed by the given {@link Executor}.
+     * Creates a succeeded {@code Future} with the given result, executing callbacks using the specified {@link Executor}.
      *
-     * @param executor An {@link Executor}.
-     * @param result   The result.
-     * @param <T>      The value type of a successful result.
-     * @return A succeeded {@code Future}.
-     * @throws NullPointerException if executor is null
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param result   the successful result
+     * @param <T>      the type of the result
+     * @return a succeeded {@code Future} containing the given result
+     * @throws NullPointerException if {@code executor} is null
      */
     static <T> Future<T> successful(Executor executor, T result) {
         Objects.requireNonNull(executor, "executor is null");
@@ -738,35 +752,35 @@ default CompletableFuture<T> toCompletableFuture() {
     }
 
     /**
-     * Maps the values of an iterable in parallel to a sequence of mapped values into a single {@code Future} by
-     * transforming an {@code Iterable<? extends T>} into a {@code Future<Seq<U>>}.
-     * <p>
-     * The resulting {@code Future} is backed by the {@link #DEFAULT_EXECUTOR}.
+     * Maps the values of an iterable in parallel to a sequence of mapped values, producing a single {@code Future}
+     * by transforming an {@code Iterable<? extends T>} into a {@code Future<Seq<U>>}.
+     *
+     * <p>The resulting {@code Future} executes using the {@link #DEFAULT_EXECUTOR}.</p>
      *
-     * @param values An {@code Iterable} of {@code Future}s.
-     * @param mapper A mapper of values to Futures
-     * @param <T>    The type of the given values.
-     * @param <U>    The mapped value type.
-     * @return A {@code Future} of a {@link Seq} of results.
-     * @throws NullPointerException if values or f is null.
+     * @param values an {@code Iterable} of input values
+     * @param mapper a function mapping values to {@code Future}s
+     * @param <T>    the type of the input values
+     * @param <U>    the type of the mapped values
+     * @return a {@code Future} containing a {@link Seq} of mapped results
+     * @throws NullPointerException if {@code values} or {@code mapper} is null
      */
     static <T, U> Future<Seq<U>> traverse(Iterable<? extends T> values, Function<? super T, ? extends Future<? extends U>> mapper) {
         return traverse(DEFAULT_EXECUTOR, values, mapper);
     }
 
     /**
-     * Maps the values of an iterable in parallel to a sequence of mapped values into a single {@code Future} by
-     * transforming an {@code Iterable<? extends T>} into a {@code Future<Seq<U>>}.
-     * <p>
-     * The resulting {@code Future} is backed by the given {@link Executor}.
+     * Maps the values of an iterable in parallel to a sequence of mapped values, producing a single {@code Future}
+     * by transforming an {@code Iterable<? extends T>} into a {@code Future<Seq<U>>}.
+     *
+     * <p>The resulting {@code Future} executes using the specified {@link Executor}.</p>
      *
-     * @param executor An {@link Executor}.
-     * @param values   An {@code Iterable} of values.
-     * @param mapper   A mapper of values to Futures
-     * @param <T>      The type of the given values.
-     * @param <U>      The mapped value type.
-     * @return A {@code Future} of a {@link Seq} of results.
-     * @throws NullPointerException if executor, values or f is null.
+     * @param executor the {@link Executor} to run asynchronous handlers
+     * @param values   an {@code Iterable} of input values
+     * @param mapper   a function mapping values to {@code Future}s
+     * @param <T>      the type of the input values
+     * @param <U>      the type of the mapped values
+     * @return a {@code Future} containing a {@link Seq} of mapped results
+     * @throws NullPointerException if {@code executor}, {@code values}, or {@code mapper} is null
      */
     static <T, U> Future<Seq<U>> traverse(Executor executor, Iterable<? extends T> values, Function<? super T, ? extends Future<? extends U>> mapper) {
         Objects.requireNonNull(executor, "executor is null");
@@ -778,22 +792,22 @@ static <T, U> Future<Seq<U>> traverse(Executor executor, Iterable<? extends T> v
     // -- non-static Future API
 
     /**
-     * Support for chaining of callbacks that are guaranteed to be executed in a specific order.
-     * <p>
-     * An exception, which occurs when performing the given {@code action}, is not propagated to the outside.
-     * In other words, subsequent actions are performed based on the value of the original Future.
-     * <p>
-     * Example:
+     * Supports chaining of callbacks that are guaranteed to be executed in order.
+     *
+     * <p>Exceptions thrown by the given {@code action} are not propagated. Subsequent actions
+     * are executed based on the value of the original {@code Future}.</p>
+     *
+     * <p>Example:</p>
      * <pre><code>
      * // prints Success(1)
-     * Future.of(() -&gt; 1)
-     *       .andThen(t -&gt; { throw new Error(""); })
+     * Future.of(() -> 1)
+     *       .andThen(t -> { throw new Error(""); })
      *       .andThen(System.out::println);
      * </code></pre>
      *
-     * @param action A side-effecting action.
-     * @return A new Future that contains this result and which is completed after the given action was performed.
-     * @throws NullPointerException if action is null
+     * @param action a side-effecting action to perform after the future completes
+     * @return a new {@code Future} containing the original result, completed after the action executes
+     * @throws NullPointerException if {@code action} is null
      */
     default Future<T> andThen(Consumer<? super Try<T>> action) {
         Objects.requireNonNull(action, "action is null");
@@ -806,22 +820,23 @@ default Future<T> andThen(Consumer<? super Try<T>> action) {
     }
 
     /**
-     * Blocks the current Thread until this Future completed or returns immediately if this Future is already completed.
-     * <p>
-     * In the case the current thread was interrupted while waiting, a failed {@code Future} is returned containing
-     * the corresponding {@link InterruptedException}.
+     * Blocks the current thread until this {@code Future} is completed, or returns immediately if it is already completed.
+     *
+     * <p>If the current thread is interrupted while waiting, a failed {@code Future} is returned containing
+     * the corresponding {@link InterruptedException}.</p>
      *
      * @return this {@code Future} instance
      */
     Future<T> await();
 
     /**
-     * Blocks the current Thread until this Future completed or returns immediately if this Future is already completed.
-     * <p>
-     * In the case the current thread was interrupted while waiting, a failed {@code Future} is returned containing
-     * the corresponding {@link InterruptedException}.
-     * <p>
-     * If the deadline wasn't met, a failed {@code Future} is returned containing a {@link TimeoutException}.
+     * Blocks the current thread until this {@code Future} is completed, or returns immediately if it is already completed.
+     *
+     * <p>If the current thread is interrupted while waiting, a failed {@code Future} is returned containing
+     * the corresponding {@link InterruptedException}.</p>
+     *
+     * <p>If the specified timeout is reached before completion, a failed {@code Future} is returned containing
+     * a {@link TimeoutException}.</p>
      *
      * @param timeout the maximum time to wait
      * @param unit    the time unit of the timeout argument
@@ -832,12 +847,12 @@ default Future<T> andThen(Consumer<? super Try<T>> action) {
     Future<T> await(long timeout, TimeUnit unit);
 
     /**
-     * Cancels the Future. A running thread is interrupted.
-     * <p>
-     * If the Future was successfully cancelled, the result is a {@code Failure(CancellationException)}.
+     * Cancels this {@code Future}. If it is running, the executing thread is interrupted.
+     *
+     * <p>If the future is successfully cancelled, its result becomes a {@code Failure(CancellationException)}.</p>
      *
-     * @return {@code false}, if this {@code Future} is already completed or could not be cancelled, otherwise {@code true}.
-     * @throws SecurityException if the current thread cannot modify the Future's thread
+     * @return {@code false} if this {@code Future} is already completed or could not be cancelled, {@code true} otherwise
+     * @throws SecurityException if the current thread is not permitted to modify the Future's thread
      * @see Future#isCancelled()
      */
     default boolean cancel() {
@@ -845,35 +860,32 @@ default boolean cancel() {
     }
 
     /**
-     * Cancels the Future. A pending Future may be interrupted, depending on the underlying {@code Executor}.
-     * <p>
-     * If the Future was successfully cancelled, the result is a {@code Failure(CancellationException)}.
+     * Cancels this {@code Future}. A pending future may be interrupted depending on the underlying {@code Executor}.
+     *
+     * <p>If the future is successfully cancelled, its result becomes a {@code Failure(CancellationException)}.</p>
      *
-     * @param mayInterruptIfRunning {@code true} if a running thread should be interrupted, otherwise a running thread
-     *                              is allowed to complete its computation.
-     * @return {@code false}, if this {@code Future} is already completed or could not be cancelled, otherwise {@code true}.
-     * @throws SecurityException if the current thread cannot modify the Future's thread
+     * @param mayInterruptIfRunning {@code true} if a running thread should be interrupted; {@code false} allows it to complete
+     * @return {@code false} if this {@code Future} is already completed or could not be cancelled, {@code true} otherwise
+     * @throws SecurityException if the current thread is not permitted to modify the Future's thread
      * @see Future#isCancelled()
      * @see java.util.concurrent.Future#cancel(boolean)
      */
     boolean cancel(boolean mayInterruptIfRunning);
 
     /**
-     * Collects value that is in the domain of the given {@code partialFunction} by mapping the value to type {@code R}.
-     *
-     * <pre>{@code
-     * partialFunction.isDefinedAt(value)
-     * }</pre>
-     *
-     * If the element makes it through that filter, the mapped instance is wrapped in {@code Future}
+     * Applies a {@code partialFunction} to the value of this {@code Future}, collecting results only for values
+     * where the function is defined. The mapped result is wrapped in a new {@code Future}.
      *
+     * <p>Example:</p>
      * <pre>{@code
-     * R newValue = partialFunction.apply(value)
+     * if (partialFunction.isDefinedAt(value)) {
+     *     R newValue = partialFunction.apply(value);
+     * }
      * }</pre>
      *
-     * @param partialFunction A function that is not necessarily defined on value of this future.
-     * @param <R>             The new value type
-     * @return A new {@code Future} instance containing value of type {@code R}
+     * @param partialFunction a function that may not be defined for every value of this future
+     * @param <R>             the type of the mapped result
+     * @return a new {@code Future} containing the mapped value
      * @throws NullPointerException if {@code partialFunction} is null
      */
     default <R> Future<R> collect(PartialFunction<? super T, ? extends R> partialFunction) {
@@ -884,9 +896,9 @@ default <R> Future<R> collect(PartialFunction<? super T, ? extends R> partialFun
     }
 
     /**
-     * Returns the {@link Executor} used by this {@code Future}.
+     * Returns the {@link Executor} that executes asynchronous handlers for this {@code Future}.
      *
-     * @return The underlying {@code Executor}.
+     * @return the underlying {@code Executor}
      */
     default Executor executor() {
         return executorService();
@@ -906,13 +918,12 @@ default Executor executor() {
     ExecutorService executorService() throws UnsupportedOperationException;
 
     /**
-     * A projection that inverses the result of this Future.
-     * <p>
-     * If this Future succeeds, the failed projection returns a failure containing a {@code NoSuchElementException}.
-     * <p>
-     * If this Future fails, the failed projection returns a success containing the exception.
+     * Returns a projection that inverts the result of this {@code Future}.
+     *
+     * <p>If this {@code Future} succeeds, the resulting failed projection contains a {@code NoSuchElementException}.</p>
+     * <p>If this {@code Future} fails, the resulting failed projection succeeds with the exception as its value.</p>
      *
-     * @return A new Future which contains an exception at a point of time.
+     * @return a new {@code Future} representing the inverted result
      */
     default Future<Throwable> failed() {
         return run(executor(), complete ->
@@ -927,23 +938,23 @@ default Future<Throwable> failed() {
     }
 
     /**
-     * Returns a Future that returns the result of this Future, if it is a success. If the value of this Future is a
-     * failure, the result of {@code that} Future is returned, if that is a success. If both Futures fail, the failure
-     * of this Future is returned.
-     * <p>
-     * Example:
+     * Returns a {@code Future} that yields the result of this {@code Future} if it succeeds.
+     * If this {@code Future} fails, the result of the given {@code that} {@code Future} is returned if it succeeds.
+     * If both {@code Future}s fail, the failure of this {@code Future} is returned.
+     *
+     * <p>Example:</p>
      * <pre><code>
-     * Future&lt;Integer&gt; future = Future.of(() -&gt; { throw new Error(); });
-     * Future&lt;Integer&gt; that = Future.of(() -&gt; 1);
+     * Future&lt;Integer&gt; future = Future.of(() -> { throw new Error(); });
+     * Future&lt;Integer&gt; that = Future.of(() -> 1);
      * Future&lt;Integer&gt; result = future.fallbackTo(that);
      *
-     * // prints Some(1)
+     * // prints Success(1)
      * result.onComplete(System.out::println);
      * </code></pre>
      *
-     * @param that A fallback future computation
-     * @return A new Future
-     * @throws NullPointerException if that is null
+     * @param that a fallback {@code Future} to use if this one fails
+     * @return a new {@code Future} representing the result or fallback
+     * @throws NullPointerException if {@code that} is null
      */
     default Future<T> fallbackTo(Future<? extends T> that) {
         Objects.requireNonNull(that, "that is null");
@@ -959,10 +970,10 @@ default Future<T> fallbackTo(Future<? extends T> that) {
     }
 
     /**
-     * Shortcut for {@code filterTry(predicate::test}.
+     * Shortcut for {@code filterTry(predicate::test)}, filtering the result of this {@code Future} using the given predicate.
      *
-     * @param predicate A predicate
-     * @return A new {@code Future}
+     * @param predicate a predicate to test the value of the future
+     * @return a new {@code Future} containing the value if the predicate passes, or a failure otherwise
      * @throws NullPointerException if {@code predicate} is null
      */
     default Future<T> filter(Predicate<? super T> predicate) {
@@ -971,10 +982,11 @@ default Future<T> filter(Predicate<? super T> predicate) {
     }
 
     /**
-     * Filters the result of this {@code Future} by calling {@link Try#filterTry(CheckedPredicate)}.
+     * Filters the result of this {@code Future} using the given {@link CheckedPredicate}, delegating to
+     * {@link Try#filterTry(CheckedPredicate)}.
      *
-     * @param predicate A checked predicate
-     * @return A new {@code Future}
+     * @param predicate a checked predicate to test the value of the future
+     * @return a new {@code Future} containing the value if the predicate passes, or a failure otherwise
      * @throws NullPointerException if {@code predicate} is null
      */
     default Future<T> filterTry(CheckedPredicate<? super T> predicate) {
@@ -983,70 +995,73 @@ default Future<T> filterTry(CheckedPredicate<? super T> predicate) {
     }
 
     /**
-     * Returns the underlying exception of this Future, syntactic sugar for {@code future.getValue().map(Try::getCause)}.
+     * Returns the underlying exception. This is syntactic sugar for
+     * {@code future.getValue().map(Try::getCause)}.
      *
-     * @return None if the Future is not completed yet. Returns Some(Throwable) if the Future was completed with a failure.
-     * @throws UnsupportedOperationException if the Future was successfully completed with a value
+     * @return {@code None} if the {@code Future} is not yet completed, or {@code Some(Throwable)} if it completed with a failure
+     * @throws UnsupportedOperationException if the {@code Future} completed successfully with a value
      */
+
     default Option<Throwable> getCause() {
         return getValue().map(Try::getCause);
     }
 
     /**
-     * Returns the value of the Future.
+     * Returns the value of this {@code Future}.
      *
-     * @return {@code None}, if the Future is not yet completed or was cancelled, otherwise {@code Some(Try)}.
+     * @return {@code None} if the {@code Future} is not yet completed or was cancelled; otherwise, {@code Some(Try)} containing the result or failure
      */
     Option<Try<T>> getValue();
 
     /**
-     * Checks if this Future is cancelled, i.e. the thread was forced to stop before completion.
+     * Checks whether this {@code Future} was cancelled, i.e., its computation was interrupted before completion.
      *
-     * @return true, if the computation was cancelled, false otherwise
+     * @return {@code true} if the computation was cancelled, {@code false} otherwise
      */
     boolean isCancelled();
 
     /**
-     * Checks if this Future is completed, i.e. has a value.
+     * Checks whether this {@code Future} is completed, i.e., whether it has finished with a value, failed, or was cancelled.
      *
-     * @return true, if the computation successfully finished, failed or was cancelled, false otherwise.
+     * @return {@code true} if the computation has completed in any state, {@code false} otherwise
      */
     boolean isCompleted();
 
     /**
-     * Checks if this Future completed with a success.
+     * Checks whether this {@code Future} completed successfully.
      *
-     * @return true, if this Future completed and is a Success, false otherwise.
+     * @return {@code true} if this {@code Future} has completed with a successful result, {@code false} otherwise
      */
     default boolean isSuccess() {
         return isCompleted() && getValue().get().isSuccess();
     }
 
     /**
-     * Checks if this Future completed with a failure.
+     * Checks whether this {@code Future} completed with a failure.
      *
-     * @return true, if this Future completed and is a Failure, false otherwise.
+     * @return {@code true} if this {@code Future} has completed with a failure, {@code false} otherwise
      */
     default boolean isFailure() {
         return isCompleted() && getValue().get().isFailure();
     }
 
     /**
-     * Performs the action once the Future is complete.
+     * Performs the given action once this {@code Future} is complete.
      *
-     * @param action An action to be performed when this future is complete.
-     * @return this Future
-     * @throws NullPointerException if {@code action} is null.
+     * @param action an action to execute when the future completes
+     * @return this {@code Future}
+     * @throws NullPointerException if {@code action} is null
      */
     Future<T> onComplete(Consumer<? super Try<T>> action);
 
     /**
-     * Performs the action once the Future is complete and the result is a {@link Try.Failure}. Please note that the
-     * future is also a failure when it was cancelled.
+     * Performs the given action once this {@code Future} is complete and its result is a {@link Try.Failure}.
+     * <p>
+     * Note that a cancelled {@code Future} is also considered a failure.
      *
-     * @param action An action to be performed when this future failed.
-     * @return this Future
-     * @throws NullPointerException if {@code action} is null.
+     * @param action an action to execute when this future fails
+     * @return this {@code Future}
+     * @throws NullPointerException if {@code action} is null
      */
     default Future<T> onFailure(Consumer<? super Throwable> action) {
         Objects.requireNonNull(action, "action is null");
@@ -1054,11 +1069,11 @@ default Future<T> onFailure(Consumer<? super Throwable> action) {
     }
 
     /**
-     * Performs the action once the Future is complete and the result is a {@link Try.Success}.
+     * Performs the given action once this {@code Future} is complete and its result is a {@link Try.Success}.
      *
-     * @param action An action to be performed when this future succeeded.
-     * @return this Future
-     * @throws NullPointerException if {@code action} is null.
+     * @param action an action to execute when this future succeeds
+     * @return this {@code Future}
+     * @throws NullPointerException if {@code action} is null
      */
     default Future<T> onSuccess(Consumer<? super T> action) {
         Objects.requireNonNull(action, "action is null");
@@ -1066,16 +1081,17 @@ default Future<T> onSuccess(Consumer<? super T> action) {
     }
 
     /**
-     * Handles a failure of this Future by returning another result.
-     * <p>
-     * Example:
+     * Handles a failure of this {@code Future} by mapping the exception to a new result.
+     *
+     * <p>Example:</p>
      * <pre><code>
      * // = "oh!"
-     * Future.of(() -&gt; new Error("oh!")).recover(Throwable::getMessage);
+     * Future.of(() -> { throw new Error("oh!"); })
+     *       .recover(Throwable::getMessage);
      * </code></pre>
      *
-     * @param f A function which takes the exception of a failure and returns a new value.
-     * @return A new Future.
+     * @param f a function that maps the failure exception to a new value
+     * @return a new {@code Future} containing either the original success or the recovered value
      * @throws NullPointerException if {@code f} is null
      */
     default Future<T> recover(Function<? super Throwable, ? extends T> f) {
@@ -1084,16 +1100,17 @@ default Future<T> recover(Function<? super Throwable, ? extends T> f) {
     }
 
     /**
-     * Handles a failure of this Future by returning the result of another Future.
-     * <p>
-     * Example:
+     * Handles a failure of this {@code Future} by returning the result of another {@code Future}.
+     *
+     * <p>Example:</p>
      * <pre><code>
      * // = "oh!"
-     * Future.of(() -&gt; { throw new Error("oh!"); }).recoverWith(x -&gt; Future.of(x::getMessage));
+     * Future.of(() -> { throw new Error("oh!"); })
+     *       .recoverWith(ex -> Future.of(() -> ex.getMessage()));
      * </code></pre>
      *
-     * @param f A function which takes the exception of a failure and returns a new future.
-     * @return A new Future.
+     * @param f a function that maps the failure exception to a new {@code Future}
+     * @return a new {@code Future} containing either the original success or the result of the recovered {@code Future}
      * @throws NullPointerException if {@code f} is null
      */
     default Future<T> recoverWith(Function<? super Throwable, ? extends Future<? extends T>> f) {
@@ -1111,11 +1128,11 @@ default Future<T> recoverWith(Function<? super Throwable, ? extends Future<? ext
     }
 
     /**
-     * Transforms this {@code Future}.
+     * Transforms the result of this {@code Future} using the given function.
      *
-     * @param f   A transformation
-     * @param <U> Type of transformation result
-     * @return An instance of type {@code U}
+     * @param f   a function to transform the result
+     * @param <U> the type of the transformed result
+     * @return a new {@code Future} containing the transformed result
      * @throws NullPointerException if {@code f} is null
      */
     default <U> U transform(Function<? super Future<T>, ? extends U> f) {
@@ -1124,11 +1141,11 @@ default <U> U transform(Function<? super Future<T>, ? extends U> f) {
     }
 
     /**
-     * Transforms the value of this {@code Future}, whether it is a success or a failure.
+     * Transforms the value of this {@code Future}, regardless of whether it completed successfully or with a failure.
      *
-     * @param f   A transformation
-     * @param <U> Generic type of transformation {@code Try} result
-     * @return A {@code Future} of type {@code U}
+     * @param f   a function to transform the {@link Try} result
+     * @param <U> the type of the transformed {@code Try} result
+     * @return a new {@code Future} containing the transformed result
      * @throws NullPointerException if {@code f} is null
      */
     default <U> Future<U> transformValue(Function<? super Try<T>, ? extends Try<? extends U>> f) {
@@ -1141,14 +1158,14 @@ default <U> Future<U> transformValue(Function<? super Try<T>, ? extends Try<? ex
     }
 
     /**
-     * Returns a tuple of this and that Future result.
+     * Combines this {@code Future} with another {@code Future}, returning a {@code Future} of a tuple of both results.
      * <p>
-     * If this Future failed the result contains this failure. Otherwise the result contains that failure or
-     * a tuple of both successful Future results.
+     * If this {@code Future} fails, the resulting {@code Future} contains this failure. Otherwise, it contains
+     * the failure of {@code that} {@code Future}, or a tuple of both successful results if both succeed.
      *
-     * @param that Another Future
-     * @param <U>  Result type of {@code that}
-     * @return A new Future that returns both Future results.
+     * @param that another {@code Future} to combine with
+     * @param <U>  the result type of {@code that}
+     * @return a new {@code Future} containing either a failure or a tuple of both results
      * @throws NullPointerException if {@code that} is null
      */
     default <U> Future<Tuple2<T, U>> zip(Future<? extends U> that) {
@@ -1157,17 +1174,17 @@ default <U> Future<Tuple2<T, U>> zip(Future<? extends U> that) {
     }
 
     /**
-     * Returns a this and that Future result combined using a given combinator function.
+     * Combines this {@code Future} with another {@code Future} using the given combinator function.
      * <p>
-     * If this Future failed the result contains this failure. Otherwise the result contains that failure or
-     * a combination of both successful Future results.
-     *
-     * @param that       Another Future
-     * @param combinator The combinator function
-     * @param <U>        Result type of {@code that}
-     * @param <R>        Result type of {@code f}
-     * @return A new Future that returns both Future results.
-     * @throws NullPointerException if {@code that} is null
+     * If this {@code Future} fails, the resulting {@code Future} contains this failure. Otherwise, it contains
+     * the failure of {@code that} {@code Future}, or the result of applying the combinator function to both successful results.
+     *
+     * @param that       another {@code Future} to combine with
+     * @param combinator a function to combine the successful results of both futures
+     * @param <U>        the result type of {@code that}
+     * @param <R>        the result type of the combined value
+     * @return a new {@code Future} containing either a failure or the combined result
+     * @throws NullPointerException if {@code that} or {@code combinator} is null
      */
     @SuppressWarnings({"deprecation", "unchecked"})
     default <U, R> Future<R> zipWith(Future<? extends U> that, BiFunction<? super T, ? super U, ? extends R> combinator) {
@@ -1205,10 +1222,12 @@ default <U> Future<U> flatMapTry(CheckedFunction1<? super T, ? extends Future<?
     }
 
     /**
-     * Performs the given {@code action} asynchronously hence this Future result becomes available.
-     * The {@code action} is not performed, if the result is a failure.
+     * Performs the given {@code action} asynchronously when this {@code Future} completes successfully.
+     * <p>
+     * The {@code action} is not executed if the {@code Future} completes with a failure.
      *
-     * @param action A {@code Consumer}
+     * @param action a {@code Consumer} to be executed with the successful result
+     * @throws NullPointerException if {@code action} is null
      */
     @Override
     default void forEach(Consumer<? super T> action) {
@@ -1217,12 +1236,12 @@ default void forEach(Consumer<? super T> action) {
     }
 
     /**
-     * Gets the value if the computation result is a {@code Success} or throws if it was a {@code Failure}.
-     * Waits for the result if necessary by blocking the current thread.
-     * <p>
-     * <strong>IMPORTANT! If the computation result is a {@link Try.Failure}, the underlying {@code cause} of type {@link Throwable} is thrown.</strong>
+     * Returns the value of this {@code Future} if it completed successfully, or throws the underlying exception
+     * if it completed with a failure. Blocks the current thread if the computation is not yet finished.
+     *
+     * <p><strong>Note:</strong> If the computation failed, the underlying {@link Throwable} cause is thrown.</p>
      *
-     * @return The value of this {@code Future}.
+     * @return the successful result of this {@code Future}
      */
     @Override
     default T get() {
diff --git a/vavr/src/main/java/io/vavr/concurrent/Promise.java b/vavr/src/main/java/io/vavr/concurrent/Promise.java
index ba0e89598..91244bd45 100644
--- a/vavr/src/main/java/io/vavr/concurrent/Promise.java
+++ b/vavr/src/main/java/io/vavr/concurrent/Promise.java
@@ -27,62 +27,63 @@
 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");
@@ -90,13 +91,14 @@ static <T> Promise<T> failed(Throwable 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,23 +136,24 @@ 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");
@@ -156,13 +161,12 @@ static <T> Promise<T> make(Executor 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) {
@@ -170,24 +174,26 @@ static <T> Promise<T> narrow(Promise<? extends 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,29 +255,30 @@ 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);
@@ -279,42 +286,44 @@ default Promise<T> tryCompleteWith(Future<? extends T> other) {
     }
 
     /**
-     * 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));
diff --git a/vavr/src/main/java/io/vavr/control/Either.java b/vavr/src/main/java/io/vavr/control/Either.java
index 6c58cfb37..79ee48d31 100644
--- a/vavr/src/main/java/io/vavr/control/Either.java
+++ b/vavr/src/main/java/io/vavr/control/Either.java
@@ -70,41 +70,37 @@ public interface Either<L, R> extends Value<R>, Serializable {
     long serialVersionUID = 1L;
 
     /**
-     * Constructs a {@link Right}
+     * Constructs a new {@link Right} instance containing the given value.
      *
-     * @param right The value.
-     * @param <L>   Type of left value.
-     * @param <R>   Type of right value.
-     *
-     * @return A new {@code Right} instance.
+     * @param right the value to store in the {@code Right}
+     * @param <L>   the type of the left value
+     * @param <R>   the type of the right value
+     * @return a new {@code Right} instance
      */
     static <L, R> Either<L, R> right(R right) {
         return new Right<>(right);
     }
 
     /**
-     * Constructs a {@link Left}
-     *
-     * @param left The value.
-     * @param <L>  Type of left value.
-     * @param <R>  Type of right value.
+     * Constructs a new {@link Left} instance containing the given value.
      *
-     * @return A new {@code Left} instance.
+     * @param left the value to store in the {@code Left}
+     * @param <L>  the type of the left value
+     * @param <R>  the type of the right value
+     * @return a new {@code Left} instance
      */
     static <L, R> Either<L, R> left(L left) {
         return new Left<>(left);
     }
 
     /**
-     * Narrows a widened {@code Either<? extends L, ? extends R>} to {@code Either<L, R>}
-     * by performing a type-safe cast. This is eligible because immutable/read-only
-     * collections are covariant.
-     *
-     * @param either A {@code Either}.
-     * @param <L>    Type of left value.
-     * @param <R>    Type of right value.
+     * Narrows a {@code Either<? extends L, ? extends R>} to {@code Either<L, R>} via a type-safe cast.
+     * This is safe because immutable or read-only collections are covariant.
      *
-     * @return the given {@code either} instance as narrowed type {@code Either<L, R>}.
+     * @param either the {@code Either} to narrow
+     * @param <L>    the type of the left value
+     * @param <R>    the type of the right value
+     * @return the same {@code either} instance cast to {@code Either<L, R>}
      */
     @SuppressWarnings("unchecked")
     static <L, R> Either<L, R> narrow(Either<? extends L, ? extends R> either) {
@@ -112,19 +108,19 @@ static <L, R> Either<L, R> narrow(Either<? extends L, ? extends R> either) {
     }
 
     /**
-     * Decides which {@code Either<L, R>} to return, depending on the test value -
-     * if it's true, the result will be a {@link Either.Right},
-     * if it's false - the result will be a {@link Either.Left}
-     *
-     * @param test   A {@code boolean} value to evaluate
-     * @param right  A {@code Supplier<? extends R>} supplier of right value, called if test is true
-     * @param left   A {@code Supplier<? extends L>} supplier of left value, called if test is false
-     * @param <L>    Type of left value
-     * @param <R>    Type of right value
-     *
-     * @return {@code Either<L, R>} with right or left value, depending on the test condition evaluation
-     *
-     * @throws NullPointerException if any of the arguments is null
+     * Returns an {@code Either<L, R>} based on the given test condition.
+     * <ul>
+     *   <li>If {@code test} is {@code true}, the result is a {@link Either.Right} created from {@code right}.</li>
+     *   <li>If {@code test} is {@code false}, the result is a {@link Either.Left} created from {@code left}.</li>
+     * </ul>
+     *
+     * @param test  the boolean condition to evaluate
+     * @param right a {@code Supplier<? extends R>} providing the right value if {@code test} is true
+     * @param left  a {@code Supplier<? extends L>} providing the left value if {@code test} is false
+     * @param <L>   the type of the left value
+     * @param <R>   the type of the right value
+     * @return an {@code Either<L, R>} containing the left or right value depending on {@code test}
+     * @throws NullPointerException if any argument is null
      */
     static <L, R> Either<L, R> cond(boolean test, Supplier<? extends R> right, Supplier<? extends L> left) {
         Objects.requireNonNull(right, "right is null");
@@ -134,19 +130,19 @@ static <L, R> Either<L, R> cond(boolean test, Supplier<? extends R> right, Suppl
     }
 
     /**
-     * Decides which {@code Either<L, R>} to return, depending on the test value -
-     * if it's true, the result will be a {@link Either.Right},
-     * if it's false - the result will be a {@link Either.Left}
-     *
-     * @param test   A {@code boolean} value to evaluate
-     * @param right  A n{@code R} right value, returned if test is true
-     * @param left   A {@code L} left value, returned if test is false
-     * @param <L>    Type of left value
-     * @param <R>    Type of right value
-     *
-     * @return {@code Either<L, R>} with right or left value, depending on the test condition evaluation
-     *
-     * @throws NullPointerException if any of the arguments is null
+     * Returns an {@code Either<L, R>} based on the given test condition.
+     * <ul>
+     *   <li>If {@code test} is {@code true}, the result is a {@link Either.Right} containing {@code right}.</li>
+     *   <li>If {@code test} is {@code false}, the result is a {@link Either.Left} containing {@code left}.</li>
+     * </ul>
+     *
+     * @param test  the boolean condition to evaluate
+     * @param right the {@code R} value to return if {@code test} is true
+     * @param left  the {@code L} value to return if {@code test} is false
+     * @param <L>   the type of the left value
+     * @param <R>   the type of the right value
+     * @return an {@code Either<L, R>} containing either the left or right value depending on {@code test}
+     * @throws NullPointerException if any argument is null
      */
     static <L, R> Either<L, R> cond(boolean test, R right, L left) {
         Objects.requireNonNull(right, "right is null");
@@ -156,25 +152,24 @@ static <L, R> Either<L, R> cond(boolean test, R right, L left) {
     }
 
     /**
-     * Returns the left value.
+     * Returns the left value of this {@code Either}.
      *
-     * @return The left value.
-     *
-     * @throws NoSuchElementException if this is a {@code Right}.
+     * @return the left value
+     * @throws NoSuchElementException if this {@code Either} is a {@link Either.Right}
      */
     L getLeft();
 
     /**
-     * Returns whether this Either is a Left.
+     * Checks whether this {@code Either} is a {@link Either.Left}.
      *
-     * @return true, if this is a Left, false otherwise
+     * @return {@code true} if this is a {@code Left}, {@code false} otherwise
      */
     boolean isLeft();
 
     /**
-     * Returns whether this Either is a Right.
+     * Checks whether this {@code Either} is a {@link Either.Right}.
      *
-     * @return true, if this is a Right, false otherwise
+     * @return {@code true} if this is a {@code Right}, {@code false} otherwise
      */
     boolean isRight();
 
@@ -203,14 +198,17 @@ default RightProjection<L, R> right() {
     }
 
     /**
-     * Maps either the left or the right side of this disjunction.
-     *
-     * @param leftMapper  maps the left value if this is a Left
-     * @param rightMapper maps the right value if this is a Right
-     * @param <X>         The new left type of the resulting Either
-     * @param <Y>         The new right type of the resulting Either
-     *
-     * @return A new Either instance
+     * Transforms the value of this {@code Either} by applying one of the given mapping functions.
+     * <ul>
+     *   <li>If this is a {@link Either.Left}, {@code leftMapper} is applied to the left value.</li>
+     *   <li>If this is a {@link Either.Right}, {@code rightMapper} is applied to the right value.</li>
+     * </ul>
+     *
+     * @param leftMapper  function to transform the left value if this is a {@code Left}
+     * @param rightMapper function to transform the right value if this is a {@code Right}
+     * @param <X>         the type of the left value in the resulting {@code Either}
+     * @param <Y>         the type of the right value in the resulting {@code Either}
+     * @return a new {@code Either} instance with the transformed value
      */
     default <X, Y> Either<X, Y> bimap(Function<? super L, ? extends X> leftMapper, Function<? super R, ? extends Y> rightMapper) {
         Objects.requireNonNull(leftMapper, "leftMapper is null");
@@ -223,13 +221,16 @@ default <X, Y> Either<X, Y> bimap(Function<? super L, ? extends X> leftMapper, F
     }
 
     /**
-     * Folds either the left or the right side of this disjunction.
-     *
-     * @param leftMapper  maps the left value if this is a Left
-     * @param rightMapper maps the right value if this is a Right
-     * @param <U>         type of the folded value
-     *
-     * @return A value of type U
+     * Reduces this {@code Either} to a single value by applying one of the given functions.
+     * <ul>
+     *   <li>If this is a {@link Either.Left}, {@code leftMapper} is applied to the left value.</li>
+     *   <li>If this is a {@link Either.Right}, {@code rightMapper} is applied to the right value.</li>
+     * </ul>
+     *
+     * @param leftMapper  function to transform the left value if this is a {@code Left}
+     * @param rightMapper function to transform the right value if this is a {@code Right}
+     * @param <U>         the type of the resulting value
+     * @return a value of type {@code U} obtained by applying the appropriate function
      */
     default <U> U fold(Function<? super L, ? extends U> leftMapper, Function<? super R, ? extends U> rightMapper) {
         Objects.requireNonNull(leftMapper, "leftMapper is null");
@@ -242,14 +243,13 @@ default <U> U fold(Function<? super L, ? extends U> leftMapper, Function<? super
     }
 
     /**
-     * Reduces many {@code Either}s into a single {@code Either} by transforming an
-     * {@code Iterable<Either<L, R>>} into a {@code Either<Seq<L>, Seq<R>>}.
+     * Transforms an {@link Iterable} of {@code Either<L, R>} into a single {@code Either<Seq<L>, Seq<R>>}.
      * <p>
-     * If any of the given {@code Either}s is a {@link Either.Left} then {@code sequence} returns a
-     * {@link Either.Left} containing a non-empty {@link Seq} of all left values.
+     * If any of the given {@code Either}s is a {@link Either.Left}, the result is a {@link Either.Left}
+     * containing a non-empty {@link Seq} of all left values.
      * <p>
-     * If none of the given {@code Either}s is a {@link Either.Left} then {@code sequence} returns a
-     * {@link Either.Right} containing a (possibly empty) {@link Seq} of all right values.
+     * If all of the given {@code Either}s are {@link Either.Right}, the result is a {@link Either.Right}
+     * containing a (possibly empty) {@link Seq} of all right values.
      *
      * <pre>{@code
      * // = Right(Seq())
@@ -262,12 +262,11 @@ default <U> U fold(Function<? super L, ? extends U> leftMapper, Function<? super
      * Either.sequence(List.of(Either.right(1), Either.left("x")))
      * }</pre>
      *
-     * @param eithers An {@link Iterable} of {@code Either}s
-     * @param <L>     closure of all left types of the given {@code Either}s
-     * @param <R>     closure of all right types of the given {@code Either}s
-     *
-     * @return An {@code Either} of a {@link Seq} of left or right values
-     *
+     * @param eithers an {@link Iterable} of {@code Either} instances
+     * @param <L>     the common type of left values
+     * @param <R>     the common type of right values
+     * @return an {@code Either} containing a {@link Seq} of left values if any {@code Either} was a {@link Either.Left}, 
+     *         otherwise a {@link Seq} of right values
      * @throws NullPointerException if {@code eithers} is null
      */
     @SuppressWarnings("unchecked")
@@ -282,18 +281,20 @@ static <L, R> Either<Seq<L>, Seq<R>> sequence(Iterable<? extends Either<? extend
     }
 
     /**
-     * Maps the values of an iterable to a sequence of mapped values into a single {@code Either} by
-     * transforming an {@code Iterable<? extends T>} into a {@code Either<Seq<U>>}.
-     *
-     * @param values An {@code Iterable} of values.
-     * @param mapper A mapper of values to Eithers
-     * @param <L>    The mapped left value type.
-     * @param <R>    The mapped right value type.
-     * @param <T>    The type of the given values.
-     *
-     * @return A {@code Either} of a {@link Seq} of results.
-     *
-     * @throws NullPointerException if values or f is null.
+     * Transforms an {@link Iterable} of values into a single {@code Either<Seq<L>, Seq<R>>} by applying a mapping function 
+     * that returns an {@code Either} for each value.
+     * <p>
+     * If the mapper returns any {@link Either.Left}, the resulting {@code Either} is a {@link Either.Left}
+     * containing a {@link Seq} of all left values. Otherwise, the result is a {@link Either.Right} containing 
+     * a {@link Seq} of all right values.
+     *
+     * @param values an {@code Iterable} of values to map
+     * @param mapper a function mapping each value to an {@code Either<L, R>}
+     * @param <L>    the type of left values
+     * @param <R>    the type of right values
+     * @param <T>    the type of the input values
+     * @return a single {@code Either} containing a {@link Seq} of left or right results
+     * @throws NullPointerException if {@code values} or {@code mapper} is null
      */
     static <L, R, T> Either<Seq<L>, Seq<R>> traverse(Iterable<? extends T> values, Function<? super T, ? extends Either<? extends L, ? extends R>> mapper) {
         Objects.requireNonNull(values, "values is null");
@@ -302,14 +303,13 @@ static <L, R, T> Either<Seq<L>, Seq<R>> traverse(Iterable<? extends T> values, F
     }
 
     /**
-     * Reduces many {@code Either}s into a single {@code Either} by transforming an
-     * {@code Iterable<Either<L, R>>} into a {@code Either<L, Seq<R>>}.
+     * Transforms an {@link Iterable} of {@code Either<L, R>} into a single {@code Either<L, Seq<R>>}.
      * <p>
-     * If any of the given {@code Either}s is a {@link Either.Left} then {@code sequenceRight} returns a
-     * {@link Either.Left} containing the first left value (in iteration order).
+     * If any of the given {@code Either}s is a {@link Either.Left}, the result is a {@link Either.Left}
+     * containing the first left value encountered in iteration order.
      * <p>
-     * If none of the given {@code Either}s is a {@link Either.Left} then {@code sequenceRight} returns a
-     * {@link Either.Right} containing a (possibly empty) {@link Seq} of all right values.
+     * If all of the given {@code Either}s are {@link Either.Right}, the result is a {@link Either.Right}
+     * containing a (possibly empty) {@link Seq} of all right values.
      *
      * <pre>{@code
      * // = Right(Seq())
@@ -322,12 +322,10 @@ static <L, R, T> Either<Seq<L>, Seq<R>> traverse(Iterable<? extends T> values, F
      * Either.sequenceRight(List.of(Either.right(1), Either.left("x1"), Either.left("x2")))
      * }</pre>
      *
-     * @param eithers An {@link Iterable} of {@code Either}s
-     * @param <L>     closure of all left types of the given {@code Either}s
-     * @param <R>     closure of all right types of the given {@code Either}s
-     *
-     * @return An {@code Either} of either a {@link Seq} of right values or the first left value, if present.
-     *
+     * @param eithers an {@link Iterable} of {@code Either} instances
+     * @param <L>     the type of left values
+     * @param <R>     the type of right values
+     * @return an {@code Either} containing either the first left value if present, or a {@link Seq} of all right values
      * @throws NullPointerException if {@code eithers} is null
      */
     static <L, R> Either<L, Seq<R>> sequenceRight(Iterable<? extends Either<? extends L, ? extends R>> eithers) {
@@ -344,18 +342,20 @@ static <L, R> Either<L, Seq<R>> sequenceRight(Iterable<? extends Either<? extend
     }
 
     /**
-     * Maps the values of an iterable to a sequence of mapped values into a single {@code Either} by
-     * transforming an {@code Iterable<? extends T>} into a {@code Either<Seq<U>>}.
-     *
-     * @param values An {@code Iterable} of values.
-     * @param mapper A mapper of values to Eithers
-     * @param <L>    The mapped left value type.
-     * @param <R>    The mapped right value type.
-     * @param <T>    The type of the given values.
-     *
-     * @return A {@code Either} of a {@link Seq} of results.
-     *
-     * @throws NullPointerException if values or f is null.
+     * Transforms an {@link Iterable} of values into a single {@code Either<Seq<L>, Seq<R>>} by applying a mapping 
+     * function that returns an {@code Either} for each element.
+     * <p>
+     * If the mapper returns any {@link Either.Left}, the resulting {@code Either} is a {@link Either.Left}
+     * containing a {@link Seq} of all left values. Otherwise, the result is a {@link Either.Right} containing 
+     * a {@link Seq} of all right values.
+     *
+     * @param values an {@code Iterable} of values to map
+     * @param mapper a function mapping each value to an {@code Either<L, R>}
+     * @param <L>    the type of left values
+     * @param <R>    the type of right values
+     * @param <T>    the type of input values
+     * @return a single {@code Either} containing a {@link Seq} of left or right results
+     * @throws NullPointerException if {@code values} or {@code mapper} is null
      */
     static <L, R, T> Either<L, Seq<R>> traverseRight(Iterable<? extends T> values, Function<? super T, ? extends Either<? extends L, ? extends R>> mapper) {
         Objects.requireNonNull(values, "values is null");
@@ -364,12 +364,10 @@ static <L, R, T> Either<L, Seq<R>> traverseRight(Iterable<? extends T> values, F
     }
 
     /**
-     * Gets the Right value or an alternate value, if the projected Either is a Left.
-     *
-     * @param other a function which converts a Left value to an alternative Right value
+     * Returns the right value of this {@code Either}, or an alternative value if this is a {@link Either.Left}.
      *
-     * @return the right value, if the underlying Either is a Right or else the alternative Right value provided by
-     * {@code other} by applying the Left value.
+     * @param other a function that converts a left value to an alternative right value
+     * @return the right value if present, otherwise the alternative value produced by applying {@code other} to the left value
      */
     default R getOrElseGet(Function<? super L, ? extends R> other) {
         Objects.requireNonNull(other, "other is null");
@@ -381,9 +379,9 @@ default R getOrElseGet(Function<? super L, ? extends R> other) {
     }
 
     /**
-     * Runs an action in the case this is a projection on a Left value.
+     * Executes the given action if this projection represents a {@link Either.Left} value.
      *
-     * @param action an action which consumes a Left value
+     * @param action a consumer that processes the left value
      */
     default void orElseRun(Consumer<? super L> action) {
         Objects.requireNonNull(action, "action is null");
@@ -393,15 +391,12 @@ default void orElseRun(Consumer<? super L> action) {
     }
 
     /**
-     * Gets the Right value or throws, if the projected Either is a Left.
+     * Returns the right value of this {@code Either}, or throws an exception if it is a {@link Either.Left}.
      *
-     * @param <X>               a throwable type
-     * @param exceptionFunction a function which creates an exception based on a Left value
-     *
-     * @return the right value, if the underlying Either is a Right or else throws the exception provided by
-     * {@code exceptionFunction} by applying the Left value.
-     *
-     * @throws X if the projected Either is a Left
+     * @param <X>               the type of exception to be thrown
+     * @param exceptionFunction a function that produces an exception from the left value
+     * @return the right value if present
+     * @throws X if this {@code Either} is a {@link Either.Left}, using the exception produced by {@code exceptionFunction}
      */
     default <X extends Throwable> R getOrElseThrow(Function<? super L, X> exceptionFunction) throws X {
         Objects.requireNonNull(exceptionFunction, "exceptionFunction is null");
@@ -413,9 +408,10 @@ default <X extends Throwable> R getOrElseThrow(Function<? super L, X> exceptionF
     }
 
     /**
-     * Converts a {@code Left} to a {@code Right} vice versa by wrapping the value in a new type.
+     * Swaps the sides of this {@code Either}, converting a {@link Either.Left} to a {@link Either.Right}
+     * and vice versa.
      *
-     * @return a new {@code Either}
+     * @return a new {@code Either} with the left and right values swapped
      */
     default Either<R, L> swap() {
         if (isRight()) {
@@ -428,13 +424,14 @@ default Either<R, L> swap() {
     // -- Adjusted return types of Monad methods
 
     /**
-     * FlatMaps this right-biased Either.
-     *
-     * @param mapper A mapper
-     * @param <U>    Component type of the mapped right value
-     *
-     * @return this as {@code Either<L, U>} if this is a Left, otherwise the right mapping result
+     * Applies a flat-mapping function to the right value of this right-biased {@code Either}.
+     * <p>
+     * If this {@code Either} is a {@link Either.Left}, it is returned unchanged. 
+     * Otherwise, the {@code mapper} function is applied to the right value, and its result is returned.
      *
+     * @param mapper a function that maps the right value to another {@code Either<L, U>}
+     * @param <U>    the type of the right value in the resulting {@code Either}
+     * @return this {@code Either} unchanged if it is a {@link Either.Left}, or the result of applying {@code mapper} if it is a {@link Either.Right}
      * @throws NullPointerException if {@code mapper} is null
      */
     @SuppressWarnings("unchecked")
@@ -448,7 +445,9 @@ default <U> Either<L, U> flatMap(Function<? super R, ? extends Either<L, ? exten
     }
 
     /**
-     * Maps the value of this Either if it is a Right, performs no operation if this is a Left.
+     * Transforms the right value of this {@code Either} using the given mapping function.
+     * <p>
+     * If this {@code Either} is a {@link Either.Left}, no operation is performed and it is returned unchanged.
      *
      * <pre><code>
      * import static io.vavr.API.*;
@@ -460,11 +459,9 @@ default <U> Either<L, U> flatMap(Function<? super R, ? extends Either<L, ? exten
      * Left(1).map(String::toUpperCase);
      * </code></pre>
      *
-     * @param mapper A mapper
-     * @param <U>    Component type of the mapped right value
-     *
-     * @return a mapped {@code Monad}
-     *
+     * @param mapper a function to transform the right value
+     * @param <U>    the type of the right value in the resulting {@code Either}
+     * @return a new {@code Either} with the right value transformed, or the original left value
      * @throws NullPointerException if {@code mapper} is null
      */
     @SuppressWarnings("unchecked")
@@ -479,7 +476,9 @@ default <U> Either<L, U> map(Function<? super R, ? extends U> mapper) {
     }
 
     /**
-     * Maps the value of this Either if it is a Left, performs no operation if this is a Right.
+     * Transforms the left value of this {@code Either} using the given mapping function.
+     * <p>
+     * If this {@code Either} is a {@link Either.Right}, no operation is performed and it is returned unchanged.
      *
      * <pre>{@code
      * import static io.vavr.API.*;
@@ -491,12 +490,10 @@ default <U> Either<L, U> map(Function<? super R, ? extends U> mapper) {
      * Right("a").mapLeft(i -> i + 1);
      * }</pre>
      *
-     * @param leftMapper A mapper
-     * @param <U>        Component type of the mapped right value
-     *
-     * @return a mapped {@code Monad}
-     *
-     * @throws NullPointerException if {@code mapper} is null
+     * @param leftMapper a function to transform the left value
+     * @param <U>        the type of the left value in the resulting {@code Either}
+     * @return a new {@code Either} with the left value transformed, or the original right value
+     * @throws NullPointerException if {@code leftMapper} is null
      */
     @SuppressWarnings("unchecked")
     default <U> Either<U, R> mapLeft(Function<? super L, ? extends U> leftMapper) {
@@ -511,12 +508,13 @@ default <U> Either<U, R> mapLeft(Function<? super L, ? extends U> leftMapper) {
     // -- Adjusted return types of Value methods
 
     /**
-     * Filters this right-biased {@code Either} by testing a predicate.
-     *
-     * @param predicate A predicate
-     *
-     * @return a new {@code Option} instance
+     * Returns an {@link Option} describing the right value of this right-biased {@code Either}
+     * if it satisfies the given predicate.
+     * <p>
+     * If this {@code Either} is a {@link Either.Left} or the predicate does not match, {@link Option#none()} is returned.
      *
+     * @param predicate a predicate to test the right value
+     * @return an {@link Option} containing the right value if it satisfies the predicate, or {@link Option#none()} otherwise
      * @throws NullPointerException if {@code predicate} is null
      */
     default Option<Either<L, R>> filter(Predicate<? super R> predicate) {
@@ -525,10 +523,11 @@ default Option<Either<L, R>> filter(Predicate<? super R> predicate) {
     }
 
     /**
-     * Filters this right-biased {@code Either} by testing a predicate.
-     * If the {@code Either} is a {@code Right} and the predicate doesn't match, the
-     * {@code Either} will be turned into a {@code Left} with contents computed by applying
-     * the zero function to the {@code Either} value.
+     * Filters this right-biased {@code Either} using the given predicate. 
+     * <p>
+     * If this {@code Either} is a {@link Either.Right} and the predicate evaluates to {@code false}, 
+     * the result is a {@link Either.Left} obtained by applying the {@code zero} function to the right value.
+     * If the predicate evaluates to {@code true}, the {@code Either.Right} is returned unchanged.
      *
      * <pre>{@code
      * import static io.vavr.API.*;
@@ -540,12 +539,10 @@ default Option<Either<L, R>> filter(Predicate<? super R> predicate) {
      * Right("a").filterOrElse(i -> true, val -> "bad: " + val);
      * }</pre>
      *
-     * @param predicate A predicate
-     * @param zero      A function that turns a right value into a left value if the right value does not make it through the filter.
-     *
-     * @return an {@code Either} instance
-     *
-     * @throws NullPointerException if {@code predicate} is null
+     * @param predicate a predicate to test the right value
+     * @param zero      a function that converts a right value to a left value if the predicate fails
+     * @return an {@code Either} containing the right value if the predicate matches, or a left value otherwise
+     * @throws NullPointerException if {@code predicate} or {@code zero} is null
      */
     default Either<L, R> filterOrElse(Predicate<? super R> predicate, Function<? super R, ? extends L> zero) {
         Objects.requireNonNull(predicate, "predicate is null");
@@ -558,11 +555,10 @@ default Either<L, R> filterOrElse(Predicate<? super R> predicate, Function<? sup
     }
 
     /**
-     * Gets the right value if this is a {@code Right} or throws if this is a {@code Left}.
+     * Returns the right value if this is a {@code Right}; otherwise throws.
      *
      * @return the right value
-     *
-     * @throws NoSuchElementException if this is a {@code Left}.
+     * @throws NoSuchElementException if this is a {@code Left}
      */
     @Override
     R get();
@@ -585,9 +581,9 @@ default Either<L, R> orElse(Supplier<? extends Either<? extends L, ? extends R>>
     }
 
     /**
-     * A right-biased {@code Either}'s value is computed synchronously.
+     * Indicates that a right-biased {@code Either} computes its value synchronously.
      *
-     * @return false
+     * @return {@code false}
      */
     @Override
     default boolean isAsync() {
@@ -595,9 +591,9 @@ default boolean isAsync() {
     }
 
     /**
-     * A right-biased {@code Either}'s value is computed eagerly.
+     * Indicates that a right-biased {@code Either} computes its value eagerly.
      *
-     * @return false
+     * @return {@code false}
      */
     @Override
     default boolean isLazy() {
@@ -605,7 +601,7 @@ default boolean isLazy() {
     }
 
     /**
-     * A right-biased {@code Either} is single-valued.
+     * Indicates that a right-biased {@code Either} contains exactly one value.
      *
      * @return {@code true}
      */
diff --git a/vavr/src/main/java/io/vavr/control/Option.java b/vavr/src/main/java/io/vavr/control/Option.java
index 3b6e27d27..a23775eed 100644
--- a/vavr/src/main/java/io/vavr/control/Option.java
+++ b/vavr/src/main/java/io/vavr/control/Option.java
@@ -34,42 +34,42 @@
 import java.util.function.Supplier;
 
 /**
- * Replacement for {@link java.util.Optional}.
+ * A replacement for {@link java.util.Optional}.
  * <p>
- * Option is a <a href="http://stackoverflow.com/questions/13454347/monads-with-java-8">monadic</a> container type which
- * represents an optional value. Instances of Option are either an instance of {@link Some} or the
- * singleton {@link None}.
+ * {@code Option} is a monadic container type representing the presence or absence of a value.
+ * An instance is either a {@link Some} holding a value or the singleton {@link None}.
  * <p>
- * Most of the API is taken from {@link java.util.Optional}. A similar type can be found in <a
- * href="http://hackage.haskell.org/package/base-4.6.0.1/docs/Data-Maybe.html">Haskell</a> and <a
- * href="http://www.scala-lang.org/api/current/#scala.Option">Scala</a>.
+ * The design is similar to {@link java.util.Optional} and related types in
+ * <a href="http://hackage.haskell.org/package/base-4.6.0.1/docs/Data-Maybe.html">Haskell</a> and
+ * <a href="http://www.scala-lang.org/api/current/#scala.Option">Scala</a>.
  *
- * @param <T> The type of the optional value.
- * @author Daniel Dietrich
+ * @param <T> the type of the optional value
  */
 public interface Option<T> extends Value<T>, Serializable {
 
     long serialVersionUID = 1L;
 
     /**
-     * Creates a new {@code Option} of a given value.
+     * Creates an {@code Option} from the given value.
      *
-     * @param value A value
-     * @param <T>   type of the value
-     * @return {@code Some(value)} if value is not {@code null}, {@code None} otherwise
+     * @param value the value to wrap
+     * @param <T>   the value type
+     * @return {@code Some(value)} if the value is non-null, otherwise {@code None}
      */
     static <T> Option<T> of(T value) {
         return (value == null) ? none() : some(value);
     }
 
     /**
-     * Reduces many {@code Option}s into a single {@code Option} by transforming an
-     * {@code Iterable<Option<? extends T>>} into a {@code Option<Seq<T>>}. If any of
-     * the Options are {@link Option.None}, then this returns {@link Option.None}.
+     * Reduces multiple {@code Option} values into a single {@code Option} by transforming
+     * an {@code Iterable<Option<? extends T>>} into an {@code Option<Seq<T>>}.
+     * <p>
+     * If any element is {@link Option.None}, the result is {@code None}.
+     * Otherwise, all contained values are collected into a {@link Seq} wrapped in {@code Some}.
      *
-     * @param values An {@code Iterable} of {@code Option}s
-     * @param <T>    type of the Options
-     * @return An {@code Option} of a {@link Seq} of results
+     * @param values an iterable of {@code Option} values
+     * @param <T>    the element type
+     * @return an {@code Option} containing a {@code Seq} of all values, or {@code None} if any value is empty
      * @throws NullPointerException if {@code values} is null
      */
     static <T> Option<Seq<T>> sequence(Iterable<? extends Option<? extends T>> values) {
@@ -85,15 +85,19 @@ static <T> Option<Seq<T>> sequence(Iterable<? extends Option<? extends T>> value
     }
 
     /**
-     * Maps the values of an iterable to a sequence of mapped values into a single {@code Option} by
-     * transforming an {@code Iterable<? extends T>} into a {@code Option<Seq<U>>}.
-     *
-     * @param values   An {@code Iterable} of values.
-     * @param mapper   A mapper of values to Options
-     * @param <T>      The type of the given values.
-     * @param <U>      The mapped value type.
-     * @return A {@code Option} of a {@link Seq} of results.
-     * @throws NullPointerException if values or f is null.
+     * Maps the elements of an iterable into {@code Option} values and collects the results
+     * into a single {@code Option}.
+     * <p>
+     * Each element is transformed using {@code mapper}.
+     * If any mapped value is {@link Option.None}, the result is {@code None}.
+     * Otherwise, all mapped values are accumulated into a {@link Seq} wrapped in {@code Some}.
+     *
+     * @param values an iterable of input values
+     * @param mapper a function mapping each value to an {@code Option}
+     * @param <T>    the input element type
+     * @param <U>    the mapped element type
+     * @return an {@code Option} containing a {@code Seq} of mapped values, or {@code None} if any mapping yields {@code None}
+     * @throws NullPointerException if {@code values} or {@code mapper} is null
      */
     static <T, U> Option<Seq<U>> traverse(Iterable<? extends T> values, Function<? super T, ? extends Option<? extends U>> mapper) {
         Objects.requireNonNull(values, "values is null");
@@ -102,29 +106,27 @@ static <T, U> Option<Seq<U>> traverse(Iterable<? extends T> values, Function<? s
     }
 
     /**
-     * Creates a new {@code Some} of a given value.
+     * Creates a {@code Some} containing the given value.
      * <p>
-     * The only difference to {@link Option#of(Object)} is, when called with argument {@code null}.
+     * Unlike {@link Option#of(Object)}, this method preserves {@code null}:
      * <pre>
-     * <code>
-     * Option.of(null);   // = None
-     * Option.some(null); // = Some(null)
-     * </code>
+     * Option.of(null);   // yields None
+     * Option.some(null); // yields Some(null)
      * </pre>
      *
-     * @param value A value
-     * @param <T>   type of the value
-     * @return {@code Some(value)}
+     * @param value the value to wrap, possibly {@code null}
+     * @param <T>   the value type
+     * @return a {@code Some} containing {@code value}
      */
     static <T> Option<T> some(T value) {
         return new Some<>(value);
     }
 
     /**
-     * Returns the single instance of {@code None}
+     * Returns the singleton {@code None} instance.
      *
-     * @param <T> component type
-     * @return the single instance of {@code None}
+     * @param <T> the option's component type
+     * @return the singleton {@code None}
      */
     static <T> Option<T> none() {
         @SuppressWarnings("unchecked")
@@ -133,13 +135,13 @@ static <T> Option<T> none() {
     }
 
     /**
-     * Narrows a widened {@code Option<? extends T>} to {@code Option<T>}
-     * by performing a type-safe cast. This is eligible because immutable/read-only
-     * collections are covariant.
+     * Narrows a widened {@code Option<? extends T>} to {@code Option<T>} via a type-safe cast.
+     * <p>
+     * This is safe because immutable/read-only types are covariant.
      *
-     * @param option A {@code Option}.
-     * @param <T>    Component type of the {@code Option}.
-     * @return the given {@code option} instance as narrowed type {@code Option<T>}.
+     * @param option the {@code Option} to narrow
+     * @param <T>    the component type of the {@code Option}
+     * @return the same {@code Option} instance, cast to {@code Option<T>}
      */
     @SuppressWarnings("unchecked")
     static <T> Option<T> narrow(Option<? extends T> option) {
@@ -147,13 +149,14 @@ static <T> Option<T> narrow(Option<? extends T> option) {
     }
 
     /**
-     * Creates {@code Some} of suppliers value if condition is true, or {@code None} in other case
-     *
-     * @param <T>       type of the optional value
-     * @param condition A boolean value
-     * @param supplier  An optional value supplier, may supply {@code null}
-     * @return return {@code Some} of supplier's value if condition is true, or {@code None} in other case
-     * @throws NullPointerException if the given {@code supplier} is null
+     * Returns {@code Some} of the value supplied by {@code supplier} if {@code condition} is true,
+     * or {@code None} if {@code condition} is false.
+     *
+     * @param <T>       the type of the optional value
+     * @param condition the condition to test
+     * @param supplier  a supplier of the value, may return {@code null}
+     * @return {@code Some} of the supplied value if {@code condition} is true, otherwise {@code None}
+     * @throws NullPointerException if {@code supplier} is null
      */
     static <T> Option<T> when(boolean condition, Supplier<? extends T> supplier) {
         Objects.requireNonNull(supplier, "supplier is null");
@@ -161,23 +164,23 @@ static <T> Option<T> when(boolean condition, Supplier<? extends T> supplier) {
     }
 
     /**
-     * Creates {@code Some} of value if condition is true, or {@code None} in other case
+     * Returns {@code Some} of the given {@code value} if {@code condition} is true, or {@code None} otherwise.
      *
-     * @param <T>       type of the optional value
-     * @param condition A boolean value
-     * @param value     An optional value, may be {@code null}
-     * @return return {@code Some} of value if condition is true, or {@code None} in other case
+     * @param <T>       the type of the optional value
+     * @param condition the condition to test
+     * @param value     the value to wrap, may be {@code null}
+     * @return {@code Some} of {@code value} if {@code condition} is true, otherwise {@code None}
      */
     static <T> Option<T> when(boolean condition, T value) {
         return condition ? some(value) : none();
     }
 
     /**
-     * Wraps a Java Optional to a new Option
+     * Wraps a {@link java.util.Optional} in a new {@code Option}.
      *
-     * @param optional a given optional to wrap in {@code Option}
-     * @param <T>      type of the value
-     * @return {@code Some(optional.get())} if value is Java {@code Optional} is present, {@code None} otherwise
+     * @param optional the Java {@code Optional} to wrap
+     * @param <T>      the type of the contained value
+     * @return {@code Some(optional.get())} if the {@code Optional} is present, otherwise {@code None}
      */
     @SuppressWarnings("OptionalUsedAsFieldOrParameterType")
     static <T> Option<T> ofOptional(Optional<? extends T> optional) {
@@ -186,22 +189,21 @@ static <T> Option<T> ofOptional(Optional<? extends T> optional) {
     }
 
     /**
-     * Collects value that is in the domain of the given {@code partialFunction} by mapping the value to type {@code R}.
-     *
-     * <pre>{@code
-     * partialFunction.isDefinedAt(value)
-     * }</pre>
-     *
-     * If the element makes it through that filter, the mapped instance is wrapped in {@code Option}
+     * Applies a {@code partialFunction} to the value of this {@code Option} if it is defined for that value,
+     * and wraps the result in a new {@code Option}.
+     * <p>
+     * If the {@code partialFunction} is not defined for the value, {@code None} is returned.
      *
      * <pre>{@code
-     * R newValue = partialFunction.apply(value)
+     * if (partialFunction.isDefinedAt(value)) {
+     *     R newValue = partialFunction.apply(value);
+     *     // wrapped in Some(newValue)
+     * }
      * }</pre>
      *
-     *
-     * @param partialFunction A function that is not necessarily defined on value of this option.
-     * @param <R> The new value type
-     * @return A new {@code Option} instance containing value of type {@code R}
+     * @param partialFunction a function that may not be defined for all input values
+     * @param <R>             the type of the mapped value
+     * @return a new {@code Option} containing the mapped value if defined, otherwise {@code None}
      * @throws NullPointerException if {@code partialFunction} is null
      */
     default <R> Option<R> collect(PartialFunction<? super T, ? extends R> partialFunction) {
@@ -210,17 +212,17 @@ default <R> Option<R> collect(PartialFunction<? super T, ? extends R> partialFun
     }
 
     /**
-     * Returns true, if this is {@code None}, otherwise false, if this is {@code Some}.
+     * Checks whether this {@code Option} is empty.
      *
-     * @return true, if this {@code Option} is empty, false otherwise
+     * @return {@code true} if this is {@code None}, {@code false} if this is {@code Some}
      */
     @Override
     boolean isEmpty();
 
     /**
-     * Runs a Java Runnable passed as parameter if this {@code Option} is empty.
+     * Executes the given {@link Runnable} if this {@code Option} is empty ({@code None}).
      *
-     * @param action a given Runnable to be run
+     * @param action a {@code Runnable} to execute
      * @return this {@code Option}
      */
     default Option<T> onEmpty(Runnable action) {
@@ -232,9 +234,9 @@ default Option<T> onEmpty(Runnable action) {
     }
 
     /**
-     * An {@code Option}'s value is computed synchronously.
+     * Indicates that an {@code Option}'s value is computed synchronously.
      *
-     * @return false
+     * @return {@code false}
      */
     @Override
     default boolean isAsync() {
@@ -242,20 +244,20 @@ default boolean isAsync() {
     }
 
     /**
-     * Returns true, if this is {@code Some}, otherwise false, if this is {@code None}.
+     * Checks whether this {@code Option} contains a value.
      * <p>
-     * Please note that it is possible to create {@code new Some(null)}, which is defined.
+     * Note that {@code Some(null)} is considered defined.
      *
-     * @return true, if this {@code Option} has a defined value, false otherwise
+     * @return {@code true} if this is {@code Some}, {@code false} if this is {@code None}
      */
     default boolean isDefined() {
         return !isEmpty();
     }
 
     /**
-     * An {@code Option}'s value is computed eagerly.
+     * Indicates that an {@code Option}'s value is computed eagerly.
      *
-     * @return false
+     * @return {@code false}
      */
     @Override
     default boolean isLazy() {
@@ -263,7 +265,7 @@ default boolean isLazy() {
     }
 
     /**
-     * An {@code Option} is single-valued.
+     * Indicates that an {@code Option} contains exactly one value.
      *
      * @return {@code true}
      */
@@ -273,21 +275,21 @@ default boolean isSingleValued() {
     }
 
     /**
-     * Gets the value if this is a {@code Some} or throws if this is a {@code None}.
+     * Returns the value contained in this {@code Some}, or throws if this is {@code None}.
      *
-     * @return the value
-     * @throws NoSuchElementException if this is a {@code None}.
+     * @return the contained value
+     * @throws NoSuchElementException if this is {@code None}
      */
     @Override
     T get();
 
     /**
-     * Returns the value if this is a {@code Some} or the {@code other} value if this is a {@code None}.
+     * Returns the value contained in this {@code Some}, or the provided {@code other} value if this is {@code None}.
      * <p>
-     * Please note, that the other value is eagerly evaluated.
+     * Note that {@code other} is evaluated eagerly.
      *
-     * @param other An alternative value
-     * @return This value, if this Option is defined or the {@code other} value, if this Option is empty.
+     * @param other an alternative value to return if this is {@code None}
+     * @return the contained value if defined, otherwise {@code other}
      */
     @Override
     default T getOrElse(T other) {
@@ -295,10 +297,10 @@ default T getOrElse(T other) {
     }
 
     /**
-     * Returns this {@code Option} if it is nonempty, otherwise return the alternative.
+     * Returns this {@code Option} if it is non-empty, otherwise returns the provided alternative {@code Option}.
      *
-     * @param other An alternative {@code Option}
-     * @return this {@code Option} if it is nonempty, otherwise return the alternative.
+     * @param other an alternative {@code Option} to return if this is {@code None}
+     * @return this {@code Option} if defined, otherwise {@code other}
      */
     @SuppressWarnings("unchecked")
     default Option<T> orElse(Option<? extends T> other) {
@@ -307,10 +309,11 @@ default Option<T> orElse(Option<? extends T> other) {
     }
 
     /**
-     * Returns this {@code Option} if it is nonempty, otherwise return the result of evaluating supplier.
+     * Returns this {@code Option} if it is non-empty; otherwise, returns the {@code Option} provided by the supplier.
      *
-     * @param supplier An alternative {@code Option} supplier
-     * @return this {@code Option} if it is nonempty, otherwise return the result of evaluating supplier.
+     * @param supplier a supplier of an alternative {@code Option} if this is {@code None}
+     * @return this {@code Option} if defined, otherwise the result of {@code supplier.get()}
+     * @throws NullPointerException if {@code supplier} is null
      */
     @SuppressWarnings("unchecked")
     default Option<T> orElse(Supplier<? extends Option<? extends T>> supplier) {
@@ -319,13 +322,13 @@ default Option<T> orElse(Supplier<? extends Option<? extends T>> supplier) {
     }
 
     /**
-     * Returns the value if this is a {@code Some}, otherwise the {@code other} value is returned,
-     * if this is a {@code None}.
+     * Returns the value contained in this {@code Some}, or the value supplied by {@code supplier} if this is {@code None}.
      * <p>
-     * Please note, that the other value is lazily evaluated.
+     * The alternative value is evaluated lazily.
      *
-     * @param supplier An alternative value supplier
-     * @return This value, if this Option is defined or the {@code other} value, if this Option is empty.
+     * @param supplier a supplier of an alternative value if this is {@code None}
+     * @return the contained value if defined, otherwise the value returned by {@code supplier}
+     * @throws NullPointerException if {@code supplier} is null
      */
     @Override
     default T getOrElse(Supplier<? extends T> supplier) {
@@ -334,12 +337,13 @@ default T getOrElse(Supplier<? extends T> supplier) {
     }
 
     /**
-     * Returns the value if this is a {@code Some}, otherwise throws an exception.
+     * Returns the value contained in this {@code Some}, or throws an exception provided by {@code exceptionSupplier} if this is {@code None}.
      *
-     * @param exceptionSupplier An exception supplier
-     * @param <X>               A throwable
-     * @return This value, if this Option is defined, otherwise throws X
-     * @throws X a throwable
+     * @param exceptionSupplier a supplier of the exception to throw if this is {@code None}
+     * @param <X>               the type of the exception
+     * @return the contained value if defined
+     * @throws X if this {@code Option} is {@code None}
+     * @throws NullPointerException if {@code exceptionSupplier} is null
      */
     @Override
     default <X extends Throwable> T getOrElseThrow(Supplier<X> exceptionSupplier) throws X {
@@ -352,11 +356,12 @@ default <X extends Throwable> T getOrElseThrow(Supplier<X> exceptionSupplier) th
     }
 
     /**
-     * Returns {@code Some(value)} if this is a {@code Some} and the value satisfies the given predicate.
-     * Otherwise {@code None} is returned.
+     * Returns {@code Some(value)} if this {@code Option} is a {@code Some} and the contained value satisfies the given predicate.
+     * Otherwise, returns {@code None}.
      *
-     * @param predicate A predicate which is used to test an optional value
-     * @return {@code Some(value)} or {@code None} as specified
+     * @param predicate a predicate to test the contained value
+     * @return {@code Some(value)} if the value satisfies the predicate, otherwise {@code None}
+     * @throws NullPointerException if {@code predicate} is null
      */
     default Option<T> filter(Predicate<? super T> predicate) {
         Objects.requireNonNull(predicate, "predicate is null");
@@ -364,11 +369,13 @@ default Option<T> filter(Predicate<? super T> predicate) {
     }
 
     /**
-     * Maps the value to a new {@code Option} if this is a {@code Some}, otherwise returns {@code None}.
+     * Transforms the value of this {@code Option} using the given mapper if it is a {@code Some}.
+     * Returns {@code None} if this is {@code None}.
      *
-     * @param mapper A mapper
-     * @param <U>    Component type of the resulting Option
-     * @return a new {@code Option}
+     * @param mapper a function to transform the contained value
+     * @param <U>    the type of the resulting {@code Option}'s value
+     * @return a new {@code Option} containing the mapped value, or {@code None}
+     * @throws NullPointerException if {@code mapper} is null
      */
     @SuppressWarnings("unchecked")
     default <U> Option<U> flatMap(Function<? super T, ? extends Option<? extends U>> mapper) {
@@ -377,11 +384,13 @@ default <U> Option<U> flatMap(Function<? super T, ? extends Option<? extends U>>
     }
 
     /**
-     * Maps the value and wraps it in a new {@code Some} if this is a {@code Some}, returns {@code None}.
+     * Transforms the value of this {@code Some} using the given mapper and wraps it in a new {@code Some}.
+     * Returns {@code None} if this is {@code None}.
      *
-     * @param mapper A value mapper
-     * @param <U>    The new value type
-     * @return a new {@code Some} containing the mapped value if this Option is defined, otherwise {@code None}, if this is empty.
+     * @param mapper a function to transform the contained value
+     * @param <U>    the type of the resulting {@code Some}'s value
+     * @return a new {@code Some} with the mapped value if this is defined, otherwise {@code None}
+     * @throws NullPointerException if {@code mapper} is null
      */
     @Override
     default <U> Option<U> map(Function<? super T, ? extends U> mapper) {
@@ -400,12 +409,12 @@ default Option<Void> mapToVoid() {
     }
 
     /**
-     * Converts this to a {@link Try}, then runs the given checked function if this is a {@link Try.Success},
-     * passing the result of the current expression to it.
+     * Converts this {@code Option} to a {@link Try}, then applies the given checked function if this is a {@link Try.Success},
+     * passing the contained value to it.
      *
-     * @param <U>    The new component type
-     * @param mapper A checked function
-     * @return a {@code Try}
+     * @param <U>    the type of the resulting {@code Try}'s value
+     * @param mapper a checked function to transform the contained value
+     * @return a {@code Try} containing the mapped value if this {@code Option} is defined, otherwise a {@link Try.Failure}
      * @throws NullPointerException if {@code mapper} is null
      */
     default <U> Try<U> mapTry(CheckedFunction1<? super T, ? extends U> mapper) {
@@ -413,22 +422,29 @@ default <U> Try<U> mapTry(CheckedFunction1<? super T, ? extends U> mapper) {
     }
 
     /**
-     * Folds either the {@code None} or the {@code Some} side of the Option value.
-     *
-     * @param ifNone  maps the left value if this is a None
-     * @param f maps the value if this is a Some
-     * @param <U>         type of the folded value
-     * @return A value of type U
+     * Folds this {@code Option} into a single value by applying one of two functions:
+     * <ul>
+     *     <li>{@code ifNone} is applied if this is {@code None}</li>
+     *     <li>{@code f} is applied to the contained value if this is {@code Some}</li>
+     * </ul>
+     *
+     * @param ifNone a function to produce a value if this is {@code None}
+     * @param f      a function to transform the contained value if this is {@code Some}
+     * @param <U>    the type of the folded result
+     * @return the result of applying {@code f} or {@code ifNone} depending on whether this is {@code Some} or {@code None}
+     * @throws NullPointerException if {@code ifNone} or {@code f} is null
      */
     default <U> U fold(Supplier<? extends U> ifNone, Function<? super T, ? extends U> f) {
         return this.<U>map(f).getOrElse(ifNone);
     }
 
     /**
-     * Applies an action to this value, if this option is defined, otherwise does nothing.
+     * Executes the given action on the contained value if this {@code Option} is defined ({@code Some}),
+     * otherwise does nothing.
      *
-     * @param action An action which can be applied to an optional value
+     * @param action a consumer to apply to the contained value
      * @return this {@code Option}
+     * @throws NullPointerException if {@code action} is null
      */
     @Override
     default Option<T> peek(Consumer<? super T> action) {
@@ -440,11 +456,11 @@ default Option<T> peek(Consumer<? super T> action) {
     }
 
     /**
-     * Transforms this {@code Option}.
+     * Transforms this {@code Option} into a value of type {@code U} using the given function.
      *
-     * @param f   A transformation
-     * @param <U> Type of transformation result
-     * @return An instance of type {@code U}
+     * @param f   a function to transform this {@code Option}
+     * @param <U> the type of the result
+     * @return the result of applying {@code f} to this {@code Option}
      * @throws NullPointerException if {@code f} is null
      */
     default <U> U transform(Function<? super Option<T>, ? extends U> f) {
diff --git a/vavr/src/main/java/io/vavr/control/Try.java b/vavr/src/main/java/io/vavr/control/Try.java
index 34a89877f..f8092aee4 100644
--- a/vavr/src/main/java/io/vavr/control/Try.java
+++ b/vavr/src/main/java/io/vavr/control/Try.java
@@ -37,35 +37,39 @@
 import static io.vavr.control.TryModule.sneakyThrow;
 
 /**
- * The Try control gives us the ability write safe code without focusing on try-catch blocks in the presence of exceptions.
+ * A control structure that allows writing safe code without explicitly managing try-catch blocks for exceptions.
  * <p>
- * The following exceptions are considered to be fatal/non-recoverable:
+ * The following exceptions are considered fatal or non-recoverable:
  * <ul>
- * <li>{@linkplain InterruptedException}</li>
- * <li>{@linkplain LinkageError}</li>
- * <li>{@linkplain ThreadDeath}</li>
- * <li>{@linkplain VirtualMachineError} (i.e. {@linkplain OutOfMemoryError} or {@linkplain StackOverflowError})</li>
+ *     <li>{@linkplain InterruptedException}</li>
+ *     <li>{@linkplain LinkageError}</li>
+ *     <li>{@linkplain ThreadDeath}</li>
+ *     <li>{@linkplain VirtualMachineError}, including {@linkplain OutOfMemoryError} and {@linkplain StackOverflowError}</li>
  * </ul>
  * <p>
- * <strong>Important note:</strong> Try may re-throw (undeclared) exceptions, e.g. on {@code get()}. From within a
- * dynamic proxy {@link java.lang.reflect.InvocationHandler} this will lead to an
- * {@link java.lang.reflect.UndeclaredThrowableException}. For more information, please read
- * <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/reflection/proxy.html">Dynamic Proxy Classes</a>.
+ * <strong>Note:</strong> Methods such as {@code get()} may re-throw exceptions without declaring them. When used
+ * within a {@link java.lang.reflect.InvocationHandler} of a dynamic proxy, such exceptions will be wrapped in
+ * {@link java.lang.reflect.UndeclaredThrowableException}. See 
+ * <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/reflection/proxy.html">
+ * Dynamic Proxy Classes</a> for more details.
  *
- * @param <T> Value type in the case of success.
- * @author Daniel Dietrich
+ * @param <T> the type of the value in case of success
+ * @author Daniel
  */
 public interface Try<T> extends Value<T>, Serializable {
 
     long serialVersionUID = 1L;
 
     /**
-     * Creates a Try of a CheckedFunction0.
+     * Creates a {@link Try} instance from a {@link CheckedFunction0}.
+     * <p>
+     * If the supplier executes without throwing an exception, a {@link Success} containing the result is returned.
+     * If an exception occurs during execution, a {@link Failure} wrapping the thrown exception is returned.
      *
-     * @param supplier A checked supplier
-     * @param <T>      Component type
-     * @return {@code Success(supplier.apply())} if no exception occurs, otherwise {@code Failure(throwable)} if an
-     * exception occurs calling {@code supplier.apply()}.
+     * @param supplier the checked supplier to execute
+     * @param <T>      the type of the value returned by the supplier
+     * @return a {@link Success} with the supplier's result, or a {@link Failure} if an exception is thrown
+     * @throws NullPointerException if {@code supplier} is {@code null}
      */
     static <T> Try<T> of(CheckedFunction0<? extends T> supplier) {
         Objects.requireNonNull(supplier, "supplier is null");
@@ -78,12 +82,15 @@ static <T> Try<T> of(CheckedFunction0<? extends T> supplier) {
 
 
     /**
-     * Creates a Try of a Supplier.
+     * Creates a {@link Try} instance from a {@link Supplier}.
+     * <p>
+     * If the supplier executes without throwing an exception, a {@link Success} containing the result is returned.
+     * If an exception occurs during execution, a {@link Failure} wrapping the thrown exception is returned.
      *
-     * @param supplier A supplier
-     * @param <T>      Component type
-     * @return {@code Success(supplier.get())} if no exception occurs, otherwise {@code Failure(throwable)} if an
-     * exception occurs calling {@code supplier.get()}.
+     * @param supplier the supplier to execute
+     * @param <T>      the type of the value returned by the supplier
+     * @return a {@link Success} with the supplier's result, or a {@link Failure} if an exception is thrown
+     * @throws NullPointerException if {@code supplier} is {@code null}
      */
     static <T> Try<T> ofSupplier(Supplier<? extends T> supplier) {
         Objects.requireNonNull(supplier, "supplier is null");
@@ -91,12 +98,15 @@ static <T> Try<T> ofSupplier(Supplier<? extends T> supplier) {
     }
 
     /**
-     * Creates a Try of a Callable.
+     * Creates a {@link Try} instance from a {@link Callable}.
+     * <p>
+     * If the callable executes without throwing an exception, a {@link Success} containing the result is returned.
+     * If an exception occurs during execution, a {@link Failure} wrapping the thrown exception is returned.
      *
-     * @param callable A callable
-     * @param <T>      Component type
-     * @return {@code Success(callable.call())} if no exception occurs, otherwise {@code Failure(throwable)} if an
-     * exception occurs calling {@code callable.call()}.
+     * @param callable the callable to execute
+     * @param <T>      the type of the value returned by the callable
+     * @return a {@link Success} with the callable's result, or a {@link Failure} if an exception is thrown
+     * @throws NullPointerException if {@code callable} is {@code null}
      */
     static <T> Try<T> ofCallable(Callable<? extends T> callable) {
         Objects.requireNonNull(callable, "callable is null");
@@ -104,11 +114,15 @@ static <T> Try<T> ofCallable(Callable<? extends T> callable) {
     }
 
     /**
-     * Creates a Try of a CheckedRunnable.
+     * Creates a {@link Try} instance from a {@link CheckedRunnable}.
+     * <p>
+     * If the runnable executes without throwing an exception, a {@link Success} containing {@code null} (representing
+     * the absence of a value) is returned. If an exception occurs during execution, a {@link Failure} wrapping the
+     * thrown exception is returned.
      *
-     * @param runnable A checked runnable
-     * @return {@code Success(null)} if no exception occurs, otherwise {@code Failure(throwable)} if an exception occurs
-     * calling {@code runnable.run()}.
+     * @param runnable the checked runnable to execute
+     * @return a {@link Success} with {@code null} if the runnable completes successfully, or a {@link Failure} if an exception is thrown
+     * @throws NullPointerException if {@code runnable} is {@code null}
      */
     static Try<Void> run(CheckedRunnable runnable) {
         Objects.requireNonNull(runnable, "runnable is null");
@@ -121,26 +135,33 @@ static Try<Void> run(CheckedRunnable runnable) {
     }
 
     /**
-     * Creates a Try of a Runnable.
+     * Creates a {@link Try} instance from a {@link Runnable}.
+     * <p>
+     * If the runnable executes without throwing an exception, a {@link Success} containing {@code null} (representing
+     * the absence of a value) is returned. If an exception occurs during execution, a {@link Failure} wrapping the
+     * thrown exception is returned.
      *
-     * @param runnable A runnable
-     * @return {@code Success(null)} if no exception occurs, otherwise {@code Failure(throwable)} if an exception occurs
-     * calling {@code runnable.run()}.
+     * @param runnable the runnable to execute
+     * @return a {@link Success} with {@code null} if the runnable completes successfully, or a {@link Failure} if an exception is thrown
+     * @throws NullPointerException if {@code runnable} is {@code null}
      */
     static Try<Void> runRunnable(Runnable runnable) {
         Objects.requireNonNull(runnable, "runnable is null");
         return run(runnable::run);
     }
 
+
     /**
-     * Reduces many {@code Try}s into a single {@code Try} by transforming an
-     * {@code Iterable<Try<? extends T>>} into a {@code Try<Seq<T>>}. If any of
-     * the {@code Try}s are {@link Try.Failure}, then this returns a {@link Try.Failure}.
+     * Transforms an {@link Iterable} of {@link Try} instances into a single {@link Try} containing a {@link Seq}
+     * of all successful results. 
+     * <p>
+     * If any element in the input iterable is a {@link Try.Failure}, the resulting {@link Try} will also be a
+     * {@link Try.Failure}, containing the first encountered failure's cause.
      *
-     * @param values An {@link Iterable} of {@code Try}s
-     * @param <T>    type of the Trys
-     * @return A {@code Try} of a {@link Seq} of results
-     * @throws NullPointerException if {@code values} is null
+     * @param values an {@link Iterable} of {@code Try} instances
+     * @param <T>    the type of values contained in the {@code Try}s
+     * @return a {@link Try} containing a {@link Seq} of all successful results, or a {@link Try.Failure} if any input is a failure
+     * @throws NullPointerException if {@code values} is {@code null}
      */
     static <T> Try<Seq<T>> sequence(Iterable<? extends Try<? extends T>> values) {
         Objects.requireNonNull(values, "values is null");
@@ -155,15 +176,18 @@ static <T> Try<Seq<T>> sequence(Iterable<? extends Try<? extends T>> values) {
     }
 
     /**
-     * Maps the values of an iterable to a sequence of mapped values into a single {@code Try} by
-     * transforming an {@code Iterable<? extends T>} into a {@code Try<Seq<U>>}.
+     * Transforms an {@link Iterable} of values into a single {@link Try} containing a {@link Seq} of mapped results.
+     * <p>
+     * Each value in the input iterable is mapped using the provided {@code mapper} function, which produces a
+     * {@link Try}. If all mappings succeed, a {@link Success} containing a {@link Seq} of results is returned.
+     * If any mapping results in a {@link Try.Failure}, the first encountered failure is returned.
      *
-     * @param values   An {@code Iterable} of values.
-     * @param mapper   A mapper of values to Trys
-     * @param <T>      The type of the given values.
-     * @param <U>      The mapped value type.
-     * @return A {@code Try} of a {@link Seq} of results.
-     * @throws NullPointerException if values or f is null.
+     * @param values an {@link Iterable} of input values
+     * @param mapper a function mapping each input value to a {@link Try} of the mapped result
+     * @param <T>    the type of the input values
+     * @param <U>    the type of the mapped results
+     * @return a {@link Try} containing a {@link Seq} of all mapped results, or a {@link Try.Failure} if any mapping fails
+     * @throws NullPointerException if {@code values} or {@code mapper} is {@code null}
      */
     static <T, U> Try<Seq<U>> traverse(Iterable<? extends T> values, Function<? super T, ? extends Try<? extends U>> mapper) {
         Objects.requireNonNull(values, "values is null");
@@ -172,35 +196,39 @@ static <T, U> Try<Seq<U>> traverse(Iterable<? extends T> values, Function<? supe
     }
 
     /**
-     * Creates a {@link Success} that contains the given {@code value}. Shortcut for {@code new Success<>(value)}.
+     * Creates a {@link Success} containing the given {@code value}.
+     * <p>
+     * This is a convenience method equivalent to {@code new Success<>(value)}.
      *
-     * @param value A value.
-     * @param <T>   Type of the given {@code value}.
-     * @return A new {@code Success}.
+     * @param value the value to wrap in a {@link Success}
+     * @param <T>   the type of the value
+     * @return a new {@link Success} containing {@code value}
      */
     static <T> Try<T> success(T value) {
         return new Success<>(value);
     }
 
     /**
-     * Creates a {@link Failure} that contains the given {@code exception}. Shortcut for {@code new Failure<>(exception)}.
+     * Creates a {@link Failure} containing the given {@code exception}.
+     * <p>
+     * This is a convenience method equivalent to {@code new Failure<>(exception)}.
      *
-     * @param exception An exception.
-     * @param <T>       Component type of the {@code Try}.
-     * @return A new {@code Failure}.
+     * @param exception the exception to wrap in a {@link Failure}
+     * @param <T>       the component type of the {@code Try}
+     * @return a new {@link Failure} containing {@code exception}
      */
     static <T> Try<T> failure(Throwable exception) {
         return new Failure<>(exception);
     }
 
     /**
-     * Narrows a widened {@code Try<? extends T>} to {@code Try<T>}
-     * by performing a type-safe cast. This is eligible because immutable/read-only
-     * collections are covariant.
+     * Narrows a {@code Try<? extends T>} to {@code Try<T>} using a type-safe cast.
+     * <p>
+     * This is safe because {@code Try} is immutable and its contents are read-only, allowing covariance.
      *
-     * @param t   A {@code Try}.
-     * @param <T> Component type of the {@code Try}.
-     * @return the given {@code t} instance as narrowed type {@code Try<T>}.
+     * @param t   the {@code Try} instance to narrow
+     * @param <T> the component type of the {@code Try}
+     * @return the given {@code Try} instance as {@code Try<T>}
      */
     @SuppressWarnings("unchecked")
     static <T> Try<T> narrow(Try<? extends T> t) {
@@ -208,35 +236,37 @@ static <T> Try<T> narrow(Try<? extends T> t) {
     }
 
     /**
-     * Shortcut for {@code andThenTry(consumer::accept)}, see {@link #andThenTry(CheckedConsumer)}.
+     * Performs the given {@link Consumer} on the value of this {@code Try} if it is a {@link Success}.
+     * <p>
+     * This is a shortcut for {@code andThenTry(consumer::accept)}. If this {@code Try} is a {@link Failure}, 
+     * it is returned unchanged. If the consumer throws an exception, a {@link Failure} is returned.
      *
-     * @param consumer A consumer
-     * @return this {@code Try} if this is a {@code Failure} or the consumer succeeded, otherwise the
-     * {@code Failure} of the consumption.
-     * @throws NullPointerException if {@code consumer} is null
+     * @param consumer the consumer to execute on the value
+     * @return this {@code Try} if it is a {@link Failure} or the consumer succeeds, otherwise a {@link Failure} of the consumer
+     * @throws NullPointerException if {@code consumer} is {@code null}
+     * @see #andThenTry(CheckedConsumer)
      */
     default Try<T> andThen(Consumer<? super T> consumer) {
         Objects.requireNonNull(consumer, "consumer is null");
         return andThenTry(consumer::accept);
     }
 
+
     /**
-     * Passes the result to the given {@code consumer} if this is a {@code Success}.
+     * Passes the result of this {@code Try} to the given {@link CheckedConsumer} if this is a {@link Success}.
      * <p>
-     * The main use case is chaining checked functions using method references:
-     *
-     * <pre>
-     * <code>
-     * Try.of(() -&gt; 100)
-     *    .andThen(i -&gt; System.out.println(i));
-     *
-     * </code>
-     * </pre>
+     * This allows chaining of operations that may throw checked exceptions. If this {@code Try} is a {@link Failure}, 
+     * it is returned unchanged. If the consumer throws an exception, a {@link Failure} containing that exception is returned.
+     * <p>
+     * Example usage:
+     * <pre><code>
+     * Try.of(() -> 100)
+     *    .andThenTry(i -> System.out.println(i));
+     * </code></pre>
      *
-     * @param consumer A checked consumer
-     * @return this {@code Try} if this is a {@code Failure} or the consumer succeeded, otherwise the
-     * {@code Failure} of the consumption.
-     * @throws NullPointerException if {@code consumer} is null
+     * @param consumer the checked consumer to execute on the value
+     * @return this {@code Try} if it is a {@link Failure} or the consumer succeeds, otherwise a {@link Failure} of the consumer
+     * @throws NullPointerException if {@code consumer} is {@code null}
      */
     default Try<T> andThenTry(CheckedConsumer<? super T> consumer) {
         Objects.requireNonNull(consumer, "consumer is null");
@@ -253,49 +283,52 @@ default Try<T> andThenTry(CheckedConsumer<? super T> consumer) {
     }
 
     /**
-     * Shortcut for {@code andThenTry(runnable::run)}, see {@link #andThenTry(CheckedRunnable)}.
+     * Performs the given {@link Runnable} if this {@code Try} is a {@link Success}.
+     * <p>
+     * This is a shortcut for {@code andThenTry(runnable::run)}. If this {@code Try} is a {@link Failure}, it is returned unchanged.
+     * If the runnable throws an exception, a {@link Failure} containing that exception is returned.
      *
-     * @param runnable A runnable
-     * @return this {@code Try} if this is a {@code Failure} or the runnable succeeded, otherwise the
-     * {@code Failure} of the run.
-     * @throws NullPointerException if {@code runnable} is null
+     * @param runnable the runnable to execute
+     * @return this {@code Try} if it is a {@link Failure} or the runnable succeeds, otherwise a {@link Failure} of the runnable
+     * @throws NullPointerException if {@code runnable} is {@code null}
+     * @see #andThenTry(CheckedRunnable)
      */
     default Try<T> andThen(Runnable runnable) {
         Objects.requireNonNull(runnable, "runnable is null");
         return andThenTry(runnable::run);
     }
 
+
     /**
-     * Runs the given runnable if this is a {@code Success}, otherwise returns this {@code Failure}.
+     * Executes the given {@link CheckedRunnable} if this {@code Try} is a {@link Success}; 
+     * otherwise, returns this {@code Failure}.
      * <p>
-     * The main use case is chaining runnables using method references:
-     *
-     * <pre>
-     * <code>
-     * Try.run(A::methodRef).andThen(B::methodRef).andThen(C::methodRef);
-     * </code>
-     * </pre>
-     *
-     * Please note that these lines are semantically the same:
-     *
-     * <pre>
-     * <code>
+     * This allows chaining of runnables that may throw checked exceptions. If the runnable throws an exception,
+     * a {@link Failure} containing that exception is returned.
+     * <p>
+     * Example usage with method references:
+     * <pre><code>
+     * Try.run(A::methodRef)
+     *    .andThen(B::methodRef)
+     *    .andThen(C::methodRef);
+     * </code></pre>
+     *
+     * The following two forms are semantically equivalent:
+     * <pre><code>
      * Try.run(this::doStuff)
      *    .andThen(this::doMoreStuff)
      *    .andThen(this::doEvenMoreStuff);
      *
-     * Try.run(() -&gt; {
+     * Try.run(() -> {
      *     doStuff();
      *     doMoreStuff();
      *     doEvenMoreStuff();
      * });
-     * </code>
-     * </pre>
+     * </code></pre>
      *
-     * @param runnable A checked runnable
-     * @return this {@code Try} if this is a {@code Failure} or the runnable succeeded, otherwise the
-     * {@code Failure} of the run.
-     * @throws NullPointerException if {@code runnable} is null
+     * @param runnable the checked runnable to execute
+     * @return this {@code Try} if it is a {@link Failure} or the runnable succeeds, otherwise a {@link Failure} of the runnable
+     * @throws NullPointerException if {@code runnable} is {@code null}
      */
     default Try<T> andThenTry(CheckedRunnable runnable) {
         Objects.requireNonNull(runnable, "runnable is null");
@@ -312,23 +345,23 @@ default Try<T> andThenTry(CheckedRunnable runnable) {
     }
 
     /**
-     * Collects value that is in the domain of the given {@code partialFunction} by mapping the value to type {@code R}.
-     *
-     * <pre>{@code
-     * partialFunction.isDefinedAt(value)
-     * }</pre>
-     *
-     * If the element makes it through that filter, the mapped instance is wrapped in {@code Try}
-     *
+     * Transforms the value of this {@code Try} using the given {@link PartialFunction} if it is defined at the value.
+     * <p>
+     * The {@code partialFunction} is first tested with {@link PartialFunction#isDefinedAt(Object)}. If it returns
+     * {@code true}, the value is mapped using {@link PartialFunction#apply(Object)} and wrapped in a new {@code Try}.
+     * If the function is not defined at the value or this {@code Try} is a {@link Failure}, the result is a {@link Failure}.
+     * <p>
+     * Example:
      * <pre>{@code
-     * R newValue = partialFunction.apply(value)
+     * PartialFunction<Integer, String> pf = ...;
+     * Try.of(() -> 42)
+     *    .collect(pf); // maps the value if pf.isDefinedAt(42) is true
      * }</pre>
      *
-     *
-     * @param partialFunction A function that is not necessarily defined on value of this try.
-     * @param <R> The new value type
-     * @return A new {@code Try} instance containing value of type {@code R}
-     * @throws NullPointerException if {@code partialFunction} is null
+     * @param partialFunction a function that may not be defined for all input values
+     * @param <R>             the type of the mapped result
+     * @return a new {@code Try} containing the mapped value if defined, or a {@link Failure}
+     * @throws NullPointerException if {@code partialFunction} is {@code null}
      */
     @SuppressWarnings("unchecked")
     default <R> Try<R> collect(PartialFunction<? super T, ? extends R> partialFunction){
@@ -337,10 +370,11 @@ default <R> Try<R> collect(PartialFunction<? super T, ? extends R> partialFuncti
     }
 
     /**
-     * Returns {@code Success(throwable)} if this is a {@code Failure(throwable)}, otherwise
-     * a {@code Failure(new NoSuchElementException("Success.failed()"))} if this is a Success.
+     * Returns a {@code Success} containing the throwable if this {@code Try} is a {@link Failure}.
+     * <p>
+     * If this {@code Try} is a {@link Success}, a {@code Failure} containing a {@link NoSuchElementException} is returned.
      *
-     * @return a new Try
+     * @return a {@code Try<Throwable>} representing the throwable of this {@link Failure}, or a {@link Failure} if this is a {@link Success}
      */
     default Try<Throwable> failed() {
         if (isFailure()) {
@@ -351,13 +385,15 @@ default Try<Throwable> failed() {
     }
 
     /**
-     * Shortcut for {@code filterTry(predicate::test, throwableSupplier)}, see
-     * {@link #filterTry(CheckedPredicate, Supplier)}}.
+     * Returns a {@code Try} if the given {@link Predicate} evaluates to {@code true}, otherwise returns a {@link Failure}
+     * created by the given {@link Supplier} of {@link Throwable}.
+     * <p>
+     * This is a shortcut for {@link #filterTry(CheckedPredicate, Supplier)}.
      *
-     * @param predicate         A predicate
-     * @param throwableSupplier A supplier of a throwable
-     * @return a {@code Try} instance
-     * @throws NullPointerException if {@code predicate} or {@code throwableSupplier} is null
+     * @param predicate         the predicate to test the value
+     * @param throwableSupplier a supplier providing a throwable if the predicate fails
+     * @return this {@code Try} if the predicate passes, otherwise a {@link Failure} from the throwable supplier
+     * @throws NullPointerException if {@code predicate} or {@code throwableSupplier} is {@code null}
      */
     default Try<T> filter(Predicate<? super T> predicate, Supplier<? extends Throwable> throwableSupplier) {
         Objects.requireNonNull(predicate, "predicate is null");
@@ -366,13 +402,15 @@ default Try<T> filter(Predicate<? super T> predicate, Supplier<? extends Throwab
     }
 
     /**
-     * Shortcut for {@code filterTry(predicate::test, errorProvider::apply)}, see
-     * {@link #filterTry(CheckedPredicate, CheckedFunction1)}}.
+     * Returns a {@code Try} if the given {@link Predicate} evaluates to {@code true}, otherwise returns a {@link Failure}
+     * created by applying the given function to the value.
+     * <p>
+     * This is a shortcut for {@link #filterTry(CheckedPredicate, CheckedFunction1)}.
      *
-     * @param predicate A predicate
-     * @param errorProvider A function that provides some kind of Throwable for T
-     * @return a {@code Try} instance
-     * @throws NullPointerException if {@code predicate} or {@code errorProvider} is null
+     * @param predicate     the predicate to test the value
+     * @param errorProvider a function providing a throwable if the predicate fails
+     * @return this {@code Try} if the predicate passes, otherwise a {@link Failure} from the error provider
+     * @throws NullPointerException if {@code predicate} or {@code errorProvider} is {@code null}
      */
     default Try<T> filter(Predicate<? super T> predicate, Function<? super T, ? extends Throwable> errorProvider) {
         Objects.requireNonNull(predicate, "predicate is null");
@@ -381,11 +419,13 @@ default Try<T> filter(Predicate<? super T> predicate, Function<? super T, ? exte
     }
 
     /**
-     * Shortcut for {@code filterTry(predicate::test)}, see {@link #filterTry(CheckedPredicate)}}.
+     * Returns a {@code Try} if the given {@link Predicate} evaluates to {@code true}, otherwise returns a {@link Failure}.
+     * <p>
+     * This is a shortcut for {@link #filterTry(CheckedPredicate)}.
      *
-     * @param predicate A predicate
-     * @return a {@code Try} instance
-     * @throws NullPointerException if {@code predicate} is null
+     * @param predicate the predicate to test the value
+     * @return this {@code Try} if the predicate passes, otherwise a {@link Failure}
+     * @throws NullPointerException if {@code predicate} is {@code null}
      */
     default Try<T> filter(Predicate<? super T> predicate) {
         Objects.requireNonNull(predicate, "predicate is null");
@@ -393,16 +433,17 @@ default Try<T> filter(Predicate<? super T> predicate) {
     }
 
     /**
-     * Returns {@code this} if this is a Failure or this is a Success and the value satisfies the predicate.
+     * Returns {@code this} if this {@code Try} is a {@link Failure} or if it is a {@link Success} and the value
+     * satisfies the given checked predicate.
      * <p>
-     * Returns a new Failure, if this is a Success and the value does not satisfy the Predicate or an exception
-     * occurs testing the predicate. The returned Failure wraps a Throwable instance provided by the given
-     * {@code throwableSupplier}.
+     * If this is a {@link Success} and the predicate returns {@code false}, or if evaluating the predicate
+     * throws an exception, a new {@link Failure} is returned. The returned failure wraps a {@link Throwable}
+     * provided by the given {@code throwableSupplier}.
      *
-     * @param predicate         A checked predicate
-     * @param throwableSupplier A supplier of a throwable
-     * @return a {@code Try} instance
-     * @throws NullPointerException if {@code predicate} or {@code throwableSupplier} is null
+     * @param predicate         the checked predicate to test the value
+     * @param throwableSupplier a supplier providing the {@link Throwable} for the failure if the predicate does not hold
+     * @return this {@code Try} if it is a {@link Failure} or the predicate passes, otherwise a {@link Failure} from the supplier
+     * @throws NullPointerException if {@code predicate} or {@code throwableSupplier} is {@code null}
      */
     default Try<T> filterTry(CheckedPredicate<? super T> predicate, Supplier<? extends Throwable> throwableSupplier) {
         Objects.requireNonNull(predicate, "predicate is null");
@@ -424,16 +465,16 @@ default Try<T> filterTry(CheckedPredicate<? super T> predicate, Supplier<? exten
     }
 
     /**
-     * Returns {@code this} if this is a Failure or this is a Success and the value satisfies the predicate.
+     * Returns {@code this} if this {@code Try} is a {@link Failure} or if it is a {@link Success} and the value
+     * satisfies the given checked predicate.
      * <p>
-     * Returns a new Failure, if this is a Success and the value does not satisfy the Predicate or an exception
-     * occurs testing the predicate. The returned Failure wraps a Throwable instance provided by the given
-     * {@code errorProvider}.
+     * If the predicate does not hold or throws an exception, a new {@link Failure} is returned. The returned
+     * failure wraps a {@link Throwable} provided by the given {@code errorProvider} function.
      *
-     * @param predicate         A checked predicate
-     * @param errorProvider     A provider of a throwable
-     * @return a {@code Try} instance
-     * @throws NullPointerException if {@code predicate} or {@code errorProvider} is null
+     * @param predicate     the checked predicate to test the value
+     * @param errorProvider a function that provides a {@link Throwable} if the predicate fails
+     * @return this {@code Try} if it is a {@link Failure} or the predicate passes, otherwise a {@link Failure} from the error provider
+     * @throws NullPointerException if {@code predicate} or {@code errorProvider} is {@code null}
      */
     default Try<T> filterTry(CheckedPredicate<? super T> predicate, CheckedFunction1<? super T, ? extends Throwable> errorProvider) {
         Objects.requireNonNull(predicate, "predicate is null");
@@ -442,14 +483,15 @@ default Try<T> filterTry(CheckedPredicate<? super T> predicate, CheckedFunction1
     }
 
     /**
-     * Returns {@code this} if this is a Failure or this is a Success and the value satisfies the predicate.
+     * Returns {@code this} if this {@code Try} is a {@link Failure} or if it is a {@link Success} and the value
+     * satisfies the given checked predicate.
      * <p>
-     * Returns a new Failure, if this is a Success and the value does not satisfy the Predicate or an exception
-     * occurs testing the predicate. The returned Failure wraps a {@link NoSuchElementException} instance.
+     * If the predicate does not hold or throws an exception, a new {@link Failure} wrapping a
+     * {@link NoSuchElementException} is returned.
      *
-     * @param predicate A checked predicate
-     * @return a {@code Try} instance
-     * @throws NullPointerException if {@code predicate} is null
+     * @param predicate the checked predicate to test the value
+     * @return this {@code Try} if it is a {@link Failure} or the predicate passes, otherwise a {@link Failure} with a {@link NoSuchElementException}
+     * @throws NullPointerException if {@code predicate} is {@code null}
      */
     default Try<T> filterTry(CheckedPredicate<? super T> predicate) {
         Objects.requireNonNull(predicate, "predicate is null");
@@ -457,12 +499,15 @@ default Try<T> filterTry(CheckedPredicate<? super T> predicate) {
     }
 
     /**
-     * Shortcut for {@code flatMapTry(mapper::apply)}, see {@link #flatMapTry(CheckedFunction1)}.
+     * Transforms the value of this {@code Try} using the given {@link Function} if it is a {@link Success},
+     * or returns this {@link Failure}.
+     * <p>
+     * This is a shortcut for {@link #flatMapTry(CheckedFunction1)}.
      *
-     * @param mapper A mapper
-     * @param <U>    The new component type
-     * @return a {@code Try}
-     * @throws NullPointerException if {@code mapper} is null
+     * @param mapper a function mapping the value to another {@code Try}
+     * @param <U>    the type of the resulting {@code Try}
+     * @return a new {@code Try} resulting from applying the mapper, or this {@code Failure} if this is a failure
+     * @throws NullPointerException if {@code mapper} is {@code null}
      */
     default <U> Try<U> flatMap(Function<? super T, ? extends Try<? extends U>> mapper) {
         Objects.requireNonNull(mapper, "mapper is null");
@@ -470,12 +515,15 @@ default <U> Try<U> flatMap(Function<? super T, ? extends Try<? extends U>> mappe
     }
 
     /**
-     * FlatMaps the value of a Success or returns a Failure.
+     * Transforms the value of this {@code Try} using the given {@link CheckedFunction1} if it is a {@link Success},
+     * or returns this {@link Failure}.
+     * <p>
+     * If applying the mapper throws an exception, a {@link Failure} containing the exception is returned.
      *
-     * @param mapper A mapper
-     * @param <U>    The new component type
-     * @return a {@code Try}
-     * @throws NullPointerException if {@code mapper} is null
+     * @param mapper a checked function mapping the value to another {@code Try}
+     * @param <U>    the type of the resulting {@code Try}
+     * @return a new {@code Try} resulting from applying the mapper, or this {@code Failure} if this is a failure
+     * @throws NullPointerException if {@code mapper} is {@code null}
      */
     @SuppressWarnings("unchecked")
     default <U> Try<U> flatMapTry(CheckedFunction1<? super T, ? extends Try<? extends U>> mapper) {
@@ -492,29 +540,29 @@ default <U> Try<U> flatMapTry(CheckedFunction1<? super T, ? extends Try<? extend
     }
 
     /**
-     * Gets the result of this Try if this is a {@code Success} or throws if this is a {@code Failure}.
-     * <p>
-     * <strong>IMPORTANT! If this is a {@link Failure}, the underlying {@code cause} of type {@link Throwable} is thrown.</strong>
+     * Returns the value of this {@code Try} if it is a {@link Success}, or throws the underlying exception if it is a {@link Failure}.
      * <p>
-     * The thrown exception is exactly the same as the result of {@link #getCause()}.
+     * <strong>Important:</strong> If this {@code Try} is a {@link Failure}, the exception thrown is exactly the
+     * {@link #getCause()} of this {@code Failure}.
      *
-     * @return The result of this {@code Try}.
+     * @return the value contained in this {@code Success}
+     * throws Throwable the underlying cause sneakily if this is a {@link Failure}
      */
     @Override
     T get();
 
     /**
-     * Gets the cause if this is a Failure or throws if this is a Success.
+     * Returns the cause of failure if this {@code Try} is a {@link Failure}.
      *
-     * @return The cause if this is a Failure
-     * @throws UnsupportedOperationException if this is a Success
+     * @return the throwable cause of this {@link Failure}
+     * @throws UnsupportedOperationException if this {@code Try} is a {@link Success}
      */
     Throwable getCause();
 
     /**
-     * A {@code Try}'s value is computed synchronously.
+     * Indicates whether this {@code Try} is computed asynchronously.
      *
-     * @return false
+     * @return {@code false} for a regular {@code Try}, since the value is computed synchronously
      */
     @Override
     default boolean isAsync() {
@@ -522,24 +570,24 @@ default boolean isAsync() {
     }
 
     /**
-     * Checks whether this Try has no result, i.e. is a Failure.
+     * Checks whether this {@code Try} contains no value, i.e., it is a {@link Failure}.
      *
-     * @return true if this is a Failure, returns false if this is a Success.
+     * @return {@code true} if this is a {@link Failure}, {@code false} if this is a {@link Success}
      */
     @Override
     boolean isEmpty();
 
     /**
-     * Checks if this is a Failure.
+     * Checks whether this {@code Try} is a {@link Failure}.
      *
-     * @return true, if this is a Failure, otherwise false, if this is a Success
+     * @return {@code true} if this is a {@link Failure}, {@code false} if this is a {@link Success}
      */
     boolean isFailure();
 
     /**
-     * A {@code Try}'s value is computed eagerly.
+     * Indicates whether this {@code Try} is evaluated lazily.
      *
-     * @return false
+     * @return {@code false} for a standard {@code Try}, as its value is computed eagerly
      */
     @Override
     default boolean isLazy() {
@@ -547,9 +595,9 @@ default boolean isLazy() {
     }
 
     /**
-     * A {@code Try} is a single-valued.
+     * Indicates whether this {@code Try} represents a single value.
      *
-     * @return {@code true}
+     * @return {@code true}, since a {@code Try} always contains at most one value
      */
     @Override
     default boolean isSingleValued() {
@@ -557,9 +605,9 @@ default boolean isSingleValued() {
     }
 
     /**
-     * Checks if this is a Success.
+     * Checks whether this {@code Try} is a {@link Success}.
      *
-     * @return true, if this is a Success, otherwise false, if this is a Failure
+     * @return {@code true} if this is a {@link Success}, {@code false} if this is a {@link Failure}
      */
     boolean isSuccess();
 
@@ -593,12 +641,14 @@ default Try<Void> mapToVoid() {
     }
 
     /**
-     * Maps the cause to a new exception if this is a {@code Failure} or returns this instance if this is a {@code Success}.
+     * Transforms the cause of this {@link Failure} using the given sequence of match cases.
      * <p>
-     * If none of the given cases matches the cause, the same {@code Failure} is returned.
+     * If this {@code Try} is a {@link Success}, it is returned unchanged. If this is a {@link Failure}, the
+     * cause is matched against the provided {@code cases}. If a match is found, a new {@link Failure} containing
+     * the mapped exception is returned. If none of the cases match, the original {@link Failure} is returned.
      *
-     * @param cases A not necessarily exhaustive sequence of cases that will be matched against a cause.
-     * @return A new {@code Try} if this is a {@code Failure}, otherwise this.
+     * @param cases a possibly non-exhaustive sequence of match cases to handle the cause
+     * @return a new {@code Try} with a mapped cause if a match is found, otherwise this {@code Try}
      */
     @GwtIncompatible
     @SuppressWarnings({ "unchecked", "varargs" })
@@ -612,24 +662,21 @@ default Try<T> mapFailure(Match.Case<? extends Throwable, ? extends Throwable>..
     }
 
     /**
-     * Runs the given checked function if this is a {@link Try.Success},
-     * passing the result of the current expression to it.
-     * If this expression is a {@link Try.Failure} then it'll return a new
-     * {@link Try.Failure} of type R with the original exception.
+     * Applies the given checked function to the value of this {@link Success}, or returns this {@link Failure} unchanged.
      * <p>
-     * The main use case is chaining checked functions using method references:
-     *
-     * <pre>
-     * <code>
-     * Try.of(() -&gt; 0)
-     *    .map(x -&gt; 1 / x); // division by zero
-     * </code>
-     * </pre>
+     * If the function throws an exception, a new {@link Failure} containing the exception is returned.
+     * This allows chaining of computations that may throw checked exceptions.
+     * <p>
+     * Example:
+     * <pre><code>
+     * Try.of(() -> 0)
+     *    .mapTry(x -> 1 / x); // division by zero will result in a Failure
+     * </code></pre>
      *
-     * @param <U>    The new component type
-     * @param mapper A checked function
-     * @return a {@code Try}
-     * @throws NullPointerException if {@code mapper} is null
+     * @param <U>    the type of the result
+     * @param mapper a checked function to apply to the value
+     * @return a new {@code Try} containing the mapped value if this is a {@link Success}, otherwise this {@link Failure}
+     * @throws NullPointerException if {@code mapper} is {@code null}
      */
     @SuppressWarnings("unchecked")
     default <U> Try<U> mapTry(CheckedFunction1<? super T, ? extends U> mapper) {
@@ -646,18 +693,19 @@ default <U> Try<U> mapTry(CheckedFunction1<? super T, ? extends U> mapper) {
     }
 
     /**
-     * Consumes the cause if this is a {@link Try.Failure}.
-     *
+     * Performs the given action if this {@link Try} is a {@link Failure}.
+     * <p>
+     * Example:
      * <pre>{@code
-     * // (does not print anything)
+     * // does not print anything
      * Try.success(1).onFailure(System.out::println);
      *
      * // prints "java.lang.Error"
      * Try.failure(new Error()).onFailure(System.out::println);
      * }</pre>
      *
-     * @param action An exception consumer
-     * @return this
+     * @param action a consumer of the throwable cause
+     * @return this {@code Try} instance
      * @throws NullPointerException if {@code action} is null
      */
     default Try<T> onFailure(Consumer<? super Throwable> action) {
@@ -669,10 +717,11 @@ default Try<T> onFailure(Consumer<? super Throwable> action) {
     }
 
     /**
-     * Consumes the cause if this is a {@link Try.Failure} and the cause is instance of {@code X}.
-     *
+     * Performs the given action if this {@link Try} is a {@link Failure} and the cause is an instance of the specified type.
+     * <p>
+     * Example:
      * <pre>{@code
-     * // (does not print anything)
+     * // does not print anything
      * Try.success(1).onFailure(Error.class, System.out::println);
      *
      * // prints "Error"
@@ -680,11 +729,11 @@ default Try<T> onFailure(Consumer<? super Throwable> action) {
      *    .onFailure(RuntimeException.class, x -> System.out.println("Runtime exception"))
      *    .onFailure(Error.class, x -> System.out.println("Error"));
      * }</pre>
-     * 
-     * @param exceptionType the exception type that is handled
-     * @param action an excpetion consumer
-     * @param <X> the exception type that should be handled
-     * @return this
+     *
+     * @param exceptionType the type of exception to handle
+     * @param action        a consumer for the exception
+     * @param <X>           the type of exception that should be handled
+     * @return this {@code Try} instance
      * @throws NullPointerException if {@code exceptionType} or {@code action} is null
      */
     @GwtIncompatible
@@ -699,18 +748,19 @@ default <X extends Throwable> Try<T> onFailure(Class<X> exceptionType, Consumer<
     }
 
     /**
-     * Consumes the value if this is a {@link Try.Success}.
-     *
+     * Performs the given action if this {@link Try} is a {@link Success}.
+     * <p>
+     * Example:
      * <pre>{@code
      * // prints "1"
      * Try.success(1).onSuccess(System.out::println);
      *
-     * // (does not print anything)
+     * // does not print anything
      * Try.failure(new Error()).onSuccess(System.out::println);
      * }</pre>
      *
-     * @param action A value consumer
-     * @return this
+     * @param action a consumer of the value
+     * @return this {@code Try} instance
      * @throws NullPointerException if {@code action} is null
      */
     default Try<T> onSuccess(Consumer<? super T> action) {
@@ -721,18 +771,41 @@ default Try<T> onSuccess(Consumer<? super T> action) {
         return this;
     }
 
+    /**
+     * Returns this {@code Try} if it is a {@link Success}, or the given alternative {@code Try} if this is a {@link Failure}.
+     *
+     * @param other the alternative {@code Try} to return if this is a {@link Failure}
+     * @return this {@code Try} if success, otherwise {@code other}
+     * @throws NullPointerException if {@code other} is null
+     */
     @SuppressWarnings("unchecked")
     default Try<T> orElse(Try<? extends T> other) {
         Objects.requireNonNull(other, "other is null");
         return isSuccess() ? this : (Try<T>) other;
     }
 
+    /**
+     * Returns this {@code Try} if it is a {@link Success}, or a {@code Try} supplied by the given {@link Supplier} if this is a {@link Failure}.
+     * <p>
+     * The supplier is only invoked if this {@code Try} is a {@link Failure}.
+     *
+     * @param supplier a supplier of an alternative {@code Try}
+     * @return this {@code Try} if success, otherwise the {@code Try} returned by {@code supplier}
+     * @throws NullPointerException if {@code supplier} is null
+     */
     @SuppressWarnings("unchecked")
     default Try<T> orElse(Supplier<? extends Try<? extends T>> supplier) {
         Objects.requireNonNull(supplier, "supplier is null");
         return isSuccess() ? this : (Try<T>) supplier.get();
     }
 
+    /**
+     * Returns the value of this {@code Success}, or applies the given function to the cause if this is a {@link Failure}.
+     *
+     * @param other a function mapping the throwable cause to a replacement value
+     * @return the value of this {@link Success}, or the result of applying {@code other} to the failure cause
+     * @throws NullPointerException if {@code other} is null
+     */
     default T getOrElseGet(Function<? super Throwable, ? extends T> other) {
         Objects.requireNonNull(other, "other is null");
         if (isFailure()) {
@@ -742,6 +815,14 @@ default T getOrElseGet(Function<? super Throwable, ? extends T> other) {
         }
     }
 
+    /**
+     * Executes the given action if this {@code Try} is a {@link Failure}.
+     * <p>
+     * This method is typically used for side-effecting handling of failure cases.
+     *
+     * @param action a consumer of the throwable cause
+     * @throws NullPointerException if {@code action} is null
+     */
     default void orElseRun(Consumer<? super Throwable> action) {
         Objects.requireNonNull(action, "action is null");
         if (isFailure()) {
@@ -749,6 +830,18 @@ default void orElseRun(Consumer<? super Throwable> action) {
         }
     }
 
+
+    /**
+     * Returns the value of this {@link Success}, or throws a provided exception if this is a {@link Failure}.
+     * <p>
+     * The exception to throw is created by applying the given {@code exceptionProvider} function to the cause of the failure.
+     *
+     * @param <X>               the type of the exception to throw
+     * @param exceptionProvider a function mapping the throwable cause to an exception to be thrown
+     * @return the value of this {@link Success}
+     * @throws X                     the exception provided by {@code exceptionProvider} if this is a {@link Failure}
+     * @throws NullPointerException  if {@code exceptionProvider} is null
+     */
     default <X extends Throwable> T getOrElseThrow(Function<? super Throwable, X> exceptionProvider) throws X {
         Objects.requireNonNull(exceptionProvider, "exceptionProvider is null");
         if (isFailure()) {
@@ -759,12 +852,16 @@ default <X extends Throwable> T getOrElseThrow(Function<? super Throwable, X> ex
     }
 
     /**
-     * Folds either the {@code Failure} or the {@code Success} side of the Try value.
+     * Folds this {@code Try} into a single value by applying one of two functions:
+     * one for the failure case and one for the success case.
+     * <p>
+     * If this is a {@link Failure}, the {@code ifFail} function is applied to the cause.
+     * If this is a {@link Success}, the {@code f} function is applied to the value.
      *
-     * @param ifFail  maps the left value if this is a {@code Failure}
-     * @param f maps the value if this is a {@code Success}
-     * @param <X>         type of the folded value
-     * @return A value of type X
+     * @param ifFail maps the throwable cause if this is a {@link Failure}
+     * @param f      maps the value if this is a {@link Success}
+     * @param <X>    the type of the result
+     * @return the result of applying the corresponding function
      */
     default <X> X fold(Function<? super Throwable, ? extends X> ifFail, Function<? super T, ? extends X> f) {
         if (isFailure()) {
@@ -775,10 +872,12 @@ default <X> X fold(Function<? super Throwable, ? extends X> ifFail, Function<? s
     }
 
     /**
-     * Applies the action to the value of a Success or does nothing in the case of a Failure.
+     * Performs the given action if this {@code Try} is a {@link Success}, otherwise does nothing.
+     * <p>
+     * This method is useful for side-effecting operations without transforming the value.
      *
-     * @param action A Consumer
-     * @return this {@code Try}
+     * @param action a consumer of the value
+     * @return this {@code Try} instance
      * @throws NullPointerException if {@code action} is null
      */
     @Override
@@ -790,11 +889,15 @@ default Try<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+
     /**
-     * Returns {@code this}, if this is a {@code Success} or this is a {@code Failure} and the cause is not assignable
-     * from {@code cause.getClass()}. Otherwise tries to recover the exception of the failure with {@code f},
-     * i.e. calling {@code Try.of(() -> f.apply((X) getCause())}.
-     *
+     * Attempts to recover from a failure if the cause is an instance of the specified exception type.
+     * <p>
+     * If this {@code Try} is a {@link Success}, it is returned unchanged. If this is a {@link Failure} and the cause
+     * is assignable from {@code exceptionType}, the recovery function {@code f} is applied to the cause inside a new {@code Try}.
+     * Otherwise, the original {@code Failure} is returned.
+     * <p>
+     * Example:
      * <pre>{@code
      * // = Success(13)
      * Try.of(() -> 27/2).recover(ArithmeticException.class, x -> Integer.MAX_VALUE);
@@ -808,11 +911,11 @@ default Try<T> peek(Consumer<? super T> action) {
      * Try.of(() -> 1/0).recover(Error.class, x -> Integer.MAX_VALUE);
      * }</pre>
      *
-     * @param <X>           Exception type
-     * @param exceptionType The specific exception type that should be handled
-     * @param f             A recovery function taking an exception of type {@code X}
-     * @return a {@code Try}
-     * @throws NullPointerException if {@code exception} is null or {@code f} is null
+     * @param <X>           the type of exception to handle
+     * @param exceptionType the specific exception type that should be recovered
+     * @param f             a recovery function taking an exception of type {@code X} and producing a value
+     * @return a {@code Success} with the recovered value if the exception matches, otherwise this {@code Try}
+     * @throws NullPointerException if {@code exceptionType} or {@code f} is null
      */
     @GwtIncompatible
     @SuppressWarnings("unchecked")
@@ -828,12 +931,16 @@ default <X extends Throwable> Try<T> recover(Class<X> exceptionType, Function<?
         return this;
     }
 
+
     /**
-     * Returns {@code this} if this is a {@code Success}, or if this is a {@code Failure} and the cause is not assignable
-     * from {@code exceptionType}. Otherwise, attempts to recover from the failure using the provided recovery function {@code f}.
-     * The recovery function returns a new {@code Try} instance. If the returned {@code Try} is a {@link Try#isFailure()},
-     * it indicates that the recovery was not successful.
-     *
+     * Attempts to recover from a failure by applying the given recovery function if the cause matches the specified exception type.
+     * <p>
+     * If this {@code Try} is a {@link Success}, it is returned unchanged. If this is a {@link Failure} and the cause
+     * is assignable from {@code exceptionType}, the recovery function {@code f} is applied to the cause and returns a new {@code Try}.
+     * If the returned {@code Try} is a {@link Try#isFailure()}, the recovery is considered unsuccessful.
+     * Otherwise, the original {@code Failure} is returned.
+     * <p>
+     * Example:
      * <pre>{@code
      * // = Success(13)
      * Try.of(() -> 27/2).recoverWith(ArithmeticException.class, x -> Try.success(Integer.MAX_VALUE));
@@ -846,20 +953,19 @@ default <X extends Throwable> Try<T> recover(Class<X> exceptionType, Function<?
      * // = Failure(java.lang.ArithmeticException: / by zero)
      * Try.of(() -> 1/0).recoverWith(Error.class, x -> Try.success(Integer.MAX_VALUE));
      * }</pre>
-     * 
-     * @param <X>           Exception type
-     * @param exceptionType The specific exception type that should be handled
-     * @param f             A recovery function that takes an exception of type {@code X} and returns a new Try instance.
-     *                      The recovery is considered successful if the returned Try is a {@link Try#isSuccess()}.
-     * @return a {@code Try}
+     *
+     * @param <X>           the type of exception to handle
+     * @param exceptionType the specific exception type that should trigger recovery
+     * @param f             a recovery function that takes an exception of type {@code X} and returns a new {@code Try} instance
+     * @return a {@code Try} representing the recovered value if the exception matches, otherwise this {@code Try}
      * @throws NullPointerException if {@code exceptionType} or {@code f} is null
      */
     @GwtIncompatible
     @SuppressWarnings("unchecked")
-    default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType, Function<? super X, Try<? extends T>> f){
+    default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType, Function<? super X, Try<? extends T>> f) {
         Objects.requireNonNull(exceptionType, "exceptionType is null");
         Objects.requireNonNull(f, "f is null");
-        if(isFailure()){
+        if (isFailure()) {
             final Throwable cause = getCause();
             if (exceptionType.isAssignableFrom(cause.getClass())) {
                 try {
@@ -872,10 +978,15 @@ default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType, Functio
         return this;
     }
 
+
     /**
-     * Recovers this {@code Try} with the given {@code recovered}, if this is a {@link Try.Failure}
-     * and the given {@code exceptionType} is assignable to the underlying cause type.
-     *
+     * Recovers this {@code Try} with the given {@code recovered} value if this is a {@link Try.Failure}
+     * and the underlying cause is assignable to the specified {@code exceptionType}.
+     * <p>
+     * If this {@code Try} is a {@link Success}, or if the cause does not match {@code exceptionType},
+     * the original {@code Try} is returned unchanged.
+     * <p>
+     * Example:
      * <pre>{@code
      * // = Success(13)
      * Try.of(() -> 27/2).recoverWith(ArithmeticException.class, Try.success(Integer.MAX_VALUE));
@@ -889,56 +1000,65 @@ default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType, Functio
      * Try.of(() -> 1/0).recoverWith(Error.class, Try.success(Integer.MAX_VALUE));
      * }</pre>
      *
-     * @param exceptionType the exception type that is recovered
-     * @param recovered the substitute for a matching {@code Failure}
-     * @param <X> type of the exception that should be recovered
-     * @return the given {@code recovered} if this is a {@link Try.Failure} and the cause is of type {@code X}, else {@code this}
+     * @param <X>           the type of exception to handle
+     * @param exceptionType the exception type that triggers recovery
+     * @param recovered     a {@code Try} instance to return if the cause matches {@code exceptionType}
+     * @return the given {@code recovered} if the exception matches, otherwise this {@code Try}
      * @throws NullPointerException if {@code exceptionType} or {@code recovered} is null
      */
     @GwtIncompatible
-    default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType,  Try<? extends T> recovered){
+    default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType, Try<? extends T> recovered) {
         Objects.requireNonNull(exceptionType, "exceptionType is null");
         Objects.requireNonNull(recovered, "recovered is null");
         return (isFailure() && exceptionType.isAssignableFrom(getCause().getClass()))
-                ? narrow(recovered)
-                : this;
+          ? narrow(recovered)
+          : this;
     }
 
+
     /**
-     * Returns {@code this}, if this is a {@link Try.Success} or this is a {@code Failure} and the cause is not assignable
-     * from {@code cause.getClass()}. Otherwise returns a {@link Try.Success} containing the given {@code value}.
-     *
+     * Recovers this {@code Try} with the given {@code value} if this is a {@link Try.Failure}
+     * and the underlying cause matches the specified {@code exceptionType}.
+     * <p>
+     * If this {@code Try} is a {@link Success}, or if the cause is not assignable from {@code exceptionType},
+     * the original {@code Try} is returned unchanged.
+     * <p>
+     * Example:
      * <pre>{@code
      * // = Success(13)
-     * Try.of(() -> 27/2).recover(ArithmeticException.class, Integer.MAX_VALUE);
+     * Try.of(() -> 27/2).recover(ArithmeticException.class, 13);
      *
      * // = Success(2147483647)
      * Try.of(() -> 1/0)
-     *    .recover(Error.class, -1);
+     *    .recover(Error.class, -1)
      *    .recover(ArithmeticException.class, Integer.MAX_VALUE);
      *
      * // = Failure(java.lang.ArithmeticException: / by zero)
      * Try.of(() -> 1/0).recover(Error.class, Integer.MAX_VALUE);
      * }</pre>
      *
-     * @param <X>           Exception type
-     * @param exceptionType The specific exception type that should be handled
-     * @param value         A value that is used in case of a recovery
-     * @return a {@code Try}
+     * @param <X>           the type of exception to handle
+     * @param exceptionType the exception type that triggers recovery
+     * @param value         the value to return in a {@link Try.Success} if the cause matches
+     * @return a {@code Try} containing the recovery value if the exception matches, otherwise this {@code Try}
      * @throws NullPointerException if {@code exceptionType} is null
      */
     @GwtIncompatible
     default <X extends Throwable> Try<T> recover(Class<X> exceptionType, T value) {
         Objects.requireNonNull(exceptionType, "exceptionType is null");
         return (isFailure() && exceptionType.isAssignableFrom(getCause().getClass()))
-               ? Try.success(value)
-               : this;
+          ? Try.success(value)
+          : this;
     }
 
+
     /**
-     * Returns {@code this}, if this is a {@code Success}, otherwise tries to recover the exception of the failure with {@code f},
-     * i.e. calling {@code Try.of(() -> f.apply(throwable))}.
-     *
+     * Recovers this {@code Try} if it is a {@link Try.Failure} by applying the given recovery function {@code f}
+     * to the underlying exception. The result of the function is wrapped in a {@link Try.Success}.
+     * <p>
+     * If this {@code Try} is already a {@link Success}, it is returned unchanged.
+     * <p>
+     * Example:
      * <pre>{@code
      * // = Success(13)
      * Try.of(() -> 27/2).recover(x -> Integer.MAX_VALUE);
@@ -947,8 +1067,8 @@ default <X extends Throwable> Try<T> recover(Class<X> exceptionType, T value) {
      * Try.of(() -> 1/0).recover(x -> Integer.MAX_VALUE);
      * }</pre>
      *
-     * @param f A recovery function taking a Throwable
-     * @return a {@code Try}
+     * @param f A recovery function that takes the underlying exception and returns a value
+     * @return a {@code Try} containing either the original success value or the recovered value
      * @throws NullPointerException if {@code f} is null
      */
     default Try<T> recover(Function<? super Throwable, ? extends T> f) {
@@ -960,11 +1080,16 @@ default Try<T> recover(Function<? super Throwable, ? extends T> f) {
         }
     }
 
+
     /**
-     * Returns {@code this}, if this is a Success, otherwise tries to recover the exception of the failure with {@code f},
-     * i.e. calling {@code f.apply(cause.getCause())}. If an error occurs recovering a Failure, then the new Failure is
-     * returned.
-     *
+     * Recovers this {@code Try} if it is a {@link Try.Failure} by applying the given recovery function {@code f}
+     * to the underlying exception. The recovery function returns a new {@code Try} instance. 
+     * <p>
+     * If this {@code Try} is already a {@link Success}, it is returned unchanged. 
+     * If an exception occurs while executing the recovery function, a new {@link Try.Failure} is returned 
+     * wrapping that exception.
+     * <p>
+     * Example:
      * <pre>{@code
      * // = Success(13)
      * Try.of(() -> 27/2).recoverWith(x -> Try.success(Integer.MAX_VALUE));
@@ -973,8 +1098,8 @@ default Try<T> recover(Function<? super Throwable, ? extends T> f) {
      * Try.of(() -> 1/0).recoverWith(x -> Try.success(Integer.MAX_VALUE));
      * }</pre>
      *
-     * @param f A recovery function taking a Throwable
-     * @return a {@code Try}
+     * @param f A recovery function that takes the underlying exception and returns a new {@code Try}
+     * @return a {@code Try} containing either the original success value or the recovered {@code Try}
      * @throws NullPointerException if {@code f} is null
      */
     @SuppressWarnings("unchecked")
@@ -992,9 +1117,12 @@ default Try<T> recoverWith(Function<? super Throwable, ? extends Try<? extends T
     }
 
     /**
-     * Returns {@code this}, if this is a {@link Try.Success}, otherwise attempts to recover from any failure
-     * by evaluating the given {@code recoveryAttempt} (via {@link Try#of(CheckedFunction0)}).
-     *
+     * Recovers from any failure by evaluating the given {@code recoveryAttempt} if this {@code Try} is a {@link Try.Failure}.
+     * <p>
+     * If this {@code Try} is already a {@link Success}, it is returned unchanged. The {@code recoveryAttempt} is
+     * evaluated using {@link Try#of(CheckedFunction0)}, and its result is wrapped in a new {@code Try}.
+     * <p>
+     * Example:
      * <pre>{@code
      * // = Success(5)
      * Try.of(() -> 5)
@@ -1005,8 +1133,8 @@ default Try<T> recoverWith(Function<? super Throwable, ? extends Try<? extends T
      *    .recoverAllAndTry(() -> 10);
      * }</pre>
      *
-     * @param recoveryAttempt A checked function that provides a fallback in case of a failure
-     * @return a {@code Try} that is either this {@code Success} or a new {@code Try} evaluated from {@code recoveryAttempt}
+     * @param recoveryAttempt A checked supplier providing a fallback value in case of failure
+     * @return a {@code Try} containing either the original success value or the result of {@code recoveryAttempt}
      * @throws NullPointerException if {@code recoveryAttempt} is null
      */
     default Try<T> recoverAllAndTry(CheckedFunction0<? extends T> recoveryAttempt) {
@@ -1014,11 +1142,13 @@ default Try<T> recoverAllAndTry(CheckedFunction0<? extends T> recoveryAttempt) {
         return isFailure() ? of(recoveryAttempt) : this;
     }
 
+
     /**
-     * Returns {@code this}, if this is a {@link Try.Success}, otherwise attempts to recover from failure when the
-     * underlying cause is assignable to the specified {@code exceptionType}, by evaluating the given
+     * Returns {@code this} if it is a {@link Try.Success}, or attempts to recover from a failure when the
+     * underlying cause is assignable to the specified {@code exceptionType} by evaluating the given
      * {@code recoveryAttempt} (via {@link Try#of(CheckedFunction0)}).
-     *
+     * <p>
+     * Example usage:
      * <pre>{@code
      * // = Success(5)
      * Try.of(() -> 5)
@@ -1033,24 +1163,28 @@ default Try<T> recoverAllAndTry(CheckedFunction0<? extends T> recoveryAttempt) {
      *    .recoverAndTry(NullPointerException.class, () -> 10);
      * }</pre>
      *
-     * @param <X>            The type of the exception that may be recovered
-     * @param exceptionType  The specific exception type that should trigger the recovery
-     * @param recoveryAttempt A checked function that provides a fallback in case of a matching failure
-     * @return a {@code Try} that is either this {@code Success}, or a new {@code Try} evaluated from {@code recoveryAttempt}
+     * @param <X>             The type of the exception that may be recovered
+     * @param exceptionType   The specific exception type that triggers the recovery
+     * @param recoveryAttempt A checked function providing a fallback value if the exception matches
+     * @return a {@code Try} containing either the original success value or the result of {@code recoveryAttempt}
      * @throws NullPointerException if {@code exceptionType} or {@code recoveryAttempt} is null
      */
     default <X extends Throwable> Try<T> recoverAndTry(Class<X> exceptionType, CheckedFunction0<? extends T> recoveryAttempt) {
         Objects.requireNonNull(exceptionType, "exceptionType is null");
         Objects.requireNonNull(recoveryAttempt, "recoveryAttempt is null");
         return isFailure() && exceptionType.isAssignableFrom(getCause().getClass())
-                ? of(recoveryAttempt)
-                : this;
+          ? of(recoveryAttempt)
+          : this;
     }
 
+
     /**
      * Converts this {@code Try} to an {@link Either}.
+     * <p>
+     * If this is a {@link Try.Success}, the value is wrapped as a {@link Either#right(Object)}.
+     * If this is a {@link Try.Failure}, the cause is wrapped as a {@link Either#left(Object)}.
      *
-     * @return A new {@code Either}
+     * @return a new {@code Either} representing this {@code Try}
      */
     default Either<Throwable, T> toEither() {
         if (isFailure()) {
@@ -1061,13 +1195,13 @@ default Either<Throwable, T> toEither() {
     }
 
     /**
-     * Converts this {@code Try} to an {@link Either}, converting the Throwable (in the failure case)
-     * to a left value using the passed {@link Function}.
+     * Converts this {@code Try} to an {@link Either}, mapping the failure cause to a left value using
+     * the provided {@link Function}.
      *
-     * @param <L> left type of the resulting Either
-     * @param throwableMapper A transformation from throwable to the left type of the new {@code Either}
-     * @return A new {@code Either}
-     * @throws NullPointerException if the given {@code throwableMapper} is null
+     * @param <L>             the left type of the resulting {@code Either}
+     * @param throwableMapper a function to convert the failure {@link Throwable} to type {@code L}
+     * @return a new {@code Either} representing this {@code Try}
+     * @throws NullPointerException if {@code throwableMapper} is null
      */
     default <L> Either<L, T> toEither(Function<? super Throwable, ? extends L> throwableMapper) {
         Objects.requireNonNull(throwableMapper, "throwableMapper is null");
@@ -1080,25 +1214,29 @@ default <L> Either<L, T> toEither(Function<? super Throwable, ? extends L> throw
 
     /**
      * Converts this {@code Try} to a {@link Validation}.
+     * <p>
+     * A {@link Try.Success} is converted to a {@link Validation#valid(Object)}, while
+     * a {@link Try.Failure} is converted to a {@link Validation#invalid(Object)} containing
+     * the cause.
      *
-     * @return A new {@code Validation}
+     * @return a new {@code Validation} representing this {@code Try}
      */
     default Validation<Throwable, T> toValidation() {
         return toValidation(Function.identity());
     }
 
     /**
-     * Converts this {@code Try} to a {@link Validation}, converting the Throwable (in the failure case)
-     * to another object using the passed {@link Function}.
+     * Converts this {@code Try} to a {@link Validation}, mapping the failure cause to an invalid value
+     * using the provided {@link Function}.
      *
      * <pre>{@code
-     * Validation<String, Integer> = Try.of(() -> 1/0).toValidation(Throwable::getMessage));
+     * Validation<String, Integer> validation = Try.of(() -> 1/0).toValidation(Throwable::getMessage);
      * }</pre>
      *
-     * @param <U> result type of the throwable mapper
-     * @param throwableMapper  A transformation from throwable to desired invalid type of new {@code Validation}
-     * @return A new {@code Validation}
-     * @throws NullPointerException if the given {@code throwableMapper} is null.
+     * @param <U>             the type of the invalid value
+     * @param throwableMapper a function to convert the failure {@link Throwable} to type {@code U}
+     * @return a {@code Validation} representing this {@code Try}
+     * @throws NullPointerException if {@code throwableMapper} is null
      */
     default <U> Validation<U, T> toValidation(Function<? super Throwable, ? extends U> throwableMapper) {
         Objects.requireNonNull(throwableMapper, "throwableMapper is null");
@@ -1110,11 +1248,11 @@ default <U> Validation<U, T> toValidation(Function<? super Throwable, ? extends
     }
 
     /**
-     * Transforms this {@code Try}.
+     * Transforms this {@code Try} into a value of another type using the provided function.
      *
-     * @param f   A transformation
-     * @param <U> Type of transformation result
-     * @return An instance of type {@code U}
+     * @param f   a transformation function
+     * @param <U> the result type of the transformation
+     * @return the result of applying {@code f} to this {@code Try}
      * @throws NullPointerException if {@code f} is null
      */
     default <U> U transform(Function<? super Try<T>, ? extends U> f) {
@@ -1123,10 +1261,11 @@ default <U> U transform(Function<? super Try<T>, ? extends U> f) {
     }
 
     /**
-     * Provides try's finally behavior no matter what the result of the operation is.
+     * Executes a given {@link Runnable} after this {@code Try}, regardless of whether it is a
+     * {@link Try.Success} or {@link Try.Failure}.
      *
-     * @param runnable A runnable
-     * @return this {@code Try}.
+     * @param runnable a final action to perform
+     * @return this {@code Try} unchanged if the runnable succeeds, or a new {@link Try.Failure} if it throws
      * @throws NullPointerException if {@code runnable} is null
      */
     default Try<T> andFinally(Runnable runnable) {
@@ -1135,10 +1274,11 @@ default Try<T> andFinally(Runnable runnable) {
     }
 
     /**
-     * Provides try's finally behavior no matter what the result of the operation is.
+     * Executes a given {@link CheckedRunnable} after this {@code Try}, regardless of whether it is a
+     * {@link Try.Success} or {@link Try.Failure}.
      *
-     * @param runnable A runnable
-     * @return this {@code Try}.
+     * @param runnable a checked final action to perform
+     * @return this {@code Try} unchanged if the runnable succeeds, or a new {@link Try.Failure} if it throws
      * @throws NullPointerException if {@code runnable} is null
      */
     default Try<T> andFinallyTry(CheckedRunnable runnable) {
@@ -1161,9 +1301,18 @@ default Try<T> andFinallyTry(CheckedRunnable runnable) {
     String toString();
 
     /**
-     * A succeeded Try.
+     * Represents a successful {@link Try} containing a value.
+     * <p>
+     * Instances of this class indicate that the computation completed successfully
+     * and hold the resulting value of type {@code T}.
+     *
+     * <pre>{@code
+     * Try<Integer> success = new Try.Success<>(42);
+     * success.isSuccess(); // true
+     * success.get();       // 42
+     * }</pre>
      *
-     * @param <T> component type of this Success
+     * @param <T> the type of the contained value
      * @author Daniel Dietrich
      */
     final class Success<T> implements Try<T>, Serializable {
@@ -1229,9 +1378,18 @@ public String toString() {
     }
 
     /**
-     * A failed Try.
+     * Represents a failed {@link Try} containing a {@link Throwable} as the cause.
+     * <p>
+     * Instances of this class indicate that the computation threw an exception
+     * and do not contain a successful value.
+     *
+     * <pre>{@code
+     * Try<Integer> failure = new Try.Failure<>(new RuntimeException("error"));
+     * failure.isFailure();  // true
+     * failure.getCause();   // RuntimeException: error
+     * }</pre>
      *
-     * @param <T> component type of this Failure
+     * @param <T> the type of the value that would have been contained if successful
      * @author Daniel Dietrich
      */
     final class Failure<T> implements Try<T>, Serializable {
@@ -1245,7 +1403,7 @@ final class Failure<T> implements Try<T>, Serializable {
          *
          * @param cause A cause of type Throwable, may not be null.
          * @throws NullPointerException if {@code cause} is null
-         * @throws Throwable            if the given {@code cause} is fatal, i.e. non-recoverable
+         * throws Throwable             sneakily, if the given {@code cause} is fatal, i.e. non-recoverable
          */
         private Failure(Throwable cause) {
             Objects.requireNonNull(cause, "cause is null");
@@ -1788,7 +1946,7 @@ static <T extends Throwable, R> R sneakyThrow(Throwable t) throws T {
         throw (T) t;
     }
 
-    static class ThreadDeathResolver {
+    class ThreadDeathResolver {
         static final Class<?> THREAD_DEATH_CLASS = resolve();
 
         static boolean isThreadDeath(Throwable throwable) {
diff --git a/vavr/src/main/java/io/vavr/control/Validation.java b/vavr/src/main/java/io/vavr/control/Validation.java
index d3bb8ec24..788d2b7f2 100644
--- a/vavr/src/main/java/io/vavr/control/Validation.java
+++ b/vavr/src/main/java/io/vavr/control/Validation.java
@@ -31,46 +31,49 @@
 import java.util.function.Supplier;
 
 /**
- * An implementation similar to scalaz's <a href="http://eed3si9n.com/learning-scalaz/Validation.html">Validation</a> control.
+ * An implementation similar to Scalaz's 
+ * <a href="http://eed3si9n.com/learning-scalaz/Validation.html">Validation</a> control.
  *
  * <p>
- * The Validation type is different from a Monad type, it is an applicative
- * functor. Whereas a Monad will short circuit after the first error, the
- * applicative functor will continue on, accumulating ALL errors. This is
- * especially helpful in cases such as validation, where you want to know
- * all the validation errors that have occurred, not just the first one.
+ * The {@code Validation} type is an applicative functor, not a Monad. While a Monad
+ * short-circuits on the first error, an applicative functor accumulates all errors,
+ * making it particularly useful for validation scenarios where all errors should be reported.
  * </p>
  *
  * <pre>
  * <code>
- * <b>Validation construction:</b>
+ * // Validation construction:
  *
- * <i>Valid:</i>
- * Validation&lt;String,Integer&gt; valid = Validation.valid(5);
+ * // Valid
+ * Validation&lt;String, Integer&gt; valid = Validation.valid(5);
  *
- * <i>Invalid:</i>
- * Validation&lt;List&lt;String&gt;,Integer&gt; invalid = Validation.invalid(List.of("error1","error2"));
+ * // Invalid
+ * Validation&lt;List&lt;String>, Integer&gt;invalid = Validation.invalid(List.of("error1", "error2"));
  *
- * <b>Validation combination:</b>
+ * // Validation combination:
  *
- * Validation&lt;String,String&gt; valid1 = Validation.valid("John");
- * Validation&lt;String,Integer&gt; valid2 = Validation.valid(5);
- * Validation&lt;String,Option&lt;String&gt;&gt; valid3 = Validation.valid(Option.of("123 Fake St."));
- * Function3&lt;String,Integer,Option&lt;String&gt;,Person&gt; f = ...;
+ * Validation&lt;String, String> valid1 = Validation.valid("John");
+ * Validation&lt;String, Integer> valid2 = Validation.valid(5);
+ * Validation&lt;String, Option&lt;String&gt;&gt; valid3 = Validation.valid(Option.of("123 Fake St."));
+ * Function3&lt;String, Integer, Option&lt;String&gt;, Person> f = ...;
  *
- * Validation&lt;List&lt;String&gt;,String&gt; result = valid1.combine(valid2).ap((name,age) -&gt; "Name: "+name+" Age: "+age);
- * Validation&lt;List&lt;String&gt;,Person&gt; result2 = valid1.combine(valid2).combine(valid3).ap(f);
+ * Validation&lt;List&lt;String&gt;, String&gt; result =
+ *     valid1.combine(valid2).ap((name, age) -> "Name: " + name + " Age: " + age);
  *
- * <b>Another form of combining validations:</b>
+ * Validation&lt;List&lt;String&gt;, Person&gt; result2 =
+ *     valid1.combine(valid2).combine(valid3).ap(f);
  *
- * Validation&lt;List&lt;String&gt;,Person&gt; result3 = Validation.combine(valid1, valid2, valid3).ap(f);
+ * // Another way to combine validations:
+ * Validation&lt;List&lt;String&gt;, Person&gt; result3 =
+ *     Validation.combine(valid1, valid2, valid3).ap(f);
  * </code>
  * </pre>
  *
- * @param <E> value type in the case of invalid
- * @param <T> value type in the case of valid
+ * @param <E> the type of values in the case of invalid
+ * @param <T> the type of values in the case of valid
  * @author Eric Nelson
- * @see <a href="https://github.com/scalaz/scalaz/blob/series/7.3.x/core/src/main/scala/scalaz/Validation.scala">Validation</a>
+ * @see <a href="https://github.com/scalaz/scalaz/blob/series/7.3.x/core/src/main/scala/scalaz/Validation.scala">
+ *     Scalaz Validation source</a>
  */
 public interface Validation<E, T> extends Value<T>, Serializable {