javadoc, error message cleanup.

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

src/java/org/apache/commons/math/analysis/BisectionSolver.java

@@ -22,10 +22,10 @@ import java.io.Serializable;
 import org.apache.commons.math.MathException;
 
 /**
- * Provide the bisection algorithm for solving for zeros of real univariate
+ * Implements the <a href="http://mathworld.wolfram.com/Bisection.html">bisection algorithm</a>
- * functions.  It will only search for one zero in the given interval.  The
+ *  for finding zeros of univariate real functions.  This algorithm will find only one zero in the given interval.
- * function is supposed to be continuous but not necessarily smooth.
+ * The function should be continuous but not necessarily smooth.
- * @version $Revision: 1.11 $ $Date: 2004/02/18 03:24:19 $
+ * @version $Revision: 1.12 $ $Date: 2004/02/20 06:22:39 $
  */
 public class BisectionSolver extends UnivariateRealSolverImpl implements Serializable {
     /**
@@ -37,7 +37,7 @@ public class BisectionSolver extends UnivariateRealSolverImpl implements Seriali
     }
 
     /**
-     * Solve for a zero in the given interval.
+     * Find a zero in the given interval.
      * @param min the lower bound for the interval.
      * @param max the upper bound for the interval.
      * @param initial the start value to use (ignored).
@@ -52,7 +52,7 @@ public class BisectionSolver extends UnivariateRealSolverImpl implements Seriali
     }
     
     /**
-     * Solve for a zero root in the given interval.
+     * Find a zero root in the given interval.
      * @param min the lower bound for the interval.
      * @param max the upper bound for the interval.
      * @return the value where the function is zero
@@ -89,7 +89,7 @@ public class BisectionSolver extends UnivariateRealSolverImpl implements Seriali
             ++i;
         }
         
-        throw new MathException("Maximal iteration number exceeded");
+        throw new MathException("Maximum number of iterations exceeded");
     }
 
     /**

src/java/org/apache/commons/math/analysis/BrentSolver.java

@@ -22,12 +22,12 @@ import java.io.Serializable;
 import org.apache.commons.math.MathException;
 
 /**
- * Provide the Brent algorithm for solving for zeros of real univariate
+ * Implements the <a href="http://mathworld.wolfram.com/BrentsMethod.html">Brent algorithm</a>
- * functions.
+ * for  finding zeros of real univariate
- * It will only search for one zero in the given interval.
+ * functions. This algorithm will find only one zero in the given interval. 
- * The function is supposed to be continuous but not necessarily smooth.
+ * The function should be continuous but not necessarily smooth.
  *  
- * @version $Revision: 1.12 $ $Date: 2004/02/18 03:24:19 $
+ * @version $Revision: 1.13 $ $Date: 2004/02/20 06:22:39 $
  */
 public class BrentSolver extends UnivariateRealSolverImpl implements Serializable {
     /**
@@ -39,7 +39,7 @@ public class BrentSolver extends UnivariateRealSolverImpl implements Serializabl
     }
 
     /**
-     * Solve for a zero in the given interval.
+     * Find a zero in the given interval.
      * @param min the lower bound for the interval.
      * @param max the upper bound for the interval.
      * @param initial the start value to use (ignored).
@@ -54,7 +54,7 @@ public class BrentSolver extends UnivariateRealSolverImpl implements Serializabl
     }
     
     /**
-     * Solve for a zero root in the given interval.
+     * Find a zero in the given interval.
      * @param min the lower bound for the interval.
      * @param max the upper bound for the interval.
      * @return the value where the function is zero
@@ -159,6 +159,6 @@ public class BrentSolver extends UnivariateRealSolverImpl implements Serializabl
             }
             i++;
         }
-        throw new MathException("Maximal iteration number exceeded.");
+        throw new MathException("Maximum number of iterations exceeded.");
     }
 }

src/java/org/apache/commons/math/analysis/CubicSplineFunction.java

@@ -23,13 +23,11 @@ import java.util.Arrays;
 import org.apache.commons.math.MathException;
 
 /**
- * Represents a cubic spline function.
+ * Represents a <a href="http://mathworld.wolfram.com/CubicSpline.html">cubic spline function</a>.
- * Spline functions map a certain interval of real numbers to real numbers.
+ * Arguments outside of the domain determined by the x values array passed to the constructor
- * A cubic spline consists of segments of cubic functions. For this class,
+ * cause an IllegalArgumentException.
- * polynominal coefficents are used.
- * Arguments outside of the domain cause an IllegalArgumentException.
  * 
- * @version $Revision: 1.12 $ $Date: 2004/02/18 03:24:19 $
+ * @version $Revision: 1.13 $ $Date: 2004/02/20 06:22:39 $
  */
 public class CubicSplineFunction implements UnivariateRealFunction, Serializable {
     /** Spline segment interval delimiters. Size is N+1 for N segments. */
@@ -54,6 +52,7 @@ public class CubicSplineFunction implements UnivariateRealFunction, Serializable
     public CubicSplineFunction(double xval[], double c[][]) {
         super();
         // TODO: should copy the arguments here, for safety. This could be a major overhead.
+        // Should also verify that xval[] is in correct order, and arrays have correct lengths
         this.xval = xval;
         this.c = c;
     }
@@ -80,10 +79,6 @@ public class CubicSplineFunction implements UnivariateRealFunction, Serializable
 
     /**
      * Compute the value for the first derivative of the function.
-     * It is recommended to provide this method only if the first derivative is
-     * analytical. Numerical derivatives may be acceptable in some cases.
-     * An implementation should throw an UnsupportedOperationException if
-     * this method is not implemented.
      * @param x the point for which the first derivative should be computed
      * @return the value
      * @throws MathException if the derivative couldn't be computed.

src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java

@@ -56,13 +56,9 @@ package org.apache.commons.math.analysis;
 import org.apache.commons.math.MathException;
 
 /**
- * Provide an interface univariate real functions.
+ * An interface representing a univariate real function.
- * The object may held temporary data which is shared between calculations
- * of the value and the derivatives for the same argument. It is not guaranteed
- * that derivatives are evaluated after the value, the evaluation algorithm
- * should throw an InvalidStateException if it can't cope with this.
  *  
- * @version $Revision: 1.10 $ $Date: 2004/01/29 00:49:00 $
+ * @version $Revision: 1.11 $ $Date: 2004/02/20 06:22:39 $
  */
 public interface UnivariateRealFunction {
     /**

src/java/org/apache/commons/math/analysis/UnivariateRealInterpolator.java

@@ -56,9 +56,9 @@ package org.apache.commons.math.analysis;
 import org.apache.commons.math.MathException;
 
 /**
- * Interface for interpolating a data set.
+ * Interface representing a univariate real interpolating function.
  *  
- * @version $Revision: 1.8 $ $Date: 2004/01/29 00:49:00 $
+ * @version $Revision: 1.9 $ $Date: 2004/02/20 06:22:39 $
  */
 public interface UnivariateRealInterpolator {
 

src/java/org/apache/commons/math/analysis/UnivariateRealSolver.java

@@ -56,11 +56,11 @@ package org.apache.commons.math.analysis;
 import org.apache.commons.math.MathException;
 
 /**
- * Provide an interface to algorithms for solving for zeros of real univariate
+ * Interface for (univariate real) rootfinding algorithms.
- * functions.
+ * <p>
- * An implementation will only search for one zero in the given interval.
+ * Implementations will search for only one zero in the given interval.
  *  
- * @version $Revision: 1.9 $ $Date: 2004/01/29 00:49:00 $
+ * @version $Revision: 1.10 $ $Date: 2004/02/20 06:22:39 $
  */
 public interface UnivariateRealSolver {
 
@@ -68,7 +68,7 @@ public interface UnivariateRealSolver {
      * Set the upper limit for the number of iterations.
      * 
      * Usually a high iteration count indicates convergence problems. However,
-     * the "reasonable value" varies widely for different solvers, users are
+     * the "reasonable value" varies widely for different solvers.  Users are
      * advised to use the default value supplied by the solver.
      *  
      * An exception will be thrown if the number is exceeded.
@@ -96,8 +96,8 @@ public interface UnivariateRealSolver {
     /**
      * Set the absolute accuracy.
      * 
-     * The default is usually choosen so taht roots in the interval
+     * The default is usually choosen so that roots in the interval
-     * -10..-0.1 and +0.1..+10 can be found wit a reasonable accuracy. If the
+     * -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the
      * expected absolute value of your roots is of much smaller magnitude, set
      * this to a smaller value.
      *