Javadoc cleanup of transform package, removed unnecessary paragraph tags.

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

src/main/java/org/apache/commons/math3/transform/DctNormalization.java

@@ -27,7 +27,6 @@ package org.apache.commons.math3.transform;
  */
 public enum DctNormalization {
     /**
-     * <p>
      * Should be passed to the constructor of {@link FastCosineTransformer}
      * to use the <em>standard</em> normalization convention.  The standard
      * DCT-I normalization convention is defined as follows
@@ -43,12 +42,10 @@ public enum DctNormalization {
      * y<sub>n</sub> cos[&pi; nk / (N - 1)],</li>
      * </ul>
      * where N is the size of the data sample.
-     * </p>
      */
     STANDARD_DCT_I,
 
     /**
-     * <p>
      * Should be passed to the constructor of {@link FastCosineTransformer}
      * to use the <em>orthogonal</em> normalization convention. The orthogonal
      * DCT-I normalization convention is defined as follows

src/main/java/org/apache/commons/math3/transform/DftNormalization.java

@@ -27,7 +27,6 @@ package org.apache.commons.math3.transform;
  */
 public enum DftNormalization {
     /**
-     * <p>
      * Should be passed to the constructor of {@link FastFourierTransformer}
      * to use the <em>standard</em> normalization convention. This normalization
      * convention is defined as follows
@@ -38,12 +37,10 @@ public enum DftNormalization {
      * &sum;<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> exp(2&pi;i n k / N),</li>
      * </ul>
      * where N is the size of the data sample.
-     * </p>
      */
     STANDARD,
 
     /**
-     * <p>
      * Should be passed to the constructor of {@link FastFourierTransformer}
      * to use the <em>unitary</em> normalization convention. This normalization
      * convention is defined as follows
@@ -55,7 +52,6 @@ public enum DftNormalization {
      * &sum;<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> exp(2&pi;i n k / N),</li>
      * </ul>
      * which makes the transform unitary. N is the size of the data sample.
-     * </p>
      */
     UNITARY;
 }

src/main/java/org/apache/commons/math3/transform/DstNormalization.java

@@ -27,7 +27,6 @@ package org.apache.commons.math3.transform;
  */
 public enum DstNormalization {
     /**
-     * <p>
      * Should be passed to the constructor of {@link FastSineTransformer} to
      * use the <em>standard</em> normalization convention. The standard DST-I
      * normalization convention is defined as follows
@@ -38,12 +37,10 @@ public enum DstNormalization {
      * &sum;<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> sin(&pi; nk / N),</li>
      * </ul>
      * where N is the size of the data sample, and x<sub>0</sub> = 0.
-     * </p>
      */
     STANDARD_DST_I,
 
     /**
-     * <p>
      * Should be passed to the constructor of {@link FastSineTransformer} to
      * use the <em>orthogonal</em> normalization convention. The orthogonal
      * DCT-I normalization convention is defined as follows
@@ -55,7 +52,6 @@ public enum DstNormalization {
      * </ul>
      * which makes the transform orthogonal. N is the size of the data sample,
      * and x<sub>0</sub> = 0.
-     * </p>
      */
     ORTHOGONAL_DST_I
 }

src/main/java/org/apache/commons/math3/transform/FastCosineTransformer.java

@@ -27,16 +27,13 @@ import org.apache.commons.math3.util.ArithmeticUtils;
 import org.apache.commons.math3.util.FastMath;
 
 /**
- * <p>
  * Implements the Fast Cosine Transform for transformation of one-dimensional
  * real data sets. For reference, see James S. Walker, <em>Fast Fourier
  * Transforms</em>, chapter 3 (ISBN 0849371635).
- * </p>
  * <p>
  * There are several variants of the discrete cosine transform. The present
  * implementation corresponds to DCT-I, with various normalization conventions,
  * which are specified by the parameter {@link DctNormalization}.
- * </p>
  * <p>
  * DCT-I is equivalent to DFT of an <em>even extension</em> of the data series.
  * More precisely, if x<sub>0</sub>, &hellip;, x<sub>N-1</sub> is the data set
@@ -48,7 +45,6 @@ import org.apache.commons.math3.util.FastMath;
  * <li>x<sub>k</sub><sup>&#35;</sup> = x<sub>2N-2-k</sub>
  * if N &le; k &lt; 2N - 2.</li>
  * </ul>
- * </p>
  * <p>
  * Then, the standard DCT-I y<sub>0</sub>, &hellip;, y<sub>N-1</sub> of the real
  * data set x<sub>0</sub>, &hellip;, x<sub>N-1</sub> is equal to <em>half</em>
@@ -58,13 +54,11 @@ import org.apache.commons.math3.util.FastMath;
  * y<sub>n</sub> = (1 / 2) &sum;<sub>k=0</sub><sup>2N-3</sup>
  * x<sub>k</sub><sup>&#35;</sup> exp[-2&pi;i nk / (2N - 2)]
  * &nbsp;&nbsp;&nbsp;&nbsp;k = 0, &hellip;, N-1.
- * </p>
  * <p>
  * The present implementation of the discrete cosine transform as a fast cosine
  * transform requires the length of the data set to be a power of two plus one
  * (N&nbsp;=&nbsp;2<sup>n</sup>&nbsp;+&nbsp;1). Besides, it implicitly assumes
  * that the sampled function is even.
- * </p>
  *
  * @version $Id$
  * @since 1.2

src/main/java/org/apache/commons/math3/transform/FastFourierTransformer.java

@@ -31,16 +31,13 @@ import org.apache.commons.math3.util.FastMath;
 import org.apache.commons.math3.util.MathArrays;
 
 /**
- * <p>
  * Implements the Fast Fourier Transform for transformation of one-dimensional
  * real or complex data sets. For reference, see <em>Applied Numerical Linear
  * Algebra</em>, ISBN 0898713897, chapter 6.
- * </p>
  * <p>
  * There are several variants of the discrete Fourier transform, with various
  * normalization conventions, which are specified by the parameter
  * {@link DftNormalization}.
- * </p>
  * <p>
  * The current implementation of the discrete Fourier transform as a fast
  * Fourier transform requires the length of the data set to be a power of 2.
@@ -49,7 +46,6 @@ import org.apache.commons.math3.util.MathArrays;
  * reference, see S. Winograd,
  * <i>On computing the discrete Fourier transform</i>, Mathematics of
  * Computation, 32 (1978), 175 - 199.
- * </p>
  *
  * @see DftNormalization
  * @version $Id$
@@ -162,8 +158,7 @@ public class FastFourierTransformer implements Serializable {
      *
      * @param dataRI the unscaled transformed data
      * @param normalization the normalization to be applied
-     * @param type the type of transform (forward, inverse) which resulted in the
+     * @param type the type of transform (forward, inverse) which resulted in the specified data
-     * specified data
      */
     private static void normalizeTransformedData(final double[][] dataRI,
         final DftNormalization normalization, final TransformType type) {
@@ -205,21 +200,17 @@ public class FastFourierTransformer implements Serializable {
      * Computes the standard transform of the specified complex data. The
      * computation is done in place. The input data is laid out as follows
      * <ul>
-     * <li>{@code dataRI[0][i]} is the real part of the {@code i}-th data point,
+     *   <li>{@code dataRI[0][i]} is the real part of the {@code i}-th data point,</li>
-     * </li>
+     *   <li>{@code dataRI[1][i]} is the imaginary part of the {@code i}-th data point.</li>
-     * <li>{@code dataRI[1][i]} is the imaginary part of the {@code i}-th data
-     * point.</li>
      * </ul>
      *
-     * @param dataRI the two dimensional array of real and imaginary parts of
+     * @param dataRI the two dimensional array of real and imaginary parts of the data
-     * the data
+     * @param normalization the normalization to be applied to the transformed data
-     * @param normalization the normalization to be applied to the transformed
-     * data
      * @param type the type of transform (forward, inverse) to be performed
      * @throws DimensionMismatchException if the number of rows of the specified
-     * array is not two, or the array is not rectangular
+     *   array is not two, or the array is not rectangular
      * @throws MathIllegalArgumentException if the number of data points is not
-     * a power of two
+     *   a power of two
      */
     public static void transformInPlace(final double[][] dataRI,
         final DftNormalization normalization, final TransformType type) {
@@ -374,8 +365,7 @@ public class FastFourierTransformer implements Serializable {
      * @param f the real data array to be transformed
      * @param type the type of transform (forward, inverse) to be performed
      * @return the complex transformed array
-     * @throws MathIllegalArgumentException if the length of the data array is
+     * @throws MathIllegalArgumentException if the length of the data array is not a power of two
-     * not a power of two
      */
     public Complex[] transform(final double[] f, final TransformType type) {
         final double[][] dataRI = new double[][] {
@@ -398,29 +388,27 @@ public class FastFourierTransformer implements Serializable {
      * @param type the type of transform (forward, inverse) to be performed
      * @return the complex transformed array
      * @throws org.apache.commons.math3.exception.NumberIsTooLargeException
-     * if the lower bound is greater than, or equal to the upper bound
+     *   if the lower bound is greater than, or equal to the upper bound
      * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
-     * if the number of sample points {@code n} is negative
+     *   if the number of sample points {@code n} is negative
      * @throws MathIllegalArgumentException if the number of sample points
-     * {@code n} is not a power of two
+     *   {@code n} is not a power of two
      */
     public Complex[] transform(final UnivariateFunction f,
-            final double min, final double max, final int n,
+                               final double min, final double max, final int n,
-            final TransformType type) {
+                               final TransformType type) {
 
         final double[] data = FunctionUtils.sample(f, min, max, n);
         return transform(data, type);
     }
 
     /**
-     * Returns the (forward, inverse) transform of the specified complex data
+     * Returns the (forward, inverse) transform of the specified complex data set.
-     * set.
      *
      * @param f the complex data array to be transformed
      * @param type the type of transform (forward, inverse) to be performed
      * @return the complex transformed array
-     * @throws MathIllegalArgumentException if the length of the data array is
+     * @throws MathIllegalArgumentException if the length of the data array is not a power of two
-     * not a power of two
      */
     public Complex[] transform(final Complex[] f, final TransformType type) {
         final double[][] dataRI = TransformUtils.createRealImaginaryArray(f);
@@ -439,11 +427,9 @@ public class FastFourierTransformer implements Serializable {
      * &times; n<sub>d</sub>, where n<sub>k</sub> is the number of elements in
      * dimension k, and d is the total number of dimensions.
      *
-     * @param mdca Multi-Dimensional Complex Array id est
+     * @param mdca Multi-Dimensional Complex Array, i.e. {@code Complex[][][][]}
-     * {@code Complex[][][][]}
      * @param type the type of transform (forward, inverse) to be performed
-     * @return transform of {@code mdca} as a Multi-Dimensional Complex Array
+     * @return transform of {@code mdca} as a Multi-Dimensional Complex Array, i.e. {@code Complex[][][][]}
-     * id est {@code Complex[][][][]}
      * @throws IllegalArgumentException if any dimension is not a power of two
      * @deprecated see MATH-736
      */

src/main/java/org/apache/commons/math3/transform/FastHadamardTransformer.java

@@ -27,11 +27,13 @@ import org.apache.commons.math3.util.ArithmeticUtils;
 /**
  * Implements the <a href="http://www.archive.chipcenter.com/dsp/DSP000517F1.html">Fast Hadamard Transform</a> (FHT).
  * Transformation of an input vector x to the output vector y.
- * <p>In addition to transformation of real vectors, the Hadamard transform can
+ * <p>
+ * In addition to transformation of real vectors, the Hadamard transform can
  * transform integer vectors into integer vectors. However, this integer transform
  * cannot be inverted directly. Due to a scaling factor it may lead to rational results.
  * As an example, the inverse transform of integer vector (0, 1, 0, 1) is rational
- * vector (1/2, -1/2, 0, 0).</p>
+ * vector (1/2, -1/2, 0, 0).
+ *
  * @version $Id$
  * @since 2.0
  */
@@ -57,11 +59,10 @@ public class FastHadamardTransformer implements RealTransformer, Serializable {
      * {@inheritDoc}
      *
      * @throws org.apache.commons.math3.exception.NonMonotonicSequenceException
-     * if the lower bound is greater than, or equal to the upper bound
+     *   if the lower bound is greater than, or equal to the upper bound
      * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
-     * if the number of sample points is negative
+     *   if the number of sample points is negative
-     * @throws MathIllegalArgumentException if the number of sample points is
+     * @throws MathIllegalArgumentException if the number of sample points is not a power of two
-     * not a power of two
      */
     public double[] transform(final UnivariateFunction f,
         final double min, final double max, final int n,
@@ -77,8 +78,7 @@ public class FastHadamardTransformer implements RealTransformer, Serializable {
      *
      * @param f the integer data array to be transformed (signal)
      * @return the integer transformed array (spectrum)
-     * @throws MathIllegalArgumentException if the length of the data array is
+     * @throws MathIllegalArgumentException if the length of the data array is not a power of two
-     * not a power of two
      */
     public int[] transform(final int[] f) {
         return fht(f);
@@ -224,8 +224,7 @@ public class FastHadamardTransformer implements RealTransformer, Serializable {
      *
      * @param x the real data array to be transformed
      * @return the real transformed array, {@code y}
-     * @throws MathIllegalArgumentException if the length of the data array is
+     * @throws MathIllegalArgumentException if the length of the data array is not a power of two
-     * not a power of two
      */
     protected double[] fht(double[] x) throws MathIllegalArgumentException {
 
@@ -276,8 +275,7 @@ public class FastHadamardTransformer implements RealTransformer, Serializable {
      *
      * @param x the integer data array to be transformed
      * @return the integer transformed array, {@code y}
-     * @throws MathIllegalArgumentException if the length of the data array is
+     * @throws MathIllegalArgumentException if the length of the data array is not a power of two
-     * not a power of two
      */
     protected int[] fht(int[] x) throws MathIllegalArgumentException {
 

src/main/java/org/apache/commons/math3/transform/FastSineTransformer.java

@@ -27,18 +27,15 @@ import org.apache.commons.math3.util.ArithmeticUtils;
 import org.apache.commons.math3.util.FastMath;
 
 /**
- * <p>
  * Implements the Fast Sine Transform for transformation of one-dimensional real
  * data sets. For reference, see James S. Walker, <em>Fast Fourier
  * Transforms</em>, chapter 3 (ISBN 0849371635).
- * </p>
  * <p>
  * There are several variants of the discrete sine transform. The present
  * implementation corresponds to DST-I, with various normalization conventions,
  * which are specified by the parameter {@link DstNormalization}.
  * <strong>It should be noted that regardless to the convention, the first
  * element of the dataset to be transformed must be zero.</strong>
- * </p>
  * <p>
  * DST-I is equivalent to DFT of an <em>odd extension</em> of the data series.
  * More precisely, if x<sub>0</sub>, &hellip;, x<sub>N-1</sub> is the data set
@@ -51,7 +48,6 @@ import org.apache.commons.math3.util.FastMath;
  * <li>x<sub>k</sub><sup>&#35;</sup> = -x<sub>2N-k</sub> if N + 1 &le; k &lt;
  * 2N.</li>
  * </ul>
- * </p>
  * <p>
  * Then, the standard DST-I y<sub>0</sub>, &hellip;, y<sub>N-1</sub> of the real
  * data set x<sub>0</sub>, &hellip;, x<sub>N-1</sub> is equal to <em>half</em>
@@ -61,7 +57,6 @@ import org.apache.commons.math3.util.FastMath;
  * y<sub>n</sub> = (i / 2) &sum;<sub>k=0</sub><sup>2N-1</sup>
  * x<sub>k</sub><sup>&#35;</sup> exp[-2&pi;i nk / (2N)]
  * &nbsp;&nbsp;&nbsp;&nbsp;k = 0, &hellip;, N-1.
- * </p>
  * <p>
  * The present implementation of the discrete sine transform as a fast sine
  * transform requires the length of the data to be a power of two. Besides,
@@ -69,7 +64,6 @@ import org.apache.commons.math3.util.FastMath;
  * first element of the data set must be 0, which is enforced in
  * {@link #transform(UnivariateFunction, double, double, int, TransformType)},
  * after sampling.
- * </p>
  *
  * @version $Id$
  * @since 1.2
@@ -83,11 +77,9 @@ public class FastSineTransformer implements RealTransformer, Serializable {
     private final DstNormalization normalization;
 
     /**
-     * Creates a new instance of this class, with various normalization
+     * Creates a new instance of this class, with various normalization conventions.
-     * conventions.
      *
-     * @param normalization the type of normalization to be applied to the
+     * @param normalization the type of normalization to be applied to the transformed data
-     * transformed data
      */
     public FastSineTransformer(final DstNormalization normalization) {
         this.normalization = normalization;
@@ -99,7 +91,7 @@ public class FastSineTransformer implements RealTransformer, Serializable {
      * The first element of the specified data set is required to be {@code 0}.
      *
      * @throws MathIllegalArgumentException if the length of the data array is
-     * not a power of two, or the first element of the data array is not zero
+     *   not a power of two, or the first element of the data array is not zero
      */
     public double[] transform(final double[] f, final TransformType type) {
         if (normalization == DstNormalization.ORTHOGONAL_DST_I) {
@@ -119,11 +111,10 @@ public class FastSineTransformer implements RealTransformer, Serializable {
      * This implementation enforces {@code f(x) = 0.0} at {@code x = 0.0}.
      *
      * @throws org.apache.commons.math3.exception.NonMonotonicSequenceException
-     * if the lower bound is greater than, or equal to the upper bound
+     *   if the lower bound is greater than, or equal to the upper bound
      * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
-     * if the number of sample points is negative
+     *   if the number of sample points is negative
-     * @throws MathIllegalArgumentException if the number of sample points is
+     * @throws MathIllegalArgumentException if the number of sample points is not a power of two
-     * not a power of two
      */
     public double[] transform(final UnivariateFunction f,
         final double min, final double max, final int n,
@@ -141,7 +132,7 @@ public class FastSineTransformer implements RealTransformer, Serializable {
      * @param f the real data array to be transformed
      * @return the real transformed array
      * @throws MathIllegalArgumentException if the length of the data array is
-     * not a power of two, or the first element of the data array is not zero
+     *   not a power of two, or the first element of the data array is not zero
      */
     protected double[] fst(double[] f) throws MathIllegalArgumentException {
 

src/main/java/org/apache/commons/math3/transform/RealTransformer.java

@@ -22,14 +22,14 @@ import org.apache.commons.math3.exception.NonMonotonicSequenceException;
 import org.apache.commons.math3.exception.NotStrictlyPositiveException;
 
 /**
- * <p>Interface for one-dimensional data sets transformations producing real
+ * Interface for one-dimensional data sets transformations producing real results.
- * results.</p>
+ * <p>
- * <p>Such transforms include {@link FastSineTransformer sine transform},
+ * Such transforms include {@link FastSineTransformer sine transform},
  * {@link FastCosineTransformer cosine transform} or {@link
  * FastHadamardTransformer Hadamard transform}. {@link FastFourierTransformer
  * Fourier transform} is of a different kind and does not implement this
  * interface since it produces {@link org.apache.commons.math3.complex.Complex}
- * results instead of real ones.</p>
+ * results instead of real ones.
  *
  * @version $Id$
  * @since 2.0
@@ -43,8 +43,8 @@ public interface RealTransformer  {
      * @param type the type of transform (forward, inverse) to be performed
      * @return the real transformed array (spectrum)
      * @throws MathIllegalArgumentException if the array cannot be transformed
-     * with the given type (this may be for example due to array size, which is
+     *   with the given type (this may be for example due to array size, which is
-     * constrained in some transforms)
+     *   constrained in some transforms)
      */
     double[] transform(double[] f, TransformType type) throws MathIllegalArgumentException;
 
@@ -58,12 +58,11 @@ public interface RealTransformer  {
      * @param n the number of sample points
      * @param type the type of transform (forward, inverse) to be performed
      * @return the real transformed array
-     * @throws NonMonotonicSequenceException if the lower bound is greater than,
+     * @throws NonMonotonicSequenceException if the lower bound is greater than, or equal to the upper bound
-     * or equal to the upper bound
      * @throws NotStrictlyPositiveException if the number of sample points is negative
      * @throws MathIllegalArgumentException if the sample cannot be transformed
-     * with the given type (this may be for example due to sample size, which is
+     *   with the given type (this may be for example due to sample size, which is
-     * constrained in some transforms)
+     *   constrained in some transforms)
      */
     double[] transform(UnivariateFunction f, double min, double max, int n,
                        TransformType type)

src/main/java/org/apache/commons/math3/transform/TransformUtils.java

@@ -93,7 +93,7 @@ public class TransformUtils {
      *
      * @param dataC the array of {@link Complex} data to be transformed
      * @return a two dimensional array filled with the real and imaginary parts
-     * of the specified complex input
+     *   of the specified complex input
      */
     public static double[][] createRealImaginaryArray(final Complex[] dataC) {
         final double[][] dataRI = new double[2][dataC.length];
@@ -117,10 +117,9 @@ public class TransformUtils {
      * </ul>
      *
      * @param dataRI the array of real and imaginary parts to be transformed
-     * @return an array of {@link Complex} with specified real and imaginary
+     * @return an array of {@link Complex} with specified real and imaginary parts.
-     * parts.
      * @throws DimensionMismatchException if the number of rows of the specified
-     * array is not two, or the array is not rectangular
+     *   array is not two, or the array is not rectangular
      */
     public static Complex[] createComplexArray(final double[][] dataRI)
         throws DimensionMismatchException{