Adds Javadoc

Author: jqno

equalsverifier-core/src/main/java/nl/jqno/equalsverifier/api/EqualsVerifierApi.java

@@ -52,6 +52,21 @@ public interface EqualsVerifierApi<T> {
      */
     <S> EqualsVerifierApi<T> withPrefabValues(Class<S> otherType, S red, S blue);
 
+    /**
+     * Adds Suppliers for resettable prefabricated values for instance fields of classes that EqualsVerifier cannot
+     * instantiate by itself. Resettable values are values that are created new every time a new instance of {@code T}
+     * is constructed within EqualsVerifier. This can be useful when {@code T} mutates its instances of {@code S}.
+     *
+     * @param <S>       The class of the prefabricated values.
+     * @param otherType The class of the prefabricated values.
+     * @param red       An instance of {@code S}.
+     * @param blue      Another instance of {@code S}, not equal to {@code red}.
+     * @return {@code this}, for easy method chaining.
+     * @throws NullPointerException     If either {@code otherType}, {@code red}, or {@code blue} is null.
+     * @throws IllegalArgumentException If {@code red} equals {@code blue}.
+     *
+     * @since 4.1
+     */
     <S> EqualsVerifierApi<T> withResettablePrefabValue(Class<S> otherType, Supplier<S> red, Supplier<S> blue);
 
     /**

equalsverifier-core/src/main/java/nl/jqno/equalsverifier/internal/PrefabValuesApi.java

@@ -56,7 +56,7 @@ public static <T> void addResettablePrefabValues(
         Validations.validateEqual(red.get(), red.get(), "red prefab value is not equal to itself after reset.");
         Validations.validateEqual(blue.get(), blue.get(), "blue prefab value is not equal to itself after reset.");
 
-        userPrefabs.register(otherType, red, blue, red);
+        userPrefabs.registerResettable(otherType, red, blue, red);
     }
 
     public static <T> void addPrefabValuesForField(

equalsverifier-core/src/main/java/nl/jqno/equalsverifier/internal/instantiation/CacheDecider.java

@@ -1,6 +1,15 @@
 package nl.jqno.equalsverifier.internal.instantiation;
 
+/**
+ * Decides whether {@link CachingValueProvider} should cache instances of the given type.
+ */
 @FunctionalInterface
 public interface CacheDecider {
+    /**
+     * Determines whether instances of {@code type} should be cached.
+     *
+     * @param type The type whose instances should or should not be cached.
+     * @return Whether instances of the given type should be cached.
+     */
     boolean canBeCached(Class<?> type);
 }

equalsverifier-core/src/main/java/nl/jqno/equalsverifier/internal/instantiation/UserPrefabValueProvider.java

@@ -65,7 +65,17 @@ private <T> Tuple<T> attempt(Class<?> type) {
         return (Tuple<T>) cache.get(type);
     }
 
-    public <T> void register(Class<T> type, Supplier<T> red, Supplier<T> blue, Supplier<T> redCopy) {
+    /**
+     * Registers a resettable prefab value.
+     *
+     * @param type    The class of the prefabricated values.
+     * @param red     A Supplier for an instance of {@code T}.
+     * @param blue    A Supplier for another instance of {@code T}, not equal to {@code red}.
+     * @param redCopy A Supplier for an instance of {@code T}, equal to {@code red} but preferably not the same
+     *                    instance.
+     * @param <T>     The type of the instances.
+     */
+    public <T> void registerResettable(Class<T> type, Supplier<T> red, Supplier<T> blue, Supplier<T> redCopy) {
         Tuple<Supplier<?>> tuple = new Tuple<>(red, blue, redCopy);
         supplierCache.put(type, tuple);
     }