Added serveral javadoc comments. Added constructors to the matrix exception classes to mimic the existing math exceptions.

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

src/java/org/apache/commons/math/ConvergenceException.java

@@ -23,7 +23,7 @@ import java.io.Serializable;
  * Error thrown when a numerical computation can not be performed because the
  * numerical result failed to converge to a finite value.
  * 
- * @version $Revision: 1.10 $ $Date: 2004/02/18 03:24:19 $
+ * @version $Revision: 1.11 $ $Date: 2004/04/08 20:46:00 $
  */
 public class ConvergenceException extends MathException implements Serializable{
     /**
@@ -57,5 +57,4 @@ public class ConvergenceException extends MathException implements Serializable{
     public ConvergenceException(Throwable throwable) {
         this(null, throwable);
     }
-
 }

src/java/org/apache/commons/math/complex/ComplexFormat.java

@@ -24,15 +24,19 @@ import java.text.NumberFormat;
  * can be configured.
  *
  * @author Apache Software Foundation
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
  */
 public class ComplexFormat {
 
+    /** The default complex format. */ 
 	private static final ComplexFormat DEFAULT = new ComplexFormat();
 
 	// @TODO This class only allows for max fraction digits, we might want to allow other parameters
+    
+    /** The notation used to signify the imaginary part of the complex number. */
     private String imaginaryCharacter = "i";
 
+    /** The maximum number of decimal digits in the formatted output. */ 
     private int fractionDigits = 2;
 
     /**
@@ -44,6 +48,7 @@ public class ComplexFormat {
     /**
      * Create an instance with a custom imaginary character, and the default number
      * of decimal places - 2.
+     * @param imaginaryCharacter The custom imaginary character.
      */
     public ComplexFormat(String imaginaryCharacter) {
         this.imaginaryCharacter = imaginaryCharacter;
@@ -52,6 +57,8 @@ public class ComplexFormat {
     /**
      * Create an instance with a custom imaginary character, and a custom number of
      * decimal places.
+     * @param imaginaryCharacter The custom imaginary character.
+     * @param fractionDigits The custom number of decimal places.
      */
     public ComplexFormat(String imaginaryCharacter, int fractionDigits) {
         this.imaginaryCharacter = imaginaryCharacter;

src/java/org/apache/commons/math/distribution/AbstractContinuousDistribution.java

@@ -24,7 +24,7 @@ import org.apache.commons.math.analysis.UnivariateRealSolverUtils;
  * implementations for some of the methods that do not vary from distribution
  * to distribution.
  *  
- * @version $Revision: 1.19 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.20 $ $Date: 2004/04/08 20:45:59 $
  */
 public abstract class AbstractContinuousDistribution
     implements ContinuousDistribution {
@@ -44,6 +44,8 @@ public abstract class AbstractContinuousDistribution
      * @param x0 the lower bound
      * @param x1 the upper bound
      * @return the cumulative probability. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(double x0, double x1)
         throws MathException {
@@ -56,6 +58,8 @@ public abstract class AbstractContinuousDistribution
      *
      * @param p the desired probability
      * @return x, such that P(X &lt; x) = <code>p</code>
+     * @exception MathException if the inverse cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double inverseCumulativeProbability(final double p)
         throws MathException {

src/java/org/apache/commons/math/distribution/AbstractDiscreteDistribution.java

@@ -23,7 +23,7 @@ import org.apache.commons.math.MathException;
  * implementations for some of the methods that do not vary from distribution
  * to distribution.
  *  
- * @version $Revision: 1.11 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.12 $ $Date: 2004/04/08 20:45:59 $
  */
 public abstract class AbstractDiscreteDistribution
     implements DiscreteDistribution {
@@ -40,6 +40,8 @@ public abstract class AbstractDiscreteDistribution
      * @param x0 the inclusive, lower bound
      * @param x1 the inclusive, upper bound
      * @return the cumulative probability. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(int x0, int x1) throws MathException{
         return cumulativeProbability(x1) - 
@@ -52,6 +54,8 @@ public abstract class AbstractDiscreteDistribution
      *
      * @param p the desired probability
      * @return x, such that P(X &lt; x) = <code>p</code>
+     * @exception MathException if the inverse cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public int inverseCumulativeProbability(final double p) throws MathException{
         if (p < 0.0 || p > 1.0) {

src/java/org/apache/commons/math/distribution/BinomialDistributionImpl.java

@@ -24,7 +24,7 @@ import org.apache.commons.math.util.MathUtils;
 /**
  * The default implementation of {@link BinomialDistribution}.
  * 
- * @version $Revision: 1.11 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.12 $ $Date: 2004/04/08 20:45:59 $
  */
 public class BinomialDistributionImpl
     extends AbstractDiscreteDistribution
@@ -114,6 +114,8 @@ public class BinomialDistributionImpl
      * For this disbution, X, this method returns P(X ≤ x).
      * @param x the value at which the PDF is evaluated.
      * @return PDF for this distribution. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(int x) throws MathException {
         double ret;

src/java/org/apache/commons/math/distribution/ChiSquaredDistributionImpl.java

@@ -22,7 +22,7 @@ import org.apache.commons.math.MathException;
 /**
  * The default implementation of {@link ChiSquaredDistribution}
  * 
- * @version $Revision: 1.14 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.15 $ $Date: 2004/04/08 20:45:59 $
  */
 public class ChiSquaredDistributionImpl
     extends AbstractContinuousDistribution
@@ -61,6 +61,8 @@ public class ChiSquaredDistributionImpl
      * For this disbution, X, this method returns P(X < x).
      * @param x the value at which the CDF is evaluated.
      * @return CDF for this distribution. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(double x) throws MathException {
         return getGamma().cumulativeProbability(x);

src/java/org/apache/commons/math/distribution/ContinuousDistribution.java

@@ -20,13 +20,15 @@ import org.apache.commons.math.MathException;
 /**
  * Base interface for various continuous distributions.
  * 
- * @version $Revision: 1.12 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.13 $ $Date: 2004/04/08 20:45:59 $
  */
 public interface ContinuousDistribution {
     /**
      * For this disbution, X, this method returns P(X < x).
      * @param x the value at which the CDF is evaluated.
      * @return CDF for this distribution. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     double cumulativeProbability(double x) throws MathException;
 
@@ -35,6 +37,8 @@ public interface ContinuousDistribution {
      * @param x0 the lower bound
      * @param x1 the upper bound
      * @return the cumulative probability. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     double cumulativeProbability(double x0, double x1) throws MathException;
     
@@ -42,6 +46,8 @@ public interface ContinuousDistribution {
      * For this disbution, X, this method returns x such that P(X < x) = p.
      * @param p the cumulative probability.
      * @return x. 
+     * @exception MathException if the inverse cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     double inverseCumulativeProbability(double p) throws MathException;
 }

src/java/org/apache/commons/math/distribution/DiscreteDistribution.java

@@ -20,7 +20,7 @@ import org.apache.commons.math.MathException;
 /**
  * Base interface for various discrete distributions.
  * 
- * @version $Revision: 1.10 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.11 $ $Date: 2004/04/08 20:45:59 $
  */
 public interface DiscreteDistribution {
     /**
@@ -34,6 +34,8 @@ public interface DiscreteDistribution {
      * For this disbution, X, this method returns P(X ≤ x).
      * @param x the value at which the PDF is evaluated.
      * @return PDF for this distribution. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     double cumulativeProbability(int x) throws MathException;
 
@@ -42,6 +44,8 @@ public interface DiscreteDistribution {
      * @param x0 the inclusive, lower bound
      * @param x1 the inclusive, upper bound
      * @return the cumulative probability. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     double cumulativeProbability(int x0, int x1) throws MathException;
     
@@ -49,6 +53,8 @@ public interface DiscreteDistribution {
      * For this disbution, X, this method returns x such that P(X &le; x) <= p.
      * @param p the cumulative probability.
      * @return x. 
+     * @exception MathException if the inverse cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     int inverseCumulativeProbability(double p) throws MathException;
 }

src/java/org/apache/commons/math/distribution/ExponentialDistributionImpl.java

@@ -22,7 +22,7 @@ import org.apache.commons.math.MathException;
 /**
  * The default implementation of {@link ExponentialDistribution}
  * 
- * @version $Revision: 1.13 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.14 $ $Date: 2004/04/08 20:45:59 $
  */
 public class ExponentialDistributionImpl
     implements ExponentialDistribution, Serializable  {
@@ -70,6 +70,8 @@ public class ExponentialDistributionImpl
      * 
      * @param x the value at which the CDF is evaluated.
      * @return CDF for this distribution.
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(double x) throws MathException{
         double ret;
@@ -87,6 +89,8 @@ public class ExponentialDistributionImpl
      *
      * @param p the desired probability
      * @return x, such that P(X &lt; x) = <code>p</code>
+     * @exception MathException if the inverse cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double inverseCumulativeProbability(double p) throws MathException{
         double ret;
@@ -107,6 +111,8 @@ public class ExponentialDistributionImpl
      * @param x0 the lower bound
      * @param x1 the upper bound
      * @return the cumulative probability. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(double x0, double x1) throws MathException{
         return cumulativeProbability(x1) - cumulativeProbability(x0);

src/java/org/apache/commons/math/distribution/FDistributionImpl.java

@@ -24,7 +24,7 @@ import org.apache.commons.math.special.Beta;
  * Default implementation of
  * {@link org.apache.commons.math.distribution.FDistribution}.
  * 
- * @version $Revision: 1.14 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.15 $ $Date: 2004/04/08 20:45:59 $
  */
 public class FDistributionImpl
     extends AbstractContinuousDistribution
@@ -60,6 +60,8 @@ public class FDistributionImpl
      * 
      * @param x the value at which the CDF is evaluated.
      * @return CDF for this distribution. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(double x) throws MathException {
         double ret;

src/java/org/apache/commons/math/distribution/GammaDistributionImpl.java

@@ -23,7 +23,7 @@ import org.apache.commons.math.special.Gamma;
 /**
  * The default implementation of {@link GammaDistribution}
  * 
- * @version $Revision: 1.17 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.18 $ $Date: 2004/04/08 20:45:59 $
  */
 public class GammaDistributionImpl extends AbstractContinuousDistribution
     implements GammaDistribution, Serializable  {
@@ -59,6 +59,8 @@ public class GammaDistributionImpl extends AbstractContinuousDistribution
      * 
      * @param x the value at which the CDF is evaluated.
      * @return CDF for this distribution. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(double x) throws MathException{
         double ret;

src/java/org/apache/commons/math/distribution/HypergeometricDistributionImpl.java

@@ -24,7 +24,7 @@ import org.apache.commons.math.util.MathUtils;
 /**
  * The default implementation of {@link HypergeometricDistribution}.
  * 
- * @version $Revision: 1.10 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.11 $ $Date: 2004/04/08 20:45:59 $
  */
 public class HypergeometricDistributionImpl extends AbstractDiscreteDistribution
     implements HypergeometricDistribution, Serializable 
@@ -59,6 +59,8 @@ public class HypergeometricDistributionImpl extends AbstractDiscreteDistribution
      * For this disbution, X, this method returns P(X ≤ x).
      * @param x the value at which the PDF is evaluated.
      * @return PDF for this distribution. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(int x) throws MathException{
         double ret;

src/java/org/apache/commons/math/distribution/NormalDistributionImpl.java

@@ -27,8 +27,14 @@ import java.io.Serializable;
  */
 public class NormalDistributionImpl extends AbstractContinuousDistribution 
 		implements NormalDistribution, Serializable {
+    
+    /** The mean of this distribution. */
 	private double mean = 0;
+    
+    /** The standard deviation of this distribution. */
 	private double standardDeviation = 1;
+    
+    /** The algorithm used to compute cumulative probabilities. */
 	private NormalCDFAlgorithm cdfAlgorithm = new NormalCDFPreciseAlgorithm();
 	
 	/**

src/java/org/apache/commons/math/distribution/TDistributionImpl.java

@@ -24,7 +24,7 @@ import org.apache.commons.math.special.Beta;
  * Default implementation of
  * {@link org.apache.commons.math.distribution.TDistribution}.
  * 
- * @version $Revision: 1.14 $ $Date: 2004/02/21 21:35:14 $
+ * @version $Revision: 1.15 $ $Date: 2004/04/08 20:45:59 $
  */
 public class TDistributionImpl
     extends AbstractContinuousDistribution
@@ -65,6 +65,8 @@ public class TDistributionImpl
      * For this disbution, X, this method returns P(X &lt; <code>x</code>).
      * @param x the value at which the CDF is evaluated.
      * @return CDF evaluted at <code>x</code>. 
+     * @exception MathException if the cumulative probability can not be
+     *            computed due to convergence or other numerical errors.
      */
     public double cumulativeProbability(double x) throws MathException{
         double ret;

src/java/org/apache/commons/math/linear/InvalidMatrixException.java

@@ -18,16 +18,44 @@
 
 package org.apache.commons.math.linear;
 
+import org.apache.commons.lang.exception.NestableRuntimeException;
+
 /**
  * Thrown when a system attempts an operation on a matrix, and
  * that matrix does not satisfy the preconditions for the
  * aforementioned operation.
- * @version $Revision: 1.2 $ $Date: 2004/01/29 16:48:49 $
+ * @version $Revision: 1.3 $ $Date: 2004/04/08 20:46:01 $
  */
-public class InvalidMatrixException extends RuntimeException {
+public class InvalidMatrixException extends NestableRuntimeException {
-
+    /**
-    public InvalidMatrixException(String s) {
+     * Default constructor.
-        super( s );
+     */
+    public InvalidMatrixException() {
+        this(null, null);
     }
     
+    /**
+     * Construct an exception with the given message.
+     * @param message descriptive error message. 
+     */
+    public InvalidMatrixException(String message) {
+        this(message, null);
+    }
+
+    /**
+     * Construct an exception with the given message and root cause.
+     * @param message descriptive error message.
+     * @param cause root cause.
+     */
+    public InvalidMatrixException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Create an exception with a given root cause.
+     * @param throwable caught exception causing this problem
+     */
+    public InvalidMatrixException(Throwable throwable) {
+        this(null, throwable);
+    }
 }

src/java/org/apache/commons/math/linear/MatrixIndexException.java

@@ -18,15 +18,43 @@
 
 package org.apache.commons.math.linear;
 
+import org.apache.commons.lang.exception.NestableRuntimeException;
+
 /**
  * Thrown when an operation addresses a matrix coordinate (row,col)
  * which is outside of the dimensions of a matrix.
- * @version $Revision: 1.2 $ $Date: 2004/01/29 16:48:49 $
+ * @version $Revision: 1.3 $ $Date: 2004/04/08 20:46:01 $
  */
-public class MatrixIndexException extends RuntimeException {
+public class MatrixIndexException extends NestableRuntimeException {
-
+    /**
-    public MatrixIndexException(String s) {
+     * Default constructor.
-        super( s );
+     */
+    public MatrixIndexException() {
+        this(null, null);
     }
     
+    /**
+     * Construct an exception with the given message.
+     * @param message descriptive error message. 
+     */
+    public MatrixIndexException(String message) {
+        this(message, null);
+    }
+
+    /**
+     * Construct an exception with the given message and root cause.
+     * @param message descriptive error message.
+     * @param cause root cause.
+     */
+    public MatrixIndexException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Create an exception with a given root cause.
+     * @param throwable caught exception causing this problem
+     */
+    public MatrixIndexException(Throwable throwable) {
+        this(null, throwable);
+    }
 }

src/java/org/apache/commons/math/linear/RealMatrixImpl.java

@@ -42,7 +42,7 @@ import java.io.Serializable;
  * explicitly invoke <code>LUDecompose()</code> to recompute the decomposition
  * before using any of the methods above.
  *
- * @version $Revision: 1.16 $ $Date: 2004/04/08 07:01:17 $
+ * @version $Revision: 1.17 $ $Date: 2004/04/08 20:46:01 $
  */
 public class RealMatrixImpl implements RealMatrix, Serializable {
 
@@ -417,7 +417,7 @@ public class RealMatrixImpl implements RealMatrix, Serializable {
 
 	/**
 	 * @return determinant
-	 * @throws IllegalArgumentException if matrix is not square
+	 * @throws InvalidMatrixException if matrix is not square
 	 */
 	public double getDeterminant() throws InvalidMatrixException {
 		if (!isSquare()) {

src/java/org/apache/commons/math/stat/TestStatistic.java

@@ -20,7 +20,7 @@ import org.apache.commons.math.MathException;
 /**
  * A collection of commonly used test statistics and statistical tests.
  * 
- * @version $Revision: 1.13 $ $Date: 2004/03/08 04:22:12 $ 
+ * @version $Revision: 1.14 $ $Date: 2004/04/08 20:46:00 $ 
  */
 public interface TestStatistic {
     
@@ -152,6 +152,8 @@ public interface TestStatistic {
      * @param sample2 array of sample data values
      * @return t statistic
      * @throws IllegalArgumentException if the precondition is not met
+     * @throws MathException if the statistic can not be computed do to a
+     *         convergence or other numerical error.
      */
     double t(double[] sample1, double[] sample2) 
         throws IllegalArgumentException, MathException;

src/java/org/apache/commons/math/stat/TestStatisticImpl.java

@@ -26,7 +26,7 @@ import org.apache.commons.math.distribution.ChiSquaredDistribution;
 /**
  * Implements test statistics defined in the TestStatistic interface.
  *
- * @version $Revision: 1.14 $ $Date: 2004/03/08 04:22:12 $
+ * @version $Revision: 1.15 $ $Date: 2004/04/08 20:46:00 $
  */
 public class TestStatisticImpl implements TestStatistic, Serializable {
 
@@ -342,6 +342,7 @@ public class TestStatisticImpl implements TestStatistic, Serializable {
      * @param n1 first sample n
      * @param n2 second sample n
      * @return p-value
+     * @throws MathException if an error occurs computing the p-value
      */
     private double tTest(double m1, double m2, double v1, double v2, double n1, double n2)
         throws MathException {
@@ -359,6 +360,7 @@ public class TestStatisticImpl implements TestStatistic, Serializable {
      * @param v sample variance
      * @param n sample n
      * @return p-value
+     * @throws MathException if an error occurs computing the p-value
      */
     private double tTest(double m, double mu, double v, double n)
         throws MathException {

src/java/org/apache/commons/math/util/MathUtils.java

@@ -19,20 +19,26 @@ package org.apache.commons.math.util;
 /**
  * Some useful additions to the built-in functions in {@link Math}.
  *
- * @version $Revision: 1.13 $ $Date: 2004/04/05 03:47:49 $
+ * @version $Revision: 1.14 $ $Date: 2004/04/08 20:46:01 $
  */
 public final class MathUtils {
     
+    /** 0.0 cast as a byte. */
     private static final byte ZB = (byte) 0;
     
+    /** -1.0 cast as a byte. */
     private static final byte NB = (byte) -1;
     
+    /** 1.0 cast as a byte. */
     private static final byte PB = (byte) 1;
     
+    /** 0.0 cast as a short. */
     private static final short ZS = (short) 0;
     
+    /** -1.0 cast as a short. */
     private static final short NS = (short) -1;
     
+    /** 1.0 cast as a short. */
     private static final short PS = (short) 1;
     
     /**