diff --git a/assertj-core/src/main/java/org/assertj/core/api/AssertFactory.java b/assertj-core/src/main/java/org/assertj/core/api/AssertFactory.java
index 6de6632b64c..1f21e82f3d9 100644
--- a/assertj-core/src/main/java/org/assertj/core/api/AssertFactory.java
+++ b/assertj-core/src/main/java/org/assertj/core/api/AssertFactory.java
@@ -17,17 +17,19 @@
import java.util.function.Function;
/**
- * A single method factory interface to create an {@link Assert} for a given value.
- * This factory method typically wraps a call to assertThat(actual)
- * to produce a concrete assert type {@code ASSERT} for the input element of type {@code T}.
+ * A factory that creates an {@link Assert} instance for a given value of type {@link T}.
*
- * This interface is typically used by navigation assertions on iterable types like {@link AbstractIterableAssert} - * when calling {@link Assertions#assertThat(Iterable, AssertFactory) assertThat(Iterable<E>, AssertFactory<E, ASSERT>)} + * The {@link #createAssert(Object)} factory method typically wraps a call to + * {@link Assertions#assertThat}. *
- * @param
+ * This is typically used by custom assertions that want to leverage existing
+ * factories and need to manipulate the value upfront.
+ *
* The default implementation always requests a value compatible with {@code Object}.
*
- * Overriding implementations might provide a more specific {@link Type} instance to express
- * the desired type of the value returned by the provider. When doing so, the factory is required
- * to be consistent with type parameter {@link T}.
+ * Overriding implementations might provide a more specific {@link Type}
+ * instance to express the desired type of the value returned by the provider.
+ * When doing so, the factory is required to be consistent with the type parameter {@link T}.
*
* @param valueProvider the value provider for the {@code Assert} instance
* @return the custom {@code Assert} instance for the value provided by the given value provider
@@ -76,7 +81,8 @@ interface ValueProvider
- * The factory casts the value to the expected type before invoking the delegate.
+ * The factory casts the value to the expected type before invoking the
+ * delegate.
*
* @param actual the input value for the {@code Assert} instance
* @return the custom {@code Assert} instance for the given value
@@ -86,7 +87,12 @@ public ASSERT createAssert(Object actual) {
* Creates the custom {@link Assert} instance for the value provided by the
* given {@code valueProvider}.
*
- * The factory casts the provided value to the expected type before invoking the delegate.
+ * This is typically used by custom assertions that want to leverage existing
+ * factories and need to manipulate the value upfront.
+ *
+ * This implementation requests a value compatible with the {@link Class} or
+ * {@link Type} defined during instantiation and casts the provided value
+ * to it before invoking the delegate.
*
* @param valueProvider the value provider for the {@code Assert} instance
* @return the custom {@code Assert} instance for the provided value
diff --git a/assertj-core/src/test/java/org/assertj/core/api/InstanceOfAssertFactoriesTest.java b/assertj-core/src/test/java/org/assertj/core/api/InstanceOfAssertFactoriesTest.java
index 8d45d6190cf..f30edef3588 100644
--- a/assertj-core/src/test/java/org/assertj/core/api/InstanceOfAssertFactoriesTest.java
+++ b/assertj-core/src/test/java/org/assertj/core/api/InstanceOfAssertFactoriesTest.java
@@ -4137,7 +4137,7 @@ void createAssert_with_ValueProvider() {
@SafeVarargs
private static
*
* All other {@link Type} subtypes are unsupported.
*
@@ -90,7 +96,8 @@ interface ValueProvider