From fd7e4d35e6c37861c90d3d3615558a7f09ea77eb Mon Sep 17 00:00:00 2001 From: Stefano Cordio Date: Sun, 28 Apr 2024 13:28:10 +0200 Subject: [PATCH] Improve Javadoc --- .../org/assertj/core/api/AssertFactory.java | 31 ++++++++++++------- .../core/api/InstanceOfAssertFactory.java | 10 ++++-- .../api/InstanceOfAssertFactoriesTest.java | 2 +- 3 files changed, 28 insertions(+), 15 deletions(-) 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 the type of the input to the factory. - * @param 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 the type of the given value. + * @param the type of the resulting {@code Assert}. * @since 2.5.0 / 3.5.0 + * @see InstanceOfAssertFactory */ @FunctionalInterface public interface AssertFactory> { @@ -46,11 +48,14 @@ public interface AssertFactory> { * Creates the custom {@link Assert} instance for the value provided by the * given {@code valueProvider}. *

+ * 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 extends Function { * The compatibility definition depends on the actual {@code type} instance: *

* All other {@link Type} subtypes are unsupported. * @@ -90,7 +96,8 @@ interface ValueProvider extends Function { * * @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)) { diff --git a/assertj-core/src/main/java/org/assertj/core/api/InstanceOfAssertFactory.java b/assertj-core/src/main/java/org/assertj/core/api/InstanceOfAssertFactory.java index 1a5b5bb7267..999558193f6 100644 --- a/assertj-core/src/main/java/org/assertj/core/api/InstanceOfAssertFactory.java +++ b/assertj-core/src/main/java/org/assertj/core/api/InstanceOfAssertFactory.java @@ -72,7 +72,8 @@ Class getRawClass() { /** * Creates the custom {@link Assert} instance for the given value. *

- * 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 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) reified.getClass().getComponentType(), delegatesTo(delegate)); }