Fixes some errors in the Java documentation of ardor3d-math

5 files changed, 120 insertions, 20 deletions

diff --git a/ardor3d-math/src/main/java/com/ardor3d/math/Matrix4.java b/ardor3d-math/src/main/java/com/ardor3d/math/Matrix4.java
index 2bac484..e8d7123 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/Matrix4.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/Matrix4.java
@@ -68,21 +68,37 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Constructs a new matrix set to the given matrix values. (names are mRC = m[ROW][COL])
      *
      * @param m00
+     *            m00
      * @param m01
+     *            m01
      * @param m02
+     *            m02
      * @param m03
+     *            m03
      * @param m10
+     *            m10
      * @param m11
+     *            m11
      * @param m12
+     *            m12
      * @param m13
+     *            m13
      * @param m20
+     *            m20
      * @param m21
+     *            m21
      * @param m22
+     *            m22
      * @param m23
+     *            m23
      * @param m30
+     *            m30
      * @param m31
+     *            m31
      * @param m32
+     *            m32
      * @param m33
+     *            m33
      */
     public Matrix4(final double m00, final double m01, final double m02, final double m03, final double m10,
             final double m11, final double m12, final double m13, final double m20, final double m21, final double m22,
@@ -110,6 +126,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Constructs a new matrix set to the values of the given matrix.
      *
      * @param source
+     *            the source matrix
      */
     public Matrix4(final ReadOnlyMatrix4 source) {
         set(source);
@@ -117,7 +134,9 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
 
     /**
      * @param row
+     *            the row index
      * @param column
+     *            the column index
      * @return the value stored in this matrix at row, column.
      * @throws IllegalArgumentException
      *             if row and column are not in bounds [0, 3]
@@ -181,7 +200,9 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
 
     /**
      * @param row
+     *            the row index
      * @param column
+     *            the column index
      * @return the value stored in this matrix at row, column, pre-cast to a float for convenience.
      * @throws IllegalArgumentException
      *             if row and column are not in bounds [0, 2]
@@ -356,8 +377,11 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Sets the value of this matrix at row, column to the given value.
      *
      * @param row
+     *            the row index
      * @param column
+     *            the column index
      * @param value
+     *            the value to set
      * @return this matrix for chaining
      * @throws IllegalArgumentException
      *             if row and column are not in bounds [0, 3]
@@ -451,21 +475,37 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Sets the values of this matrix to the values given.
      *
      * @param m00
+     *            m00
      * @param m01
+     *            m01
      * @param m02
+     *            m02
      * @param m03
+     *            m03
      * @param m10
+     *            m10
      * @param m11
+     *            m11
      * @param m12
+     *            m12
      * @param m13
+     *            m13
      * @param m20
+     *            m20
      * @param m21
+     *            m21
      * @param m22
+     *            m22
      * @param m23
+     *            m23
      * @param m30
+     *            m30
      * @param m31
+     *            m31
      * @param m32
+     *            m32
      * @param m33
+     *            m33
      * @return this matrix for chaining
      */
     public Matrix4 set(final double m00, final double m01, final double m02, final double m03, final double m10,
@@ -496,6 +536,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Sets the values of this matrix to the values of the provided source matrix.
      *
      * @param source
+     *            the source matrix
      * @return this matrix for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -528,6 +569,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Sets the 3x3 rotation part of this matrix to the values of the provided source matrix.
      *
      * @param source
+     *            the source matrix
      * @return this matrix for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -550,6 +592,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * part of this matrix.
      *
      * @param quaternion
+     *            the quaternion
      * @return this matrix for chaining
      */
     public Matrix4 set(final ReadOnlyQuaternion quaternion) {
@@ -615,7 +658,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
     /**
      * Note: data is cast to floats.
      *
-     * @param store
+     * @param source
      *            the buffer to read our matrix data from.
      * @return this matrix for chaining.
      */
@@ -626,7 +669,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
     /**
      * Note: data is cast to floats.
      *
-     * @param store
+     * @param source
      *            the buffer to read our matrix data from.
      * @param rowMajor
      *            if true, data is stored row by row. Otherwise it is stored column by column.
@@ -676,6 +719,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Sets the values of this matrix to the values of the provided double array.
      *
      * @param source
+     *            the source values
      * @return this matrix for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -690,7 +734,9 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Sets the values of this matrix to the values of the provided double array.
      *
      * @param source
+     *            the source values
      * @param rowMajor
+     *            <code>true</code> if the source values are stored as a row major matrix
      * @return this matrix for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -740,12 +786,14 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Replaces a column in this matrix with the values of the given array.
      *
      * @param columnIndex
+     *            the column index
      * @param columnData
+     *            the column data
      * @return this matrix for chaining
      * @throws NullPointerException
      *             if columnData is null.
      * @throws IllegalArgumentException
-     *             if columnData has a length < 4
+     *             if columnData has a length &lt; 4
      * @throws IllegalArgumentException
      *             if columnIndex is not in [0, 3]
      */
@@ -785,12 +833,14 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Replaces a row in this matrix with the values of the given array.
      *
      * @param rowIndex
+     *            the row index
      * @param rowData
+     *            the row data
      * @return this matrix for chaining
      * @throws NullPointerException
      *             if rowData is null.
      * @throws IllegalArgumentException
-     *             if rowData has a length < 4
+     *             if rowData has a length &lt; 4
      * @throws IllegalArgumentException
      *             if rowIndex is not in [0, 3]
      */
@@ -1011,9 +1061,12 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * M*T
      *
      * @param x
+     *            the x value
      * @param y
+     *            the y value
      * @param z
-     * @return
+     *            the z value
+     * @return this matrix for chaining
      */
     public Matrix4 applyTranslationPost(final double x, final double y, final double z) {
         _m03 = _m00 * x + _m01 * y + _m02 * z + _m03;
@@ -1028,9 +1081,12 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * T*M
      *
      * @param x
+     *            the x value
      * @param y
+     *            the y value
      * @param z
-     * @return
+     *            the z value
+     * @return this matrix for chaining
      */
     public Matrix4 applyTranslationPre(final double x, final double y, final double z) {
         _m03 = x;
@@ -1042,6 +1098,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
 
     /**
      * @param index
+     *            the column index
      * @param store
      *            the vector to store the result in. if null, a new one is created.
      * @return the column specified by the index.
@@ -1089,6 +1146,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
 
     /**
      * @param index
+     *            the row index
      * @param store
      *            the vector to store the result in. if null, a new one is created.
      * @return the row specified by the index.
@@ -1274,7 +1332,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      *            the double array to store our matrix data in. If null, a new array is created.
      * @return matrix data as a double array in row major order.
      * @throws IllegalArgumentException
-     *             if the store is non-null and has a length < 16
+     *             if the store is non-null and has a length &lt; 16
      */
     @Override
     public double[] toArray(final double[] store) {
@@ -1288,7 +1346,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      *            if true, data is stored row by row. Otherwise it is stored column by column.
      * @return matrix data as a double array in the specified order.
      * @throws IllegalArgumentException
-     *             if the store is non-null and has a length < 16
+     *             if the store is non-null and has a length &lt; 16
      */
     @Override
     public double[] toArray(final double[] store, final boolean rowMajor) {
@@ -1343,6 +1401,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * stored into the supplied "store" matrix.
      *
      * @param vec
+     *            the vector
      * @param store
      *            a matrix to store the result in. If store is null, a new matrix is created. Note that it IS safe for
      *            vec and store to be the same object.
@@ -1371,6 +1430,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * stored into the supplied "store" matrix.
      *
      * @param vec
+     *            the vector
      * @param store
      *            a matrix to store the result in. If store is null, a new matrix is created. Note that it IS safe for
      *            vec and store to be the same object.
@@ -1396,6 +1456,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
 
     /**
      * @param matrix
+     *            the matrix
      * @return This matrix for chaining, modified internally to reflect multiplication against the given matrix
      * @throws NullPointerException
      *             if matrix is null
@@ -1406,6 +1467,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
 
     /**
      * @param matrix
+     *            the matrix
      * @param store
      *            a matrix to store the result in. if null, a new matrix is created. Note that it IS safe for matrix and
      *            store to be the same object.
@@ -1480,6 +1542,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Internally scales all values of this matrix by the given scalar.
      *
      * @param scalar
+     *            the scalar value
      * @return this matrix for chaining.
      */
     public Matrix4 multiplyLocal(final double scalar) {
@@ -1607,6 +1670,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Applies the given scale to this matrix and returns the result as a new matrix
      *
      * @param scale
+     *            the scale value
      * @param store
      *            a matrix to store the result in. If store is null, a new matrix is created.
      * @return the new matrix
@@ -1631,6 +1695,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * Applies the given scale to this matrix values internally
      *
      * @param scale
+     *            the scale value
      * @return this matrix for chaining.
      * @throws NullPointerException
      *             if scale is null.
@@ -2327,7 +2392,9 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * @param in
      *            ObjectInput
      * @throws IOException
+     *             if something wrong occurs while reading
      * @throws ClassNotFoundException
+     *             if a class is not found
      */
     @Override
     public void readExternal(final ObjectInput in) throws IOException, ClassNotFoundException {
@@ -2355,6 +2422,7 @@ public class Matrix4 implements Cloneable, Savable, Externalizable, ReadOnlyMatr
      * @param out
      *            ObjectOutput
      * @throws IOException
+     *             if something wrong occurs while writing
      */
     @Override
     public void writeExternal(final ObjectOutput out) throws IOException {
diff --git a/ardor3d-math/src/main/java/com/ardor3d/math/Ray3.java b/ardor3d-math/src/main/java/com/ardor3d/math/Ray3.java
index 1ac5715..d9823cb 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/Ray3.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/Ray3.java
@@ -3,7 +3,7 @@
  *
  * This file is part of Ardor3D.
  *
- * Ardor3D is free software: you can redistribute it and/or modify it 
+ * Ardor3D is free software: you can redistribute it and/or modify it
  * under the terms of its license which may be found in the accompanying
  * LICENSE file or at <http://www.ardor3d.com/LICENSE>.
  */
@@ -29,7 +29,7 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * Copy constructor.
-     * 
+     *
      * @param source
      *            the ray to copy from.
      */
@@ -39,10 +39,11 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * Constructs a new ray using the supplied origin point and unit length direction vector
-     * 
+     *
      * @param origin
+     *            the origin
      * @param direction
-     *            - unit length
+     *            the direction - unit length
      */
     public Ray3(final ReadOnlyVector3 origin, final ReadOnlyVector3 direction) {
         super(origin, direction);
@@ -50,8 +51,9 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * Copies the values of the given source ray into this ray.
-     * 
+     *
      * @param source
+     *            the source ray
      * @return this ray for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -83,7 +85,9 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * @param polygonVertices
+     *            the vertices of the polygon
      * @param locationStore
+     *            the store of the location
      * @return true if this ray intersects a polygon described by the given vertices.
      */
     @Override
@@ -102,8 +106,11 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * @param pointA
+     *            the point A
      * @param pointB
+     *            the point B
      * @param pointC
+     *            the point C
      * @param locationStore
      *            if not null, and this ray intersects, the point of intersection is calculated and stored in this
      *            Vector3
@@ -119,8 +126,11 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * @param pointA
+     *            the point A
      * @param pointB
+     *            the point B
      * @param pointC
+     *            the point C
      * @param locationStore
      *            if not null, and this ray intersects, the point of intersection is calculated and stored in this
      *            Vector3 as (t, u, v) where t is the distance from the _origin to the point of intersection and (u, v)
@@ -137,9 +147,13 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * @param pointA
+     *            the point A
      * @param pointB
+     *            the point B
      * @param pointC
+     *            the point C
      * @param pointD
+     *            the point D
      * @param locationStore
      *            if not null, and this ray intersects, the point of intersection is calculated and stored in this
      *            Vector3
@@ -157,9 +171,13 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * @param pointA
+     *            the point A
      * @param pointB
+     *            the point B
      * @param pointC
+     *            the point C
      * @param pointD
+     *            the point D
      * @param locationStore
      *            if not null, and this ray intersects, the point of intersection is calculated and stored in this
      *            Vector3 as (t, u, v) where t is the distance from the _origin to the point of intersection and (u, v)
@@ -178,12 +196,18 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * Ray vs triangle implementation.
-     * 
+     *
      * @param pointA
+     *            the point A
      * @param pointB
+     *            the point B
      * @param pointC
+     *            the point C
      * @param locationStore
+     *            the store of the location
      * @param doPlanar
+     *            <code>true</code> if the intersection is planar (has no effect if <code>locationStore</code> is
+     *            <code>null</code>)
      * @return true if this ray intersects a triangle formed by the given three points.
      * @throws NullPointerException
      *             if any of the points are null.
@@ -251,6 +275,7 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * @param plane
+     *            the plane
      * @param locationStore
      *            if not null, and this ray intersects the plane, the world location of the point of intersection is
      *            stored in this vector.
@@ -283,6 +308,7 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
 
     /**
      * @param point
+     *            the point
      * @param store
      *            if not null, the closest point is stored in this param
      * @return the squared distance from this ray to the given point.
@@ -317,7 +343,7 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
     /**
      * Check a ray... if it is null or the values of its origin or direction are NaN or infinite, return false. Else
      * return true.
-     * 
+     *
      * @param ray
      *            the ray to check
      * @return true or false as stated above.
@@ -383,7 +409,7 @@ public class Ray3 extends Line3Base implements ReadOnlyRay3, Poolable {
     /**
      * Releases a Ray back to be used by a future call to fetchTempInstance. TAKE CARE: this Ray object should no longer
      * have other classes referencing it or "Bad Things" will happen.
-     * 
+     *
      * @param ray
      *            the Ray to release.
      */
diff --git a/ardor3d-math/src/main/java/com/ardor3d/math/Ring.java b/ardor3d-math/src/main/java/com/ardor3d/math/Ring.java
index f9a9eb1..a38cf40 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/Ring.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/Ring.java
@@ -314,7 +314,9 @@ public class Ring implements Cloneable, Savable, Externalizable, ReadOnlyRing, P
      * @param in
      *            ObjectInput
      * @throws IOException
+     *             if something wrong occurs while reading
      * @throws ClassNotFoundException
+     *             if a class is not found
      */
     @Override
     public void readExternal(final ObjectInput in) throws IOException, ClassNotFoundException {
@@ -330,6 +332,7 @@ public class Ring implements Cloneable, Savable, Externalizable, ReadOnlyRing, P
      * @param out
      *            ObjectOutput
      * @throws IOException
+     *             if something wrong occurs while writing
      */
     @Override
     public void writeExternal(final ObjectOutput out) throws IOException {
diff --git a/ardor3d-math/src/main/java/com/ardor3d/math/ValidatingTransform.java b/ardor3d-math/src/main/java/com/ardor3d/math/ValidatingTransform.java
index 9c22e73..b06b778 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/ValidatingTransform.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/ValidatingTransform.java
@@ -3,7 +3,7 @@
  *
  * This file is part of Ardor3D.
  *
- * Ardor3D is free software: you can redistribute it and/or modify it 
+ * Ardor3D is free software: you can redistribute it and/or modify it
  * under the terms of its license which may be found in the accompanying
  * LICENSE file or at <http://www.ardor3d.com/LICENSE>.
  */
@@ -19,15 +19,17 @@ import com.ardor3d.math.type.ReadOnlyVector3;
 /**
  * A Transform that checks if any of it's member values are null, NaN or Infinity, and throws an
  * InvalidTransformException if so.
- * 
+ *
  */
 public class ValidatingTransform extends Transform {
-    public ValidatingTransform() {}
+    public ValidatingTransform() {
+    }
 
     /**
      * Copy constructor
-     * 
+     *
      * @param source
+     *            the source transform
      */
     public ValidatingTransform(final ReadOnlyTransform source) {
         super(source);
diff --git a/ardor3d-math/src/main/java/com/ardor3d/math/Vector4.java b/ardor3d-math/src/main/java/com/ardor3d/math/Vector4.java
index 642c4c9..5517d60 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/Vector4.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/Vector4.java
@@ -102,6 +102,7 @@ public class Vector4 implements Cloneable, Savable, Externalizable, ReadOnlyVect
      * Constructs a new vector set to the (x, y, z, w) values of the given source vector.
      *
      * @param src
+     *            the source vector
      */
     public Vector4(final ReadOnlyVector4 src) {
         this(src.getX(), src.getY(), src.getZ(), src.getW());