Control structures JavaDocs overhaul

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

vavr/src/main/java/io/vavr/CheckedConsumer.java

@@ -24,49 +24,50 @@
 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) {
         return 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 -> {

vavr/src/main/java/io/vavr/CheckedPredicate.java

@@ -23,30 +23,31 @@
 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
  */
 @FunctionalInterface
 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 -> {

vavr/src/main/java/io/vavr/CheckedRunnable.java

@@ -21,45 +21,48 @@
 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) {
         return 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 () -> {