Improve Javadoc

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 <code>assertThat(actual)</code>
- * 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}.
  * <p>
- * This interface is typically used by navigation assertions on iterable types like {@link AbstractIterableAssert}
- * when calling {@link Assertions#assertThat(Iterable, AssertFactory) assertThat(Iterable&lt;E&gt;, AssertFactory&lt;E, ASSERT&gt;)}
+ * The {@link #createAssert(Object)} factory method typically wraps a call to
+ * {@link Assertions#assertThat}.
  * <p>
- * @param <T> the type of the input to the factory.
- * @param <ASSERT> the type of the resulting {@code Assert}.
+ * More advanced use cases can be achieved via {@link #createAssert(ValueProvider)},
+ * where the provision of the value is externalized and the factory can require
+ * explicit type compatibility for the value to be provided.
  *
+ * @param <T> the type of the given value.
+ * @param <ASSERT> the type of the resulting {@code Assert}.
  * @since 2.5.0 / 3.5.0
+ * @see InstanceOfAssertFactory
  */
 @FunctionalInterface
 public interface AssertFactory<T, ASSERT extends Assert<?, ?>> {
@@ -46,11 +48,14 @@ public interface AssertFactory<T, ASSERT extends Assert<?, ?>> {
    * Creates the custom {@link Assert} instance for the value provided by the
    * given {@code valueProvider}.
    * <p>
+   * This is typically used by custom assertions that want to leverage existing
+   * factories and need to manipulate the value upfront.
+   * <p>
    * The default implementation always requests a value compatible with {@code Object}.
    * <p>
-   * 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<T> extends Function<Type, T> {
      * The compatibility definition depends on the actual {@code type} instance:
      * <ul>
      *   <li>If {@code type} is a {@link Class}, the provided value must be an instance of it.</li>
-     *   <li>If {@code type} is a {@link ParameterizedType}, the provided value must be an instance of its {@link ParameterizedType#getRawType() raw type}.</li>
+     *   <li>If {@code type} is a {@link ParameterizedType}, the provided value must be
+     *   an instance of its {@link ParameterizedType#getRawType() raw type}.</li>
      * </ul>
      * All other {@link Type} subtypes are unsupported.
      *
@@ -90,7 +96,8 @@ interface ValueProvider<T> extends Function<Type, T> {
      *
      * @param type the given type
      * @return the provided value
-     * @throws IllegalArgumentException if {@code type} is neither a {@link Class} nor a {@link ParameterizedType} instance
+     * @throws IllegalArgumentException if {@code type} is neither a {@link Class}
+     * nor a {@link ParameterizedType} instance
      */
     default T apply(Type type) {
       if (!(type instanceof Class || type instanceof ParameterizedType)) {

assertj-core/src/main/java/org/assertj/core/api/InstanceOfAssertFactory.java

@@ -72,7 +72,8 @@ Class<T> getRawClass() {
   /**
    * Creates the custom {@link Assert} instance for the given value.
    * <p>
-   * 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}.
    * <p>
-   * 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.
+   * <p>
+   * 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

assertj-core/src/test/java/org/assertj/core/api/InstanceOfAssertFactoriesTest.java

@@ -4137,7 +4137,7 @@ void createAssert_with_ValueProvider() {
   @SafeVarargs
   private static <T> T mockThatDelegatesTo(T delegate, T... reified) {
     if (reified.length > 0) {
-      throw new IllegalArgumentException("NioJava will detect class automagically.");
+      throw new IllegalArgumentException("Leave the vararg parameter empty. That is used to detect the class instance automagically.");
     }
     return mock((Class<T>) reified.getClass().getComponentType(), delegatesTo(delegate));
   }