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

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) {