Array/Try/Multimap JavaDocs overhaul (#2996)

Author: pivovarit

vavr/src/main/java/io/vavr/collection/AbstractMultimap.java

@@ -30,11 +30,13 @@
 import static io.vavr.API.Tuple;
 
 /**
- * An {@link Multimap} implementation (not intended to be public).
+ * An abstract base implementation of the {@link Multimap} interface that provides
+ * common functionality for concrete Multimap implementations. This class is not
+ * intended to be public and serves as a foundation for specialized Multimap types.
  *
  * @param <K> Key type
  * @param <V> Value type
- * @param <M> Multimap type
+ * @param <M> Concrete Multimap type extending this class
  * @author Ruslan Sennov
  */
 abstract class AbstractMultimap<K, V, M extends Multimap<K, V>> implements Multimap<K, V> {
@@ -45,18 +47,57 @@ abstract class AbstractMultimap<K, V, M extends Multimap<K, V>> implements Multi
     protected final SerializableSupplier<Traversable<?>> emptyContainer;
     private final ContainerType containerType;
 
+    /**
+     * Creates a new AbstractMultimap with the specified backing map, container type, and empty container supplier.
+     *
+     * @param back           The backing map that stores the key-value pairs
+     * @param containerType  The type of container used to store multiple values for a key
+     * @param emptyContainer A supplier that creates empty containers for new key entries
+     */
     AbstractMultimap(Map<K, Traversable<V>> back, ContainerType containerType, SerializableSupplier<Traversable<?>> emptyContainer) {
         this.back = back;
         this.containerType = containerType;
         this.emptyContainer = emptyContainer;
     }
 
+    /**
+     * Returns an empty Map instance specific to the implementing class.
+     *
+     * @param <K2> Key type of the empty map
+     * @param <V2> Value type of the empty map
+     * @return An empty Map instance
+     */
     protected abstract <K2, V2> Map<K2, V2> emptyMapSupplier();
 
+    /**
+     * Returns an empty Multimap instance specific to the implementing class.
+     *
+     * @param <K2> Key type of the empty multimap
+     * @param <V2> Value type of the empty multimap
+     * @return An empty Multimap instance
+     */
     protected abstract <K2, V2> Multimap<K2, V2> emptyInstance();
 
+    /**
+     * Creates a new Multimap instance from the given backing map.
+     *
+     * @param <K2> Key type of the new multimap
+     * @param <V2> Value type of the new multimap
+     * @param back The backing map to create the multimap from
+     * @return A new Multimap instance containing the entries from the backing map
+     */
     protected abstract <K2, V2> Multimap<K2, V2> createFromMap(Map<K2, Traversable<V2>> back);
 
+    /**
+     * Creates a new Multimap from the given entries by grouping values by their keys.
+     * For each key, a new container is created using the emptyContainer supplier,
+     * and values are added using the containerType's add operation.
+     *
+     * @param <K2>    Key type of the new multimap
+     * @param <V2>    Value type of the new multimap
+     * @param entries The entries to create the multimap from
+     * @return A new Multimap containing all the entries with values grouped by keys
+     */
     @SuppressWarnings("unchecked")
     private <K2, V2> Multimap<K2, V2> createFromEntries(Iterable<? extends Tuple2<? extends K2, ? extends V2>> entries) {
         Map<K2, Traversable<V2>> back = emptyMapSupplier();

vavr/src/main/java/io/vavr/collection/Array.java

@@ -33,7 +33,7 @@
 import static java.util.Arrays.sort;
 
 /**
- * Array is a Traversable wrapper for {@code Object[]} containing elements of type {@code T}.
+ * Array is an immutable Traversable wrapper for {@code Object[]} containing elements of type {@code T}.
  *
  * @param <T> Component type
  * @author Ruslan Sennov, Daniel Dietrich
@@ -120,8 +120,8 @@ public static <T> Array<T> of(T... elements) {
     /**
      * Creates an Array of the given elements.
      * <p>
-     * The resulting Array has the same iteration order as the given iterable of elements
-     * if the iteration order of the elements is stable.
+     * If the iteration order of the given elements is stable, the resulting Array
+     * will maintain that same order.
      *
      * @param <T>      Component type of the Array.
      * @param elements An Iterable of elements.
@@ -654,7 +654,7 @@ public Array<T> asJavaMutable(Consumer<? super java.util.List<T>> action) {
     public <R> Array<R> collect(PartialFunction<? super T, ? extends R> partialFunction) {
         return ofAll(iterator().<R> collect(partialFunction));
     }
-    
+
     @Override
     public boolean hasDefiniteSize() {
         return true;

vavr/src/main/java/io/vavr/control/Try.java

@@ -635,7 +635,7 @@ default <U> Try<U> mapTry(CheckedFunction1<? super T, ? extends U> mapper) {
             }
         }
     }
-    
+
     /**
      * Consumes the cause if this is a {@link Try.Failure}.
      *
@@ -820,9 +820,10 @@ default <X extends Throwable> Try<T> recover(Class<X> exceptionType, Function<?
     }
 
     /**
-     * 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} <b>which returns Try</b>.
-     * If {@link Try#isFailure()} returned by {@code f} function is <code>true</code> it means that recovery cannot take place due to some circumstances.
+     * 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.
      *
      * <pre>{@code
      * // = Success(13)
@@ -839,8 +840,8 @@ default <X extends Throwable> Try<T> recover(Class<X> exceptionType, Function<?
      * 
      * @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} and returning Try as a result of recovery.
-     *                      If Try is {@link Try#isSuccess()} then recovery ends up successfully. Otherwise the function was not able to recover.
+     * @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}
      * @throws NullPointerException if {@code exceptionType} or {@code f} is null
      */
@@ -887,7 +888,7 @@ default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType, Functio
      */
     @GwtIncompatible
     default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType,  Try<? extends T> recovered){
-        Objects.requireNonNull(exceptionType, "exeptionType is null");
+        Objects.requireNonNull(exceptionType, "exceptionType is null");
         Objects.requireNonNull(recovered, "recovered is null");
         return (isFailure() && exceptionType.isAssignableFrom(getCause().getClass()))
                 ? narrow(recovered)
@@ -915,7 +916,7 @@ default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType,  Try<?
      * @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}
-     * @throws NullPointerException if {@code exception} is null
+     * @throws NullPointerException if {@code exceptionType} is null
      */
     @GwtIncompatible
     default <X extends Throwable> Try<T> recover(Class<X> exceptionType, T value) {