Javadoc changes, with better description of trace methods

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@366617 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/lang/exception/ExceptionUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2005 The Apache Software Foundation.
+ * Copyright 2002-2006 The Apache Software Foundation.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,13 +29,13 @@
 import java.util.StringTokenizer;
 
 import org.apache.commons.lang.ArrayUtils;
+import org.apache.commons.lang.NullArgumentException;
 import org.apache.commons.lang.StringUtils;
 import org.apache.commons.lang.SystemUtils;
-import org.apache.commons.lang.NullArgumentException;
 
 /**
  * <p>Provides utilities for manipulating and examining 
-<code>Throwable</code> objects.</p>
+ * <code>Throwable</code> objects.</p>
  *
  * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
  * @author Dmitri Plotnikov
@@ -74,16 +74,12 @@ public class ExceptionUtils {
     };
 
     /**
-     * <p>
+     * <p>The Method object for Java 1.4 getCause.</p>
-     * The Method object for Java 1.4 getCause.
-     * </p>
      */
     private static final Method THROWABLE_CAUSE_METHOD;
 
     /**
-     * <p>
+     * <p>The Method object for Java 1.4 initCause.</p>
-     * The Method object for Java 1.4 initCause.
-     * </p>
      */
     private static final Method THROWABLE_INITCAUSE_METHOD;
     
@@ -149,16 +145,12 @@ public static void removeCauseMethodName(String methodName) {
     }
 
     /**
-     * <p>
+     * <p>Sets the cause of a <code>Throwable</code> using introspection, allowing
-     * Sets the cause of a <code>Throwable</code> using introspection, allowing source code compatibility between
+     * source code compatibility between pre-1.4 and post-1.4 Java releases.</p>
-     * pre-1.4 and post-1.4 Java releases.
-     * </p>
      *
-     * <p>
+     * <p>The typical use of this method is inside a constructor as in
-     * The typical use of this method is inside a constructor as in the following example:
+     * the following example:</p>
-     * </p>
      *
-     * <p>
      * <pre>
      * import org.apache.commons.lang.exception.ExceptionUtils;
      *  
@@ -172,15 +164,11 @@ public static void removeCauseMethodName(String methodName) {
      *       super(msg);
      *       ExceptionUtils.setCause(this, cause);
      *    }
-     * 
      * }
      * </pre>
-     * </p>
      *
-     * @param target
+     * @param target  the target <code>Throwable</code>
-     *            the target <code>Throwable</code>
+     * @param cause  the <code>Throwable</code> to set in the target
-     * @param cause
-     *            the <code>Throwable</code> to set in the target
      * @return a <code>true</code> if the target has been modified
      * @since 2.2
      */
@@ -225,6 +213,7 @@ private static String[] toArray(List list) {
 
     /**
      * Returns {@link #CAUSE_METHOD_NAMES} as a List.
+     *
      * @return {@link #CAUSE_METHOD_NAMES} as a List.
      */
     private static ArrayList getCauseMethodNameList() {
@@ -669,6 +658,9 @@ private static int indexOf(Throwable throwable, Class type, int fromIndex, boole
      * Then it prints the wrapped exception and continues with stack frames
      * until the wrapper exception is caught and wrapped again, etc.</p>
      *
+     * <p>The output of this method is consistent across JDK versions.
+     * Note that this is the opposite order to the JDK1.4 display.</p>
+     *
      * <p>The method is equivalent to <code>printStackTrace</code> for throwables
      * that don't have nested causes.</p>
      *
@@ -687,6 +679,9 @@ public static void printRootCauseStackTrace(Throwable throwable) {
      * Then it prints the wrapped exception and continues with stack frames
      * until the wrapper exception is caught and wrapped again, etc.</p>
      *
+     * <p>The output of this method is consistent across JDK versions.
+     * Note that this is the opposite order to the JDK1.4 display.</p>
+     *
      * <p>The method is equivalent to <code>printStackTrace</code> for throwables
      * that don't have nested causes.</p>
      *
@@ -717,6 +712,9 @@ public static void printRootCauseStackTrace(Throwable throwable, PrintStream str
      * Then it prints the wrapped exception and continues with stack frames
      * until the wrapper exception is caught and wrapped again, etc.</p>
      *
+     * <p>The output of this method is consistent across JDK versions.
+     * Note that this is the opposite order to the JDK1.4 display.</p>
+     *
      * <p>The method is equivalent to <code>printStackTrace</code> for throwables
      * that don't have nested causes.</p>
      *
@@ -744,6 +742,11 @@ public static void printRootCauseStackTrace(Throwable throwable, PrintWriter wri
      * <p>Creates a compact stack trace for the root cause of the supplied
      * <code>Throwable</code>.</p>
      *
+     * <p>The output of this method is consistent across JDK versions.
+     * It consists of the root exception followed by each of its wrapping
+     * exceptions separated by '[wrapped]'. Note that this is the opposite
+     * order to the JDK1.4 display.</p>
+     *
      * @param throwable  the throwable to examine, may be null
      * @return an array of stack trace frames, never null
      * @since 2.0
@@ -805,6 +808,11 @@ public static void removeCommonFrames(List causeFrames, List wrapperFrames) {
     /**
      * <p>Gets the stack trace from a Throwable as a String.</p>
      *
+     * <p>The result of this method vary by JDK version as this method
+     * uses {@link Throwable#printStackTrace(java.io.PrintWriter)}.
+     * On JDK1.3 and earlier, the cause exception will not be shown
+     * unless the specified throwable alters printStackTrace.</p>
+     *
      * @param throwable  the <code>Throwable</code> to be examined
      * @return the stack trace as generated by the exception's
      *  <code>printStackTrace(PrintWriter)</code> method
@@ -819,6 +827,9 @@ public static String getStackTrace(Throwable throwable) {
     /**
      * <p>A way to get the entire nested stack-trace of an throwable.</p>
      *
+     * <p>The result of this method is highly dependent on the JDK version
+     * and whether the exceptions override printStackTrace or not.</p>
+     *
      * @param throwable  the <code>Throwable</code> to be examined
      * @return the nested stack trace, with the root cause first
      * @since 2.0
@@ -842,6 +853,11 @@ public static String getFullStackTrace(Throwable throwable) {
      * <code>Throwable</code> object, decomposing it into a list of
      * stack frames.</p>
      *
+     * <p>The result of this method vary by JDK version as this method
+     * uses {@link Throwable#printStackTrace(java.io.PrintWriter)}.
+     * On JDK1.3 and earlier, the cause exception will not be shown
+     * unless the specified throwable alters printStackTrace.</p>
+     *
      * @param throwable  the <code>Throwable</code> to examine, may be null
      * @return an array of strings describing each stack frame, never null
      */
@@ -853,21 +869,16 @@ public static String[] getStackFrames(Throwable throwable) {
     }
 
     /**
-     * <p>
+     * <p>Returns an array where each element is a line from the argument.</p>
-     * Returns an array where each element is a line from the argument.
-     * </p>
-     * <p>
-     * The end of line is determined by the value of {@link SystemUtils#LINE_SEPARATOR}.
-     * </p>
      *
-     * <p>
+     * <p>The end of line is determined by the value of {@link SystemUtils#LINE_SEPARATOR}.</p>
-     * Functionality shared between the <code>getStackFrames(Throwable)</code> methods of this and the
-     * {@link org.apache.commons.lang.exception.NestableDelegate} classes.
-     * </p>
      *
-     * @param stackTrace
+     * <p>Functionality shared between the
-     *            A stack trace String.
+     * <code>getStackFrames(Throwable)</code> methods of this and the
-     * @return an array where each element is a line from the argument.
+     * {@link org.apache.commons.lang.exception.NestableDelegate} classes.</p>
+     *
+     * @param stackTrace  a stack trace String
+     * @return an array where each element is a line from the argument
      */
     static String[] getStackFrames(String stackTrace) {
         String linebreak = SystemUtils.LINE_SEPARATOR;
@@ -881,7 +892,8 @@ static String[] getStackFrames(String stackTrace) {
 
     /**
      * <p>Produces a <code>List</code> of stack frames - the message
-     * is not included.</p>
+     * is not included. Only the trace of the specified exception is
+     * returned, any caused by trace is stripped.</p>
      *
      * <p>This works in most cases - it will only fail if the exception
      * message contains a line that starts with: