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 46094be Javadoc: Tagging the first sentence as a paragraph is
redundant.
46094be is described below
commit 46094be47e240ef0f126eb36710e19dc745b3875
Author: Gary Gregory <[email protected]>
AuthorDate: Sat Jul 10 10:25:02 2021 -0400
Javadoc: Tagging the first sentence as a paragraph is redundant.
- Use pre tags instead of code tags for in-line code examples.
- Close HTML tags.
- Use "Gets..." for most getters.
---
.../commons/lang3/exception/ExceptionUtils.java | 120 +++++++++++----------
1 file changed, 62 insertions(+), 58 deletions(-)
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 e3dbd1f..0041341 100644
--- a/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java
+++ b/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java
@@ -32,8 +32,8 @@ import org.apache.commons.lang3.ClassUtils;
import org.apache.commons.lang3.StringUtils;
/**
- * <p>Provides utilities for manipulating and examining
- * {@code Throwable} objects.</p>
+ * Provides utilities for manipulating and examining
+ * {@code Throwable} objects.
*
* @since 1.0
*/
@@ -42,7 +42,7 @@ public class ExceptionUtils {
private static final int NOT_FOUND = -1;
/**
- * <p>The names of methods commonly used to access a wrapped exception.</p>
+ * The names of methods commonly used to access a wrapped exception.
*/
// TODO: Remove in Lang 4.0
private static final String[] CAUSE_METHOD_NAMES = {
@@ -61,15 +61,15 @@ public class ExceptionUtils {
};
/**
- * <p>Used when printing stack frames to denote the start of a
- * wrapped exception.</p>
+ * Used when printing stack frames to denote the start of a
+ * wrapped exception.
*
* <p>Package private for accessibility by test suite.</p>
*/
static final String WRAPPED_MARKER = " [wrapped] ";
/**
- * <p>Introspects the {@code Throwable} to obtain the cause.</p>
+ * Introspects the {@code Throwable} to obtain the cause.
*
* <p>The method searches for methods with specific names that return a
* {@code Throwable} object. This will pick up most wrapping exceptions,
@@ -101,7 +101,7 @@ public class ExceptionUtils {
}
/**
- * <p>Introspects the {@code Throwable} to obtain the cause.</p>
+ * Introspects the {@code Throwable} to obtain the cause.
*
* <p>A {@code null} set of method names means use the default set.
* A {@code null} in the set of method names will be ignored.</p>
@@ -141,7 +141,7 @@ public class ExceptionUtils {
}
/**
- * <p>Finds a {@code Throwable} by method name.</p>
+ * Gets a {@code Throwable} by method name.
*
* @param throwable the exception to examine
* @param methodName the name of the method to find and invoke
@@ -167,7 +167,7 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the default names used when searching for the cause of an
exception.</p>
+ * Gets the default names used when searching for the cause of an
exception.
*
* <p>This may be modified and used in the overloaded getCause(Throwable,
String[]) method.</p>
*
@@ -185,6 +185,7 @@ public class ExceptionUtils {
* <p>
* The message returned is of the form
* {ClassNameWithoutPackage}: {ThrowableMessage}
+ * </p>
*
* @param th the throwable to get a message for, null returns empty string
* @return the message, non-null
@@ -200,7 +201,7 @@ public class ExceptionUtils {
}
/**
- * <p>Introspects the {@code Throwable} to obtain the root cause.</p>
+ * Introspects the {@code Throwable} to obtain the root cause.
*
* <p>This method walks through the exception chain to the last element,
* "root" of the tree, using {@link Throwable#getCause()}, and
@@ -226,6 +227,7 @@ public class ExceptionUtils {
* <p>
* The message returned is of the form
* {ClassNameWithoutPackage}: {ThrowableMessage}
+ * </p>
*
* @param th the throwable to get a message for, null returns empty string
* @return the message, non-null
@@ -238,8 +240,8 @@ public class ExceptionUtils {
}
/**
- * <p>Creates a compact stack trace for the root cause of the supplied
- * {@code Throwable}.</p>
+ * Gets a compact stack trace for the root cause of the supplied
+ * {@code Throwable}.
*
* <p>The output of this method is consistent across JDK versions.
* It consists of the root exception followed by each of its wrapping
@@ -275,9 +277,9 @@ public class ExceptionUtils {
}
/**
- * <p>Produces a {@code List} of stack frames - the message
+ * Gets a {@code List} of stack frames - the message
* is not included. Only the trace of the specified exception is
- * returned, any caused by trace is stripped.</p>
+ * returned, any caused by trace is stripped.
*
* <p>This works in most cases - it will only fail if the exception
* message contains a line that starts with:
@@ -307,7 +309,7 @@ public class ExceptionUtils {
}
/**
- * <p>Returns an array where each element is a line from the argument.</p>
+ * Gets an array where each element is a line from the argument.
*
* <p>The end of line is determined by the value of {@link
System#lineSeparator()}.</p>
*
@@ -325,9 +327,9 @@ public class ExceptionUtils {
}
/**
- * <p>Captures the stack trace associated with the specified
+ * Gets the stack trace associated with the specified
* {@code Throwable} object, decomposing it into a list of
- * stack frames.</p>
+ * stack frames.
*
* <p>The result of this method vary by JDK version as this method
* uses {@link Throwable#printStackTrace(java.io.PrintWriter)}.
@@ -345,7 +347,7 @@ public class ExceptionUtils {
}
/**
- * <p>Gets the stack trace from a Throwable as a String.</p>
+ * Gets the stack trace from a Throwable as a String.
*
* <p>The result of this method vary by JDK version as this method
* uses {@link Throwable#printStackTrace(java.io.PrintWriter)}.
@@ -364,8 +366,8 @@ public class ExceptionUtils {
}
/**
- * <p>Counts the number of {@code Throwable} objects in the
- * exception chain.</p>
+ * Gets a count of the number of {@code Throwable} objects in the
+ * exception chain.
*
* <p>A throwable without cause will return {@code 1}.
* A throwable with one cause will return {@code 2} and so on.
@@ -384,8 +386,8 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the list of {@code Throwable} objects in the
- * exception chain.</p>
+ * Gets the list of {@code Throwable} objects in the
+ * exception chain.
*
* <p>A throwable without cause will return a list containing
* one element - the input throwable.
@@ -412,8 +414,8 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the list of {@code Throwable} objects in the
- * exception chain.</p>
+ * Gets the list of {@code Throwable} objects in the
+ * exception chain.
*
* <p>A throwable without cause will return an array containing
* one element - the input throwable.
@@ -436,7 +438,7 @@ public class ExceptionUtils {
}
/**
- * Does the throwable's causal chain have an immediate or wrapped exception
+ * Tests if the throwable's causal chain have an immediate or wrapped
exception
* of the given type?
*
* @param chain
@@ -457,7 +459,7 @@ public class ExceptionUtils {
}
/**
- * <p>Worker method for the {@code indexOfType} methods.</p>
+ * Worker method for the {@code indexOfType} methods.
*
* @param throwable the throwable to inspect, may be null
* @param type the type to search for, subclasses match, null returns -1
@@ -495,10 +497,10 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the (zero-based) index of the first {@code Throwable}
+ * Returns the (zero-based) index of the first {@code Throwable}
* that matches the specified class (exactly) in the exception chain.
* Subclasses of the specified class do not match - see
- * {@link #indexOfType(Throwable, Class)} for the opposite.</p>
+ * {@link #indexOfType(Throwable, Class)} for the opposite.
*
* <p>A {@code null} throwable returns {@code -1}.
* A {@code null} type returns {@code -1}.
@@ -513,11 +515,11 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the (zero-based) index of the first {@code Throwable}
+ * Returns the (zero-based) index of the first {@code Throwable}
* that matches the specified type in the exception chain from
* a specified index.
* Subclasses of the specified class do not match - see
- * {@link #indexOfType(Throwable, Class, int)} for the opposite.</p>
+ * {@link #indexOfType(Throwable, Class, int)} for the opposite.
*
* <p>A {@code null} throwable returns {@code -1}.
* A {@code null} type returns {@code -1}.
@@ -536,10 +538,10 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the (zero-based) index of the first {@code Throwable}
+ * Returns the (zero-based) index of the first {@code Throwable}
* that matches the specified class or subclass in the exception chain.
* Subclasses of the specified class do match - see
- * {@link #indexOfThrowable(Throwable, Class)} for the opposite.</p>
+ * {@link #indexOfThrowable(Throwable, Class)} for the opposite.
*
* <p>A {@code null} throwable returns {@code -1}.
* A {@code null} type returns {@code -1}.
@@ -555,11 +557,11 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the (zero-based) index of the first {@code Throwable}
+ * Returns the (zero-based) index of the first {@code Throwable}
* that matches the specified type in the exception chain from
* a specified index.
* Subclasses of the specified class do match - see
- * {@link #indexOfThrowable(Throwable, Class)} for the opposite.</p>
+ * {@link #indexOfThrowable(Throwable, Class)} for the opposite.
*
* <p>A {@code null} throwable returns {@code -1}.
* A {@code null} type returns {@code -1}.
@@ -579,8 +581,8 @@ public class ExceptionUtils {
}
/**
- * <p>Prints a compact stack trace for the root cause of a throwable
- * to {@code System.err}.</p>
+ * Prints a compact stack trace for the root cause of a throwable
+ * to {@code System.err}.
*
* <p>The compact stack trace starts with the root cause and prints
* stack frames up to the place where it was caught and wrapped.
@@ -601,7 +603,7 @@ public class ExceptionUtils {
}
/**
- * <p>Prints a compact stack trace for the root cause of a throwable.</p>
+ * Prints a compact stack trace for the root cause of a throwable.
*
* <p>The compact stack trace starts with the root cause and prints
* stack frames up to the place where it was caught and wrapped.
@@ -633,7 +635,7 @@ public class ExceptionUtils {
}
/**
- * <p>Prints a compact stack trace for the root cause of a throwable.</p>
+ * Prints a compact stack trace for the root cause of a throwable.
*
* <p>The compact stack trace starts with the root cause and prints
* stack frames up to the place where it was caught and wrapped.
@@ -665,7 +667,7 @@ public class ExceptionUtils {
}
/**
- * <p>Removes common frames from the cause trace given the two stack
traces.</p>
+ * Removes common frames from the cause trace given the two stack traces.
*
* @param causeFrames stack trace of a cause throwable
* @param wrapperFrames stack trace of a wrapper throwable
@@ -692,14 +694,15 @@ public class ExceptionUtils {
}
/**
- * Throw a checked exception without adding the exception to the throws
+ * Throws a checked exception without adding the exception to the throws
* clause of the calling method. This method prevents throws clause
* pollution and reduces the clutter of "Caused by" exceptions in the
* stacktrace.
* <p>
* The use of this technique may be controversial, but exceedingly useful
to
* library developers.
- * <code>
+ * </p>
+ * <pre>
* public int propagateExample { // note that there is no throws clause
* try {
* return invocation(); // throws IOException
@@ -707,11 +710,12 @@ public class ExceptionUtils {
* return ExceptionUtils.rethrow(e); // propagates a checked
exception
* }
* }
- * </code>
+ * </pre>
* <p>
* This is an alternative to the more conservative approach of wrapping the
* checked exception in a RuntimeException:
- * <code>
+ * </p>
+ * <pre>
* public int wrapExample { // note that there is no throws clause
* try {
* return invocation(); // throws IOException
@@ -723,7 +727,7 @@ public class ExceptionUtils {
* throw new UndeclaredThrowableException(e); // wraps a checked
exception
* }
* }
- * </code>
+ * </pre>
* <p>
* One downside to using this approach is that the java compiler will not
* allow invoking code to specify a checked exception in a catch clause
@@ -735,6 +739,7 @@ public class ExceptionUtils {
* techniques are required when interacting with non-java jvm code such as
* Jython, Scala, or Groovy, since these languages do not consider any
* exceptions as checked.
+ * </p>
*
* @param throwable
* The throwable to rethrow.
@@ -752,7 +757,7 @@ public class ExceptionUtils {
}
/**
- * <p>Worker method for the {@code throwableOfType} methods.</p>
+ * Worker method for the {@code throwableOfType} methods.
*
* @param <T> the type of Throwable you are searching.
* @param throwable the throwable to inspect, may be null
@@ -791,10 +796,10 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the first {@code Throwable}
+ * Returns the first {@code Throwable}
* that matches the specified class (exactly) in the exception chain.
* Subclasses of the specified class do not match - see
- * {@link #throwableOfType(Throwable, Class)} for the opposite.</p>
+ * {@link #throwableOfType(Throwable, Class)} for the opposite.
*
* <p>A {@code null} throwable returns {@code null}.
* A {@code null} type returns {@code null}.
@@ -811,11 +816,11 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the first {@code Throwable}
+ * Returns the first {@code Throwable}
* that matches the specified type in the exception chain from
* a specified index.
* Subclasses of the specified class do not match - see
- * {@link #throwableOfType(Throwable, Class, int)} for the opposite.</p>
+ * {@link #throwableOfType(Throwable, Class, int)} for the opposite.
*
* <p>A {@code null} throwable returns {@code null}.
* A {@code null} type returns {@code null}.
@@ -836,10 +841,10 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the throwable of the first {@code Throwable}
+ * Returns the throwable of the first {@code Throwable}
* that matches the specified class or subclass in the exception chain.
* Subclasses of the specified class do match - see
- * {@link #throwableOfThrowable(Throwable, Class)} for the opposite..</p>
+ * {@link #throwableOfThrowable(Throwable, Class)} for the opposite.
*
* <p>A {@code null} throwable returns {@code null}.
* A {@code null} type returns {@code null}.
@@ -856,11 +861,11 @@ public class ExceptionUtils {
}
/**
- * <p>Returns the first {@code Throwable}
+ * Returns the first {@code Throwable}
* that matches the specified type in the exception chain from
* a specified index.
* Subclasses of the specified class do match - see
- * {@link #throwableOfThrowable(Throwable, Class)} for the opposite.</p>
+ * {@link #throwableOfThrowable(Throwable, Class)} for the opposite.
*
* <p>A {@code null} throwable returns {@code null}.
* A {@code null} type returns {@code null}.
@@ -881,8 +886,8 @@ public class ExceptionUtils {
}
/**
- * Claim a Throwable is another Exception type using type erasure. This
- * hides a checked exception from the java compiler, allowing a checked
+ * Claims a Throwable is another Exception type using type erasure. This
+ * hides a checked exception from the Java compiler, allowing a checked
* exception to be thrown without having the exception in the method's
throw
* clause.
*/
@@ -892,7 +897,7 @@ public class ExceptionUtils {
}
/**
- * Throw a checked exception without adding the exception to the throws
+ * Throws a checked exception without adding the exception to the throws
* clause of the calling method. For checked exceptions, this method throws
* an UndeclaredThrowableException wrapping the checked exception. For
* Errors and RuntimeExceptions, the original exception is rethrown.
@@ -900,6 +905,7 @@ public class ExceptionUtils {
* The downside to using this approach is that invoking code which needs to
* handle specific checked exceptions must sniff up the exception chain to
* determine if the caught exception was caused by the checked exception.
+ * </p>
*
* @param throwable
* The throwable to rethrow.
@@ -923,10 +929,8 @@ public class ExceptionUtils {
}
/**
- * <p>
* Public constructor allows an instance of {@code ExceptionUtils} to be
created, although that is not
* normally necessary.
- * </p>
*/
public ExceptionUtils() {
}
