Added missing @since tags.

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

src/main/java/org/apache/commons/math3/linear/MatrixUtils.java

@@ -420,6 +420,7 @@ public class MatrixUtils {
      * @param eps Relative tolerance.
      * @throws NonSquareMatrixException if the matrix is not square.
      * @throws NonSymmetricMatrixException if the matrix is not symmetric.
+     * @since 3.1
      */
     public static void checkSymmetric(RealMatrix matrix,
                                       double eps) {
@@ -432,6 +433,7 @@ public class MatrixUtils {
      * @param matrix Matrix to check.
      * @param eps Relative tolerance.
      * @return {@code true} if {@code matrix} is symmetric.
+     * @since 3.1
      */
     public static boolean isSymmetric(RealMatrix matrix,
                                       double eps) {

src/main/java/org/apache/commons/math3/linear/RealVector.java

@@ -201,6 +201,7 @@ public abstract class RealVector {
      * @param end the index of the last entry of the subvector (inclusive)
      * @throws OutOfRangeException if {@code start} of {@code end} are not valid
      * @throws NumberIsTooSmallException if {@code end < start}
+     * @since 3.1
      */
     protected void checkIndices(final int start, final int end)
         throws NumberIsTooSmallException, OutOfRangeException {
@@ -889,7 +890,6 @@ public abstract class RealVector {
         return this;
     }
 
-
     /**
      * Visits (but does not alter) all entries of this vector in default order
      * (increasing index).
@@ -898,6 +898,7 @@ public abstract class RealVector {
      * vector
      * @return the value returned by {@link RealVectorPreservingVisitor#end()}
      * at the end of the walk
+     * @since 3.1
      */
     public double walkInDefaultOrder(final RealVectorPreservingVisitor visitor) {
         final int dim = getDimension();
@@ -919,6 +920,7 @@ public abstract class RealVector {
      * at the end of the walk
      * @throws NumberIsTooSmallException if {@code end < start}.
      * @throws OutOfRangeException if the indices are not valid.
+     * @since 3.1
      */
     public double walkInDefaultOrder(final RealVectorPreservingVisitor visitor,
                                      final int start, final int end)
@@ -941,6 +943,7 @@ public abstract class RealVector {
      * vector
      * @return the value returned by {@link RealVectorPreservingVisitor#end()}
      * at the end of the walk
+     * @since 3.1
      */
     public double walkInOptimizedOrder(final RealVectorPreservingVisitor visitor) {
         return walkInDefaultOrder(visitor);
@@ -959,6 +962,7 @@ public abstract class RealVector {
      * at the end of the walk
      * @throws NumberIsTooSmallException if {@code end < start}.
      * @throws OutOfRangeException if the indices are not valid.
+     * @since 3.1
      */
     public double walkInOptimizedOrder(final RealVectorPreservingVisitor visitor,
                                        final int start, final int end)
@@ -974,6 +978,7 @@ public abstract class RealVector {
      * of this vector
      * @return the value returned by {@link RealVectorChangingVisitor#end()}
      * at the end of the walk
+     * @since 3.1
      */
     public double walkInDefaultOrder(final RealVectorChangingVisitor visitor) {
         final int dim = getDimension();
@@ -995,6 +1000,7 @@ public abstract class RealVector {
      * at the end of the walk
      * @throws NumberIsTooSmallException if {@code end < start}.
      * @throws OutOfRangeException if the indices are not valid.
+     * @since 3.1
      */
     public double walkInDefaultOrder(final RealVectorChangingVisitor visitor,
                               final int start, final int end)
@@ -1017,6 +1023,7 @@ public abstract class RealVector {
      * vector
      * @return the value returned by {@link RealVectorChangingVisitor#end()}
      * at the end of the walk
+     * @since 3.1
      */
     public double walkInOptimizedOrder(final RealVectorChangingVisitor visitor) {
         return walkInDefaultOrder(visitor);
@@ -1035,6 +1042,7 @@ public abstract class RealVector {
      * at the end of the walk
      * @throws NumberIsTooSmallException if {@code end < start}.
      * @throws OutOfRangeException if the indices are not valid.
+     * @since 3.1
      */
     public double walkInOptimizedOrder(final RealVectorChangingVisitor visitor,
                                        final int start, final int end)

src/main/java/org/apache/commons/math3/linear/RectangularCholeskyDecomposition.java

@@ -63,6 +63,7 @@ public class RectangularCholeskyDecomposition {
      * @param matrix Symmetric positive semidefinite matrix.
      * @exception NonPositiveDefiniteMatrixException if the matrix is not
      * positive semidefinite.
+     * @since 3.1
      */
     public RectangularCholeskyDecomposition(RealMatrix matrix)
         throws NonPositiveDefiniteMatrixException {

src/main/java/org/apache/commons/math3/optimization/direct/BaseAbstractMultivariateOptimizer.java

@@ -136,6 +136,7 @@ public abstract class BaseAbstractMultivariateOptimizer<FUNC extends Multivariat
      * </ul>
      * @return the point/value pair giving the optimal value of the objective
      * function.
+     * @since 3.1
      */
     public PointValuePair optimize(int maxEval,
                                    FUNC f,
@@ -185,6 +186,7 @@ public abstract class BaseAbstractMultivariateOptimizer<FUNC extends Multivariat
      * function.
      * @throws TooManyEvaluationsException if the maximal number of
      * evaluations is exceeded.
+     * @since 3.1
      */
     protected PointValuePair optimizeInternal(int maxEval,
                                               FUNC f,
@@ -246,12 +248,14 @@ public abstract class BaseAbstractMultivariateOptimizer<FUNC extends Multivariat
     }
     /**
      * @return the lower bounds.
+     * @since 3.1
      */
     public double[] getLowerBound() {
         return lowerBound == null ? null : lowerBound.clone();
     }
     /**
      * @return the upper bounds.
+     * @since 3.1
      */
     public double[] getUpperBound() {
         return upperBound == null ? null : upperBound.clone();

src/main/java/org/apache/commons/math3/optimization/direct/CMAESOptimizer.java

@@ -399,6 +399,7 @@ public class CMAESOptimizer
      * values are more likely to find a local optimum close to the initial
      * guess).
      * Too small values might however lead to early termination.
+     * @since 3.1
      */
     public static class Sigma implements OptimizationData {
         /** Sigma values. */
@@ -437,6 +438,7 @@ public class CMAESOptimizer
      * Increasing the population size improves global search properties
      * at the expense of speed (which in general decreases at most
      * linearly with increasing population size).
+     * @since 3.1
      */
     public static class PopulationSize implements OptimizationData {
         /** Population size. */

src/main/java/org/apache/commons/math3/optimization/direct/PowellOptimizer.java

@@ -150,6 +150,7 @@ public class PowellOptimizer
      * @param lineAbs Absolute threshold for the internal line search optimizer.
      * @throws NotStrictlyPositiveException if {@code abs <= 0}.
      * @throws NumberIsTooSmallException if {@code rel < 2 * Math.ulp(1d)}.
+     * @since 3.1
      */
     public PowellOptimizer(double rel,
                            double abs,

src/main/java/org/apache/commons/math3/optimization/fitting/PolynomialFitter.java

@@ -57,6 +57,7 @@ public class PolynomialFitter extends CurveFitter<PolynomialFunction.Parametric>
      * Simple constructor.
      *
      * @param optimizer Optimizer to use for the fitting.
+     * @since 3.1
      */
     public PolynomialFitter(DifferentiableMultivariateVectorOptimizer optimizer) {
         super(optimizer);
@@ -88,6 +89,7 @@ public class PolynomialFitter extends CurveFitter<PolynomialFunction.Parametric>
      * the number of evaluations exceeds {@code maxEval}.
      * @throws org.apache.commons.math3.exception.ConvergenceException
      * if the algorithm failed to converge.
+     * @since 3.1
      */
     public double[] fit(int maxEval, double[] guess) {
         return fit(maxEval, new PolynomialFunction.Parametric(), guess);
@@ -102,6 +104,7 @@ public class PolynomialFitter extends CurveFitter<PolynomialFunction.Parametric>
      * @return the coefficients of the polynomial that best fits the observed points.
      * @throws org.apache.commons.math3.exception.ConvergenceException
      * if the algorithm failed to converge.
+     * @since 3.1
      */
     public double[] fit(double[] guess) {
         return fit(new PolynomialFunction.Parametric(), guess);

src/main/java/org/apache/commons/math3/optimization/general/AbstractLeastSquaresOptimizer.java

@@ -253,6 +253,7 @@ public abstract class AbstractLeastSquaresOptimizer
      * Gets the square-root of the weight matrix.
      *
      * @return the square-root of the weight matrix.
+     * @since 3.1
      */
     public RealMatrix getWeightSquareRoot() {
         return weightMatrixSqrt.copy();
@@ -320,6 +321,7 @@ public abstract class AbstractLeastSquaresOptimizer
      * @return the covariance matrix.
      * @throws org.apache.commons.math3.linear.SingularMatrixException
      * if the covariance matrix cannot be computed (singular problem).
+     * @since 3.1
      */
     public double[][] computeCovariances(double[] params,
                                          double threshold) {
@@ -392,6 +394,7 @@ public abstract class AbstractLeastSquaresOptimizer
      * @return an estimate of the standard deviation of the optimized parameters
      * @throws org.apache.commons.math3.linear.SingularMatrixException
      * if the covariance matrix cannot be computed.
+     * @since 3.1
      */
     public double[] computeSigma(double[] params,
                                  double covarianceSingularityThreshold) {
@@ -531,6 +534,7 @@ public abstract class AbstractLeastSquaresOptimizer
      * @return the residuals.
      * @throws DimensionMismatchException if {@code params} has a wrong
      * length.
+     * @since 3.1
      */
     protected double[] computeResiduals(double[] objectiveValue) {
         final double[] target = getTarget();

src/main/java/org/apache/commons/math3/random/RandomDataGenerator.java

@@ -106,7 +106,7 @@ import org.apache.commons.math3.util.FastMath;
  * </li>
  * </ul>
  * </p>
- *
+ * @since 3.1
  * @version $Id$
  */
 public class RandomDataGenerator implements RandomData, Serializable {

src/main/java/org/apache/commons/math3/special/Gamma.java

@@ -61,6 +61,7 @@ public class Gamma {
     /**
      * The value of the {@code g} constant in the Lanczos approximation, see
      * {@link #lanczos(double)}.
+     * @since 3.1
      */
     public static final double LANCZOS_G = 607.0 / 128.0;
 
@@ -506,6 +507,7 @@ public class Gamma {
      * equations (1) through (5), and Paul Godfrey's
      * <a href="http://my.fit.edu/~gabdo/gamma.txt">Note on the computation
      * of the convergent Lanczos complex Gamma approximation</a>
+     * @since 3.1
      */
     public static double lanczos(final double x) {
         double sum = 0.0;
@@ -525,6 +527,7 @@ public class Gamma {
      * @return The value of {@code 1.0 / Gamma(1.0 + x) - 1.0}.
      * @throws NumberIsTooSmallException if {@code x < -0.5}
      * @throws NumberIsTooLargeException if {@code x > 1.5}
+     * @since 3.1
      */
     public static double invGamma1pm1(final double x) {
 
@@ -617,6 +620,7 @@ public class Gamma {
      * @return The value of {@code log(Gamma(1 + x))}.
      * @throws NumberIsTooSmallException if {@code x < -0.5}.
      * @throws NumberIsTooLargeException if {@code x > 1.5}.
+     * @since 3.1
      */
     public static double logGamma1p(final double x)
         throws NumberIsTooSmallException, NumberIsTooLargeException {
@@ -639,6 +643,7 @@ public class Gamma {
      *
      * @param x Argument.
      * @return the value of {@code Gamma(x)}.
+     * @since 3.1
      */
     public static double gamma(final double x) {
 

src/main/java/org/apache/commons/math3/stat/Frequency.java

@@ -123,6 +123,7 @@ public class Frequency implements Serializable {
      * @param v the value to add.
      * @param increment the amount by which the value should be incremented
      * @throws IllegalArgumentException if <code>v</code> is not comparable with previous entries
+     * @since 3.1
      */
     public void incrementValue(Comparable<?> v, long increment){
         Comparable<?> obj = v;
@@ -206,6 +207,7 @@ public class Frequency implements Serializable {
      * map entries returned by the Iterator will in this case be Longs.</p>
      *
      * @return entry set Iterator
+     * @since 3.1
      */
     public Iterator<Map.Entry<Comparable<?>, Long>> entrySetIterator() {
         return freqTable.entrySet().iterator();
@@ -497,6 +499,7 @@ public class Frequency implements Serializable {
      * by the counts represented by other.
      *
      * @param other the other {@link Frequency} object to be merged
+     * @since 3.1
      */
     public void merge(Frequency other) {
         for (Iterator<Map.Entry<Comparable<?>, Long>> iter = other.entrySetIterator(); iter.hasNext();) {
@@ -511,6 +514,7 @@ public class Frequency implements Serializable {
      * by the counts represented by each of the others.
      *
      * @param others the other {@link Frequency} objects to be merged
+     * @since 3.1
      */
     public void merge(Collection<Frequency> others) {
         for (Iterator<Frequency> iter = others.iterator(); iter.hasNext();) {

src/main/java/org/apache/commons/math3/stat/correlation/SpearmansCorrelation.java

@@ -60,6 +60,7 @@ public class SpearmansCorrelation {
      * Create a SpearmansCorrelation with the given ranking algorithm.
      *
      * @param rankingAlgorithm ranking algorithm
+     * @since 3.1
      */
     public SpearmansCorrelation(final RankingAlgorithm rankingAlgorithm) {
         data = null;

src/main/java/org/apache/commons/math3/stat/inference/TestUtils.java

@@ -367,6 +367,7 @@ public class TestUtils  {
 
      /**
      * @see org.apache.commons.math3.stat.inference.GTest#g(double[], long[])
+     * @since 3.1
      */
     public static double g(final double[] expected, final long[] observed)
         throws NotPositiveException, NotStrictlyPositiveException,
@@ -376,6 +377,7 @@ public class TestUtils  {
 
     /**
      * @see org.apache.commons.math3.stat.inference.GTest#gTest( double[],  long[] )
+     * @since 3.1
      */
     public static double gTest(final double[] expected, final long[] observed)
         throws NotPositiveException, NotStrictlyPositiveException,
@@ -385,6 +387,7 @@ public class TestUtils  {
 
     /**
      * @see org.apache.commons.math3.stat.inference.GTest#gTestIntrinsic(double[], long[] )
+     * @since 3.1
      */
     public static double gTestIntrinsic(final double[] expected, final long[] observed)
         throws NotPositiveException, NotStrictlyPositiveException,
@@ -394,6 +397,7 @@ public class TestUtils  {
 
      /**
      * @see org.apache.commons.math3.stat.inference.GTest#gTest( double[],long[],double)
+     * @since 3.1
      */
     public static boolean gTest(final double[] expected, final long[] observed,
                                 final double alpha)
@@ -404,6 +408,7 @@ public class TestUtils  {
 
     /**
      * @see org.apache.commons.math3.stat.inference.GTest#gDataSetsComparison(long[], long[])
+     * @since 3.1
      */
     public static double gDataSetsComparison(final long[] observed1,
                                                   final long[] observed2)
@@ -413,6 +418,7 @@ public class TestUtils  {
 
     /**
      * @see org.apache.commons.math3.stat.inference.GTest#rootLogLikelihoodRatio(long, long, long, long)
+     * @since 3.1
      */
     public static double rootLogLikelihoodRatio(final long k11, final long k12, final long k21, final long k22)
         throws DimensionMismatchException, NotPositiveException, ZeroException {
@@ -422,7 +428,7 @@ public class TestUtils  {
 
     /**
      * @see org.apache.commons.math3.stat.inference.GTest#gTestDataSetsComparison(long[], long[])
-     *
+     * @since 3.1
      */
     public static double gTestDataSetsComparison(final long[] observed1,
                                                         final long[] observed2)
@@ -433,6 +439,7 @@ public class TestUtils  {
 
     /**
      * @see org.apache.commons.math3.stat.inference.GTest#gTestDataSetsComparison(long[],long[],double)
+     * @since 3.1
      */
     public static boolean gTestDataSetsComparison(final long[] observed1,
                                                   final long[] observed2,

src/main/java/org/apache/commons/math3/stat/ranking/NaNStrategy.java

@@ -49,6 +49,8 @@ public enum NaNStrategy {
     /** NaNs are left in place */
     FIXED,
 
-    /** NaNs result in an exception */
+    /** NaNs result in an exception
+     * @since 3.1
+     */
     FAILED
 }

src/main/java/org/apache/commons/math3/util/ArithmeticUtils.java

@@ -967,6 +967,7 @@ public final class ArithmeticUtils {
      * @throws NumberIsTooLargeException if {@code k > n}.
      * @throws MathArithmeticException if some overflow happens, typically for n exceeding 25 and
      * k between 20 and n-2 (S(n,n-1) is handled specifically and does not overflow)
+     * @since 3.1
      */
     public static long stirlingS2(final int n, final int k)
         throws NotPositiveException, NumberIsTooLargeException, MathArithmeticException {

src/main/java/org/apache/commons/math3/util/FastMath.java

@@ -1606,6 +1606,7 @@ public class FastMath {
      * @param d Number to raise.
      * @param e Exponent.
      * @return d<sup>e</sup>
+     * @since 3.1
      */
     public static double pow(double d, int e) {
 

src/main/java/org/apache/commons/math3/util/IterationManager.java

@@ -54,6 +54,7 @@ public class IterationManager {
      * @param callBack the function to be called when the maximum number of
      * iterations has been reached
      * @throws org.apache.commons.math3.exception.NullArgumentException if {@code callBack} is {@code null}
+     * @since 3.1
      */
     public IterationManager(final int maxIterations,
                             final Incrementor.MaxCountExceededCallback callBack) {

src/main/java/org/apache/commons/math3/util/MathArrays.java

@@ -49,6 +49,7 @@ public class MathArrays {
 
     /**
      * Real-valued function that operate on an array or a part of it.
+     * @since 3.1
      */
     public interface Function {
         /**
@@ -77,6 +78,7 @@ public class MathArrays {
      * @param b Second term of the addition.
      * @return a new array {@code r} where {@code r[i] = a[i] + b[i]}.
      * @throws DimensionMismatchException if the array lengths differ.
+     * @since 3.1
      */
     public static double[] ebeAdd(double[] a,
                                   double[] b) {
@@ -98,6 +100,7 @@ public class MathArrays {
      * @param b Element to be subtracted.
      * @return a new array {@code r} where {@code r[i] = a[i] - b[i]}.
      * @throws DimensionMismatchException if the array lengths differ.
+     * @since 3.1
      */
     public static double[] ebeSubtract(double[] a,
                                        double[] b) {
@@ -119,6 +122,7 @@ public class MathArrays {
      * @param b Second factor of the multiplication.
      * @return a new array {@code r} where {@code r[i] = a[i] * b[i]}.
      * @throws DimensionMismatchException if the array lengths differ.
+     * @since 3.1
      */
     public static double[] ebeMultiply(double[] a,
                                        double[] b) {
@@ -140,6 +144,7 @@ public class MathArrays {
      * @param b Denominator of the division.
      * @return a new array {@code r} where {@code r[i] = a[i] / b[i]}.
      * @throws DimensionMismatchException if the array lengths differ.
+     * @since 3.1
      */
     public static double[] ebeDivide(double[] a,
                                      double[] b) {
@@ -416,6 +421,7 @@ public class MathArrays {
      * @param in array to be tested
      * @throws NullArgumentException if input array is null
      * @throws DimensionMismatchException if input array is not rectangular
+     * @since 3.1
      */
     public static void checkRectangular(final long[][] in)
         throws NullArgumentException, DimensionMismatchException {
@@ -435,6 +441,7 @@ public class MathArrays {
      * @param in Array to be tested
      * @throws NotStrictlyPositiveException if any entries of the array are not
      * strictly positive.
+     * @since 3.1
      */
     public static void checkPositive(final double[] in)
         throws NotStrictlyPositiveException {
@@ -450,6 +457,7 @@ public class MathArrays {
      *
      * @param in Array to be tested
      * @throws NotPositiveException if any array entries are less than 0.
+     * @since 3.1
      */
     public static void checkNonNegative(final long[] in)
         throws NotPositiveException {
@@ -465,6 +473,7 @@ public class MathArrays {
      *
      * @param in Array to be tested
      * @throws NotPositiveException if any array entries are less than 0.
+     * @since 3.1
      */
     public static void checkNonNegative(final long[][] in)
         throws NotPositiveException {

src/main/java/org/apache/commons/math3/util/Pair.java

@@ -78,6 +78,7 @@ public class Pair<K, V> {
      * Get the first element of the pair.
      *
      * @return the first element of the pair.
+     * @since 3.1
      */
     public K getFirst() {
         return key;
@@ -87,6 +88,7 @@ public class Pair<K, V> {
      * Get the second element of the pair.
      *
      * @return the second element of the pair.
+     * @since 3.1
      */
     public V getSecond() {
         return value;

src/main/java/org/apache/commons/math3/util/Precision.java

@@ -282,6 +282,7 @@ public class Precision {
      * @param eps Amount of allowed relative error.
      * @return {@code true} if the values are two adjacent floating point
      * numbers or they are within range of each other.
+     * @since 3.1
      */
     public static boolean equalsWithRelativeTolerance(double x, double y, double eps) {
         if (equals(x, y, 1)) {

src/main/java/org/apache/commons/math3/util/ResizableDoubleArray.java

@@ -145,6 +145,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
 
     /**
      * Specification of expansion algorithm.
+     * @since 3.1
      */
     public static enum ExpansionMode {
         /** Multiplicative expansion mode. */
@@ -259,6 +260,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
      * @param expansionFactor The array will be expanded based on this
      * parameter.
      * @throws MathIllegalArgumentException if parameters are not valid.
+     * @since 3.1
      */
     public ResizableDoubleArray(int initialCapacity,
                                 double expansionFactor)
@@ -317,6 +319,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
      * parameter.
      * @param contractionCriterion Contraction criterion.
      * @throws MathIllegalArgumentException if the parameters are not valid.
+     * @since 3.1
      */
     public ResizableDoubleArray(int initialCapacity,
                                 double expansionFactor,
@@ -541,6 +544,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
      * @throws NumberIsTooSmallException if {@code contraction < expansion}.
      * @throws NumberIsTooSmallException if {@code contraction <= 1}.
      * @throws NumberIsTooSmallException if {@code expansion <= 1 }.
+     * @since 3.1
      */
     protected void checkContractExpand(double contraction,
                                        double expansion)
@@ -735,6 +739,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
      * <code>contractionFactor.</code>
      *
      * @return the contraction criterion used to reclaim memory.
+     * @since 3.1
      */
     public double getContractionCriterion() {
         return contractionCriterion;
@@ -829,6 +834,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
      * elements actually stored}.
      *
      * @return the length of the internal array.
+     * @since 3.1
      */
     public int getCapacity() {
         return internalArray.length;
@@ -922,6 +928,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
      *
      * @param f Function to be applied on this array.
      * @return the result.
+     * @since 3.1
      */
     public double compute(MathArrays.Function f) {
         return f.evaluate(internalArray, startIndex, numElements);