[commons-lang] branch master updated: Functions Javadoc (#466)

[gg...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git


The following commit(s) were added to refs/heads/master by this push:
     new 23931d5  Functions Javadoc (#466)
23931d5 is described below

commit 23931d528e829e7f76235b9df0ec03a9d4e93fca
Author: Peter Verhas <pe...@verhas.com>
AuthorDate: Sat Dec 21 14:42:53 2019 +0100

    Functions Javadoc (#466)
    
    * LANG-1480 getAbbreviatedName refactored to create appropriate length short class names
    
    * LANG-1480 code fixed for special extreme case ".." abbreviated to 1 length should result ".." it was throwing exception. Tests are added
    
    * import changed to avoid wild cards
    apache master merged into current branch
    
    * Mutable object import was moved to it's original place
    
    * some accidental formatting reverted
    
    * some accidental formatting reverted
    
    * some accidental formatting reverted
    
    * some accidental formatting reverted
    
    * some accidental formatting reverted
    
    * some accidental formatting reverted
    
    * some accidental formatting reverted
    
    * added another test case
    
    * LANG-1480 fixing JavaDoc documentation as per requested by garydgregory
    
    * LANG-1480 shortcut implemented, argument renamed, more tests
    
    * LANG-1480 checkstyle update
    
    * LANG-1492 tests methods modified to be public
    
    * LANG-1480 imports rearranged
    
    * LANG-1480 imports rearranged
    
    * LANG-1480 imports rearranged
    
    * javadoc was added that explains why there is a return type for a method that never returns
    
    * wording changed in comment
    
    * fixes based on code review by garydgregory
---
 .../java/org/apache/commons/lang3/Functions.java   | 24 +++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/src/main/java/org/apache/commons/lang3/Functions.java b/src/main/java/org/apache/commons/lang3/Functions.java
index eeed548..db422ad 100644
--- a/src/main/java/org/apache/commons/lang3/Functions.java
+++ b/src/main/java/org/apache/commons/lang3/Functions.java
@@ -491,9 +491,27 @@ public class Functions {
     }
 
     /**
-     * Rethrows a {@link Throwable} as an unchecked exception.
-     * @param pThrowable The throwable to rethrow
-     * @return Never returns anything, this method never terminates normally
+     * <p>Rethrows 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 wrapped into a {@code UncheckedIOException}.
+     * In every other cases the exception will be wrapped 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>
+     *      throw rethrow(myUncheckedException);
+     * </pre>
+     *
+     * <p>instead of just calling the method. This pattern may help the Java compiler to
+     * recognize that at that point an exception will be thrown and the code flow
+     * analysis will not demand otherwise mandatory commands that could follow the
+     * method call, like a {@code return} statement from a value returning method.</p>
+     *
+     * @param pThrowable The throwable to rethrow possibly wrapped into an unchecked exception
+     * @return Never returns anything, this method never terminates normally.
      */
     public static RuntimeException rethrow(Throwable pThrowable) {
         if (pThrowable == null) {