From 46094be47e240ef0f126eb36710e19dc745b3875 Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Sat, 10 Jul 2021 10:25:02 -0400 Subject: [PATCH] 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. --- .../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 e3dbd1f9e..0041341c3 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; /** - *

Provides utilities for manipulating and examining - * {@code Throwable} objects.

+ * 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; /** - *

The names of methods commonly used to access a wrapped exception.

+ * 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 { }; /** - *

Used when printing stack frames to denote the start of a - * wrapped exception.

+ * Used when printing stack frames to denote the start of a + * wrapped exception. * *

Package private for accessibility by test suite.

*/ static final String WRAPPED_MARKER = " [wrapped] "; /** - *

Introspects the {@code Throwable} to obtain the cause.

+ * Introspects the {@code Throwable} to obtain the cause. * *

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 { } /** - *

Introspects the {@code Throwable} to obtain the cause.

+ * Introspects the {@code Throwable} to obtain the cause. * *

A {@code null} set of method names means use the default set. * A {@code null} in the set of method names will be ignored.

@@ -141,7 +141,7 @@ public class ExceptionUtils { } /** - *

Finds a {@code Throwable} by method name.

+ * 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 { } /** - *

Returns the default names used when searching for the cause of an exception.

+ * Gets the default names used when searching for the cause of an exception. * *

This may be modified and used in the overloaded getCause(Throwable, String[]) method.

* @@ -185,6 +185,7 @@ public class ExceptionUtils { *

* The message returned is of the form * {ClassNameWithoutPackage}: {ThrowableMessage} + *

* * @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 { } /** - *

Introspects the {@code Throwable} to obtain the root cause.

+ * Introspects the {@code Throwable} to obtain the root cause. * *

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

* The message returned is of the form * {ClassNameWithoutPackage}: {ThrowableMessage} + *

* * @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 { } /** - *

Creates a compact stack trace for the root cause of the supplied - * {@code Throwable}.

+ * Gets a compact stack trace for the root cause of the supplied + * {@code Throwable}. * *

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 { } /** - *

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.

+ * returned, any caused by trace is stripped. * *

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 { } /** - *

Returns an array where each element is a line from the argument.

+ * Gets an array where each element is a line from the argument. * *

The end of line is determined by the value of {@link System#lineSeparator()}.

* @@ -325,9 +327,9 @@ public class ExceptionUtils { } /** - *

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.

+ * stack frames. * *

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 { } /** - *

Gets the stack trace from a Throwable as a String.

+ * Gets the stack trace from a Throwable as a String. * *

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 { } /** - *

Counts the number of {@code Throwable} objects in the - * exception chain.

+ * Gets a count of the number of {@code Throwable} objects in the + * exception chain. * *

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 { } /** - *

Returns the list of {@code Throwable} objects in the - * exception chain.

+ * Gets the list of {@code Throwable} objects in the + * exception chain. * *

A throwable without cause will return a list containing * one element - the input throwable. @@ -412,8 +414,8 @@ public class ExceptionUtils { } /** - *

Returns the list of {@code Throwable} objects in the - * exception chain.

+ * Gets the list of {@code Throwable} objects in the + * exception chain. * *

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 { } /** - *

Worker method for the {@code indexOfType} methods.

+ * 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 { } /** - *

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.

+ * {@link #indexOfType(Throwable, Class)} for the opposite. * *

A {@code null} throwable returns {@code -1}. * A {@code null} type returns {@code -1}. @@ -513,11 +515,11 @@ public class ExceptionUtils { } /** - *

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.

+ * {@link #indexOfType(Throwable, Class, int)} for the opposite. * *

A {@code null} throwable returns {@code -1}. * A {@code null} type returns {@code -1}. @@ -536,10 +538,10 @@ public class ExceptionUtils { } /** - *

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.

+ * {@link #indexOfThrowable(Throwable, Class)} for the opposite. * *

A {@code null} throwable returns {@code -1}. * A {@code null} type returns {@code -1}. @@ -555,11 +557,11 @@ public class ExceptionUtils { } /** - *

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.

+ * {@link #indexOfThrowable(Throwable, Class)} for the opposite. * *

A {@code null} throwable returns {@code -1}. * A {@code null} type returns {@code -1}. @@ -579,8 +581,8 @@ public class ExceptionUtils { } /** - *

Prints a compact stack trace for the root cause of a throwable - * to {@code System.err}.

+ * Prints a compact stack trace for the root cause of a throwable + * to {@code System.err}. * *

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 { } /** - *

Prints a compact stack trace for the root cause of a throwable.

+ * Prints a compact stack trace for the root cause of a throwable. * *

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 { } /** - *

Prints a compact stack trace for the root cause of a throwable.

+ * Prints a compact stack trace for the root cause of a throwable. * *

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 { } /** - *

Removes common frames from the cause trace given the two stack traces.

+ * 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. *

* The use of this technique may be controversial, but exceedingly useful to * library developers. - * + *

+ * 
      *  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
      *      }
      *  }
-     * 
+     *
*

* This is an alternative to the more conservative approach of wrapping the * checked exception in a RuntimeException: - * + *

+ * 
      *  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
      *      }
      *  }
-     * 
+     *
*

* 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. + *

* * @param throwable * The throwable to rethrow. @@ -752,7 +757,7 @@ public class ExceptionUtils { } /** - *

Worker method for the {@code throwableOfType} methods.

+ * Worker method for the {@code throwableOfType} methods. * * @param the type of Throwable you are searching. * @param throwable the throwable to inspect, may be null @@ -791,10 +796,10 @@ public class ExceptionUtils { } /** - *

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.

+ * {@link #throwableOfType(Throwable, Class)} for the opposite. * *

A {@code null} throwable returns {@code null}. * A {@code null} type returns {@code null}. @@ -811,11 +816,11 @@ public class ExceptionUtils { } /** - *

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.

+ * {@link #throwableOfType(Throwable, Class, int)} for the opposite. * *

A {@code null} throwable returns {@code null}. * A {@code null} type returns {@code null}. @@ -836,10 +841,10 @@ public class ExceptionUtils { } /** - *

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..

+ * {@link #throwableOfThrowable(Throwable, Class)} for the opposite. * *

A {@code null} throwable returns {@code null}. * A {@code null} type returns {@code null}. @@ -856,11 +861,11 @@ public class ExceptionUtils { } /** - *

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.

+ * {@link #throwableOfThrowable(Throwable, Class)} for the opposite. * *

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. + *

* * @param throwable * The throwable to rethrow. @@ -923,10 +929,8 @@ public class ExceptionUtils { } /** - *

* Public constructor allows an instance of {@code ExceptionUtils} to be created, although that is not * normally necessary. - *

*/ public ExceptionUtils() { }