Fixes some errors in the Java documentation of ardor3d-math

6 files changed, 177 insertions, 122 deletions

diff --git a/ardor3d-math/src/main/java/com/ardor3d/math/ColorRGBA.java b/ardor3d-math/src/main/java/com/ardor3d/math/ColorRGBA.java
index 37f39f3..d61ab4b 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/ColorRGBA.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/ColorRGBA.java
@@ -109,7 +109,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Constructs a new, mutable color set to the (r, g, b, a) values of the provided source color.
      *
-     * @param src
+     * @param src the source color 
      */
     public ColorRGBA(final ReadOnlyColorRGBA src) {
         this(src.getRed(), src.getGreen(), src.getBlue(), src.getAlpha());
@@ -118,10 +118,10 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Constructs a new color set to (r, g, b, a).
      *
-     * @param r
-     * @param g
-     * @param b
-     * @param a
+     * @param r the red component
+     * @param g the green component
+     * @param b the blue component
+     * @param a the alpha component
      */
     public ColorRGBA(final float r, final float g, final float b, final float a) {
         _r = r;
@@ -151,7 +151,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     }
 
     /**
-     * @param index
+     * @param index the field index in this color, must be either 0, 1, 2 or 3
      * @return r value if index == 0, g value if index == 1, b value if index == 2 or a value if index == 3
      * @throws IllegalArgumentException
      *             if index is not one of 0, 1, 2, 3.
@@ -286,7 +286,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Sets the value of this color to the (r, g, b, a) values of the provided source color.
      *
-     * @param source
+     * @param source the source color
      * @return this color for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -314,6 +314,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
      *
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
+     * @return the clamped color
      */
     @Override
     public ColorRGBA clamp(final ColorRGBA store) {
@@ -407,7 +408,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
      * Reads a color, packed into a 4 byte int as 1 byte values in the order ARGB. These byte values are normalized to
      * the range [0.0f, 1.0f]
      *
-     * @param color
+     * @param color the 4 byte int as 1 byte values in the order ARGB
      * @return this color for chaining
      */
     public ColorRGBA fromIntARGB(final int color) {
@@ -422,7 +423,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
      * Reads a color, packed into a 4 byte int as 1 byte values in the order RGBA. These byte values are normalized to
      * the range [0.0f, 1.0f]
      *
-     * @param color
+     * @param color the 4 byte int as 1 byte values in the order RGBA
      * @return this color for chaining
      */
     public ColorRGBA fromIntRGBA(final int color) {
@@ -465,10 +466,10 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Adds the given values to those of this color and returns them in store.
      *
-     * @param r
-     * @param g
-     * @param b
-     * @param a
+     * @param r the red component
+     * @param g the green component
+     * @param b the blue component
+     * @param a the alpha component
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
      * @return (this.r + r, this.g + g, this.b + b, this.a + a)
@@ -486,10 +487,10 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Increments the values of this color with the given r, g, b and a values.
      *
-     * @param r
-     * @param g
-     * @param b
-     * @param a
+     * @param r the red component
+     * @param g the green component
+     * @param b the blue component
+     * @param a the alpha component
      * @return this color for chaining
      */
     public ColorRGBA addLocal(final float r, final float g, final float b, final float a) {
@@ -499,7 +500,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Adds the values of the given source color to those of this color and returns them in store.
      *
-     * @param source
+     * @param source the source color
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
      * @return (this.r + source.r, this.g + source.g, this.b + source.b, this.a + source.a)
@@ -514,7 +515,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Increments the values of this color with the r, g, b and a values of the given color.
      *
-     * @param source
+     * @param source the source color
      * @return this color for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -526,10 +527,10 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Subtracts the given values from those of this color and returns them in store.
      *
-     * @param r
-     * @param g
-     * @param b
-     * @param a
+     * @param r the red component
+     * @param g the green component
+     * @param b the blue component
+     * @param a the alpha component
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
      * @return (this.r - r, this.g - g, this.b - b, this.a - a)
@@ -547,10 +548,10 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Decrements the values of this color by the given r, g, b and a values.
      *
-     * @param r
-     * @param g
-     * @param b
-     * @param a
+     * @param r the red component
+     * @param g the green component
+     * @param b the blue component
+     * @param a the alpha component
      * @return this color for chaining
      */
     public ColorRGBA subtractLocal(final float r, final float g, final float b, final float a) {
@@ -560,7 +561,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Subtracts the values of the given source color from those of this color and returns them in store.
      *
-     * @param source
+     * @param source the source color
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
      * @return (this.r - source.r, this.g - source.g, this.b - source.b, this.a - source.a)
@@ -575,7 +576,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Decrements the values of this color by the r, g, b and a values from the given source color.
      *
-     * @param source
+     * @param source the source color
      * @return this color for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -587,7 +588,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Multiplies the values of this color by the given scalar value and returns the result in store.
      *
-     * @param scalar
+     * @param scalar the scalar value
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
      * @return a new color (this.r * scalar, this.g * scalar, this.b * scalar, this.a * scalar)
@@ -605,10 +606,9 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Internally modifies the values of this color by multiplying them each by the given scalar value.
      *
-     * @param scalar
+     * @param scalar the scalar value
      * @return this color for chaining
      *
-     *         .
      */
     public ColorRGBA multiplyLocal(final float scalar) {
         return set(getRed() * scalar, getGreen() * scalar, getBlue() * scalar, getAlpha() * scalar);
@@ -617,7 +617,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Multiplies the values of this color by the given scalar value and returns the result in store.
      *
-     * @param scale
+     * @param scale the scale values
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
      * @return a new color (this.r * scale.r, this.g * scale.g, this.b * scale.b, this.a * scale.a)
@@ -636,7 +636,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Internally modifies the values of this color by multiplying them each by the given scale values.
      *
-     * @param scale
+     * @param scale the scale values
      * @return this color for chaining
      */
     public ColorRGBA multiplyLocal(final ReadOnlyColorRGBA scale) {
@@ -647,7 +647,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Divides the values of this color by the given scalar value and returns the result in store.
      *
-     * @param scalar
+     * @param scalar the scalar value
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
      * @return a new color (this.r / scalar, this.g / scalar, this.b / scalar, this.a / scalar)
@@ -665,7 +665,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Internally modifies the values of this color by dividing them each by the given scalar value.
      *
-     * @param scalar
+     * @param scalar the scalar value
      * @return this color for chaining
      * @throws ArithmeticException
      *             if scalar is 0
@@ -679,7 +679,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Divides the values of this color by the given scale values and returns the result in store.
      *
-     * @param scale
+     * @param scale the scale values
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
      * @return a new color (this.r / scale.r, this.g / scale.g, this.b / scale.b, this.a / scale.a)
@@ -698,7 +698,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
     /**
      * Internally modifies the values of this color by dividing them each by the given scale values.
      *
-     * @param scale
+     * @param scale the scale values
      * @return this color for chaining
      */
     public ColorRGBA divideLocal(final ReadOnlyColorRGBA scale) {
@@ -711,8 +711,8 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
      * iow, if changeAmnt is closer to 0, the result will be closer to the current value of this color and if it is
      * closer to 1, the result will be closer to the end value.
      *
-     * @param endColor
-     * @param scalar
+     * @param endColor the end color
+     * @param scalar the scalar value
      * @param store
      *            the color to store the result in for return. If null, a new color object is created and returned.
      * @return a new mutable color as described above.
@@ -738,8 +738,8 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
      * iow, if changeAmnt is closer to 0, the result will be closer to the current value of this color and if it is
      * closer to 1, the result will be closer to the end value. The result is stored back in this color.
      *
-     * @param endColor
-     * @param scalar
+     * @param endColor the end color
+     * @param scalar the scalar value
      * @return this color for chaining
      * @throws NullPointerException
      *             if endVec is null.
@@ -757,8 +757,8 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
      * if changeAmnt is closer to 0, the result will be closer to the begin value and if it is closer to 1, the result
      * will be closer to the end value.
      *
-     * @param beginColor
-     * @param endColor
+     * @param beginColor the begin color
+     * @param endColor the end color
      * @param scalar
      *            the scalar as a percent.
      * @param store
@@ -783,12 +783,12 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
 
     /**
      * Performs a linear interpolation between the given begin and end colors, using the given scalar as a percent. iow,
-     * if changeAmnt is closer to 0, the result will be closer to the begin value and if it is closer to 1, the result
+     * if scalar is closer to 0, the result will be closer to the begin value and if it is closer to 1, the result
      * will be closer to the end value. The result is stored back in this color.
      *
-     * @param beginColor
-     * @param endColor
-     * @param changeAmnt
+     * @param beginColor the begin color
+     * @param endColor the end color
+     * @param scalar
      *            the scalar as a percent.
      * @return this color for chaining
      * @throws NullPointerException
@@ -905,8 +905,8 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
      *
      * @param in
      *            ObjectInput
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if something wrong happens while reading the float values
+     * @throws ClassNotFoundException if a class is not found
      */
     @Override
     public void readExternal(final ObjectInput in) throws IOException, ClassNotFoundException {
@@ -921,7 +921,7 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
      *
      * @param out
      *            ObjectOutput
-     * @throws IOException
+     * @throws IOException exception
      */
     @Override
     public void writeExternal(final ObjectOutput out) throws IOException {
@@ -973,9 +973,9 @@ public class ColorRGBA implements Cloneable, Savable, Externalizable, ReadOnlyCo
      * <li>8: RRGGBBAA - RGBA is parsed as RR/255, GG/255, BB/255, AA/255</li>
      * </ul>
      *
-     * @param colorString
-     * @param store
-     * @return
+     * @param colorString the color string
+     * @param store the object used to store the result if not null
+     * @return the parsed color
      */
     public static ColorRGBA parseColor(final String colorString, final ColorRGBA store) {
         ColorRGBA rVal = store;
diff --git a/ardor3d-math/src/main/java/com/ardor3d/math/FastMath.java b/ardor3d-math/src/main/java/com/ardor3d/math/FastMath.java
index 9e02e16..7b5106a 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/FastMath.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/FastMath.java
@@ -47,40 +47,82 @@ public enum FastMath {
 
     private final static double _atan_a = 0.280872d;
 
-    /** sin: [-π,π] -> [-1,1] */
+    /** 
+     * sin: [-π,π] → [-1,1]
+     *
+     * @param x x
+     *
+     * @return the sine
+     */
     public final static double sin(double x) {
         x = FastMath._sin_a * x * Math.abs(x) + FastMath._sin_b * x;
         return FastMath._sin_p * (x * Math.abs(x) - x) + x;
     }
 
-    /** cos: [-π,π] -> [-1,1] */
+    /** 
+     * cos: [-π,π] → [-1,1] 
+     * 
+     * @param x x
+     *
+     * @return the cosine
+     */
     public final static double cos(final double x) {
         return sin(x + (x > MathUtils.HALF_PI ? -MathUtils.THREE_PI_HALVES : MathUtils.HALF_PI));
     }
 
-    /** tan: [-π,π] \ {-π/2,π/2} -> R */
+    /** 
+     * tan: [-π,π] \ {-π/2,π/2} → R
+     *
+     * @param x x
+     *
+     * @return the tangent
+     */
     public final static double tan(final double x) {
         return sin(x) / cos(x);
     }
 
-    /** asin: [-1,1] -> [-π/2,π/2] */
+    /** 
+     * asin: [-1,1] → [-π/2,π/2] 
+     * 
+     * @param x x
+     *
+     * @return the arc sine
+     */
     public final static double asin(final double x) {
         return x * (Math.abs(x) * (Math.abs(x) * FastMath._asin_a + FastMath._asin_b) + FastMath._asin_c)
                 + Math.signum(x) * (FastMath._asin_d - Math.sqrt(1 - x * x));
     }
 
-    /** acos: [-1,1] -> [0,π] */
+    /** 
+     * acos: [-1,1] → [0,π] 
+     *
+     * @param x x
+     *
+     * @return the arc cosine
+     */
     public final static double acos(final double x) {
         return MathUtils.HALF_PI - asin(x);
     }
 
-    /** atan: (-∞,∞) -> (-π/2,π/2) */
+    /** 
+     * atan: (-‚àû,‚àû) → (-π/2,π/2) 
+     * 
+     * @param x x
+     * 
+     * @return the arc tangent
+     */
     public final static double atan(final double x) {
         return Math.abs(x) < 1 ? x / (1 + FastMath._atan_a * x * x) : Math.signum(x) * MathUtils.HALF_PI - x
                 / (x * x + FastMath._atan_a);
     }
 
-    /** inverseSqrt: (0,‚àû) -> (0,‚àû) **/
+    /** 
+     * inverseSqrt: (0,‚àû) → (0,‚àû) 
+     * 
+     * @param x x
+     * 
+     * @return the inverse square root
+     */
     public final static double inverseSqrt(double x) {
         final double xhalves = 0.5d * x;
         x = Double.longBitsToDouble(0x5FE6EB50C7B537AAL - (Double.doubleToRawLongBits(x) >> 1));
diff --git a/ardor3d-math/src/main/java/com/ardor3d/math/Line3.java b/ardor3d-math/src/main/java/com/ardor3d/math/Line3.java
index 7d05103..a2c7b54 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/Line3.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/Line3.java
@@ -41,7 +41,7 @@ public class Line3 extends Line3Base implements ReadOnlyLine3, Poolable {
     /**
      * Constructs a new line using the supplied source line
      * 
-     * @param source
+     * @param source the source line
      */
     public Line3(final ReadOnlyLine3 source) {
         super(source.getOrigin(), source.getDirection());
@@ -50,7 +50,7 @@ public class Line3 extends Line3Base implements ReadOnlyLine3, Poolable {
     /**
      * Copies the values of the given source line into this line.
      * 
-     * @param source
+     * @param source the source line
      * @return this line for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -62,7 +62,7 @@ public class Line3 extends Line3Base implements ReadOnlyLine3, Poolable {
     }
 
     /**
-     * @param point
+     * @param point the point
      * @param store
      *            if not null, the closest point is stored in this param
      * @return the squared distance from this line to the given point.
diff --git a/ardor3d-math/src/main/java/com/ardor3d/math/Line3Base.java b/ardor3d-math/src/main/java/com/ardor3d/math/Line3Base.java
index 9b9e6d5..f6548b5 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/Line3Base.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/Line3Base.java
@@ -48,7 +48,7 @@ public abstract class Line3Base implements Savable, Externalizable {
     /**
      * Sets the line's origin point to the values of the given vector.
      *
-     * @param origin
+     * @param origin the origin
      * @throws NullPointerException
      *             if normal is null.
      */
@@ -59,7 +59,7 @@ public abstract class Line3Base implements Savable, Externalizable {
     /**
      * Sets the line's direction to the values of the given vector.
      *
-     * @param direction
+     * @param direction the direction
      * @throws NullPointerException
      *             if direction is null.
      */
@@ -106,8 +106,8 @@ public abstract class Line3Base implements Savable, Externalizable {
      *
      * @param in
      *            ObjectInput
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @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 {
@@ -120,7 +120,7 @@ public abstract class Line3Base implements Savable, Externalizable {
      *
      * @param out
      *            ObjectOutput
-     * @throws IOException
+     * @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/LineSegment3.java b/ardor3d-math/src/main/java/com/ardor3d/math/LineSegment3.java
index 30290b3..8e55a44 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/LineSegment3.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/LineSegment3.java
@@ -54,10 +54,10 @@ public class LineSegment3 extends Line3Base implements ReadOnlyLineSegment3, Poo
     /**
      * Constructs a new segment segment using the supplied origin point, unit length direction vector and extent
      *
-     * @param origin
-     * @param direction
+     * @param origin the origin
+     * @param direction the direction vector
      *            - unit length
-     * @param extent
+     * @param extent the extent
      */
     public LineSegment3(final ReadOnlyVector3 origin, final ReadOnlyVector3 direction, final double extent) {
         super(origin, direction);
@@ -67,8 +67,8 @@ public class LineSegment3 extends Line3Base implements ReadOnlyLineSegment3, Poo
     /**
      * Constructs a new segment segment using the supplied start and end points
      *
-     * @param start
-     * @param end
+     * @param start the start point
+     * @param end the end point
      */
     public LineSegment3(final ReadOnlyVector3 start, final ReadOnlyVector3 end) {
         this();
@@ -81,7 +81,7 @@ public class LineSegment3 extends Line3Base implements ReadOnlyLineSegment3, Poo
     /**
      * Copies the values of the given source segment into this segment.
      *
-     * @param source
+     * @param source the line segment to copy from
      * @return this segment for chaining
      * @throws NullPointerException
      *             if source is null.
@@ -103,7 +103,7 @@ public class LineSegment3 extends Line3Base implements ReadOnlyLineSegment3, Poo
     /**
      * Sets the segment's extent to the provided value.
      *
-     * @param extent
+     * @param extent the extent
      */
     public void setExtent(final double extent) {
         _extent = extent;
@@ -130,7 +130,7 @@ public class LineSegment3 extends Line3Base implements ReadOnlyLineSegment3, Poo
     }
 
     /**
-     * @param point
+     * @param point the point
      * @param store
      *            if not null, the closest point is stored in this param
      * @return the squared distance from this segment to the given point.
@@ -172,8 +172,9 @@ public class LineSegment3 extends Line3Base implements ReadOnlyLineSegment3, Poo
 
     /**
      *
-     * @param position
-     *            a random position lying somewhere on this line segment.
+     * @param store the object to store the result if not null
+     *
+     * @return a random position lying somewhere on this line segment.
      */
     public Vector3 random(final Vector3 store) {
         Vector3 result = store;
@@ -275,8 +276,8 @@ public class LineSegment3 extends Line3Base implements ReadOnlyLineSegment3, Poo
      *
      * @param in
      *            ObjectInput
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @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 {
@@ -289,7 +290,7 @@ public class LineSegment3 extends Line3Base implements ReadOnlyLineSegment3, Poo
      *
      * @param out
      *            ObjectOutput
-     * @throws IOException
+     * @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/MathUtils.java b/ardor3d-math/src/main/java/com/ardor3d/math/MathUtils.java
index 4f55718..0eda32e 100644
--- a/ardor3d-math/src/main/java/com/ardor3d/math/MathUtils.java
+++ b/ardor3d-math/src/main/java/com/ardor3d/math/MathUtils.java
@@ -63,6 +63,10 @@ public class MathUtils {
      * functions give due to rounding in the angle reduction but it will be very very close.
      * 
      * note: code from wiki posting on java.net by jeffpk
+     *
+     * @param radians the angle in radians
+     *
+     * @return the reduced sine angle
      */
     private static double reduceSinAngle(double radians) {
         radians %= MathUtils.TWO_PI; // put us in -2PI to +2PI space
@@ -140,6 +144,7 @@ public class MathUtils {
      *            (Radius, Azimuth, Polar)
      * @param store
      *            the vector to store the result in for return. If null, a new vector object is created and returned.
+     * @return the Cartesian coordinates
      */
     public static Vector3 sphericalToCartesian(final ReadOnlyVector3 sphereCoords, final Vector3 store) {
         final double a = sphereCoords.getX() * cos(sphereCoords.getZ());
@@ -158,9 +163,10 @@ public class MathUtils {
      * 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
+     * @param cartCoords the Cartesian coordinates (using positive Y as up)
      * @param store
      *            the vector to store the result in for return. If null, a new vector object is created and returned.
+     * @return the spherical coordinates
      */
     public static Vector3 cartesianToSpherical(final ReadOnlyVector3 cartCoords, final Vector3 store) {
         final double cartX = Math.abs(cartCoords.getX()) <= MathUtils.EPSILON ? MathUtils.EPSILON : cartCoords.getX();
@@ -186,6 +192,7 @@ public class MathUtils {
      *            (Radius, Azimuth, Polar)
      * @param store
      *            the vector to store the result in for return. If null, a new vector object is created and returned.
+     * @return the Cartesian coordinates
      */
     public static Vector3 sphericalToCartesianZ(final ReadOnlyVector3 sphereCoords, final Vector3 store) {
         final double a = sphereCoords.getX() * cos(sphereCoords.getZ());
@@ -204,9 +211,10 @@ public class MathUtils {
      * 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
+     * @param cartCoords the Cartesian coordinates (using positive Z as up)
      * @param store
      *            the vector to store the result in for return. If null, a new vector object is created and returned.
+     * @return the spherical coordinates
      */
     public static Vector3 cartesianZToSpherical(final ReadOnlyVector3 cartCoords, final Vector3 store) {
         final double cartX = Math.abs(cartCoords.getX()) <= MathUtils.EPSILON ? MathUtils.EPSILON : cartCoords.getX();
@@ -241,6 +249,7 @@ public class MathUtils {
 
     /**
      * @param number
+                 The number to test
      * @return the closest power of two to the given number.
      */
     public static int nearestPowerOfTwo(final int number) {
@@ -248,8 +257,8 @@ public class MathUtils {
     }
 
     /**
-     * @param value
-     * @param base
+     * @param value the value
+     * @param base the base
      * @return the logarithm of value with given base, calculated as log(value)/log(base) such that pow(base,
      *         return)==value
      */
@@ -260,7 +269,7 @@ public class MathUtils {
     /**
      * Sets the seed to use for "random" operations. The default is the current system milliseconds.
      * 
-     * @param seed
+     * @param seed the seed
      */
     public static void setRandomSeed(final long seed) {
         MathUtils.rand.setSeed(seed);
@@ -294,6 +303,9 @@ public class MathUtils {
     /**
      * Returns a random int between min and max.
      * 
+     * @param min the minimum value
+     * @param max the maximum value
+     * 
      * @return A random int between <tt>min</tt> (inclusive) to <tt>max</tt> (inclusive).
      */
     public static int nextRandomInt(final int min, final int max) {
@@ -302,10 +314,10 @@ public class MathUtils {
 
     /**
      * 
-     * @param percent
-     * @param startValue
-     * @param endValue
-     * @return
+     * @param percent the percent value
+     * @param startValue the start value
+     * @param endValue the end value
+     * @return the lerp
      */
     public static float lerp(final float percent, final float startValue, final float endValue) {
         if (startValue == endValue) {
@@ -316,10 +328,10 @@ public class MathUtils {
 
     /**
      * 
-     * @param percent
-     * @param startValue
-     * @param endValue
-     * @return
+     * @param percent the percent value
+     * @param startValue the start value
+     * @param endValue the end value
+     * @return the lerp
      */
     public static double lerp(final double percent, final double startValue, final double endValue) {
         if (startValue == endValue) {
@@ -384,13 +396,13 @@ public class MathUtils {
 
     /**
      * 
-     * @param left
-     * @param right
-     * @param bottom
-     * @param top
-     * @param nearZ
-     * @param farZ
-     * @param store
+     * @param left the left abscissa
+     * @param right the right abscissa
+     * @param bottom the bottom ordinate
+     * @param top the top ordinate
+     * @param nearZ the near applicate
+     * @param farZ the far applicate
+     * @param store the object to store the matrix of the frustum (similar to glFrustum)
      */
     public static void matrixFrustum(final double left, final double right, final double bottom, final double top,
             final double nearZ, final double farZ, final Matrix4 store) {
@@ -406,13 +418,13 @@ public class MathUtils {
 
     /**
      * 
-     * @param left
-     * @param right
-     * @param bottom
-     * @param top
-     * @param nearZ
-     * @param farZ
-     * @param store
+     * @param left the left abscissa
+     * @param right the right abscissa
+     * @param bottom the bottom ordinate
+     * @param top the top ordinate
+     * @param nearZ the near applicate
+     * @param farZ the far applicate
+     * @param store the object to store the matrix in orthogonal projection
      */
     public static void matrixOrtho(final double left, final double right, final double bottom, final double top,
             final double nearZ, final double farZ, final Matrix4 store) {
@@ -423,11 +435,11 @@ public class MathUtils {
 
     /**
      * 
-     * @param fovY
-     * @param aspect
-     * @param zNear
-     * @param zFar
-     * @param store
+     * @param fovY the fov Y
+     * @param aspect the aspect
+     * @param zNear the near applicate
+     * @param zFar the far applicate
+     * @param store the object to store the matrix in perspective projection (similar to gluPerspective)
      */
     public static void matrixPerspective(final double fovY, final double aspect, final double zNear, final double zFar,
             final Matrix4 store) {
@@ -439,10 +451,10 @@ public class MathUtils {
 
     /**
      * 
-     * @param position
-     * @param target
-     * @param up
-     * @param store
+     * @param position the position
+     * @param target the target
+     * @param worldUp the up vector
+     * @param store the object to store the result, the model view matrix (similar to gluLookAt)
      */
     public static void matrixLookAt(final ReadOnlyVector3 position, final ReadOnlyVector3 target,
             final ReadOnlyVector3 worldUp, final Matrix4 store) {
@@ -467,10 +479,10 @@ public class MathUtils {
 
     /**
      * 
-     * @param position
-     * @param target
-     * @param up
-     * @param store
+     * @param position the position
+     * @param target the target
+     * @param worldUp the up vector
+     * @param store the object to store the result, the model view matrix (similar to gluLookAt)
      */
     public static void matrixLookAt(final ReadOnlyVector3 position, final ReadOnlyVector3 target,
             final ReadOnlyVector3 worldUp, final Matrix3 store) {