fixed javadoc errors in order to support some maven versions (e.g. 3.…

…3.3)
apache · krichter722 · Oct 4, 2016 · Oct 4, 2016 · a6390033617b4a92b4d73af35f94dcdebef36bb4
commit a6390033617b4a92b4d73af35f94dcdebef36bb4
diff --git a/.travis.yml b/.travis.yml
@@ -35,5 +35,6 @@ before_install:
   - export PATH=$M2_HOME/bin:$PATH
 
 
-script: ./runtests.sh
-
+script:
+- ./runtests.sh
+- mvn javadoc:javadoc
diff --git a/math/src/main/java/org/apache/mahout/collections/Arithmetic.java b/math/src/main/java/org/apache/mahout/collections/Arithmetic.java
@@ -249,11 +249,17 @@ public final class Arithmetic extends Constants {
   }
 
   /**
-   * Efficiently returns the binomial coefficient, often also referred to as "n over k" or "n choose k". The binomial
-   * coefficient is defined as <tt>(n * n-1 * ... * n-k+1 ) / ( 1 * 2 * ... * k )</tt>. <ul> <li>k<0<tt>: <tt>0</tt>.
-   * <li>k==0<tt>: <tt>1</tt>. <li>k==1<tt>: <tt>n</tt>. <li>else: <tt>(n * n-1 * ... * n-k+1 ) / ( 1 * 2 * ... * k
-   * )</tt>. </ul>
+   * Efficiently returns the binomial coefficient, often also referred to as 
+   * "n over k" or "n choose k". The binomial coefficient is defined as 
+   * <tt>(n * n-1 * ... * n-k+1 ) / ( 1 * 2 * ... * k )</tt>.
+   * <ul> <li><tt>k&lt;0</tt>: <tt>0</tt>.</li>
+   * <li><tt>k==0</tt>: <tt>1</tt>.</li>
+   * <li><tt>k==1</tt>: <tt>n</tt>.</li>
+   * <li>else: <tt>(n * n-1 * ... * n-k+1 ) / ( 1 * 2 * ... * k)</tt>.</li>
+   * </ul>
    *
+     * @param n
+     * @param k
    * @return the binomial coefficient.
    */
   public static double binomial(double n, long k) {
@@ -279,7 +285,7 @@ public static double binomial(double n, long k) {
 
   /**
    * Efficiently returns the binomial coefficient, often also referred to as "n over k" or "n choose k". The binomial
-   * coefficient is defined as <ul> <li>k<0<tt>: <tt>0</tt>. <li>k==0 || k==n<tt>: <tt>1</tt>. <li>k==1 || k==n-1<tt>:
+   * coefficient is defined as <ul> <li><tt>k&lt;0</tt>: <tt>0</tt>. <li><tt>k==0 || k==n</tt>: <tt>1</tt>. <li><tt>k==1 || k==n-1</tt>:
    * <tt>n</tt>. <li>else: <tt>(n * n-1 * ... * n-k+1 ) / ( 1 * 2 * ... * k )</tt>. </ul>
    *
    * @return the binomial coefficient.
@@ -325,8 +331,9 @@ public static double binomial(long n, long k) {
   }
 
   /**
-   * Returns the smallest <code>long &gt;= value</code>. <dt>Examples: {@code 1.0 -> 1, 1.2 -> 2, 1.9 -> 2}. This
-   * method is safer than using (long) Math.ceil(value), because of possible rounding error.
+   * Returns the smallest <code>long &gt;= value</code>.
+   * <dl><dt>Examples: {@code 1.0 -> 1, 1.2 -> 2, 1.9 -> 2}. This
+   * method is safer than using (long) Math.ceil(value), because of possible rounding error.</dt></dl>
    */
   public static long ceil(double value) {
     return Math.round(Math.ceil(value));
@@ -337,15 +344,15 @@ public static long ceil(double value) {
    * <pre>
    *        N-1
    *         - '
-   *  y  =   >   coef[i] T (x/2)
+   *  y  =   &gt;   coef[i] T (x/2)
    *         -            i
    *        i=0
    * </pre>
    * Coefficients are stored in reverse order, i.e. the zero order term is last in the array.  Note N is the number of
-   * coefficients, not the order. <p> If coefficients are for the interval a to b, x must have been transformed to x ->
+   * coefficients, not the order. <p> If coefficients are for the interval a to b, x must have been transformed to x -&lt;
    * 2(2x - b - a)/(b-a) before entering the routine.  This maps x from (a, b) to (-1, 1), over which the Chebyshev
    * polynomials are defined. <p> If the coefficients are for the inverted interval, in which (a, b) is mapped to (1/b,
-   * 1/a), the transformation required is x -> 2(2ab/x - b - a)/(b-a).  If b is infinity, this becomes x -> 4a/x - 1.
+   * 1/a), the transformation required is {@code x -> 2(2ab/x - b - a)/(b-a)}.  If b is infinity, this becomes {@code x -> 4a/x - 1}.
    * <p> SPEED: <p> Taking advantage of the recurrence properties of the Chebyshev polynomials, the routine requires one
    * more addition per loop than evaluating a nested polynomial of the same degree.
    *
@@ -396,7 +403,7 @@ private static double factorial(int k) {
 
   /**
    * Returns the largest <code>long &lt;= value</code>.
-   * <dt>Examples: {@code 1.0 -> 1, 1.2 -> 1, 1.9 -> 1 <dt> 2.0 -> 2,} 2.2 -> 2, 2.9 -> 2 </code><dt>
+   * <dl><dt>Examples: {@code 1.0 -> 1, 1.2 -> 1, 1.9 -> 1 <dt> 2.0 -> 2, 2.2 -> 2, 2.9 -> 2}</dt></dl>
    * This method is safer than using (long) Math.floor(value), because of possible rounding error.
    */
   public static long floor(double value) {
@@ -421,8 +428,8 @@ public static double log2(double value) {
   }
 
   /**
-   * Returns <tt>log(k!)</tt>. Tries to avoid overflows. For <tt>k<30</tt> simply looks up a table in O(1). For
-   * <tt>k>=30</tt> uses stirlings approximation.
+   * Returns <tt>log(k!)</tt>. Tries to avoid overflows. For <tt>k&lt;30</tt> simply looks up a table in O(1). For
+   * <tt>k&gt;=30</tt> uses stirlings approximation.
    *
    * @param k must hold <tt>k &gt;= 0</tt>.
    */
@@ -445,7 +452,7 @@ public static double logFactorial(int k) {
   /**
    * Instantly returns the factorial <tt>k!</tt>.
    *
-   * @param k must hold <tt>k &gt;= 0 && k &lt; 21</tt>.
+   * @param k must hold {@code k >= 0 && k < 21}
    */
   public static long longFactorial(int k) {
     if (k < 0) {
@@ -460,8 +467,8 @@ public static long longFactorial(int k) {
 
   /**
    * Returns the StirlingCorrection. <p> Correction term of the Stirling approximation for <tt>log(k!)</tt> (series in
-   * 1/k, or table values for small k) with int parameter k. <p> <tt> log k! = (k + 1/2)log(k + 1) - (k + 1) +
-   * (1/2)log(2Pi) + STIRLING_CORRECTION(k + 1) <p> log k! = (k + 1/2)log(k)     -  k      + (1/2)log(2Pi) +
+   * 1/k, or table values for small k) with int parameter k. </p> <tt> log k! = (k + 1/2)log(k + 1) - (k + 1) +
+   * (1/2)log(2Pi) + STIRLING_CORRECTION(k + 1) log k! = (k + 1/2)log(k)     -  k      + (1/2)log(2Pi) +
    * STIRLING_CORRECTION(k) </tt>
    */
   public static double stirlingCorrection(int k) {

diff --git a/math/src/main/java/org/apache/mahout/math/AbstractMatrix.java b/math/src/main/java/org/apache/mahout/math/AbstractMatrix.java
@@ -719,7 +719,7 @@ public void set(double value) {
     /**
      * Used internally by assign() to update multiple indices and values at once.
      * Only really useful for sparse vectors (especially SequentialAccessSparseVector).
-     * <p/>
+     * <p>
      * If someone ever adds a new type of sparse vectors, this method must merge (index, value) pairs into the vector.
      *
      * @param updates a mapping of indices to values to merge in the vector.

diff --git a/math/src/main/java/org/apache/mahout/math/AbstractVector.java b/math/src/main/java/org/apache/mahout/math/AbstractVector.java
@@ -56,15 +56,17 @@ public Iterator<Element> iterator() {
   }
 
   /**
-   * Iterates over all elements <p/> * NOTE: Implementations may choose to reuse the Element returned for performance
+   * Iterates over all elements <p>
+   * NOTE: Implementations may choose to reuse the Element returned for performance
    * reasons, so if you need a copy of it, you should call {@link #getElement(int)} for the given index
    *
    * @return An {@link Iterator} over all elements
    */
   protected abstract Iterator<Element> iterator();
 
   /**
-   * Iterates over all non-zero elements. <p/> NOTE: Implementations may choose to reuse the Element returned for
+   * Iterates over all non-zero elements. <p>
+   * NOTE: Implementations may choose to reuse the Element returned for
    * performance reasons, so if you need a copy of it, you should call {@link #getElement(int)} for the given index
    *
    * @return An {@link Iterator} over all non-zero elements

diff --git a/math/src/main/java/org/apache/mahout/math/CholeskyDecomposition.java b/math/src/main/java/org/apache/mahout/math/CholeskyDecomposition.java
@@ -22,7 +22,7 @@
 
 /**
  * Cholesky decomposition shamelessly ported from JAMA.
- * <p/>
+ * <p>
  * A Cholesky decomposition of a semi-positive definite matrix A is a lower triangular matrix L such
  * that L L^* = A.  If A is full rank, L is unique.  If A is real, then it must be symmetric and R
  * will also be real.

diff --git a/math/src/main/java/org/apache/mahout/math/ConstantVector.java b/math/src/main/java/org/apache/mahout/math/ConstantVector.java
@@ -47,7 +47,7 @@ protected Matrix matrixLike(int rows, int columns) {
   /**
    * Used internally by assign() to update multiple indices and values at once.
    * Only really useful for sparse vectors (especially SequentialAccessSparseVector).
-   * <p/>
+   * <p>
    * If someone ever adds a new type of sparse vectors, this method must merge (index, value) pairs into the vector.
    *
    * @param updates a mapping of indices to values to merge in the vector.
@@ -77,7 +77,8 @@ public boolean isSequentialAccess() {
   }
 
   /**
-   * Iterates over all elements <p/> * NOTE: Implementations may choose to reuse the Element returned
+   * Iterates over all elements <p>
+   * NOTE: Implementations may choose to reuse the Element returned
    * for performance reasons, so if you need a copy of it, you should call {@link #getElement(int)}
    * for the given index
    *
@@ -100,7 +101,8 @@ protected Element computeNext() {
   }
 
   /**
-   * Iterates over all non-zero elements. <p/> NOTE: Implementations may choose to reuse the Element
+   * Iterates over all non-zero elements.<p>
+   * NOTE: Implementations may choose to reuse the Element
    * returned for performance reasons, so if you need a copy of it, you should call {@link
    * #getElement(int)} for the given index
    *

diff --git a/math/src/main/java/org/apache/mahout/math/FileBasedSparseBinaryMatrix.java b/math/src/main/java/org/apache/mahout/math/FileBasedSparseBinaryMatrix.java
@@ -41,13 +41,13 @@
  * DoubleBuffer and we access that instead.  The interesting aspect of this is that the values in
  * the matrix are binary and sparse so we don't need to store the actual data, just the location of
  * non-zero values.
- * <p/>
+ * <p>
  * Currently file data is formatted as follows:
- * <p/>
+ * <p>
  * <ul> <li>A magic number to indicate the file format.</li> <li>The size of the matrix (max rows
  * and columns possible)</li> <li>Number of non-zeros in each row.</li> <li>A list of non-zero
  * columns for each row.  The list starts with a count and then has column numbers</li> </ul>
- * <p/>
+ * <p>
  * It would be preferable to use something like protobufs to define the format so that we can use
  * different row formats for different kinds of data.  For instance, Golay coding of column numbers
  * or compressed bit vectors might be good representations for some purposes.

diff --git a/math/src/main/java/org/apache/mahout/math/Matrices.java b/math/src/main/java/org/apache/mahout/math/Matrices.java
@@ -29,7 +29,7 @@ public final class Matrices {
 
   /**
    * Create a matrix view based on a function generator.
-   * <p/>
+   * <p>
    * The generator needs to be idempotent, i.e. returning same value
    * for each combination of (row, column) argument sent to generator's
    * {@link IntIntFunction#apply(int, int)} call.
@@ -129,7 +129,7 @@ public double apply(int first, int second) {
 
   /**
    * Uniform [-1,1) matrix generator function.
-   * <p/>
+   * <p>
    * WARNING: to keep things performant, it is stateful and so not thread-safe.
    * You'd need to create a copy per thread (with same seed) if shared between threads.
    *

diff --git a/math/src/main/java/org/apache/mahout/math/Matrix.java b/math/src/main/java/org/apache/mahout/math/Matrix.java
@@ -271,28 +271,28 @@ public interface Matrix extends Cloneable, VectorIterable {
   /**
    * Return a map of the current column label bindings of the receiver
    *
-   * @return a Map<String, Integer>
+   * @return a {@code Map<String, Integer>}
    */
   Map<String, Integer> getColumnLabelBindings();
 
   /**
    * Return a map of the current row label bindings of the receiver
    *
-   * @return a Map<String, Integer>
+   * @return a {@code Map<String, Integer>}
    */
   Map<String, Integer> getRowLabelBindings();
 
   /**
    * Sets a map of column label bindings in the receiver
    *
-   * @param bindings a Map<String, Integer> of label bindings
+   * @param bindings a {@code Map<String, Integer>} of label bindings
    */
   void setColumnLabelBindings(Map<String, Integer> bindings);
 
   /**
    * Sets a map of row label bindings in the receiver
    *
-   * @param bindings a Map<String, Integer> of label bindings
+   * @param bindings a {@code Map<String, Integer>} of label bindings
    */
   void setRowLabelBindings(Map<String, Integer> bindings);
 

diff --git a/math/src/main/java/org/apache/mahout/math/MatrixVectorView.java b/math/src/main/java/org/apache/mahout/math/MatrixVectorView.java
@@ -84,7 +84,8 @@ public boolean isSequentialAccess() {
   }
 
   /**
-   * Iterates over all elements <p/> * NOTE: Implementations may choose to reuse the Element returned
+   * Iterates over all elements <p>
+   * NOTE: Implementations may choose to reuse the Element returned
    * for performance reasons, so if you need a copy of it, you should call {@link #getElement(int)} for
    * the given index
    *
@@ -118,7 +119,8 @@ public void remove() {
   }
 
   /**
-   * Iterates over all non-zero elements. <p/> NOTE: Implementations may choose to reuse the Element
+   * Iterates over all non-zero elements. <p>
+   * NOTE: Implementations may choose to reuse the Element
    * returned for performance reasons, so if you need a copy of it, you should call {@link
    * #getElement(int)} for the given index
    *
@@ -274,7 +276,7 @@ public Vector clone() {
   /**
    * Used internally by assign() to update multiple indices and values at once.
    * Only really useful for sparse vectors (especially SequentialAccessSparseVector).
-   * <p/>
+   * <p>
    * If someone ever adds a new type of sparse vectors, this method must merge (index, value) pairs into the vector.
    *
    * @param updates a mapping of indices to values to merge in the vector.

diff --git a/math/src/main/java/org/apache/mahout/math/MurmurHash.java b/math/src/main/java/org/apache/mahout/math/MurmurHash.java
@@ -23,9 +23,9 @@
 import java.nio.ByteOrder;
 
 /**
- * This is a very fast, non-cryptographic hash suitable for general hash-based
+ * <p>This is a very fast, non-cryptographic hash suitable for general hash-based
  * lookup.  See http://murmurhash.googlepages.com/ for more details.
- * <p/>
+ * </p>
  * <p>The C version of MurmurHash 2.0 found at that site was ported
  * to Java by Andrzej Bialecki (ab at getopt org).</p>
  */

diff --git a/math/src/main/java/org/apache/mahout/math/OldQRDecomposition.java b/math/src/main/java/org/apache/mahout/math/OldQRDecomposition.java
@@ -58,7 +58,7 @@ public class OldQRDecomposition implements QR {
    * can be retrieved via instance methods of the returned decomposition object.
    *
    * @param a A rectangular matrix.
-   * @throws IllegalArgumentException if <tt>A.rows() < A.columns()</tt>.
+   * @throws IllegalArgumentException if {@code A.rows() < A.columns()}
    */
 
   public OldQRDecomposition(Matrix a) {

diff --git a/math/src/main/java/org/apache/mahout/math/PermutedVectorView.java b/math/src/main/java/org/apache/mahout/math/PermutedVectorView.java
@@ -67,7 +67,7 @@ protected Matrix matrixLike(int rows, int columns) {
   /**
    * Used internally by assign() to update multiple indices and values at once.
    * Only really useful for sparse vectors (especially SequentialAccessSparseVector).
-   * <p/>
+   * <p>
    * If someone ever adds a new type of sparse vectors, this method must merge (index, value) pairs into the vector.
    *
    * @param updates a mapping of indices to values to merge in the vector.
@@ -102,7 +102,7 @@ public boolean isSequentialAccess() {
   }
 
   /**
-   * Iterates over all elements <p/> * NOTE: Implementations may choose to reuse the Element
+   * Iterates over all elements <p> * NOTE: Implementations may choose to reuse the Element
    * returned for performance reasons, so if you need a copy of it, you should call {@link
    * #getElement(int)} for the given index
    *
@@ -143,7 +143,7 @@ public void set(double value) {
   }
 
   /**
-   * Iterates over all non-zero elements. <p/> NOTE: Implementations may choose to reuse the Element
+   * Iterates over all non-zero elements. <p> NOTE: Implementations may choose to reuse the Element
    * returned for performance reasons, so if you need a copy of it, you should call {@link
    * #getElement(int)} for the given index
    *

diff --git a/math/src/main/java/org/apache/mahout/math/QRDecomposition.java b/math/src/main/java/org/apache/mahout/math/QRDecomposition.java
@@ -28,7 +28,7 @@
 import java.util.Locale;
 
 /**
- For an <tt>m x n</tt> matrix <tt>A</tt> with <tt>m >= n</tt>, the QR decomposition is an <tt>m x n</tt>
+ For an <tt>m x n</tt> matrix <tt>A</tt> with {@code m >= n}, the QR decomposition is an <tt>m x n</tt>
  orthogonal matrix <tt>Q</tt> and an <tt>n x n</tt> upper triangular matrix <tt>R</tt> so that
  <tt>A = Q*R</tt>.
  <P>
@@ -53,7 +53,7 @@ public class QRDecomposition implements QR {
    * object.
    *
    * @param a A rectangular matrix.
-   * @throws IllegalArgumentException if <tt>A.rows() < A.columns()</tt>.
+   * @throws IllegalArgumentException if {@code A.rows() < A.columns()}.
    */
   public QRDecomposition(Matrix a) {
 

diff --git a/math/src/main/java/org/apache/mahout/math/SparseMatrix.java b/math/src/main/java/org/apache/mahout/math/SparseMatrix.java
@@ -41,7 +41,7 @@ public class SparseMatrix extends AbstractMatrix {
    *
    * @param rows no of rows
    * @param columns no of columns
-   * @param rowVectors a Map<Integer, RandomAccessSparseVector> of rows
+   * @param rowVectors a {@code Map<Integer, RandomAccessSparseVector>} of rows
    */
   public SparseMatrix(int rows, int columns, Map<Integer, Vector> rowVectors) {
     this(rows, columns, rowVectors, false);