added missing javadoc

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

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

@@ -17,6 +17,11 @@
 
 package org.apache.commons.math;
 
+/**
+ * Error thrown when a method is called with an out of bounds argument.
+ *
+ * @version $Revision$ $Date$
+ */
 public class ArgumentOutsideDomainException extends FunctionEvaluationException {
 
     /** Serializable version identifier. */

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

@@ -54,6 +54,7 @@ public class MathException extends Exception {
         JDK_SUPPORTS_NESTED = flag;
     }
 
+    /** Cache for resources bundle. */
     private static ResourceBundle cachedResources = null;
  
     /**

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

@@ -19,6 +19,12 @@ package org.apache.commons.math;
 
 import org.apache.commons.math.ConvergenceException;
 
+/**
+ * Error thrown when a numerical computation exceeds its allowed
+ * number of iterations.
+ *
+ * @version $Revision$ $Date$
+ */
 public class MaxIterationsExceededException extends ConvergenceException {
 
     /** Serializable version identifier. */

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

@@ -30,10 +30,14 @@ public class MessagesResources_fr
   public MessagesResources_fr() {
   }
 
+  /** Get the non-translated/translated messages arrays from this resource bundle.
+   * @return non-translated/translated messages arrays
+   */
   public Object[][] getContents() {
     return (Object[][]) contents.clone();
   }
 
+  /** Non-translated/translated messages arrays. */
   static final Object[][] contents = {
 
     // org.apache.commons.math.FunctionEvaluationException

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

@@ -33,6 +33,7 @@ public class PoissonDistributionImpl extends AbstractIntegerDistribution
     /** Serializable version identifier */
     private static final long serialVersionUID = -3349935121172596109L;
 
+    /** Distribution used to compute normal approximation. */
     private NormalDistribution normal;
     
     /**

src/java/org/apache/commons/math/estimation/AbstractEstimator.java

@@ -22,6 +22,13 @@ import java.util.Arrays;
 import org.apache.commons.math.linear.InvalidMatrixException;
 import org.apache.commons.math.linear.RealMatrixImpl;
 
+/**
+ * Base class for implementing estimators.
+ * <p>This base class handles the boilerplates methods associated to thresholds
+ * settings, jacobian and error estimation.</p>
+ * @version $Revision$ $Date$
+ *
+ */
 public abstract class AbstractEstimator implements Estimator {
 
     /**
@@ -227,6 +234,20 @@ public abstract class AbstractEstimator implements Estimator {
 
     }
 
+    /** 
+     * Solve an estimation problem.
+     *
+     * <p>The method should set the parameters of the problem to several
+     * trial values until it reaches convergence. If this method returns
+     * normally (i.e. without throwing an exception), then the best
+     * estimate of the parameters can be retrieved from the problem
+     * itself, through the {@link EstimationProblem#getAllParameters
+     * EstimationProblem.getAllParameters} method.</p>
+     *
+     * @param problem estimation problem to solve
+     * @exception EstimationException if the problem cannot be solved
+     *
+     */
     public abstract void estimate(EstimationProblem problem)
     throws EstimationException;
 

src/java/org/apache/commons/math/estimation/EstimatedParameter.java

@@ -117,6 +117,7 @@ public class EstimatedParameter
    */
   private   boolean bound;
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -555440800213416949L;
 
 }

src/java/org/apache/commons/math/estimation/GaussNewtonEstimator.java

@@ -170,9 +170,13 @@ public class GaussNewtonEstimator extends AbstractEstimator implements Serializa
 
     }
 
+    /** Threshold for cost steady state detection. */
     private double steadyStateThreshold;
+
+    /** Threshold for cost convergence. */
     private double convergence;
 
+    /** Serializable version identifier */
      private static final long serialVersionUID = 5485001826076289109L;
 
 }

src/java/org/apache/commons/math/estimation/LevenbergMarquardtEstimator.java

@@ -859,6 +859,7 @@ public class LevenbergMarquardtEstimator extends AbstractEstimator implements Se
    * and the columns of the jacobian. */
   private double orthoTolerance;
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -5705952631533171019L;
 
 }

src/java/org/apache/commons/math/estimation/SimpleEstimationProblem.java

@@ -48,10 +48,18 @@ public class SimpleEstimationProblem implements EstimationProblem {
         measurements = new ArrayList();
     }
 
+    /** 
+     * Get all the parameters of the problem.
+     * @return parameters
+     */
     public EstimatedParameter[] getAllParameters() {
         return (EstimatedParameter[]) parameters.toArray(new EstimatedParameter[parameters.size()]);
     }
 
+    /** 
+     * Get the unbound parameters of the problem.
+     * @return unbound parameters
+     */
     public EstimatedParameter[] getUnboundParameters() {
 
         // filter the unbound parameters
@@ -68,10 +76,17 @@ public class SimpleEstimationProblem implements EstimationProblem {
         
     }
 
+    /** 
+     * Get the measurements of an estimation problem.
+     * @return measurements
+     */
     public WeightedMeasurement[] getMeasurements() {
         return (WeightedMeasurement[]) measurements.toArray(new WeightedMeasurement[measurements.size()]);
     }
 
+    /** Add a parameter to the problem.
+     * @param p parameter to add
+     */
     protected void addParameter(EstimatedParameter p) {
         parameters.add(p);
     }

src/java/org/apache/commons/math/estimation/WeightedMeasurement.java

@@ -154,8 +154,13 @@ public abstract class WeightedMeasurement implements Serializable {
     return ignored;
   }
 
+  /** Measurement weight. */
   private final double  weight;
+
+  /** Value of the measurements. */
   private final double  measuredValue;
+
+  /** Ignore measurement indicator. */
   private       boolean ignored;
 
 }

src/java/org/apache/commons/math/fraction/FractionConversionException.java

@@ -19,6 +19,12 @@ package org.apache.commons.math.fraction;
 
 import org.apache.commons.math.MaxIterationsExceededException;
 
+/**
+ * Error thrown when a double value cannot be converted to a fraction
+ * in the allowed number of iterations.
+ *
+ * @version $Revision$ $Date$
+ */
 public class FractionConversionException extends MaxIterationsExceededException {
 
     /** Serializable version identifier. */

src/java/org/apache/commons/math/geometry/CardanEulerSingularityException.java

@@ -25,7 +25,6 @@ import org.apache.commons.math.MathException;
  * @version $Revision$ $Date$
 
  */
-
 public class CardanEulerSingularityException
   extends MathException {
 
@@ -38,6 +37,7 @@ public class CardanEulerSingularityException
     super(isCardan ? "Cardan angles singularity" : "Euler angles singularity", new Object[0]);
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -1360952845582206770L;
 
 }

src/java/org/apache/commons/math/geometry/NotARotationMatrixException.java

@@ -38,6 +38,7 @@ public class NotARotationMatrixException
     super(specifier, parts);
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = 5647178478658937642L;
 
 }

src/java/org/apache/commons/math/geometry/Rotation.java

@@ -1028,6 +1028,7 @@ public class Rotation implements Serializable {
   /** Third coordinate of the vectorial part of the quaternion. */
   private final double q3;
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = 5127795878493115119L;
 
 }

src/java/org/apache/commons/math/geometry/Vector3D.java

@@ -354,6 +354,7 @@ public class Vector3D
   /** Height. */
   private final double z;
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = 7318440192750283659L;
 
 }

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

@@ -1095,8 +1095,8 @@ public class BigMatrixImpl implements BigMatrix, Serializable {
     }
     
     /**
-     * 
-     * @see Object#toString()
+     * Get a string representation for this matrix.
+     * @return a string representation for this matrix
      */
     public String toString() {
         StringBuffer res = new StringBuffer();

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

@@ -846,8 +846,8 @@ public class RealMatrixImpl implements RealMatrix, Serializable {
     }
 
     /**
-     *
-     * @see java.lang.Object#toString()
+     * Get a string representation for this matrix.
+     * @return a string representation for this matrix
      */
     public String toString() {
         StringBuffer res = new StringBuffer();

src/java/org/apache/commons/math/ode/AbstractStepInterpolator.java

@@ -354,9 +354,17 @@ public abstract class AbstractStepInterpolator
     throws DerivativeException {
   }
 
+  /** Write the instance to an output channel.
+   * @param out output channel
+   * @exception IOException if the instance cannot be written
+   */
   public abstract void writeExternal(ObjectOutput out)
     throws IOException;
 
+  /** Read the instance from an input channel.
+   * @param in input channel
+   * @exception IOException if the instance cannot be read
+   */
   public abstract void readExternal(ObjectInput in)
     throws IOException;
 

src/java/org/apache/commons/math/ode/AdaptiveStepsizeIntegrator.java

@@ -324,15 +324,49 @@ public abstract class AdaptiveStepsizeIntegrator
 
   }
 
+  /** Integrate the differential equations up to the given time.
+   * <p>This method solves an Initial Value Problem (IVP).</p>
+   * <p>Since this method stores some internal state variables made
+   * available in its public interface during integration ({@link
+   * #getCurrentSignedStepsize()}), it is <em>not</em> thread-safe.</p>
+   * @param equations differential equations to integrate
+   * @param t0 initial time
+   * @param y0 initial value of the state vector at t0
+   * @param t target time for the integration
+   * (can be set to a value smaller than <code>t0</code> for backward integration)
+   * @param y placeholder where to put the state vector at each successful
+   *  step (and hence at the end of integration), can be the same object as y0
+   * @throws IntegratorException if the integrator cannot perform integration
+   * @throws DerivativeException this exception is propagated to the caller if
+   * the underlying user function triggers one
+   */
   public abstract void integrate (FirstOrderDifferentialEquations equations,
                                   double t0, double[] y0,
                                   double t, double[] y)
     throws DerivativeException, IntegratorException;
 
+  /** Get the current value of the step start time t<sub>i</sub>.
+   * <p>This method can be called during integration (typically by
+   * the object implementing the {@link FirstOrderDifferentialEquations
+   * differential equations} problem) if the value of the current step that
+   * is attempted is needed.</p>
+   * <p>The result is undefined if the method is called outside of
+   * calls to {@link #integrate}</p>
+   * @return current value of the step start time t<sub>i</sub>
+   */
   public double getCurrentStepStart() {
     return stepStart;
   }
 
+  /** Get the current signed value of the integration stepsize.
+   * <p>This method can be called during integration (typically by
+   * the object implementing the {@link FirstOrderDifferentialEquations
+   * differential equations} problem) if the signed value of the current stepsize
+   * that is tried is needed.</p>
+   * <p>The result is undefined if the method is called outside of
+   * calls to {@link #integrate}</p>
+   * @return current signed value of the stepsize
+   */
   public double getCurrentSignedStepsize() {
     return stepSize;
   }

src/java/org/apache/commons/math/ode/ClassicalRungeKuttaIntegrator.java

@@ -46,18 +46,22 @@ package org.apache.commons.math.ode;
 public class ClassicalRungeKuttaIntegrator
   extends RungeKuttaIntegrator {
 
+  /** Integrator method name. */
   private static final String methodName = "classical Runge-Kutta";
 
+  /** Time steps Butcher array. */
   private static final double[] c = {
     1.0 / 2.0, 1.0 / 2.0, 1.0
   };
 
+  /** Internal weights Butcher array. */
   private static final double[][] a = {
     { 1.0 / 2.0 },
     { 0.0, 1.0 / 2.0 },
     { 0.0, 0.0, 1.0 }
   };
 
+  /** Propagation weights Butcher array. */
   private static final double[] b = {
     1.0 / 6.0, 1.0 / 3.0, 1.0 / 3.0, 1.0 / 6.0
   };

src/java/org/apache/commons/math/ode/ClassicalRungeKuttaStepInterpolator.java

@@ -104,6 +104,7 @@ class ClassicalRungeKuttaStepInterpolator
 
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -6576285612589783992L;
 
 }

src/java/org/apache/commons/math/ode/ContinuousOutputModel.java

@@ -371,6 +371,7 @@ public class ContinuousOutputModel
   /** Steps table. */
   private ArrayList steps;
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = 2259286184268533249L;
 
 }

src/java/org/apache/commons/math/ode/DerivativeException.java

@@ -44,6 +44,7 @@ public class DerivativeException
     super(cause);
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -4100440615830558122L;
 
 }

src/java/org/apache/commons/math/ode/DormandPrince54Integrator.java

@@ -46,12 +46,15 @@ package org.apache.commons.math.ode;
 public class DormandPrince54Integrator
   extends EmbeddedRungeKuttaIntegrator {
 
+  /** Integrator method name. */
   private static final String methodName = "Dormand-Prince 5(4)";
 
+  /** Time steps Butcher array. */
   private static final double[] staticC = {
     1.0/5.0, 3.0/10.0, 4.0/5.0, 8.0/9.0, 1.0, 1.0
   };
 
+  /** Internal weights Butcher array. */
   private static final double[][] staticA = {
     {1.0/5.0},
     {3.0/40.0, 9.0/40.0},
@@ -61,15 +64,29 @@ public class DormandPrince54Integrator
     {35.0/384.0, 0.0, 500.0/1113.0, 125.0/192.0, -2187.0/6784.0, 11.0/84.0}
   };
 
+  /** Propagation weights Butcher array. */
   private static final double[] staticB = {
     35.0/384.0, 0.0, 500.0/1113.0, 125.0/192.0, -2187.0/6784.0, 11.0/84.0, 0.0
   };
 
+  /** Error array, element 1. */
   private static final double e1 =     71.0 / 57600.0;
+
+  // element 2 is zero, so it is neither stored nor used
+
+  /** Error array, element 3. */
   private static final double e3 =    -71.0 / 16695.0;
+
+  /** Error array, element 4. */
   private static final double e4 =     71.0 / 1920.0;
+
+  /** Error array, element 5. */
   private static final double e5 = -17253.0 / 339200.0;
+
+  /** Error array, element 6. */
   private static final double e6 =     22.0 / 525.0;
+
+  /** Error array, element 7. */
   private static final double e7 =     -1.0 / 40.0;
 
   /** Simple constructor.

src/java/org/apache/commons/math/ode/DormandPrince54StepInterpolator.java

@@ -172,20 +172,44 @@ class DormandPrince54StepInterpolator
   /** Initialization indicator for the interpolation vectors. */
   private boolean vectorsInitialized;
 
-  // last row of the Butcher-array internal weights, note that a71 is null
+  /** Last row of the Butcher-array internal weights, element 0. */
   private static final double a70 =    35.0 /  384.0;
+
+  // element 1 is zero, so it is neither stored nor used
+
+  /** Last row of the Butcher-array internal weights, element 2. */
   private static final double a72 =   500.0 / 1113.0;
+
+  /** Last row of the Butcher-array internal weights, element 3. */
   private static final double a73 =   125.0 /  192.0;
+
+  /** Last row of the Butcher-array internal weights, element 4. */
   private static final double a74 = -2187.0 / 6784.0;
+
+  /** Last row of the Butcher-array internal weights, element 5. */
   private static final double a75 =    11.0 /   84.0;
 
-  // dense output of Shampine (1986), note that d1 is null
+  /** Shampine (1986) Dense output, element 0. */
   private static final double d0 =  -12715105075.0 /  11282082432.0;
+
+  // element 1 is zero, so it is neither stored nor used
+
+  /** Shampine (1986) Dense output, element 2. */
   private static final double d2 =   87487479700.0 /  32700410799.0;
+
+  /** Shampine (1986) Dense output, element 3. */
   private static final double d3 =  -10690763975.0 /   1880347072.0;
+
+  /** Shampine (1986) Dense output, element 4. */
   private static final double d4 =  701980252875.0 / 199316789632.0;
+
+  /** Shampine (1986) Dense output, element 5. */
   private static final double d5 =   -1453857185.0 /    822651844.0;
+
+  /** Shampine (1986) Dense output, element 6. */
   private static final double d6 =      69997945.0 /     29380423.0;
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = 4104157279605906956L;
+
 }

src/java/org/apache/commons/math/ode/DormandPrince853Integrator.java

@@ -54,68 +54,69 @@ package org.apache.commons.math.ode;
 public class DormandPrince853Integrator
   extends EmbeddedRungeKuttaIntegrator {
 
+  /** Integrator method name. */
   private static final String methodName = "Dormand-Prince 8 (5, 3)";
 
-  private static final double sqrt6 = Math.sqrt(6.0);
-
+  /** Time steps Butcher array. */
   private static final double[] staticC = {
-    (12.0 - 2.0 * sqrt6) / 135.0, (6.0 - sqrt6) / 45.0, (6.0 - sqrt6) / 30.0,
-    (6.0 + sqrt6) / 30.0, 1.0/3.0, 1.0/4.0, 4.0/13.0, 127.0/195.0, 3.0/5.0,
+    (12.0 - 2.0 * Math.sqrt(6.0)) / 135.0, (6.0 - Math.sqrt(6.0)) / 45.0, (6.0 - Math.sqrt(6.0)) / 30.0,
+    (6.0 + Math.sqrt(6.0)) / 30.0, 1.0/3.0, 1.0/4.0, 4.0/13.0, 127.0/195.0, 3.0/5.0,
     6.0/7.0, 1.0, 1.0
   };
 
+  /** Internal weights Butcher array. */
   private static final double[][] staticA = {
 
     // k2
-    {(12.0 - 2.0 * sqrt6) / 135.0},
+    {(12.0 - 2.0 * Math.sqrt(6.0)) / 135.0},
 
     // k3
-    {(6.0 - sqrt6) / 180.0, (6.0 - sqrt6) / 60.0},
+    {(6.0 - Math.sqrt(6.0)) / 180.0, (6.0 - Math.sqrt(6.0)) / 60.0},
 
     // k4
-    {(6.0 - sqrt6) / 120.0, 0.0, (6.0 - sqrt6) / 40.0},
+    {(6.0 - Math.sqrt(6.0)) / 120.0, 0.0, (6.0 - Math.sqrt(6.0)) / 40.0},
 
     // k5
-    {(462.0 + 107.0 * sqrt6) / 3000.0, 0.0,
-     (-402.0 - 197.0 * sqrt6) / 1000.0, (168.0 + 73.0 * sqrt6) / 375.0},
+    {(462.0 + 107.0 * Math.sqrt(6.0)) / 3000.0, 0.0,
+     (-402.0 - 197.0 * Math.sqrt(6.0)) / 1000.0, (168.0 + 73.0 * Math.sqrt(6.0)) / 375.0},
 
     // k6
-    {1.0 / 27.0, 0.0, 0.0, (16.0 + sqrt6) / 108.0, (16.0 - sqrt6) / 108.0},
+    {1.0 / 27.0, 0.0, 0.0, (16.0 + Math.sqrt(6.0)) / 108.0, (16.0 - Math.sqrt(6.0)) / 108.0},
 
     // k7
-    {19.0 / 512.0, 0.0, 0.0, (118.0 + 23.0 * sqrt6) / 1024.0,
-     (118.0 - 23.0 * sqrt6) / 1024.0, -9.0 / 512.0},
+    {19.0 / 512.0, 0.0, 0.0, (118.0 + 23.0 * Math.sqrt(6.0)) / 1024.0,
+     (118.0 - 23.0 * Math.sqrt(6.0)) / 1024.0, -9.0 / 512.0},
 
     // k8
-    {13772.0 / 371293.0, 0.0, 0.0, (51544.0 + 4784.0 * sqrt6) / 371293.0,
-     (51544.0 - 4784.0 * sqrt6) / 371293.0, -5688.0 / 371293.0, 3072.0 / 371293.0},
+    {13772.0 / 371293.0, 0.0, 0.0, (51544.0 + 4784.0 * Math.sqrt(6.0)) / 371293.0,
+     (51544.0 - 4784.0 * Math.sqrt(6.0)) / 371293.0, -5688.0 / 371293.0, 3072.0 / 371293.0},
 
     // k9
     {58656157643.0 / 93983540625.0, 0.0, 0.0,
-     (-1324889724104.0 - 318801444819.0 * sqrt6) / 626556937500.0,
-     (-1324889724104.0 + 318801444819.0 * sqrt6) / 626556937500.0,
+     (-1324889724104.0 - 318801444819.0 * Math.sqrt(6.0)) / 626556937500.0,
+     (-1324889724104.0 + 318801444819.0 * Math.sqrt(6.0)) / 626556937500.0,
      96044563816.0 / 3480871875.0, 5682451879168.0 / 281950621875.0,
      -165125654.0 / 3796875.0},
 
     // k10
     {8909899.0 / 18653125.0, 0.0, 0.0,
-     (-4521408.0 - 1137963.0 * sqrt6) / 2937500.0,
-     (-4521408.0 + 1137963.0 * sqrt6) / 2937500.0,
+     (-4521408.0 - 1137963.0 * Math.sqrt(6.0)) / 2937500.0,
+     (-4521408.0 + 1137963.0 * Math.sqrt(6.0)) / 2937500.0,
      96663078.0 / 4553125.0, 2107245056.0 / 137915625.0,
      -4913652016.0 / 147609375.0, -78894270.0 / 3880452869.0},
 
     // k11
     {-20401265806.0 / 21769653311.0, 0.0, 0.0,
-     (354216.0 + 94326.0 * sqrt6) / 112847.0,
-     (354216.0 - 94326.0 * sqrt6) / 112847.0,
+     (354216.0 + 94326.0 * Math.sqrt(6.0)) / 112847.0,
+     (354216.0 - 94326.0 * Math.sqrt(6.0)) / 112847.0,
      -43306765128.0 / 5313852383.0, -20866708358144.0 / 1126708119789.0,
      14886003438020.0 / 654632330667.0, 35290686222309375.0 / 14152473387134411.0,
      -1477884375.0 / 485066827.0},
 
     // k12
     {39815761.0 / 17514443.0, 0.0, 0.0,
-     (-3457480.0 - 960905.0 * sqrt6) / 551636.0,
-     (-3457480.0 + 960905.0 * sqrt6) / 551636.0,
+     (-3457480.0 - 960905.0 * Math.sqrt(6.0)) / 551636.0,
+     (-3457480.0 + 960905.0 * Math.sqrt(6.0)) / 551636.0,
      -844554132.0 / 47026969.0, 8444996352.0 / 302158619.0,
      -2509602342.0 / 877790785.0, -28388795297996250.0 / 3199510091356783.0,
      226716250.0 / 18341897.0, 1371316744.0 / 2131383595.0},
@@ -130,6 +131,7 @@ public class DormandPrince853Integrator
 
   };
 
+  /** Propagation weights Butcher array. */
   private static final double[] staticB = {
       104257.0/1920240.0,
       0.0,
@@ -146,22 +148,57 @@ public class DormandPrince853Integrator
       0.0
   };
 
+  /** First error weights array, element 1. */
   private static final double e1_01 =         116092271.0 / 8848465920.0;
+
+  // elements 2 to 5 are zero, so they are neither stored nor used
+
+  /** First error weights array, element 6. */
   private static final double e1_06 =          -1871647.0 / 1527680.0;
+
+  /** First error weights array, element 7. */
   private static final double e1_07 =         -69799717.0 / 140793660.0;
+
+  /** First error weights array, element 8. */
   private static final double e1_08 =     1230164450203.0 / 739113984000.0;
+
+  /** First error weights array, element 9. */
   private static final double e1_09 = -1980813971228885.0 / 5654156025964544.0;
+
+  /** First error weights array, element 10. */
   private static final double e1_10 =         464500805.0 / 1389975552.0;
+
+  /** First error weights array, element 11. */
   private static final double e1_11 =     1606764981773.0 / 19613062656000.0;
+
+  /** First error weights array, element 12. */
   private static final double e1_12 =           -137909.0 / 6168960.0;
 
+
+  /** Second error weights array, element 1. */
   private static final double e2_01 =           -364463.0 / 1920240.0;
+
+  // elements 2 to 5 are zero, so they are neither stored nor used
+
+  /** Second error weights array, element 6. */
   private static final double e2_06 =           3399327.0 / 763840.0;
+
+  /** Second error weights array, element 7. */
   private static final double e2_07 =          66578432.0 / 35198415.0;
+
+  /** Second error weights array, element 8. */
   private static final double e2_08 =       -1674902723.0 / 288716400.0;
+
+  /** Second error weights array, element 9. */
   private static final double e2_09 =   -74684743568175.0 / 176692375811392.0;
+
+  /** Second error weights array, element 10. */
   private static final double e2_10 =           -734375.0 / 4826304.0;
+
+  /** Second error weights array, element 11. */
   private static final double e2_11 =         171414593.0 / 851261400.0;
+
+  /** Second error weights array, element 12. */
   private static final double e2_12 =             69869.0 / 3084480.0;
 
   /** Simple constructor.

src/java/org/apache/commons/math/ode/DormandPrince853StepInterpolator.java

@@ -310,62 +310,143 @@ class DormandPrince853StepInterpolator
   /** Initialization indicator for the interpolation vectors. */
   private boolean vectorsInitialized;
 
-  // external weights of the integrator,
-  // note that b_02 through b_05 are null
-  private static double b_01 =         104257.0 / 1920240.0;
-  private static double b_06 =        3399327.0 / 763840.0;
-  private static double b_07 =       66578432.0 / 35198415.0;
-  private static double b_08 =    -1674902723.0 / 288716400.0;
-  private static double b_09 = 54980371265625.0 / 176692375811392.0;
-  private static double b_10 =        -734375.0 / 4826304.0;
-  private static double b_11 =      171414593.0 / 851261400.0;
-  private static double b_12 =         137909.0 / 3084480.0;
+  /** Propagation weights, element 1. */
+  private static final double b_01 =         104257.0 / 1920240.0;
 
-  // k14 for interpolation only
-  private static double c14    = 1.0 / 10.0;
+  // elements 2 to 5 are zero, so they are neither stored nor used
 
-  private static double k14_01 =       13481885573.0 / 240030000000.0      - b_01;
-  private static double k14_06 =                 0.0                       - b_06;
-  private static double k14_07 =      139418837528.0 / 549975234375.0      - b_07;
-  private static double k14_08 =   -11108320068443.0 / 45111937500000.0    - b_08;
-  private static double k14_09 = -1769651421925959.0 / 14249385146080000.0 - b_09;
-  private static double k14_10 =          57799439.0 / 377055000.0         - b_10;
-  private static double k14_11 =      793322643029.0 / 96734250000000.0    - b_11;
-  private static double k14_12 =        1458939311.0 / 192780000000.0      - b_12;
-  private static double k14_13 =             -4149.0 / 500000.0;
+  /** Propagation weights, element 6. */
+  private static final double b_06 =        3399327.0 / 763840.0;
 
-  // k15 for interpolation only
-  private static double c15    = 1.0 / 5.0;
+  /** Propagation weights, element 7. */
+  private static final double b_07 =       66578432.0 / 35198415.0;
 
-  private static double k15_01 =     1595561272731.0 / 50120273500000.0    - b_01;
-  private static double k15_06 =      975183916491.0 / 34457688031250.0    - b_06;
-  private static double k15_07 =    38492013932672.0 / 718912673015625.0   - b_07;
-  private static double k15_08 = -1114881286517557.0 / 20298710767500000.0 - b_08;
-  private static double k15_09 =                 0.0                       - b_09;
-  private static double k15_10 =                 0.0                       - b_10;
-  private static double k15_11 =    -2538710946863.0 / 23431227861250000.0 - b_11;
-  private static double k15_12 =        8824659001.0 / 23066716781250.0    - b_12;
-  private static double k15_13 =      -11518334563.0 / 33831184612500.0;
-  private static double k15_14 =        1912306948.0 / 13532473845.0;
+  /** Propagation weights, element 8. */
+  private static final double b_08 =    -1674902723.0 / 288716400.0;
 
-  // k16 for interpolation only
-  private static double c16    = 7.0 / 9.0;
+  /** Propagation weights, element 9. */
+  private static final double b_09 = 54980371265625.0 / 176692375811392.0;
 
-  private static double k16_01 =      -13613986967.0 / 31741908048.0       - b_01;
-  private static double k16_06 =       -4755612631.0 / 1012344804.0        - b_06;
-  private static double k16_07 =    42939257944576.0 / 5588559685701.0     - b_07;
-  private static double k16_08 =    77881972900277.0 / 19140370552944.0    - b_08;
-  private static double k16_09 =    22719829234375.0 / 63689648654052.0    - b_09;
-  private static double k16_10 =                 0.0                       - b_10;
-  private static double k16_11 =                 0.0                       - b_11;
-  private static double k16_12 =                 0.0                       - b_12;
-  private static double k16_13 =       -1199007803.0 / 857031517296.0;
-  private static double k16_14 =      157882067000.0 / 53564469831.0;
-  private static double k16_15 =     -290468882375.0 / 31741908048.0;
+  /** Propagation weights, element 10. */
+  private static final double b_10 =        -734375.0 / 4826304.0;
 
-  // interpolation weights
-  // (beware that only the non-null values are in the table)
-  private static double[][] d = {
+  /** Propagation weights, element 11. */
+  private static final double b_11 =      171414593.0 / 851261400.0;
+
+  /** Propagation weights, element 12. */
+  private static final double b_12 =         137909.0 / 3084480.0;
+
+  /** Time step for stage 14 (interpolation only). */
+  private static final double c14    = 1.0 / 10.0;
+
+  /** Internal weights for stage 14, element 1. */
+  private static final double k14_01 =       13481885573.0 / 240030000000.0      - b_01;
+
+  // elements 2 to 5 are zero, so they are neither stored nor used
+
+  /** Internal weights for stage 14, element 6. */
+  private static final double k14_06 =                 0.0                       - b_06;
+
+  /** Internal weights for stage 14, element 7. */
+  private static final double k14_07 =      139418837528.0 / 549975234375.0      - b_07;
+
+  /** Internal weights for stage 14, element 8. */
+  private static final double k14_08 =   -11108320068443.0 / 45111937500000.0    - b_08;
+
+  /** Internal weights for stage 14, element 9. */
+  private static final double k14_09 = -1769651421925959.0 / 14249385146080000.0 - b_09;
+
+  /** Internal weights for stage 14, element 10. */
+  private static final double k14_10 =          57799439.0 / 377055000.0         - b_10;
+
+  /** Internal weights for stage 14, element 11. */
+  private static final double k14_11 =      793322643029.0 / 96734250000000.0    - b_11;
+
+  /** Internal weights for stage 14, element 12. */
+  private static final double k14_12 =        1458939311.0 / 192780000000.0      - b_12;
+
+  /** Internal weights for stage 14, element 13. */
+  private static final double k14_13 =             -4149.0 / 500000.0;
+
+  /** Time step for stage 15 (interpolation only). */
+  private static final double c15    = 1.0 / 5.0;
+
+
+  /** Internal weights for stage 15, element 1. */
+  private static final double k15_01 =     1595561272731.0 / 50120273500000.0    - b_01;
+
+  // elements 2 to 5 are zero, so they are neither stored nor used
+
+  /** Internal weights for stage 15, element 6. */
+  private static final double k15_06 =      975183916491.0 / 34457688031250.0    - b_06;
+
+  /** Internal weights for stage 15, element 7. */
+  private static final double k15_07 =    38492013932672.0 / 718912673015625.0   - b_07;
+
+  /** Internal weights for stage 15, element 8. */
+  private static final double k15_08 = -1114881286517557.0 / 20298710767500000.0 - b_08;
+
+  /** Internal weights for stage 15, element 9. */
+  private static final double k15_09 =                 0.0                       - b_09;
+
+  /** Internal weights for stage 15, element 10. */
+  private static final double k15_10 =                 0.0                       - b_10;
+
+  /** Internal weights for stage 15, element 11. */
+  private static final double k15_11 =    -2538710946863.0 / 23431227861250000.0 - b_11;
+
+  /** Internal weights for stage 15, element 12. */
+  private static final double k15_12 =        8824659001.0 / 23066716781250.0    - b_12;
+
+  /** Internal weights for stage 15, element 13. */
+  private static final double k15_13 =      -11518334563.0 / 33831184612500.0;
+
+  /** Internal weights for stage 15, element 14. */
+  private static final double k15_14 =        1912306948.0 / 13532473845.0;
+
+  /** Time step for stage 16 (interpolation only). */
+  private static final double c16    = 7.0 / 9.0;
+
+
+  /** Internal weights for stage 16, element 1. */
+  private static final double k16_01 =      -13613986967.0 / 31741908048.0       - b_01;
+
+  // elements 2 to 5 are zero, so they are neither stored nor used
+
+  /** Internal weights for stage 16, element 6. */
+  private static final double k16_06 =       -4755612631.0 / 1012344804.0        - b_06;
+
+  /** Internal weights for stage 16, element 7. */
+  private static final double k16_07 =    42939257944576.0 / 5588559685701.0     - b_07;
+
+  /** Internal weights for stage 16, element 8. */
+  private static final double k16_08 =    77881972900277.0 / 19140370552944.0    - b_08;
+
+  /** Internal weights for stage 16, element 9. */
+  private static final double k16_09 =    22719829234375.0 / 63689648654052.0    - b_09;
+
+  /** Internal weights for stage 16, element 10. */
+  private static final double k16_10 =                 0.0                       - b_10;
+
+  /** Internal weights for stage 16, element 11. */
+  private static final double k16_11 =                 0.0                       - b_11;
+
+  /** Internal weights for stage 16, element 12. */
+  private static final double k16_12 =                 0.0                       - b_12;
+
+  /** Internal weights for stage 16, element 13. */
+  private static final double k16_13 =       -1199007803.0 / 857031517296.0;
+
+  /** Internal weights for stage 16, element 14. */
+  private static final double k16_14 =      157882067000.0 / 53564469831.0;
+
+  /** Internal weights for stage 16, element 15. */
+  private static final double k16_15 =     -290468882375.0 / 31741908048.0;
+
+  /** Interpolation weights.
+   * (beware that only the non-null values are in the table)
+   */
+  private static final double[][] d = {
 
     {        -17751989329.0 / 2106076560.0,               4272954039.0 / 7539864640.0,
             -118476319744.0 / 38604839385.0,            755123450731.0 / 316657731600.0,
@@ -397,6 +478,7 @@ class DormandPrince853StepInterpolator
 
   };
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = 7152276390558450974L;
 
 }

src/java/org/apache/commons/math/ode/DummyStepHandler.java

@@ -87,6 +87,7 @@ public class DummyStepHandler
   /** The only instance. */
   private static DummyStepHandler instance = new DummyStepHandler();
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = 2731635121223090252L;
 
 }

src/java/org/apache/commons/math/ode/DummyStepInterpolator.java

@@ -92,12 +92,20 @@ public class DummyStepInterpolator
       System.arraycopy(currentState, 0, interpolatedState, 0, currentState.length);
   }
     
+  /** Write the instance to an output channel.
+   * @param out output channel
+   * @exception IOException if the instance cannot be written
+   */
   public void writeExternal(ObjectOutput out)
     throws IOException {
     // save the state of the base class
     writeBaseExternal(out);
   }
 
+  /** Read the instance from an input channel.
+   * @param in input channel
+   * @exception IOException if the instance cannot be read
+   */
   public void readExternal(ObjectInput in)
     throws IOException {
 
@@ -113,6 +121,7 @@ public class DummyStepInterpolator
 
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = 1708010296707839488L;
 
 }

src/java/org/apache/commons/math/ode/EmbeddedRungeKuttaIntegrator.java

@@ -61,7 +61,7 @@ public abstract class EmbeddedRungeKuttaIntegrator
    * @param fsal indicate that the method is an <i>fsal</i>
    * @param c time steps from Butcher array (without the first zero)
    * @param a internal weights from Butcher array (without the first empty row)
-   * @param b external weights for the high order method from Butcher array
+   * @param b propagation weights for the high order method from Butcher array
    * @param prototype prototype of the step interpolator to use
    * @param minStep minimal step (must be positive even for backward
    * integration), the last step can be smaller than this
@@ -98,7 +98,7 @@ public abstract class EmbeddedRungeKuttaIntegrator
    * @param fsal indicate that the method is an <i>fsal</i>
    * @param c time steps from Butcher array (without the first zero)
    * @param a internal weights from Butcher array (without the first empty row)
-   * @param b external weights for the high order method from Butcher array
+   * @param b propagation weights for the high order method from Butcher array
    * @param prototype prototype of the step interpolator to use
    * @param minStep minimal step (must be positive even for backward
    * integration), the last step can be smaller than this
@@ -155,6 +155,22 @@ public abstract class EmbeddedRungeKuttaIntegrator
     this.safety = safety;
   }
 
+  /** Integrate the differential equations up to the given time.
+   * <p>This method solves an Initial Value Problem (IVP).</p>
+   * <p>Since this method stores some internal state variables made
+   * available in its public interface during integration ({@link
+   * #getCurrentSignedStepsize()}), it is <em>not</em> thread-safe.</p>
+   * @param equations differential equations to integrate
+   * @param t0 initial time
+   * @param y0 initial value of the state vector at t0
+   * @param t target time for the integration
+   * (can be set to a value smaller than <code>t0</code> for backward integration)
+   * @param y placeholder where to put the state vector at each successful
+   *  step (and hence at the end of integration), can be the same object as y0
+   * @throws IntegratorException if the integrator cannot perform integration
+   * @throws DerivativeException this exception is propagated to the caller if
+   * the underlying user function triggers one
+   */
   public void integrate(FirstOrderDifferentialEquations equations,
                         double t0, double[] y0,
                         double t, double[] y)

src/java/org/apache/commons/math/ode/EulerIntegrator.java

@@ -49,14 +49,18 @@ package org.apache.commons.math.ode;
 public class EulerIntegrator
   extends RungeKuttaIntegrator {
 
+  /** Integrator method name. */
   private static final String methodName = "Euler";
 
+  /** Time steps Butcher array. */
   private static final double[] c = {
   };
 
+  /** Internal weights Butcher array. */
   private static final double[][] a = {
   };
 
+  /** Propagation weights Butcher array. */
   private static final double[] b = {
     1.0
   };

src/java/org/apache/commons/math/ode/EulerStepInterpolator.java

@@ -89,6 +89,7 @@ class EulerStepInterpolator
 
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -7179861704951334960L;
 
 }

src/java/org/apache/commons/math/ode/FirstOrderConverter.java

@@ -69,10 +69,22 @@ public class FirstOrderConverter
       zDDot          = new double[dimension];
   }
 
+  /** Get the dimension of the problem.
+   * <p>The dimension of the first order problem is twice the
+   * dimension of the underlying second order problem.</p>
+   * @return dimension of the problem
+   */
   public int getDimension() {
     return 2 * dimension;
   }
 
+  /** Get the current time derivative of the state vector.
+   * @param t current value of the independent <I>time</I> variable
+   * @param y array containing the current value of the state vector
+   * @param yDot placeholder array where to put the time derivative of the state vector
+   * @throws DerivativeException this exception is propagated to the caller if the
+   * underlying user function triggers one
+   */
   public void computeDerivatives(double t, double[] y, double[] yDot)
   throws DerivativeException {
 

src/java/org/apache/commons/math/ode/GillIntegrator.java

@@ -45,22 +45,24 @@ package org.apache.commons.math.ode;
 public class GillIntegrator
   extends RungeKuttaIntegrator {
 
+  /** Integrator method name. */
   private static final String methodName = "Gill";
 
-  private static final double sqrt2 = Math.sqrt(2.0);
-
+  /** Time steps Butcher array. */
   private static final double[] c = {
     1.0 / 2.0, 1.0 / 2.0, 1.0
   };
 
+  /** Internal weights Butcher array. */
   private static final double[][] a = {
     { 1.0 / 2.0 },
-    { (sqrt2 - 1.0) / 2.0, (2.0 - sqrt2) / 2.0 },
-    { 0.0, -sqrt2 / 2.0, (2.0 + sqrt2) / 2.0 }
+    { (Math.sqrt(2.0) - 1.0) / 2.0, (2.0 - Math.sqrt(2.0)) / 2.0 },
+    { 0.0, -Math.sqrt(2.0) / 2.0, (2.0 + Math.sqrt(2.0)) / 2.0 }
   };
 
+  /** Propagation weights Butcher array. */
   private static final double[] b = {
-    1.0 / 6.0, (2.0 - sqrt2) / 6.0, (2.0 + sqrt2) / 6.0, 1.0 / 6.0
+    1.0 / 6.0, (2.0 - Math.sqrt(2.0)) / 6.0, (2.0 + Math.sqrt(2.0)) / 6.0, 1.0 / 6.0
   };
 
   /** Simple constructor.

src/java/org/apache/commons/math/ode/GillStepInterpolator.java

@@ -111,6 +111,7 @@ class GillStepInterpolator
   /** Second Gill coefficient. */
   private static final double tPq = 2 + Math.sqrt(2.0);
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -107804074496313322L;
 
 }

src/java/org/apache/commons/math/ode/GraggBulirschStoerIntegrator.java

@@ -87,6 +87,7 @@ package org.apache.commons.math.ode;
 public class GraggBulirschStoerIntegrator
   extends AdaptiveStepsizeIntegrator {
 
+  /** Integrator method name. */
   private static final String methodName = "Gragg-Bulirsch-Stoer";
 
   /** Simple constructor.
@@ -503,6 +504,22 @@ public class GraggBulirschStoerIntegrator
     }
   }
 
+  /** Integrate the differential equations up to the given time.
+   * <p>This method solves an Initial Value Problem (IVP).</p>
+   * <p>Since this method stores some internal state variables made
+   * available in its public interface during integration ({@link
+   * #getCurrentSignedStepsize()}), it is <em>not</em> thread-safe.</p>
+   * @param equations differential equations to integrate
+   * @param t0 initial time
+   * @param y0 initial value of the state vector at t0
+   * @param t target time for the integration
+   * (can be set to a value smaller than <code>t0</code> for backward integration)
+   * @param y placeholder where to put the state vector at each successful
+   *  step (and hence at the end of integration), can be the same object as y0
+   * @throws IntegratorException if the integrator cannot perform integration
+   * @throws DerivativeException this exception is propagated to the caller if
+   * the underlying user function triggers one
+   */
   public void integrate(FirstOrderDifferentialEquations equations,
                         double t0, double[] y0, double t, double[] y)
   throws DerivativeException, IntegratorException {

src/java/org/apache/commons/math/ode/GraggBulirschStoerStepInterpolator.java

@@ -393,6 +393,7 @@ class GraggBulirschStoerStepInterpolator
 
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = 7320613236731409847L;
 
 }

src/java/org/apache/commons/math/ode/HighamHall54Integrator.java

@@ -34,12 +34,15 @@ package org.apache.commons.math.ode;
 public class HighamHall54Integrator
   extends EmbeddedRungeKuttaIntegrator {
 
+  /** Integrator method name. */
   private static final String methodName = "Higham-Hall 5(4)";
 
+  /** Time steps Butcher array. */
   private static final double[] staticC = {
     2.0/9.0, 1.0/3.0, 1.0/2.0, 3.0/5.0, 1.0, 1.0
   };
 
+  /** Internal weights Butcher array. */
   private static final double[][] staticA = {
     {2.0/9.0},
     {1.0/12.0, 1.0/4.0},
@@ -49,10 +52,12 @@ public class HighamHall54Integrator
     {1.0/12.0, 0.0, 27.0/32.0, -4.0/3.0, 125.0/96.0, 5.0/48.0}
   };
 
+  /** Propagation weights Butcher array. */
   private static final double[] staticB = {
     1.0/12.0, 0.0, 27.0/32.0, -4.0/3.0, 125.0/96.0, 5.0/48.0, 0.0
   };
 
+  /** Error weights Butcher array. */
   private static final double[] staticE = {
     -1.0/20.0, 0.0, 81.0/160.0, -6.0/5.0, 25.0/32.0, 1.0/16.0, -1.0/10.0
   };

src/java/org/apache/commons/math/ode/HighamHall54StepInterpolator.java

@@ -88,6 +88,7 @@ class HighamHall54StepInterpolator
 
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -3583240427587318654L;
 
 }

src/java/org/apache/commons/math/ode/IntegratorException.java

@@ -44,6 +44,7 @@ public class IntegratorException
     super(cause);
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -1215318282266670558L;
 
 }

src/java/org/apache/commons/math/ode/MidpointIntegrator.java

@@ -42,16 +42,20 @@ package org.apache.commons.math.ode;
 public class MidpointIntegrator
   extends RungeKuttaIntegrator {
 
+  /** Integrator method name. */
   private static final String methodName = "midpoint";
 
+  /** Time steps Butcher array. */
   private static final double[] c = {
     1.0 / 2.0
   };
 
+  /** Internal weights Butcher array. */
   private static final double[][] a = {
     { 1.0 / 2.0 }
   };
 
+  /** Propagation weights Butcher array. */
   private static final double[] b = {
     0.0, 1.0
   };

src/java/org/apache/commons/math/ode/MidpointStepInterpolator.java

@@ -95,6 +95,7 @@ class MidpointStepInterpolator
 
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -865524111506042509L;
 
 }

src/java/org/apache/commons/math/ode/RungeKuttaIntegrator.java

@@ -51,7 +51,7 @@ public abstract class RungeKuttaIntegrator
    * step. The default step handler does nothing.
    * @param c time steps from Butcher array (without the first zero)
    * @param a internal weights from Butcher array (without the first empty row)
-   * @param b external weights for the high order method from Butcher array
+   * @param b propagation weights for the high order method from Butcher array
    * @param prototype prototype of the step interpolator to use
    * @param step integration step
    */
@@ -138,6 +138,22 @@ public abstract class RungeKuttaIntegrator
     }      
   }
 
+  /** Integrate the differential equations up to the given time.
+   * <p>This method solves an Initial Value Problem (IVP).</p>
+   * <p>Since this method stores some internal state variables made
+   * available in its public interface during integration ({@link
+   * #getCurrentSignedStepsize()}), it is <em>not</em> thread-safe.</p>
+   * @param equations differential equations to integrate
+   * @param t0 initial time
+   * @param y0 initial value of the state vector at t0
+   * @param t target time for the integration
+   * (can be set to a value smaller than <code>t0</code> for backward integration)
+   * @param y placeholder where to put the state vector at each successful
+   *  step (and hence at the end of integration), can be the same object as y0
+   * @throws IntegratorException if the integrator cannot perform integration
+   * @throws DerivativeException this exception is propagated to the caller if
+   * the underlying user function triggers one
+   */
   public void integrate(FirstOrderDifferentialEquations equations,
                         double t0, double[] y0,
                         double t, double[] y)
@@ -254,10 +270,28 @@ public abstract class RungeKuttaIntegrator
 
   }
 
+  /** Get the current value of the step start time t<sub>i</sub>.
+   * <p>This method can be called during integration (typically by
+   * the object implementing the {@link FirstOrderDifferentialEquations
+   * differential equations} problem) if the value of the current step that
+   * is attempted is needed.</p>
+   * <p>The result is undefined if the method is called outside of
+   * calls to {@link #integrate}</p>
+   * @return current value of the step start time t<sub>i</sub>
+   */
   public double getCurrentStepStart() {
     return stepStart;
   }
 
+  /** Get the current signed value of the integration stepsize.
+   * <p>This method can be called during integration (typically by
+   * the object implementing the {@link FirstOrderDifferentialEquations
+   * differential equations} problem) if the signed value of the current stepsize
+   * that is tried is needed.</p>
+   * <p>The result is undefined if the method is called outside of
+   * calls to {@link #integrate}</p>
+   * @return current signed value of the stepsize
+   */
   public double getCurrentSignedStepsize() {
     return stepSize;
   }

src/java/org/apache/commons/math/ode/ThreeEighthesIntegrator.java

@@ -45,18 +45,22 @@ package org.apache.commons.math.ode;
 public class ThreeEighthesIntegrator
   extends RungeKuttaIntegrator {
 
+  /** Integrator method name. */
   private static final String methodName = "3/8";
 
+  /** Time steps Butcher array. */
   private static final double[] c = {
     1.0 / 3.0, 2.0 / 3.0, 1.0
   };
 
+  /** Internal weights Butcher array. */
   private static final double[][] a = {
     {  1.0 / 3.0 },
     { -1.0 / 3.0, 1.0 },
     {  1.0, -1.0, 1.0 }
   };
 
+  /** Propagation weights Butcher array. */
   private static final double[] b = {
     1.0 / 8.0, 3.0 / 8.0, 3.0 / 8.0, 1.0 / 8.0
   };

src/java/org/apache/commons/math/ode/ThreeEighthesStepInterpolator.java

@@ -105,6 +105,7 @@ class ThreeEighthesStepInterpolator
 
   }
 
+  /** Serializable version identifier */
   private static final long serialVersionUID = -3345024435978721931L;
 
 }

src/java/org/apache/commons/math/random/UniformRandomGenerator.java

@@ -24,7 +24,7 @@ package org.apache.commons.math.random;
  * deviation equal to 1. Generated values fall in the range
  * [-&#x0221A;3, +&#x0221A;3].</p>
  * 
- * @version $Revision:$ $Date$
+ * @version $Revision$ $Date$
  */
 
 public class UniformRandomGenerator implements NormalizedRandomGenerator {
@@ -48,6 +48,7 @@ public class UniformRandomGenerator implements NormalizedRandomGenerator {
     /** Underlying generator. */
     private RandomGenerator generator;
 
+    /** Square root of three. */
     private static final double SQRT3 = Math.sqrt(3.0);
 
 }

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

@@ -436,6 +436,8 @@ public class Frequency implements Serializable {
      * natural order.  Copied from Commons Collections ComparableComparator.
      */
     private class NaturalComparator implements Comparator, Serializable {
+
+        /** Serializable version identifier */
         private static final long serialVersionUID = -3852193713161395148L;
 
         /**

src/java/org/apache/commons/math/stat/descriptive/DescriptiveStatistics.java

@@ -66,16 +66,34 @@ public class DescriptiveStatistics implements StatisticalSummary, Serializable {
      */
     protected ResizableDoubleArray eDA = new ResizableDoubleArray();
   
-    // UnivariateStatistic stats implementations - can be reset by setters
+    /** Mean statistic implementation - can be reset by setter. */
     private UnivariateStatistic meanImpl = new Mean();
+    
+    /** Geometric mean statistic implementation - can be reset by setter. */
     private UnivariateStatistic geometricMeanImpl = new GeometricMean();
+    
+    /** Kurtosis statistic implementation - can be reset by setter. */
     private UnivariateStatistic kurtosisImpl = new Kurtosis();
+    
+    /** Maximum statistic implementation - can be reset by setter. */
     private UnivariateStatistic maxImpl = new Max();
+    
+    /** Minimum statistic implementation - can be reset by setter. */
     private UnivariateStatistic minImpl = new Min();
+    
+    /** Percentile statistic implementation - can be reset by setter. */
     private UnivariateStatistic percentileImpl = new Percentile();
+    
+    /** Skewness statistic implementation - can be reset by setter. */
     private UnivariateStatistic skewnessImpl = new Skewness();
+    
+    /** Variance statistic implementation - can be reset by setter. */
     private UnivariateStatistic varianceImpl = new Variance();
+    
+    /** Sum of squares statistic implementation - can be reset by setter. */
     private UnivariateStatistic sumsqImpl = new SumOfSquares();
+    
+    /** Sum statistic implementation - can be reset by setter. */
     private UnivariateStatistic sumImpl = new Sum();
     
     /**

src/java/org/apache/commons/math/stat/descriptive/SummaryStatistics.java

@@ -128,14 +128,28 @@ public class SummaryStatistics implements StatisticalSummary, Serializable {
     /** variance of values that have been added */
     protected Variance variance = new Variance();
     
-    //  Statistics implementations - can be reset by setters 
+    /** Sum statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic sumImpl = sum;
+    
+    /** Sum of squares statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic sumsqImpl = sumsq;
+    
+    /** Minimum statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic minImpl = min;
+    
+    /** Maximum statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic maxImpl = max;
+    
+    /** Sum of log statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic sumLogImpl = sumLog;
+    
+    /** Geometric mean statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic geoMeanImpl = geoMean;
+    
+    /** Mean statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic meanImpl = mean;
+    
+    /** Variance statistic implementation - can be reset by setter. */
     private StorelessUnivariateStatistic varianceImpl = variance;
 
     /**

src/java/org/apache/commons/math/stat/descriptive/SummaryStatisticsImpl.java

@@ -36,6 +36,7 @@ public class SummaryStatisticsImpl extends SummaryStatistics implements Serializ
         super();
     }
 
+    /** Resets all statistics and storage. */
     public void clear() {
         super.clear();
     }

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

@@ -132,6 +132,9 @@ public class TransformerMap implements NumberTransformer, Serializable {
      * Attempts to transform the Object against the map of
      * NumberTransformers. Otherwise it returns Double.NaN.
      * 
+     * @param o the Object to be transformed.
+     * @return the double value of the Object.
+     * @throws MathException if the Object can not be transformed into a Double. 
      * @see org.apache.commons.math.util.NumberTransformer#transform(java.lang.Object)
      */
     public double transform(Object o) throws MathException {