From b08c92e75d9885ffa03dc61f323489beb2ca7778 Mon Sep 17 00:00:00 2001 From: Allon Mureinik Date: Fri, 8 Feb 2019 19:21:27 +0200 Subject: [PATCH] Fix Javadoc issues in Functions --- .../org/apache/commons/lang3/Functions.java | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/src/main/java/org/apache/commons/lang3/Functions.java b/src/main/java/org/apache/commons/lang3/Functions.java index b48d13a58..cff1279f7 100644 --- a/src/main/java/org/apache/commons/lang3/Functions.java +++ b/src/main/java/org/apache/commons/lang3/Functions.java @@ -48,37 +48,88 @@ import java.lang.reflect.UndeclaredThrowableException; public class Functions { @FunctionalInterface public interface FailableRunnable { + /** + * Runs the function. + * @throws T if the function fails + */ void run() throws T; } @FunctionalInterface public interface FailableCallable { + /** + * Calls the callable. + * @return The value returned from the callable + * @throws T if the callable fails + */ O call() throws T; } @FunctionalInterface public interface FailableConsumer { + /** + * Accepts the consumer. + * @param pObject the parameter for the consumable to accept + * @throws T if the consumer fails + */ void accept(O pObject) throws T; } @FunctionalInterface public interface FailableBiConsumer { + /** + * Accepts the consumer. + * @param pObject1 the first parameter for the consumable to accept + * @param pObject2 the second parameter for the consumable to accept + * @throws T if the consumer fails + */ void accept(O1 pObject1, O2 pObject2) throws T; } @FunctionalInterface public interface FailableFunction { + /** + * Apply the function. + * @param pInput the input for the function + * @return the result of the function + * @throws T if the function fails + */ O apply(I pInput) throws T; } @FunctionalInterface public interface FailableBiFunction { + /** + * Apply the function. + * @param pInput1 the first input for the function + * @param pInput2 the second input for the function + * @return the result of the function + * @throws T if the function fails + */ O apply(I1 pInput1, I2 pInput2) throws T; } @FunctionalInterface public interface FailablePredicate { + /** + * Test the predicate. + * @param pObject the object to test the predicate on + * @return the predicate's evaluation + * @throws T if the predicate fails + */ boolean test(O pObject) throws T; } @FunctionalInterface public interface FailableBiPredicate { + /** + * Test the predicate. + * @param pObject1 the first object to test the predicate on + * @param pObject2 the second object to test the predicate on + * @return the predicate's evaluation + * @throws T if the predicate fails + */ boolean test(O1 pObject1, O2 pObject2) throws T; } + /** + * Runs a runnable and rethrows any exception as a {@link RuntimeException}. + * @param pRunnable The runnable to run + * @param the type of checked exception the runnable may throw + */ public static void run(FailableRunnable pRunnable) { try { pRunnable.run(); @@ -87,6 +138,13 @@ public class Functions { } } + /** + * Calls a callable and rethrows any exception as a {@link RuntimeException}. + * @param pCallable the callable to call + * @param the return type of the callable + * @param the type of checked exception the callable may throw + * @return the value returned from the callable + */ public static O call(FailableCallable pCallable) { try { return pCallable.call(); @@ -95,6 +153,13 @@ public class Functions { } } + /** + * Consumes a consumer and rethrows any exception as a {@link RuntimeException}. + * @param pConsumer the consumer to consume + * @param pObject the object to consume by pConsumer + * @param the type the consumer accepts + * @param the type of checked exception the consumer may throw + */ public static void accept(FailableConsumer pConsumer, O pObject) { try { pConsumer.accept(pObject); @@ -103,6 +168,15 @@ public class Functions { } } + /** + * Consumes a consumer and rethrows any exception as a {@link RuntimeException}. + * @param pConsumer the consumer to consume + * @param pObject1 the first object to consume by pConsumer + * @param pObject2 the second object to consume by pConsumer + * @param the type of the first argument the consumer accepts + * @param the type of the second argument the consumer accepts + * @param the type of checked exception the consumer may throw + */ public static void accept(FailableBiConsumer pConsumer, O1 pObject1, O2 pObject2) { try { pConsumer.accept(pObject1, pObject2); @@ -111,6 +185,15 @@ public class Functions { } } + /** + * Applies a function and rethrows any exception as a {@link RuntimeException}. + * @param pFunction the function to apply + * @param pInput the input to apply pFunction on + * @param the type of the argument the function accepts + * @param the return type of the function + * @param the type of checked exception the function may throw + * @return the value returned from the function + */ public static O apply(FailableFunction pFunction, I pInput) { try { return pFunction.apply(pInput); @@ -119,6 +202,17 @@ public class Functions { } } + /** + * Applies a function and rethrows any exception as a {@link RuntimeException}. + * @param pFunction the function to apply + * @param pInput1 the first input to apply pFunction on + * @param pInput2 the second input to apply pFunction on + * @param the type of the first argument the function accepts + * @param the type of the second argument the function accepts + * @param the return type of the function + * @param the type of checked exception the function may throw + * @return the value returned from the function + */ public static O apply(FailableBiFunction pFunction, I1 pInput1, I2 pInput2) { try { return pFunction.apply(pInput1, pInput2); @@ -127,6 +221,14 @@ public class Functions { } } + /** + * Tests a predicate and rethrows any exception as a {@link RuntimeException}. + * @param pPredicate the predicate to test + * @param pObject the input to test by pPredicate + * @param the type of argument the predicate tests + * @param the type of checked exception the predicate may throw + * @return the boolean value returned by the predicate + */ public static boolean test(FailablePredicate pPredicate, O pObject) { try { return pPredicate.test(pObject); @@ -135,6 +237,16 @@ public class Functions { } } + /** + * Tests a predicate and rethrows any exception as a {@link RuntimeException}. + * @param pPredicate the predicate to test + * @param pObject1 the first input to test by pPredicate + * @param pObject2 the second input to test by pPredicate + * @param the type of the first argument the predicate tests + * @param the type of the second argument the predicate tests + * @param the type of checked exception the predicate may throw + * @return the boolean value returned by the predicate + */ public static boolean test(FailableBiPredicate pPredicate, O1 pObject1, O2 pObject2) { try { return pPredicate.test(pObject1, pObject2); @@ -233,6 +345,11 @@ public class Functions { tryWithResources(pAction, null, pResources); } + /** + * Rethrow a {@link Throwable} as an unchecked exception. + * @param pThrowable The throwable to rethrow + * @return Never returns anything, this method never terminates normally + */ public static RuntimeException rethrow(Throwable pThrowable) { if (pThrowable == null) { throw new NullPointerException("The Throwable must not be null.");