Add examples to Javadoc for Throwing*.of factory methods

Closes gh-28969

Author: philwebb

spring-core/src/main/java/org/springframework/util/function/ThrowingBiFunction.java

@@ -104,6 +104,13 @@ public R apply(T t, U u) {
 	 * {@link ThrowingBiFunction} where the {@link #apply(Object, Object)}
 	 * method wraps any checked exception thrown by the supplied lambda expression
 	 * or method reference.
+	 * <p>This method can be especially useful when working with method references.
+	 * It allows you to easily convert a method that throws a checked exception
+	 * into an instance compatible with a regular {@link BiFunction}.
+	 * <p>For example:
+	 * <pre class="code">
+	 * map.replaceAll(ThrowingBiFunction.of(Example::methodThatCanThrowCheckedException));
+	 * </pre>
 	 * @param <T> the type of the first argument to the function
 	 * @param <U> the type of the second argument to the function
 	 * @param <R> the type of the result of the function
@@ -119,6 +126,13 @@ static <T, U, R> ThrowingBiFunction<T, U, R> of(ThrowingBiFunction<T, U, R> func
 	 * {@link ThrowingBiFunction} where the {@link #apply(Object, Object)}
 	 * method wraps any thrown checked exceptions using the given
 	 * {@code exceptionWrapper}.
+	 * <p>This method can be especially useful when working with method references.
+	 * It allows you to easily convert a method that throws a checked exception
+	 * into an instance compatible with a regular {@link BiFunction}.
+	 * <p>For example:
+	 * <pre class="code">
+	 * map.replaceAll(ThrowingBiFunction.of(Example::methodThatCanThrowCheckedException, IllegalStateException::new));
+	 * </pre>
 	 * @param <T> the type of the first argument to the function
 	 * @param <U> the type of the second argument to the function
 	 * @param <R> the type of the result of the function

spring-core/src/main/java/org/springframework/util/function/ThrowingConsumer.java

@@ -96,6 +96,13 @@ public void accept(T t) {
 	 * {@link ThrowingConsumer} where the {@link #accept(Object)} method wraps
 	 * any checked exception thrown by the supplied lambda expression or method
 	 * reference.
+	 * <p>This method can be especially useful when working with method references.
+	 * It allows you to easily convert a method that throws a checked exception
+	 * into an instance compatible with a regular {@link Consumer}.
+	 * <p>For example:
+	 * <pre class="code">
+	 * list.forEach(ThrowingConsumer.of(Example::methodThatCanThrowCheckedException));
+	 * </pre>
 	 * @param <T> the type of the input to the operation
 	 * @param consumer the source consumer
 	 * @return a new {@link ThrowingConsumer} instance
@@ -108,6 +115,13 @@ static <T> ThrowingConsumer<T> of(ThrowingConsumer<T> consumer) {
 	 * Lambda friendly convenience method that can be used to create a
 	 * {@link ThrowingConsumer} where the {@link #accept(Object)} method wraps
 	 * any thrown checked exceptions using the given {@code exceptionWrapper}.
+	 * <p>This method can be especially useful when working with method references.
+	 * It allows you to easily convert a method that throws a checked exception
+	 * into an instance compatible with a regular {@link Consumer}.
+	 * <p>For example:
+	 * <pre class="code">
+	 * list.forEach(ThrowingConsumer.of(Example::methodThatCanThrowCheckedException, IllegalStateException::new));
+	 * </pre>
 	 * @param <T> the type of the input to the operation
 	 * @param consumer the source consumer
 	 * @param exceptionWrapper the exception wrapper to use

spring-core/src/main/java/org/springframework/util/function/ThrowingFunction.java

@@ -99,6 +99,13 @@ public R apply(T t) {
 	 * {@link ThrowingFunction} where the {@link #apply(Object)} method wraps
 	 * any checked exception thrown by the supplied lambda expression or method
 	 * reference.
+	 * <p>This method can be especially useful when working with method references.
+	 * It allows you to easily convert a method that throws a checked exception
+	 * into an instance compatible with a regular {@link Function}.
+	 * <p>For example:
+	 * <pre class="code">
+	 * stream.map(ThrowingFunction.of(Example::methodThatCanThrowCheckedException));
+	 * </pre>
 	 * @param <T> the type of the input to the function
 	 * @param <R> the type of the result of the function
 	 * @param function the source function
@@ -112,6 +119,13 @@ static <T, R> ThrowingFunction<T, R> of(ThrowingFunction<T, R> function) {
 	 * Lambda friendly convenience method that can be used to create a
 	 * {@link ThrowingFunction} where the {@link #apply(Object)} method wraps
 	 * any thrown checked exceptions using the given {@code exceptionWrapper}.
+	 * <p>This method can be especially useful when working with method references.
+	 * It allows you to easily convert a method that throws a checked exception
+	 * into an instance compatible with a regular {@link Function}.
+	 * <p>For example:
+	 * <pre class="code">
+	 * stream.map(ThrowingFunction.of(Example::methodThatCanThrowCheckedException, IllegalStateException::new));
+	 * </pre>
 	 * @param <T> the type of the input to the function
 	 * @param <R> the type of the result of the function
 	 * @param function the source function

spring-core/src/main/java/org/springframework/util/function/ThrowingSupplier.java

@@ -94,6 +94,13 @@ public T get() {
 	 * Lambda friendly convenience method that can be used to create a
 	 * {@link ThrowingSupplier} where the {@link #get()} method wraps any checked
 	 * exception thrown by the supplied lambda expression or method reference.
+	 * <p>This method can be especially useful when working with method references.
+	 * It allows you to easily convert a method that throws a checked exception
+	 * into an instance compatible with a regular {@link Supplier}.
+	 * <p>For example:
+	 * <pre class="code">
+	 * optional.orElseGet(ThrowingSupplier.of(Example::methodThatCanThrowCheckedException));
+	 * </pre>
 	 * @param <T> the type of results supplied by this supplier
 	 * @param supplier the source supplier
 	 * @return a new {@link ThrowingSupplier} instance
@@ -106,6 +113,13 @@ static <T> ThrowingSupplier<T> of(ThrowingSupplier<T> supplier) {
 	 * Lambda friendly convenience method that can be used to create
 	 * {@link ThrowingSupplier} where the {@link #get()} method wraps any
 	 * thrown checked exceptions using the given {@code exceptionWrapper}.
+	 * <p>This method can be especially useful when working with method references.
+	 * It allows you to easily convert a method that throws a checked exception
+	 * into an instance compatible with a regular {@link Supplier}.
+	 * <p>For example:
+	 * <pre class="code">
+	 * optional.orElseGet(ThrowingSupplier.of(Example::methodThatCanThrowCheckedException, IllegalStateException::new));
+	 * </pre>
 	 * @param <T> the type of results supplied by this supplier
 	 * @param supplier the source supplier
 	 * @param exceptionWrapper the exception wrapper to use