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 9f67b81da Improve Javadoc in ExceptionUtils #1136 9f67b81da is described below commit 9f67b81dab0502b9fde981cbeac9ae3bbcd2039d Author: Gary Gregory <garydgreg...@gmail.com> AuthorDate: Tue Nov 21 21:05:31 2023 -0500 Improve Javadoc in ExceptionUtils #1136 --- src/changes/changes.xml | 1 + .../commons/lang3/exception/ExceptionUtils.java | 40 +++++++++++----------- 2 files changed, 21 insertions(+), 20 deletions(-) diff --git a/src/changes/changes.xml b/src/changes/changes.xml index d4f03b69c..fa3cf1a78 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -46,6 +46,7 @@ The <action> type attribute can be add,update,fix,remove. </properties> <body> <release version="3.14.1" date="202Y-MM-DD" description="New features and bug fixes (Java 8 or above)."> + <action type="fix" dev="ggregory" due-to="Miklós Karakó, Gary Gregory">Improve Javadoc in ExceptionUtils #1136.</action> </release> <release version="3.14.0" date="2023-11-18" description="New features and bug fixes (Java 8 or above)."> <!-- FIX --> diff --git a/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java b/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java index 110feb621..b9ac4e990 100644 --- a/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java +++ b/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java @@ -288,17 +288,17 @@ public class ExceptionUtils { } /** - * Introspects the {@link Throwable} to obtain the root cause. + * Walks the {@link Throwable} to obtain its root cause. * - * <p>This method walks through the exception chain to the last element, - * "root" of the tree, using {@link Throwable#getCause()}, and + * <p>This method walks through the exception chain until the last element, + * the root cause of the chain, using {@link Throwable#getCause()}, and * returns that exception.</p> * - * <p>From version 2.2, this method handles recursive cause structures - * that might otherwise cause infinite loops. If the throwable parameter - * has a cause of itself, then null will be returned. If the throwable - * parameter cause chain loops, the last element in the chain before the - * loop is returned.</p> + * <p>This method handles recursive cause chains that might + * otherwise cause infinite loops. The cause chain is processed until + * the end, or until the next item in the chain is already + * processed. If we detect a loop, then return the element before the loop.</p> + * * @param throwable the throwable to get the root cause for, may be null * @return the root cause of the {@link Throwable}, @@ -477,13 +477,13 @@ public class ExceptionUtils { * A throwable with one cause will return {@code 2} and so on. * A {@code null} throwable will return {@code 0}.</p> * - * <p>From version 2.2, this method handles recursive cause structures + * <p>This method handles recursive cause chains * that might otherwise cause infinite loops. The cause chain is - * processed until the end is reached, or until the next item in the - * chain is already in the result set.</p> + * processed until the end, or until the next item in the + * chain is already in the result.</p> * * @param throwable the throwable to inspect, may be null - * @return the count of throwables, zero if null input + * @return the count of throwables, zero on null input */ public static int getThrowableCount(final Throwable throwable) { return getThrowableList(throwable).size(); @@ -499,10 +499,10 @@ public class ExceptionUtils { * two elements. - the input throwable and the cause throwable. * A {@code null} throwable will return a list of size zero.</p> * - * <p>This method handles recursive cause structures that might + * <p>This method handles recursive cause chains that might * otherwise cause infinite loops. The cause chain is processed until - * the end is reached, or until the next item in the chain is already - * in the result set.</p> + * the end, or until the next item in the chain is already + * in the result list.</p> * * @param throwable the throwable to inspect, may be null * @return the list of throwables, never null @@ -527,10 +527,10 @@ public class ExceptionUtils { * two elements. - the input throwable and the cause throwable. * A {@code null} throwable will return an array of size zero.</p> * - * <p>From version 2.2, this method handles recursive cause structures + * <p>This method handles recursive cause chains * that might otherwise cause infinite loops. The cause chain is - * processed until the end is reached, or until the next item in the - * chain is already in the result set.</p> + * processed until the end, or until the next item in the + * chain is already in the result array.</p> * * @see #getThrowableList(Throwable) * @param throwable the throwable to inspect, may be null @@ -887,8 +887,8 @@ public class ExceptionUtils { * </p> * * <p> - * This method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is - * processed until the end is reached, or until the next item in the chain is already in the result set. + * This method handles recursive cause chains that might otherwise cause infinite loops. The cause chain is + * processed until the end, or until the next item in the chain is already in the result. * </p> * * @param throwable The Throwable to traverse