[GitHub] [commons-lang] garydgregory commented on a change in pull request #466: Functions.java JavaDoc was added

[GitBox <gi...@apache.org>]

garydgregory commented on a change in pull request #466: Functions.java JavaDoc was added
URL: https://github.com/apache/commons-lang/pull/466#discussion_r334552250
 
 

 ##########
 File path: src/main/java/org/apache/commons/lang3/Functions.java
 ##########
 @@ -491,9 +491,27 @@ public static void tryWithResources(FailableRunnable<? extends Throwable> pActio
     }
 
     /**
-     * Rethrows a {@link Throwable} as an unchecked exception.
-     * @param pThrowable The throwable to rethrow
-     * @return Never returns anything, this method never terminates normally
+     * <p>Rethrow a {@link Throwable} as an unchecked exception. If the argument is
+     * already unchecked, namely a {@code RuntimeException} or {@code Error} then
+     * the argument will be rethrown without modification. If the exception is
+     * {@code IOException} then it will be enveloped into a {@code UncheckedIOException}.
+     * In every other cases the exception will be enveloped into a {@code
+     * UndeclaredThrowableException}</p>
+     *
+     * <p>Note that there is a declared return type for this method, even though it
+     * never returns. The reason for that is to support the usual pattern:</p>
+     *
+     * <pre>{@code
+     *      throw rethrow(myUncheckedException);
+     * }</pre>
+     *
+     * <p>instead of just calling the method. This pattern helps the Java compiler to
 
 Review comment:
   "help" is not unlikely to be guaranteed, it might be safer to say "may help".

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services