Javadoc fixes.

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

src/main/java/org/apache/commons/math/analysis/FunctionUtils.java

@@ -32,10 +32,12 @@ public class FunctionUtils {
     private FunctionUtils() {}
 
     /**
-     * Compose functions.
+     * Compose functions.  The functions in the argument list are composed
+     * sequentially, in the order given.  For example, compose(f1,f2,f3)
+     * acts like f1(f2(f3(x))).
      *
      * @param f List of functions.
-     * @return the composed function.
+     * @return the composite function.
      */
     public static UnivariateRealFunction compose(final UnivariateRealFunction ... f) {
         return new UnivariateRealFunction() {
@@ -54,7 +56,7 @@ public class FunctionUtils {
      * Add functions.
      *
      * @param f List of functions.
-     * @return a function that computes the addition of the functions.
+     * @return a function that computes the sum of the functions.
      */
     public static UnivariateRealFunction add(final UnivariateRealFunction ... f) {
         return new UnivariateRealFunction() {
@@ -73,7 +75,7 @@ public class FunctionUtils {
      * Multiply functions.
      *
      * @param f List of functions.
-     * @return a function that computes the multiplication of the functions.
+     * @return a function that computes the product of the functions.
      */
     public static UnivariateRealFunction multiply(final UnivariateRealFunction ... f) {
         return new UnivariateRealFunction() {
@@ -89,12 +91,13 @@ public class FunctionUtils {
     }
 
     /**
-     * Combine functions.
+     * Returns the univariate function <br/>
+     * {@code h(x) = combiner(f(x), g(x))}.
      *
      * @param combiner Combiner function.
      * @param f Function.
      * @param g Function.
-     * @return the composed function.
+     * @return the composite function.
      */
     public static UnivariateRealFunction combine(final BivariateRealFunction combiner,
                                                  final UnivariateRealFunction f,
@@ -108,7 +111,9 @@ public class FunctionUtils {
     }
 
     /**
-     * Generate a collector function.
+     * Returns a MultivariateRealFunction h(x[]) defined by <pre> <code>
+     * h(x[]) = combiner(...combiner(combiner(initialValue,f(x[0])),f(x[1]))...),f(x[x.length-1]))
+     * </code></pre>
      *
      * @param combiner Combiner function.
      * @param f Function.
@@ -131,7 +136,9 @@ public class FunctionUtils {
     }
 
     /**
-     * Generate a collector function.
+     * Returns a MultivariateRealFunction h(x[]) defined by <pre> <code>
+     * h(x[]) = combiner(...combiner(combiner(initialValue,x[0]),x[1])...),x[x.length-1])
+     * </code></pre>
      *
      * @param combiner Combiner function.
      * @param initialValue Initial value.
@@ -147,7 +154,7 @@ public class FunctionUtils {
      *
      * @param f Binary function.
      * @param fixed Value to which the first argument of {@code f} is set.
-     * @return a unary function.
+     * @return the unary function h(x) = f(fixed, x)
      */
     public static UnivariateRealFunction fix1stArgument(final BivariateRealFunction f,
                                                         final double fixed) {
@@ -163,7 +170,7 @@ public class FunctionUtils {
      *
      * @param f Binary function.
      * @param fixed Value to which the second argument of {@code f} is set.
-     * @return a unary function.
+     * @return the unary function h(x) = f(x, fixed)
      */
     public static UnivariateRealFunction fix2ndArgument(final BivariateRealFunction f,
                                                         final double fixed) {

src/main/java/org/apache/commons/math/analysis/ParametricUnivariateRealFunction.java

@@ -21,6 +21,7 @@ package org.apache.commons.math.analysis;
  * An interface representing a real function that depends on one independent
  * variable plus some extra parameters.
  *
+ * @since 3.0
  * @version $Id$
  */
 public interface ParametricUnivariateRealFunction {

src/main/java/org/apache/commons/math/analysis/function/Cbrt.java

@@ -21,7 +21,7 @@ import org.apache.commons.math.analysis.UnivariateRealFunction;
 import org.apache.commons.math.util.FastMath;
 
 /**
- * Cubic-root function.
+ * Cube root function.
  *
  * @version $Id$
  * @since 3.0

src/main/java/org/apache/commons/math/analysis/function/HarmonicOscillator.java

@@ -34,7 +34,7 @@ import org.apache.commons.math.util.FastMath;
 public class HarmonicOscillator implements DifferentiableUnivariateRealFunction {
     /** Amplitude. */
     private final double amplitude;
-    /** Angular requency. */
+    /** Angular frequency. */
     private final double omega;
     /** Phase. */
     private final double phase;

src/main/java/org/apache/commons/math/analysis/function/Sinc.java

@@ -21,7 +21,11 @@ import org.apache.commons.math.analysis.UnivariateRealFunction;
 import org.apache.commons.math.util.FastMath;
 
 /**
- * Sinc function.
+ * Sinc function, defined by <pre><code>
+ *
+ * sinc(x) = 1 if abs(x) < 1e-9;
+ *           sin(x) / x; otherwise
+ * </code></pre>
  *
  * @version $Id$
  * @since 3.0

src/main/java/org/apache/commons/math/analysis/interpolation/DividedDifferenceInterpolator.java

@@ -22,7 +22,7 @@ import org.apache.commons.math.analysis.polynomials.PolynomialFunctionNewtonForm
 
 /**
  * Implements the <a href="
- * "http://mathworld.wolfram.com/NewtonsDividedDifferenceInterpolationFormula.html">
+ * http://mathworld.wolfram.com/NewtonsDividedDifferenceInterpolationFormula.html">
  * Divided Difference Algorithm</a> for interpolation of real univariate
  * functions. For reference, see <b>Introduction to Numerical Analysis</b>,
  * ISBN 038795452X, chapter 2.

src/main/java/org/apache/commons/math/analysis/interpolation/LoessInterpolator.java

@@ -40,7 +40,7 @@ import org.apache.commons.math.util.MathUtils;
  * Scatterplots</a>
  * <p/>
  * This class implements both the loess method and serves as an interpolation
- * adapter to it, allowing to build a spline on the obtained loess fit.
+ * adapter to it, allowing one to build a spline on the obtained loess fit.
  *
  * @version $Id$
  * @since 2.0

src/main/java/org/apache/commons/math/analysis/interpolation/NevilleInterpolator.java

@@ -26,7 +26,7 @@ import org.apache.commons.math.analysis.polynomials.PolynomialFunctionLagrangeFo
  * reference, see <b>Introduction to Numerical Analysis</b>, ISBN 038795452X,
  * chapter 2.
  * <p>
- * The actual code of Neville's evalution is in PolynomialFunctionLagrangeForm,
+ * The actual code of Neville's algorithm is in PolynomialFunctionLagrangeForm,
  * this class provides an easy-to-use interface to it.</p>
  *
  * @version $Id$

src/main/java/org/apache/commons/math/analysis/interpolation/UnivariateRealPeriodicInterpolator.java

@@ -21,7 +21,7 @@ import org.apache.commons.math.util.MathUtils;
 import org.apache.commons.math.exception.NumberIsTooSmallException;
 
 /**
- * Adapter for class implementing the {@link UnivariateRealInterpolator}
+ * Adapter for classes implementing the {@link UnivariateRealInterpolator}
  * interface.
  * The data to be interpolated is assumed to be periodic. Thus values that are
  * outside of the range can be passed to the interpolation function: They will

src/main/java/org/apache/commons/math/analysis/polynomials/PolynomialFunction.java

@@ -366,6 +366,8 @@ public class PolynomialFunction implements DifferentiableUnivariateRealFunction,
 
     /**
      * Dedicated parametric polynomial class.
+     *
+     * @since 3.0
      */
     public static class Parametric implements ParametricUnivariateRealFunction {
         /** {@inheritDoc} */

src/main/java/org/apache/commons/math/optimization/fitting/CurveFitter.java

@@ -139,6 +139,7 @@ public class CurveFitter {
      * if the number of allowed evaluations is exceeded.
      * @throws org.apache.commons.math.exception.DimensionMismatchException
      * if the start point dimension is wrong.
+     * @since 3.0
      */
     public double[] fit(int maxEval, final ParametricUnivariateRealFunction f,
                         final double[] initialGuess) {

src/main/java/org/apache/commons/math/optimization/fitting/GaussianFitter.java

@@ -79,6 +79,7 @@ public class GaussianFitter extends CurveFitter {
      * </ul>
      * @return the parameters of the Gaussian function that best fits the
      * observed points (in the same order as above).
+     * @since 3.0
      */
     public double[] fit(double[] initialGuess) {
         final ParametricUnivariateRealFunction f = new ParametricUnivariateRealFunction() {