add missing javadoc tags to 10 files in the com.jme3.math package

jme3-core/src/main/java/com/jme3/math/FastMath.java

@@ -801,6 +801,24 @@ final public class FastMath {
 
     /**
      * Returns the determinant of a 4x4 matrix.
+     *
+     * @param m00 the element in row 0, column 0 of the matrix
+     * @param m01 the element in row 0, column 1 of the matrix
+     * @param m02 the element in row 0, column 2 of the matrix
+     * @param m03 the element in row 0, column 3 of the matrix
+     * @param m10 the element in row 1, column 0 of the matrix
+     * @param m11 the element in row 1, column 1 of the matrix
+     * @param m12 the element in row 1, column 2 of the matrix
+     * @param m13 the element in row 1, column 3 of the matrix
+     * @param m20 the element in row 2, column 0 of the matrix
+     * @param m21 the element in row 2, column 1 of the matrix
+     * @param m22 the element in row 2, column 2 of the matrix
+     * @param m23 the element in row 2, column 3 of the matrix
+     * @param m30 the element in row 3, column 0 of the matrix
+     * @param m31 the element in row 3, column 1 of the matrix
+     * @param m32 the element in row 3, column 2 of the matrix
+     * @param m33 the element in row 3, column 3 of the matrix
+     * @return the determinant
      */
     public static float determinant(double m00, double m01, double m02,
             double m03, double m10, double m11, double m12, double m13,
@@ -832,6 +850,8 @@ final public class FastMath {
     /**
      * Returns a random integer between min and max.
      *
+     * @param min the desired minimum value
+     * @param max the desired maximum value
      * @return A random int between <tt>min</tt> (inclusive) to
      * <tt>max</tt> (inclusive).
      */
@@ -852,6 +872,12 @@ final public class FastMath {
     /**
      * Converts a point from Spherical coordinates to Cartesian (using positive
      * Y as up) and stores the results in the store var.
+     *
+     * @param sphereCoords the input spherical coordinates: x=distance from
+     * origin, y=longitude in radians, z=latitude in radians (not null,
+     * unaffected)
+     * @param store storage for the result (modified if not null)
+     * @return the Cartesian coordinates (either store or a new vector)
      */
     public static Vector3f sphericalToCartesian(Vector3f sphereCoords,
             Vector3f store) {
@@ -870,6 +896,11 @@ final public class FastMath {
      * Converts a point from Cartesian coordinates (using positive Y as up) to
      * Spherical and stores the results in the store var. (Radius, Azimuth,
      * Polar)
+     *
+     * @param cartCoords the input Cartesian coordinates (not null, unaffected)
+     * @param store storage for the result (modified if not null)
+     * @return the Cartesian coordinates: x=distance from origin, y=longitude in
+     * radians, z=latitude in radians (either store or a new vector)
      */
     public static Vector3f cartesianToSpherical(Vector3f cartCoords,
             Vector3f store) {
@@ -894,6 +925,12 @@ final public class FastMath {
     /**
      * Converts a point from Spherical coordinates to Cartesian (using positive
      * Z as up) and stores the results in the store var.
+     *
+     * @param sphereCoords the input spherical coordinates: x=distance from
+     * origin, y=longitude in radians, z=latitude in radians (not null,
+     * unaffected)
+     * @param store storage for the result (modified if not null)
+     * @return the Cartesian coordinates (either store or a new vector)
      */
     public static Vector3f sphericalToCartesianZ(Vector3f sphereCoords,
             Vector3f store) {
@@ -912,6 +949,11 @@ final public class FastMath {
      * Converts a point from Cartesian coordinates (using positive Z as up) to
      * Spherical and stores the results in the store var. (Radius, Azimuth,
      * Polar)
+     *
+     * @param cartCoords the input Cartesian coordinates (not null, unaffected)
+     * @param store storage for the result (modified if not null)
+     * @return the Cartesian coordinates: x=distance from origin, y=latitude in
+     * radians, z=longitude in radians (either store or a new vector)
      */
     public static Vector3f cartesianZToSpherical(Vector3f cartCoords,
             Vector3f store) {
@@ -938,6 +980,10 @@ final public class FastMath {
      *
      * @param val -
      *            the angle to normalize (in radians)
+     * @param min
+     *            the lower limit of the range
+     * @param max
+     *            the upper limit of the range
      * @return the normalized angle (also in radians)
      */
     public static float normalize(float val, float min, float max) {

jme3-core/src/main/java/com/jme3/math/LineSegment.java

@@ -79,6 +79,11 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
     /**
      * <p>Creates a new LineSegment with the given origin, direction and extent.</p>
      * <p>Note that the origin is not one of the ends of the LineSegment, but its center.</p>
+     *
+     * @param origin the location of the desired midpoint (alias created)
+     * @param direction the desired direction vector (alias created)
+     * @param extent the extent: 1/2 of the desired length, assuming direction
+     * is a unit vector
      */
     public LineSegment(Vector3f origin, Vector3f direction, float extent) {
         this.origin = origin;
@@ -89,6 +94,9 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
     /**
      * <p>Creates a new LineSegment with a given origin and end. This constructor will calculate the
      * center, the direction and the extent.</p>
+     *
+     * @param start location of the negative endpoint (not null, unaffected)
+     * @param end location of the negative endpoint (not null, unaffected)
      */
     public LineSegment(Vector3f start, Vector3f end) {
         this.origin = new Vector3f(0.5f * (start.x + end.x), 0.5f * (start.y + end.y), 0.5f * (start.z + end.z));
@@ -716,6 +724,9 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
     /**
      * <p>Evaluates whether a given point is contained within the axis aligned bounding box
      * that contains this LineSegment.</p><p>This function is float error aware.</p>
+     * 
+     * @param point the location of the input point (not null, unaffected)
+     * @return true if contained in the box, otherwise false
      */
     public boolean isPointInsideBounds(Vector3f point) {
         return isPointInsideBounds(point, Float.MIN_VALUE);
@@ -725,6 +736,10 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
      * <p>Evaluates whether a given point is contained within the axis aligned bounding box
      * that contains this LineSegment.</p><p>This function accepts an error parameter, which
      * is added to the extent of the bounding box.</p>
+     * 
+     * @param point the location of the input point (not null, unaffected)
+     * @param error the desired margin for error
+     * @return true if contained in the box, otherwise false
      */
     public boolean isPointInsideBounds(Vector3f point, float error) {
 

jme3-core/src/main/java/com/jme3/math/Matrix3f.java

@@ -459,6 +459,8 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
      * @param fb
      *            the buffer to fill, starting at current position. Must have
      *            room for 9 more floats.
+     * @param columnMajor
+     *            true → column-major order, false → row-major order
      * @return matrix data as a FloatBuffer. (position is advanced by 9 and any
      *         limit set is not changed).
      */
@@ -1021,6 +1023,7 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     /**
      * Inverts this matrix and stores it in the given store.
      *
+     * @param store storage for the result (modified if not null)
      * @return The store
      */
     public Matrix3f invert(Matrix3f store) {

jme3-core/src/main/java/com/jme3/math/Matrix4f.java

@@ -142,6 +142,23 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
 
     /**
      * constructs a matrix with the given values.
+     *
+     * @param m00 the desired value for row 0, column 0
+     * @param m01 the desired value for row 0, column 1
+     * @param m02 the desired value for row 0, column 2
+     * @param m03 the desired value for row 0, column 3
+     * @param m10 the desired value for row 1, column 0
+     * @param m11 the desired value for row 1, column 1
+     * @param m12 the desired value for row 1, column 2
+     * @param m13 the desired value for row 1, column 3
+     * @param m20 the desired value for row 2, column 0
+     * @param m21 the desired value for row 2, column 1
+     * @param m22 the desired value for row 2, column 2
+     * @param m23 the desired value for row 2, column 3
+     * @param m30 the desired value for row 3, column 0
+     * @param m31 the desired value for row 3, column 1
+     * @param m32 the desired value for row 3, column 2
+     * @param m33 the desired value for row 3, column 3
      */
     public Matrix4f(float m00, float m01, float m02, float m03,
             float m10, float m11, float m12, float m13,
@@ -593,6 +610,23 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
 
     /**
      * Sets the values of this matrix
+     *
+     * @param m00 the desired value for row 0, column 0
+     * @param m01 the desired value for row 0, column 1
+     * @param m02 the desired value for row 0, column 2
+     * @param m03 the desired value for row 0, column 3
+     * @param m10 the desired value for row 1, column 0
+     * @param m11 the desired value for row 1, column 1
+     * @param m12 the desired value for row 1, column 2
+     * @param m13 the desired value for row 1, column 3
+     * @param m20 the desired value for row 2, column 0
+     * @param m21 the desired value for row 2, column 1
+     * @param m22 the desired value for row 2, column 2
+     * @param m23 the desired value for row 2, column 3
+     * @param m30 the desired value for row 3, column 0
+     * @param m31 the desired value for row 3, column 1
+     * @param m32 the desired value for row 3, column 2
+     * @param m33 the desired value for row 3, column 3
      */
     public void set(float m00, float m01, float m02, float m03,
             float m10, float m11, float m12, float m13,
@@ -622,6 +656,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
      *
      * @param matrix
      *            the matrix to read the value from.
+     * @return this
      */
     public Matrix4f set(Matrix4f matrix) {
         m00 = matrix.m00;
@@ -1513,6 +1548,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     /**
      * Inverts this matrix and stores it in the given store.
      *
+     * @param store storage for the result (modified if not null)
      * @return The store
      */
     public Matrix4f invert(Matrix4f store) {

jme3-core/src/main/java/com/jme3/math/Plane.java

@@ -119,6 +119,9 @@ public class Plane implements Savable, Cloneable, java.io.Serializable {
     /**
      * <code>setNormal</code> sets the normal of the plane.
      *
+     * @param x the desired X component for the normal vector
+     * @param y the desired Y component for the normal vector
+     * @param z the desired Z component for the normal vector
      */
     public void setNormal(float x, float y, float z) {
         this.normal.set(x, y, z);

jme3-core/src/main/java/com/jme3/math/Quaternion.java

@@ -249,6 +249,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      *
      * @param angles
      *            the Euler angles of rotation (in radians).
+     * @return this
      */
     public Quaternion fromAngles(float[] angles) {
         if (angles.length != 3) {
@@ -276,6 +277,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * @param zAngle
      *            the Euler roll of rotation (in radians). (aka Bank, often
      *            rot around z)
+     * @return this
      */
     public Quaternion fromAngles(float xAngle, float yAngle, float zAngle) {
         float angle;
@@ -352,6 +354,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      *
      * @param matrix
      *            the matrix that defines the rotation.
+     * @return this
      */
     public Quaternion fromRotationMatrix(Matrix3f matrix) {
         return fromRotationMatrix(matrix.m00, matrix.m01, matrix.m02, matrix.m10,
@@ -688,6 +691,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      *            the angle to rotate (in radians).
      * @param axis
      *            the axis of rotation (already normalized).
+     * @return this
      */
     public Quaternion fromAngleNormalAxis(float angle, Vector3f axis) {
         if (axis.x == 0 && axis.y == 0 && axis.z == 0) {
@@ -746,6 +750,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      *            the second quaternion.
      * @param t
      *            the amount to interpolate between the two quaternions.
+     * @return this
      */
     public Quaternion slerp(Quaternion q1, Quaternion q2, float t) {
         // Create a local quaternion to store the interpolated quaternion
@@ -992,6 +997,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * @param axis
      *            the array containing the three vectors representing the
      *            coordinate system.
+     * @return this
      */
     public Quaternion fromAxes(Vector3f[] axis) {
         if (axis.length != 3) {
@@ -1012,6 +1018,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * @param xAxis vector representing the x-axis of the coordinate system.
      * @param yAxis vector representing the y-axis of the coordinate system.
      * @param zAxis vector representing the z-axis of the coordinate system.
+     * @return this
      */
     public Quaternion fromAxes(Vector3f xAxis, Vector3f yAxis, Vector3f zAxis) {
         return fromRotationMatrix(xAxis.x, yAxis.x, zAxis.x, xAxis.y, yAxis.y,
@@ -1206,6 +1213,8 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
     /**
      * <code>normalize</code> normalizes the current <code>Quaternion</code>.
      * The result is stored internally.
+     *
+     * @return this
      */
     public Quaternion normalizeLocal() {
         float n = FastMath.invSqrt(norm());
@@ -1316,6 +1325,10 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
     /**
      * Returns true if this quaternion is similar to the specified quaternion
      * within some value of epsilon.
+     *
+     * @param other the Quaternion to compare with (not null, unaffected)
+     * @param epsilon the error tolerance for each component
+     * @return true if all 4 components are within tolerance, otherwise false
      */
     public boolean isSimilar(Quaternion other, float epsilon) {
         if (other == null) {
@@ -1402,6 +1415,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * @param up
      *            a vector indicating the local up direction.
      *            (typically {0, 1, 0} in jME.)
+     * @return this
      */
     public Quaternion lookAt(Vector3f direction, Vector3f up) {
         TempVars vars = TempVars.get();

jme3-core/src/main/java/com/jme3/math/Spline.java

@@ -312,6 +312,8 @@ public class Spline implements Savable {
 
     /**
      * returns the curve tension
+     *
+     * @return the value of the tension parameter
      */
     public float getCurveTension() {
         return curveTension;
@@ -330,7 +332,7 @@ public class Spline implements Savable {
     }
 
     /**
-     * returns true if the spline cycle
+     * @return true if the spline cycles
      */
     public boolean isCycle() {
         return cycle;
@@ -359,7 +361,7 @@ public class Spline implements Savable {
     }
 
     /**
-     * return the total length of the spline
+     * @return the total length of the spline
      */
     public float getTotalLength() {
         return totalLength;
@@ -367,6 +369,8 @@ public class Spline implements Savable {
 
     /**
      * return the type of the spline
+     *
+     * @return the enum value
      */
     public SplineType getType() {
         return type;
@@ -384,6 +388,8 @@ public class Spline implements Savable {
 
     /**
      * returns this spline control points
+     * 
+     * @return the pre-existing list
      */
     public List<Vector3f> getControlPoints() {
         return controlPoints;
@@ -391,6 +397,8 @@ public class Spline implements Savable {
 
     /**
      * returns a list of float representing the segments length
+     *
+     * @return the pre-existing list
      */
     public List<Float> getSegmentsLength() {
         return segmentsLength;

jme3-core/src/main/java/com/jme3/math/Vector2f.java

@@ -235,6 +235,7 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
      * @param changeAmnt
      *            An amount between 0.0 - 1.0 representing a percentage change
      *            from this towards finalVec
+     * @return this
      */
     public Vector2f interpolateLocal(Vector2f finalVec, float changeAmnt) {
         this.x = (1 - changeAmnt) * this.x + changeAmnt * finalVec.x;
@@ -253,6 +254,7 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
      * @param changeAmnt
      *            An amount between 0.0 - 1.0 representing a percentage change
      *            from beginVec towards finalVec
+     * @return this
      */
     public Vector2f interpolateLocal(Vector2f beginVec, Vector2f finalVec,
             float changeAmnt) {
@@ -622,6 +624,8 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
 
     /**
      * <code>zero</code> resets this vector's data to zero internally.
+     *
+     * @return this
      */
     public Vector2f zero() {
         x = y = 0;
@@ -698,6 +702,10 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     /**
      * Returns true if this vector is similar to the specified vector within
      * some value of epsilon.
+     *
+     * @param other the vector to compare with (not null, unaffected)
+     * @param epsilon the desired error tolerance for each component
+     * @return true if both components are within tolerance, otherwise false
      */
     public boolean isSimilar(Vector2f other, float epsilon) {
         if (other == null) {

jme3-core/src/main/java/com/jme3/math/Vector3f.java

@@ -247,6 +247,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      *            the value to multiply this vector by.
      * @param add
      *            the value to add
+     * @return this
      */
     public Vector3f scaleAdd(float scalar, Vector3f add) {
         x = x * scalar + add.x;
@@ -265,6 +266,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      *            the value to multiply the scalar by
      * @param add
      *            the value to add
+     * @return this
      */
     public Vector3f scaleAdd(float scalar, Vector3f mult, Vector3f add) {
         this.x = mult.x * scalar + add.x;
@@ -789,6 +791,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * in this vector.
      *
      * @param other
+     * @return this
      */
     public Vector3f maxLocal(Vector3f other) {
         x = other.x > x ? other.x : x;
@@ -803,6 +806,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * in this vector.
      *
      * @param other
+     * @return this
      */
     public Vector3f minLocal(Vector3f other) {
         x = other.x < x ? other.x : x;
@@ -813,6 +817,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
 
     /**
      * <code>zero</code> resets this vector's data to zero internally.
+     * @return this
      */
     public Vector3f zero() {
         x = y = z = 0;
@@ -839,6 +844,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * @param finalVec The final vector to interpolate towards
      * @param changeAmnt An amount between 0.0 - 1.0 representing a percentage
      *  change from this towards finalVec
+     * @return this
      */
     public Vector3f interpolateLocal(Vector3f finalVec, float changeAmnt) {
         this.x = (1 - changeAmnt) * this.x + changeAmnt * finalVec.x;
@@ -855,6 +861,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * @param finalVec The final vector to interpolate towards
      * @param changeAmnt An amount between 0.0 - 1.0 representing a percentage
      *  change from beginVec towards finalVec
+     * @return this
      */
     public Vector3f interpolateLocal(Vector3f beginVec, Vector3f finalVec, float changeAmnt) {
         this.x = (1 - changeAmnt) * beginVec.x + changeAmnt * finalVec.x;
@@ -978,6 +985,10 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
     /**
      * Returns true if this vector is similar to the specified vector within
      * some value of epsilon.
+     *
+     * @param other the vector to compare with (not null, unaffected)
+     * @param epsilon the desired error tolerance for each component
+     * @return true if all 3 components are within tolerance, otherwise false
      */
     public boolean isSimilar(Vector3f other, float epsilon) {
         if (other == null) {

jme3-core/src/main/java/com/jme3/math/Vector4f.java

@@ -232,6 +232,8 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
      *            the y value to add.
      * @param addZ
      *            the z value to add.
+     * @param addW
+     *            the w value to add.
      * @return the result vector.
      */
     public Vector4f add(float addX, float addY, float addZ, float addW) {
@@ -249,6 +251,8 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
      *            value to add to y
      * @param addZ
      *            value to add to z
+     * @param addW
+     *            the w value to add.
      * @return this
      */
     public Vector4f addLocal(float addX, float addY, float addZ, float addW) {
@@ -268,6 +272,7 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
      *            the value to multiply this vector by.
      * @param add
      *            the value to add
+     * @return this
      */
     public Vector4f scaleAdd(float scalar, Vector4f add) {
         x = x * scalar + add.x;
@@ -288,6 +293,7 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
      *            the value to multiply the scalar by
      * @param add
      *            the value to add
+     * @return this
      */
     public Vector4f scaleAdd(float scalar, Vector4f mult, Vector4f add) {
         this.x = mult.x * scalar + add.x;
@@ -732,6 +738,7 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
      * component in this and <code>other</code> vector. The result is stored
      * in this vector.
      * @param other
+     * @return this
      */
     public Vector4f maxLocal(Vector4f other){
         x = other.x > x ? other.x : x;
@@ -746,6 +753,7 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
      * component in this and <code>other</code> vector. The result is stored
      * in this vector.
      * @param other
+     * @return this
      */
     public Vector4f minLocal(Vector4f other){
         x = other.x < x ? other.x : x;
@@ -757,6 +765,8 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
 
     /**
      * <code>zero</code> resets this vector's data to zero internally.
+     *
+     * @return this, with all components set to zero
      */
     public Vector4f zero() {
         x = y = z = w = 0;
@@ -782,6 +792,7 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
      * @param finalVec The final vector to interpolate towards
      * @param changeAmnt An amount between 0.0 - 1.0 representing a percentage
      *  change from this towards finalVec
+     * @return this
      */
     public Vector4f interpolateLocal(Vector4f finalVec, float changeAmnt) {
         this.x=(1-changeAmnt)*this.x + changeAmnt*finalVec.x;
@@ -798,6 +809,7 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
      * @param finalVec The final vector to interpolate towards
      * @param changeAmnt An amount between 0.0 - 1.0 representing a percentage
      *  change from beginVec towards finalVec
+     * @return this
      */
     public Vector4f interpolateLocal(Vector4f beginVec,Vector4f finalVec, float changeAmnt) {
         this.x=(1-changeAmnt)*beginVec.x + changeAmnt*finalVec.x;
@@ -879,6 +891,10 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
     /**
      * Returns true if this vector is similar to the specified vector within
      * some value of epsilon.
+     *
+     * @param other the vector to compare with (not null, unaffected)
+     * @param epsilon the desired error tolerance for each component
+     * @return true if all 4 components are within tolerance, otherwise false
      */
     public boolean isSimilar(Vector4f other, float epsilon) {
         if (other == null) {