From 84f08fce9f8f5a4e18f1552ec9db132cd9526bf0 Mon Sep 17 00:00:00 2001
From: XenoAmess <xenoamess@gmail.com>
Date: Wed, 3 Jun 2020 01:47:04 +0800
Subject: [PATCH] refine javadoc

---
 .../analysis/interpolation/DividedDifferenceInterpolator.java | 4 ++--
 src/main/java/org/apache/commons/math4/dfp/Dfp.java           | 2 +-
 .../math4/fitting/leastsquares/AbstractEvaluation.java        | 2 +-
 src/main/java/org/apache/commons/math4/linear/RealVector.java | 2 +-
 .../apache/commons/math4/ml/neuralnet/oned/NeuronString.java  | 2 +-
 .../nonlinear/scalar/MultivariateFunctionMappingAdapter.java  | 3 ++-
 .../scalar/gradient/NonLinearConjugateGradientOptimizer.java  | 4 ++--
 .../math4/optim/nonlinear/scalar/noderiv/PowellOptimizer.java | 4 ++--
 .../org/apache/commons/math4/stat/correlation/Covariance.java | 4 +---
 .../apache/commons/math4/stat/descriptive/rank/Median.java    | 2 +-
 src/test/java/org/apache/commons/math4/PerfTestUtils.java     | 4 ++--
 .../interpolation/TricubicInterpolatingFunctionTest.java      | 2 +-
 .../math4/distribution/RealDistributionAbstractTest.java      | 3 ---
 .../math4/random/RandomUtilsDataGeneratorAbstractTest.java    | 2 +-
 .../math4/random/RandomUtilsDataGeneratorJDKRandomTest.java   | 2 +-
 .../org/apache/commons/math4/util/IntegerSequenceTest.java    | 2 +-
 .../java/org/apache/commons/math4/util/MathArraysTest.java    | 2 +-
 17 files changed, 21 insertions(+), 25 deletions(-)

diff --git a/src/main/java/org/apache/commons/math4/analysis/interpolation/DividedDifferenceInterpolator.java b/src/main/java/org/apache/commons/math4/analysis/interpolation/DividedDifferenceInterpolator.java
index e6ea96683..7a41012aa 100644
--- a/src/main/java/org/apache/commons/math4/analysis/interpolation/DividedDifferenceInterpolator.java
+++ b/src/main/java/org/apache/commons/math4/analysis/interpolation/DividedDifferenceInterpolator.java
@@ -57,14 +57,14 @@ public class DividedDifferenceInterpolator
         throws DimensionMismatchException,
                NumberIsTooSmallException,
                NonMonotonicSequenceException {
-        /**
+        /*
          * a[] and c[] are defined in the general formula of Newton form:
          * p(x) = a[0] + a[1](x-c[0]) + a[2](x-c[0])(x-c[1]) + ... +
          *        a[n](x-c[0])(x-c[1])...(x-c[n-1])
          */
         PolynomialFunctionLagrangeForm.verifyInterpolationArray(x, y, true);
 
-        /**
+        /*
          * When used for interpolation, the Newton form formula becomes
          * p(x) = f[x0] + f[x0,x1](x-x0) + f[x0,x1,x2](x-x0)(x-x1) + ... +
          *        f[x0,x1,...,x[n-1]](x-x0)(x-x1)...(x-x[n-2])
diff --git a/src/main/java/org/apache/commons/math4/dfp/Dfp.java b/src/main/java/org/apache/commons/math4/dfp/Dfp.java
index 08d29d0a1..de1d4a010 100644
--- a/src/main/java/org/apache/commons/math4/dfp/Dfp.java
+++ b/src/main/java/org/apache/commons/math4/dfp/Dfp.java
@@ -1122,7 +1122,7 @@ public class Dfp implements RealFieldElement<Dfp> {
                         result = result.add(a);
                     }
 
-                    /** If exactly equal to 1/2 and odd then increment */
+                    /* If exactly equal to 1/2 and odd then increment */
                     if (a.equals(half) && result.exp > 0 && (result.mant[mant.length-result.exp]&1) != 0) {
                         a = newInstance(getOne());
                         a.sign = sign;
diff --git a/src/main/java/org/apache/commons/math4/fitting/leastsquares/AbstractEvaluation.java b/src/main/java/org/apache/commons/math4/fitting/leastsquares/AbstractEvaluation.java
index bc4f23b05..43984d8b0 100644
--- a/src/main/java/org/apache/commons/math4/fitting/leastsquares/AbstractEvaluation.java
+++ b/src/main/java/org/apache/commons/math4/fitting/leastsquares/AbstractEvaluation.java
@@ -41,7 +41,7 @@ public abstract class AbstractEvaluation implements Evaluation {
      * Constructor.
      *
      * @param observationSize the number of observations.
-     * Needed for {@link #getRMS()} and {@link #getReducedChiSquare()}.
+     * Needed for {@link #getRMS()} and {@link #getReducedChiSquare(int)}.
      */
     AbstractEvaluation(final int observationSize) {
         this.observationSize = observationSize;
diff --git a/src/main/java/org/apache/commons/math4/linear/RealVector.java b/src/main/java/org/apache/commons/math4/linear/RealVector.java
index f4fa84396..7344f4243 100644
--- a/src/main/java/org/apache/commons/math4/linear/RealVector.java
+++ b/src/main/java/org/apache/commons/math4/linear/RealVector.java
@@ -1209,7 +1209,7 @@ public abstract class RealVector {
      * @return an unmodifiable view of {@code v}.
      */
     public static RealVector unmodifiableRealVector(final RealVector v) {
-        /**
+        /*
          * This anonymous class is an implementation of {@link RealVector}
          * with read-only access.
          * It wraps any {@link RealVector}, and exposes all methods which
diff --git a/src/main/java/org/apache/commons/math4/ml/neuralnet/oned/NeuronString.java b/src/main/java/org/apache/commons/math4/ml/neuralnet/oned/NeuronString.java
index 864b62a46..eeecf78b5 100644
--- a/src/main/java/org/apache/commons/math4/ml/neuralnet/oned/NeuronString.java
+++ b/src/main/java/org/apache/commons/math4/ml/neuralnet/oned/NeuronString.java
@@ -229,7 +229,7 @@ public class NeuronString implements Serializable {
         /**
          * Custom serialization.
          *
-         * @return the {@link Neuron} for which this instance is the proxy.
+         * @return the {@link NeuronString} for which this instance is the proxy.
          */
         private Object readResolve() {
             return new NeuronString(wrap,
diff --git a/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/MultivariateFunctionMappingAdapter.java b/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/MultivariateFunctionMappingAdapter.java
index a430d486a..c2aa2ee72 100644
--- a/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/MultivariateFunctionMappingAdapter.java
+++ b/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/MultivariateFunctionMappingAdapter.java
@@ -22,6 +22,7 @@ import org.apache.commons.math4.analysis.function.Logit;
 import org.apache.commons.math4.analysis.function.Sigmoid;
 import org.apache.commons.math4.exception.DimensionMismatchException;
 import org.apache.commons.math4.exception.NumberIsTooSmallException;
+import org.apache.commons.math4.optim.OptimizationData;
 import org.apache.commons.math4.util.FastMath;
 import org.apache.commons.math4.util.MathUtils;
 
@@ -52,7 +53,7 @@ import org.apache.commons.math4.util.MathUtils;
  * user is responsible for converting his bounded point to unbounded by calling
  * {@link #boundedToUnbounded(double[])} before providing them to the optimizer.
  * For the same reason, the point returned by the {@link
- * org.apache.commons.math4.optim.BaseMultivariateOptimizer#optimize(OptimizationData[])}
+ * org.apache.commons.math4.optim.BaseMultivariateOptimizer#optimize(OptimizationData...)}
  * method is unbounded. So to convert this point to bounded, users must call
  * {@link #unboundedToBounded(double[])} by themselves!</p>
  * <p>
diff --git a/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/gradient/NonLinearConjugateGradientOptimizer.java b/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/gradient/NonLinearConjugateGradientOptimizer.java
index 2bd188ee3..8714d1555 100644
--- a/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/gradient/NonLinearConjugateGradientOptimizer.java
+++ b/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/gradient/NonLinearConjugateGradientOptimizer.java
@@ -108,7 +108,7 @@ public class NonLinearConjugateGradientOptimizer
      * find an interval that brackets the optimum in order to perform the
      * line search.
      *
-     * @see LineSearch#LineSearch(MultivariateOptimizer,double,double,double)
+     * @see LineSearch#LineSearch(org.apache.commons.math4.optim.nonlinear.scalar.MultivariateOptimizer,double,double,double)
      * @since 3.3
      */
     public NonLinearConjugateGradientOptimizer(final Formula updateFormula,
@@ -136,7 +136,7 @@ public class NonLinearConjugateGradientOptimizer
      * find an interval that brackets the optimum in order to perform the
      * line search.
      *
-     * @see LineSearch#LineSearch(MultivariateOptimizer,double,double,double)
+     * @see LineSearch#LineSearch(org.apache.commons.math4.optim.nonlinear.scalar.MultivariateOptimizer, double, double, double)
      * @since 3.3
      */
     public NonLinearConjugateGradientOptimizer(final Formula updateFormula,
diff --git a/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/noderiv/PowellOptimizer.java b/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/noderiv/PowellOptimizer.java
index e4f7ef6cc..76ae42855 100644
--- a/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/noderiv/PowellOptimizer.java
+++ b/src/main/java/org/apache/commons/math4/optim/nonlinear/scalar/noderiv/PowellOptimizer.java
@@ -43,7 +43,7 @@ import org.apache.commons.math4.util.FastMath;
  * Line search is performed by the {@link LineSearch} class.
  * <br>
  * Constraints are not supported: the call to
- * {@link #optimize(OptimizationData[]) optimize} will throw
+ * {@link #optimize(org.apache.commons.math4.optim.OptimizationData...)} will throw
  * {@link MathUnsupportedOperationException} if bounds are passed to it.
  * In order to impose simple constraints, the objective function must be
  * wrapped in an adapter like
@@ -288,7 +288,7 @@ public class PowellOptimizer
 
     /**
      * @throws MathUnsupportedOperationException if bounds were passed to the
-     * {@link #optimize(OptimizationData[]) optimize} method.
+     * {@link #optimize(org.apache.commons.math4.optim.OptimizationData[]) optimize} method.
      */
     private void checkParameters() {
         if (getLowerBound() != null ||
diff --git a/src/main/java/org/apache/commons/math4/stat/correlation/Covariance.java b/src/main/java/org/apache/commons/math4/stat/correlation/Covariance.java
index a42d43548..e2699acdc 100644
--- a/src/main/java/org/apache/commons/math4/stat/correlation/Covariance.java
+++ b/src/main/java/org/apache/commons/math4/stat/correlation/Covariance.java
@@ -48,9 +48,7 @@ public class Covariance {
     /** covariance matrix */
     private final RealMatrix covarianceMatrix;
 
-    /**
-     * Create an empty covariance matrix.
-     */
+    /* Create an empty covariance matrix. */
     /** Number of observations (length of covariate vectors) */
     private final int n;
 
diff --git a/src/main/java/org/apache/commons/math4/stat/descriptive/rank/Median.java b/src/main/java/org/apache/commons/math4/stat/descriptive/rank/Median.java
index d2a62cc7c..61c33544a 100644
--- a/src/main/java/org/apache/commons/math4/stat/descriptive/rank/Median.java
+++ b/src/main/java/org/apache/commons/math4/stat/descriptive/rank/Median.java
@@ -61,7 +61,7 @@ public class Median extends Percentile implements Serializable {
     }
 
     /**
-     * Constructs a Median with the specific {@link EstimationType}, {@link NaNStrategy} and {@link PivotingStrategy}.
+     * Constructs a Median with the specific {@link EstimationType}, {@link NaNStrategy} and {@link KthSelector}.
      *
      * @param estimationType one of the percentile {@link EstimationType  estimation types}
      * @param nanStrategy one of {@link NaNStrategy} to handle with NaNs
diff --git a/src/test/java/org/apache/commons/math4/PerfTestUtils.java b/src/test/java/org/apache/commons/math4/PerfTestUtils.java
index f1170a495..f51bf32de 100644
--- a/src/test/java/org/apache/commons/math4/PerfTestUtils.java
+++ b/src/test/java/org/apache/commons/math4/PerfTestUtils.java
@@ -258,8 +258,8 @@ public class PerfTestUtils {
 
     /**
      * Timing and report (to standard output).
-     * This method calls {@link #timeAndReport(String,int,int,boolean,RunTest[])
-     * timeAndReport(title, 1000, 10000, false, methods)}.
+     * This method calls {@link #timeAndReport(String,int,int,int,boolean,RunTest[])
+     * timeAndReport(title, 45, 1000, 10000, false, methods)}.
      *
      * @param title Title of the test (for the report).
      * @param methods Codes being timed.
diff --git a/src/test/java/org/apache/commons/math4/analysis/interpolation/TricubicInterpolatingFunctionTest.java b/src/test/java/org/apache/commons/math4/analysis/interpolation/TricubicInterpolatingFunctionTest.java
index f2ccc0be2..008de54a2 100644
--- a/src/test/java/org/apache/commons/math4/analysis/interpolation/TricubicInterpolatingFunctionTest.java
+++ b/src/test/java/org/apache/commons/math4/analysis/interpolation/TricubicInterpolatingFunctionTest.java
@@ -287,7 +287,7 @@ public final class TricubicInterpolatingFunctionTest {
      * @param d2fdxdy Second partial cross-derivative w.r.t x and y of the function to test.
      * @param d2fdxdz Second partial cross-derivative w.r.t x and z of the function to test.
      * @param d2fdydz Second partial cross-derivative w.r.t y and z of the function to test.
-     * @param d3fdxdy Third partial cross-derivative w.r.t x, y and z of the function to test.
+     * @param d3fdxdydz Third partial cross-derivative w.r.t x, y and z of the function to test.
      * @param meanRelativeTolerance Allowed average error (mean error on all interpolated values).
      * @param maxRelativeTolerance Allowed error on each interpolated value.
      * @param onDataMaxAbsoluteTolerance Allowed error on a data point.
diff --git a/src/test/java/org/apache/commons/math4/distribution/RealDistributionAbstractTest.java b/src/test/java/org/apache/commons/math4/distribution/RealDistributionAbstractTest.java
index 7039efab4..233d66bd3 100644
--- a/src/test/java/org/apache/commons/math4/distribution/RealDistributionAbstractTest.java
+++ b/src/test/java/org/apache/commons/math4/distribution/RealDistributionAbstractTest.java
@@ -67,9 +67,6 @@ import org.junit.Test;
  * where possible, and the source of the reference data and/or validation
  * should be documented in the test cases.  A framework for validating
  * distribution data against R is included in the /src/test/R source tree.
- * <p>
- * See {@link NormalDistributionTest} and {@link ChiSquaredDistributionTest}
- * for examples.
  *
  */
 public abstract class RealDistributionAbstractTest {
diff --git a/src/test/java/org/apache/commons/math4/random/RandomUtilsDataGeneratorAbstractTest.java b/src/test/java/org/apache/commons/math4/random/RandomUtilsDataGeneratorAbstractTest.java
index e27165aed..2b4ced9af 100644
--- a/src/test/java/org/apache/commons/math4/random/RandomUtilsDataGeneratorAbstractTest.java
+++ b/src/test/java/org/apache/commons/math4/random/RandomUtilsDataGeneratorAbstractTest.java
@@ -27,7 +27,7 @@ import org.junit.Test;
 import org.junit.runner.RunWith;
 
 /**
- * Test cases for the {@link RandomUtils#DataGenerator} class.
+ * Test cases for the {@link RandomUtils.DataGenerator} class.
  */
 @RunWith(RetryRunner.class)
 public abstract class RandomUtilsDataGeneratorAbstractTest {
diff --git a/src/test/java/org/apache/commons/math4/random/RandomUtilsDataGeneratorJDKRandomTest.java b/src/test/java/org/apache/commons/math4/random/RandomUtilsDataGeneratorJDKRandomTest.java
index a5118262b..83c8fb325 100644
--- a/src/test/java/org/apache/commons/math4/random/RandomUtilsDataGeneratorJDKRandomTest.java
+++ b/src/test/java/org/apache/commons/math4/random/RandomUtilsDataGeneratorJDKRandomTest.java
@@ -19,7 +19,7 @@ package org.apache.commons.math4.random;
 import java.util.Random;
 
 /**
- * Test cases for the {@link RandomUtils#DataGenerator} class, using
+ * Test cases for the {@link RandomUtils.DataGenerator} class, using
  * {@link Random} as the underlying source of randomness.
  */
 public class RandomUtilsDataGeneratorJDKRandomTest
diff --git a/src/test/java/org/apache/commons/math4/util/IntegerSequenceTest.java b/src/test/java/org/apache/commons/math4/util/IntegerSequenceTest.java
index 857188b20..a15f36f8a 100644
--- a/src/test/java/org/apache/commons/math4/util/IntegerSequenceTest.java
+++ b/src/test/java/org/apache/commons/math4/util/IntegerSequenceTest.java
@@ -24,7 +24,7 @@ import org.junit.Assert;
 import org.junit.Test;
 
 /**
- * Tests for {@link IntegerSequence} and {@link IntegerSequence#Incrementor}.
+ * Tests for {@link IntegerSequence} and {@link IntegerSequence.Incrementor}.
  */
 public class IntegerSequenceTest {
     @Test
diff --git a/src/test/java/org/apache/commons/math4/util/MathArraysTest.java b/src/test/java/org/apache/commons/math4/util/MathArraysTest.java
index 87ab07e84..746a9fc6a 100644
--- a/src/test/java/org/apache/commons/math4/util/MathArraysTest.java
+++ b/src/test/java/org/apache/commons/math4/util/MathArraysTest.java
@@ -501,8 +501,8 @@ public class MathArraysTest {
         Assert.assertEquals(125, x3[0], FastMath.ulp(1d));
     }
 
-    @Test
     /** Example in javadoc */
+    @Test
     public void testSortInPlaceExample() {
         final double[] x = {3, 1, 2};
         final double[] y = {1, 2, 3};