add some missing javadoc (13 files in com.jme3.math)

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

@@ -34,13 +34,48 @@ package com.jme3.math;
 import com.jme3.collision.Collidable;
 import com.jme3.collision.CollisionResults;
 
+/**
+ * A Collidable with a triangular shape.
+ */
 public abstract class AbstractTriangle implements Collidable {
 
+    /**
+     * Determine the location of the first vertex.
+     *
+     * @return a location vector
+     */
     public abstract Vector3f get1();
+
+    /**
+     * Determine the location of the 2nd vertex.
+     *
+     * @return a location vector
+     */
     public abstract Vector3f get2();
+
+    /**
+     * Determine the location of the 3rd vertex.
+     *
+     * @return a location vector
+     */
     public abstract Vector3f get3();
+
+    /**
+     * Alter all 3 vertex locations.
+     *
+     * @param v1 the location for the first vertex
+     * @param v2 the location for the 2nd vertex
+     * @param v3 the location for the 3rd vertex
+     */
     public abstract void set(Vector3f v1, Vector3f v2, Vector3f v3);
 
+    /**
+     * Generate collision results for this triangle with another Collidable.
+     *
+     * @param other the other Collidable
+     * @param results storage for collision results
+     * @return the number of collisions found
+     */
     @Override
     public int collideWith(Collidable other, CollisionResults results){
         return other.collideWith(this, results);

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

@@ -1,9 +1,10 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine All rights reserved.
+ * Copyright (c) 2009-2020 jMonkeyEngine
+ * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
- *  *
+ *
  * * Redistributions of source code must retain the above copyright notice,
  * this list of conditions and the following disclaimer.
  *
@@ -387,6 +388,11 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable
         return "Color[" + r + ", " + g + ", " + b + ", " + a + "]";
     }
 
+    /**
+     * Create a copy of this color.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public ColorRGBA clone() {
         try {
@@ -462,6 +468,13 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable
         return hash;
     }
     
+    /**
+     * Serialize this color to the specified exporter, for example when
+     * saving to a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the exporter
+     */
     @Override
     public void write(JmeExporter e) throws IOException {
         OutputCapsule capsule = e.getCapsule(this);
@@ -471,6 +484,13 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable
         capsule.write(a, "a", 0);
     }
 
+    /**
+     * De-serialize this color from the specified importer, for example when
+     * loading from a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the importer
+     */
     @Override
     public void read(JmeImporter e) throws IOException {
         InputCapsule capsule = e.getCapsule(this);

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

@@ -7,6 +7,9 @@ package com.jme3.math;
 public class Easing {
 
 
+    /**
+     * a function that always returns 0
+     */
     public static EaseFunction constant = new EaseFunction() {
         @Override
         public float apply(float value) {
@@ -23,6 +26,9 @@ public class Easing {
         }
     };
 
+    /**
+     * a function that returns the square of its input
+     */
     public static EaseFunction inQuad = new EaseFunction() {
         @Override
         public float apply(float value) {
@@ -30,6 +36,9 @@ public class Easing {
         }
     };
 
+    /**
+     * a function that returns the cube of its input
+     */
     public static EaseFunction inCubic = new EaseFunction() {
         @Override
         public float apply(float value) {
@@ -37,6 +46,9 @@ public class Easing {
         }
     };
 
+    /**
+     * a function that returns the 4th power of its input
+     */
     public static EaseFunction inQuart = new EaseFunction() {
         @Override
         public float apply(float value) {
@@ -44,6 +56,9 @@ public class Easing {
         }
     };
 
+    /**
+     * a function that returns the 5th power of its input
+     */
     public static EaseFunction inQuint = new EaseFunction() {
         @Override
         public float apply(float value) {
@@ -62,6 +77,9 @@ public class Easing {
         }
     };
 
+    /**
+     * a function that starts quickly, then bounces several times
+     */
     public static EaseFunction outBounce = new EaseFunction() {
         @Override
         public float apply(float value) {
@@ -81,6 +99,9 @@ public class Easing {
      * In Elastic and bounce
      */
     public static EaseFunction inElastic = new Invert(outElastic);
+    /**
+     * a function containing a series of increasing bounces
+     */
     public static EaseFunction inBounce = new Invert(outBounce);
 
     /**
@@ -128,6 +149,12 @@ public class Easing {
         private EaseFunction in;
         private EaseFunction out;
 
+        /**
+         * Instantiate a function that blends 2 pre-existing functions.
+         *
+         * @param in the function to use at value=0
+         * @param out the function to use at value=1
+         */
         public InOut(EaseFunction in, EaseFunction out) {
             this.in = in;
             this.out = out;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2020 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -34,6 +34,9 @@ package com.jme3.math;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
+/**
+ * A calculator for the eigenvectors and eigenvalues of a Matrix3f. 
+ */
 public class Eigen3f implements java.io.Serializable {
 
     static final long serialVersionUID = 1;
@@ -48,14 +51,27 @@ public class Eigen3f implements java.io.Serializable {
     static final double ROOT_THREE_DOUBLE = Math.sqrt(3.0);
 
     
+    /**
+     * Instantiate an empty calculator.
+     */
     public Eigen3f() {
 
     }
     
+    /**
+     * Calculate the eigenvalues and eigenvectors of the specified matrix.
+     *
+     * @param data the input Matrix3f
+     */
     public Eigen3f(Matrix3f data) {
         calculateEigen(data);
     }
 
+    /**
+     * Calculate the eigenvalues and eigenvectors of the specified matrix.
+     *
+     * @param data the input Matrix3f
+     */
     public void calculateEigen(Matrix3f data) {
         // prep work...
         eigenVectors[0] = new Vector3f();
@@ -378,6 +394,11 @@ public class Eigen3f implements java.io.Serializable {
         }
     }
 
+    /**
+     * Test the Eigen3f class.
+     * 
+     * @param args ignored
+     */
     public static void main(String[] args) {
         Matrix3f mat = new Matrix3f(2, 1, 1, 1, 2, 1, 1, 1, 2);
         Eigen3f eigenSystem = new Eigen3f(mat);
@@ -402,18 +423,40 @@ public class Eigen3f implements java.io.Serializable {
         // -0.816485 0.004284 0.577350
     }
 
+    /**
+     * Read the indexed eigenvalue.
+     * 
+     * @param i which value to read (0, 1, or 2)
+     * @return the previously calculated eigenvalue
+     */
     public float getEigenValue(int i) {
         return eigenValues[i];
     }
 
+    /**
+     * Access the indexed eigenvector.
+     * 
+     * @param i which vector to read (0, 1, or 2)
+     * @return the pre-existing eigenvector
+     */
     public Vector3f getEigenVector(int i) {
         return eigenVectors[i];
     }
 
+    /**
+     * Access the array of eigenvalues.
+     * 
+     * @return the pre-existing array
+     */
     public float[] getEigenValues() {
         return eigenValues;
     }
 
+    /**
+     * Access the array of eigenvectors.
+     * 
+     * @return the pre-existing array of vectors
+     */
     public Vector3f[] getEigenVectors() {
         return eigenVectors;
     }

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

@@ -55,6 +55,9 @@ final public class FastMath {
      * A "close to zero" float epsilon value for use
      */
     public static final float ZERO_TOLERANCE = 0.0001f;
+    /**
+     * The value 1/3, as a float.
+     */
     public static final float ONE_THIRD = 1f / 3f;
     /**
      * The value PI as a float. (180 degrees)
@@ -612,6 +615,12 @@ final public class FastMath {
         return (float) (1.0f / Math.sqrt(fValue));
     }
 
+    /**
+     * Quickly estimate 1/sqrt(fValue).
+     *
+     * @param x the input value (≥0)
+     * @return an approximate value for 1/sqrt(x)
+     */
     public static float fastInvSqrt(float x) {
         float xhalf = 0.5f * x;
         int i = Float.floatToIntBits(x); // get bits for floating value
@@ -830,6 +839,12 @@ final public class FastMath {
         return (int) (nextRandomFloat() * (max - min + 1)) + min;
     }
 
+    /**
+     * Choose a pseudo-random, uniformly-distributed integer value from
+     * the shared generator.
+     *
+     * @return the next integer value
+     */
     public static int nextRandomInt() {
         return rand.nextInt();
     }
@@ -1025,6 +1040,14 @@ final public class FastMath {
         }
     }
 
+    /**
+     * Convert a single-precision (32-bit) floating-point value
+     * to half precision.
+     *
+     * @param flt the input value (not a NaN)
+     * @return a near-equivalent value in half precision
+     * @throws UnsupportedOperationException if flt is a NaN
+     */
     public static short convertFloatToHalf(float flt) {
         if (Float.isNaN(flt)) {
             throw new UnsupportedOperationException("NaN to half conversion not supported!");

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

@@ -108,6 +108,12 @@ public class Line implements Savable, Cloneable, java.io.Serializable {
         this.direction = direction;
     }
 
+    /**
+     * Calculate the squared distance from this line to the specified point.
+     *
+     * @param point location vector of the input point (not null, unaffected)
+     * @return the square of the minimum distance (≥0)
+     */
     public float distanceSquared(Vector3f point) {
         TempVars vars = TempVars.get();
 
@@ -123,10 +129,21 @@ public class Line implements Savable, Cloneable, java.io.Serializable {
         return len;
     }
 
+    /**
+     * Calculate the distance from this line to the specified point.
+     *
+     * @param point location vector of the input point (not null, unaffected)
+     * @return the minimum distance (≥0)
+     */
     public float distance(Vector3f point) {
         return FastMath.sqrt(distanceSquared(point));
     }
 
+    /**
+     * Fit this line to the specified points.
+     *
+     * @param points a buffer containing location vectors, or null
+     */
     public void orthogonalLineFit(FloatBuffer points) {
         if (points == null) {
             return;
@@ -213,6 +230,13 @@ public class Line implements Savable, Cloneable, java.io.Serializable {
         return result;
     }
 
+    /**
+     * Serialize this line to the specified exporter, for example when
+     * saving to a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the exporter
+     */
     @Override
     public void write(JmeExporter e) throws IOException {
         OutputCapsule capsule = e.getCapsule(this);
@@ -220,6 +244,13 @@ public class Line implements Savable, Cloneable, java.io.Serializable {
         capsule.write(direction, "direction", Vector3f.ZERO);
     }
 
+    /**
+     * De-serialize this line from the specified importer, for example when
+     * loading from a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the importer
+     */
     @Override
     public void read(JmeImporter e) throws IOException {
         InputCapsule capsule = e.getCapsule(this);
@@ -227,6 +258,11 @@ public class Line implements Savable, Cloneable, java.io.Serializable {
         direction = (Vector3f) capsule.readSavable("direction", Vector3f.ZERO.clone());
     }
 
+    /**
+     * Create a copy of this line.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Line clone() {
         try {

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

@@ -57,11 +57,19 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
     private Vector3f direction;
     private float extent;
 
+    /**
+     * Instantiate a zero-length segment at the origin.
+     */
     public LineSegment() {
         origin = new Vector3f();
         direction = new Vector3f();
     }
 
+    /**
+     * Instantiate a copy of the specified segment.
+     *
+     * @param ls the LineSegment to copy (not null, unaffected)
+     */
     public LineSegment(LineSegment ls) {
         this.origin = new Vector3f(ls.getOrigin());
         this.direction = new Vector3f(ls.getDirection());
@@ -89,24 +97,54 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
         direction.normalizeLocal();
     }
 
+    /**
+     * Copy the specified segment to this one.
+     *
+     * @param ls the LineSegment to copy (not null, unaffected)
+     */
     public void set(LineSegment ls) {
         this.origin = new Vector3f(ls.getOrigin());
         this.direction = new Vector3f(ls.getDirection());
         this.extent = ls.getExtent();
     }
 
+    /**
+     * Calculate the distance between this segment and the specified point.
+     *
+     * @param point a location vector (not null, unaffected)
+     * @return the minimum distance (≥0)
+     */
     public float distance(Vector3f point) {
         return FastMath.sqrt(distanceSquared(point));
     }
 
+    /**
+     * Calculate the distance between this segment and another.
+     *
+     * @param ls the other LineSegment (not null, unaffected)
+     * @return the minimum distance (≥0)
+     */
     public float distance(LineSegment ls) {
         return FastMath.sqrt(distanceSquared(ls));
     }
 
+    /**
+     * Calculate the distance between this segment and the specified Ray.
+     *
+     * @param r the input Ray (not null, unaffected)
+     * @return the minimum distance (≥0)
+     */
     public float distance(Ray r) {
         return FastMath.sqrt(distanceSquared(r));
     }
 
+    /**
+     * Calculate the squared distance between this segment and the specified
+     * point.
+     *
+     * @param point location vector of the input point (not null, unaffected)
+     * @return the square of the minimum distance (≥0)
+     */
     public float distanceSquared(Vector3f point) {
         TempVars vars = TempVars.get();
         Vector3f compVec1 = vars.vect1;
@@ -131,6 +169,12 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
         return len;
     }
 
+    /**
+     * Calculate the squared distance between this segment and another.
+     *
+     * @param test the other LineSegment (not null, unaffected)
+     * @return the square of the minimum distance (≥0)
+     */
     public float distanceSquared(LineSegment test) {
         TempVars vars = TempVars.get();
         Vector3f compVec1 = vars.vect1;
@@ -416,6 +460,13 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
         return FastMath.abs(squareDistance);
     }
 
+    /**
+     * Calculate the squared distance between this segment and the specified
+     * Ray.
+     *
+     * @param r the input Ray (not null, unaffected)
+     * @return the square of the minimum distance (≥0)
+     */
     public float distanceSquared(Ray r) {
         Vector3f kDiff = r.getOrigin().subtract(origin);
         float fA01 = -r.getDirection().dot(direction);
@@ -535,31 +586,66 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
         return FastMath.abs(fSqrDist);
     }
 
+    /**
+     * Access the direction of this segment.
+     *
+     * @return the pre-existing direction vector
+     */
     public Vector3f getDirection() {
         return direction;
     }
 
+    /**
+     * Alter the direction of this segment.
+     *
+     * @param direction the desired direction vector (alias created!)
+     */
     public void setDirection(Vector3f direction) {
         this.direction = direction;
     }
 
+    /**
+     * Read the extent of this segment.
+     *
+     * @return the extent
+     */
     public float getExtent() {
         return extent;
     }
 
+    /**
+     * Alter the extent of this segment.
+     *
+     * @param extent the desired extent
+     */
     public void setExtent(float extent) {
         this.extent = extent;
     }
 
+    /**
+     * Access the origin of this segment.
+     *
+     * @return the pre-existing location vector
+     */
     public Vector3f getOrigin() {
         return origin;
     }
 
+    /**
+     * Alter the origin of this segment.
+     *
+     * @param origin the desired location vector (alias created!)
+     */
     public void setOrigin(Vector3f origin) {
         this.origin = origin;
     }
 
-    // P+e*D
+    /**
+     * Determine the location of this segment's positive end.
+     * 
+     * @param store storage for the result (modified if not null)
+     * @return a location vector (either store or a new vector)
+     */
     public Vector3f getPositiveEnd(Vector3f store) {
         if (store == null) {
             store = new Vector3f();
@@ -567,7 +653,12 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
         return origin.add((direction.mult(extent, store)), store);
     }
 
-    // P-e*D
+    /**
+     * Determine the location of this segment's negative end.
+     * 
+     * @param store storage for the result (modified if not null)
+     * @return a location vector (either store or a new vector)
+     */
     public Vector3f getNegativeEnd(Vector3f store) {
         if (store == null) {
             store = new Vector3f();
@@ -575,6 +666,13 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
         return origin.subtract((direction.mult(extent, store)), store);
     }
 
+    /**
+     * Serialize this segment to the specified exporter, for example when
+     * saving to a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the exporter
+     */
     @Override
     public void write(JmeExporter e) throws IOException {
         OutputCapsule capsule = e.getCapsule(this);
@@ -583,6 +681,13 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
         capsule.write(extent, "extent", 0);
     }
 
+    /**
+     * De-serialize this segment from the specified importer, for example
+     * when loading from a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the importer
+     */
     @Override
     public void read(JmeImporter e) throws IOException {
         InputCapsule capsule = e.getCapsule(this);
@@ -591,6 +696,11 @@ public class LineSegment implements Cloneable, Savable, java.io.Serializable {
         extent = capsule.readFloat("extent", 0);
     }
 
+    /**
+     * Create a copy of this segment.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public LineSegment clone() {
         try {

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

@@ -8,6 +8,13 @@ import com.jme3.util.TempVars;
  */
 public class MathUtils {
 
+    /**
+     * Calculate the natural logarithm of a unit quaternion.
+     *
+     * @param q the input Quaternion (not null, normalized, unaffected)
+     * @param store storage for the result (not null, modified)
+     * @return the logarithm (store)
+     */
     public static Quaternion log(Quaternion q, Quaternion store) {
         float a = FastMath.acos(q.w);
         float sina = FastMath.sin(a);
@@ -25,6 +32,13 @@ public class MathUtils {
         return store;
     }
 
+    /**
+     * Calculate the exponential of a pure quaternion.
+     *
+     * @param q the input Quaternion (not null, w=0, unaffected)
+     * @param store storage for the result (not null, modified)
+     * @return the exponential (store)
+     */
     public static Quaternion exp(Quaternion q, Quaternion store) {
 
         float len = FastMath.sqrt(q.x * q.x + q.y * q.y + q.z * q.z);
@@ -66,6 +80,15 @@ public class MathUtils {
         return store;
     }
 
+    /**
+     * Interpolate between 2 quaternions using Slerp.
+     *
+     * @param q1 the desired value for t=0
+     * @param q2 the desired value for t=1
+     * @param t the fractional parameter (≥0, ≤1)
+     * @param store storage for the result (not null, modified)
+     * @return the interpolated Quaternion (store)
+     */
     public static Quaternion slerp(Quaternion q1, Quaternion q2, float t, Quaternion store) {
 
         float dot = (q1.x * q2.x) + (q1.y * q2.y) + (q1.z * q2.z)

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

@@ -52,10 +52,49 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     static final long serialVersionUID = 1;
 
     private static final Logger logger = Logger.getLogger(Matrix3f.class.getName());
-    protected float m00, m01, m02;
+    /**
-    protected float m10, m11, m12;
+     * the element in row 0, column 0
-    protected float m20, m21, m22;
+     */
+    protected float m00;
+    /**
+     * the element in row 0, column 1
+     */
+    protected float m01;
+    /**
+     * the element in row 0, column 2
+     */
+    protected float m02;
+    /**
+     * the element in row 1, column 0
+     */
+    protected float m10;
+    /**
+     * the element in row 1, column 1
+     */
+    protected float m11;
+    /**
+     * the element in row 1, column 2
+     */
+    protected float m12;
+    /**
+     * the element in row 2, column 0
+     */
+    protected float m20;
+    /**
+     * the element in row 2, column 1
+     */
+    protected float m21;
+    /**
+     * the element in row 2, column 2
+     */
+    protected float m22;
+    /**
+     * an instance of the zero matrix (all elements = 0)
+     */
     public static final Matrix3f ZERO = new Matrix3f(0, 0, 0, 0, 0, 0, 0, 0, 0);
+    /**
+     * an instance of the identity matrix (diagonals = 1, other elements = 0)
+     */
     public static final Matrix3f IDENTITY = new Matrix3f();
 
     /**
@@ -444,6 +483,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
         return fb;
     }
 
+    /**
+     * Copy all elements of this matrix to a float array.
+     *
+     * @param f   the array to fill (not null, length >= 9)
+     * @param columnMajor
+     *            true → column-major order, false → row-major order
+     */
     public void fillFloatArray(float[] f, boolean columnMajor) {
         if (columnMajor) {
             f[0] = m00;
@@ -1229,6 +1275,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
         return true;
     }
 
+    /**
+     * Serialize this matrix to the specified exporter, for example when
+     * saving to a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the exporter
+     */
     @Override
     public void write(JmeExporter e) throws IOException {
         OutputCapsule cap = e.getCapsule(this);
@@ -1243,6 +1296,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
         cap.write(m22, "m22", 1);
     }
 
+    /**
+     * De-serialize this matrix from the specified importer, for example
+     * when loading from a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the importer
+     */
     @Override
     public void read(JmeImporter e) throws IOException {
         InputCapsule cap = e.getCapsule(this);
@@ -1402,6 +1462,11 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
         return true;
     }
 
+    /**
+     * Create a copy of this matrix.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Matrix3f clone() {
         try {

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

@@ -59,11 +59,77 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     static final long serialVersionUID = 1;
 
     private static final Logger logger = Logger.getLogger(Matrix4f.class.getName());
-    public float m00, m01, m02, m03;
+    /**
-    public float m10, m11, m12, m13;
+     * the element in row 0, column 0
-    public float m20, m21, m22, m23;
+     */
-    public float m30, m31, m32, m33;
+    public float m00;
+    /**
+     * the element in row 0, column 1
+     */
+    public float m01;
+    /**
+     * the element in row 0, column 2
+     */
+    public float m02;
+    /**
+     * the element in row 0, column 3
+     */
+    public float m03;
+    /**
+     * the element in row 1, column 0
+     */
+    public float m10;
+    /**
+     * the element in row 1, column 1
+     */
+    public float m11;
+    /**
+     * the element in row 1, column 2
+     */
+    public float m12;
+    /**
+     * the element in row 1, column 3
+     */
+    public float m13;
+    /**
+     * the element in row 2, column 0
+     */
+    public float m20;
+    /**
+     * the element in row 2, column 1
+     */
+    public float m21;
+    /**
+     * the element in row 2, column 2
+     */
+    public float m22;
+    /**
+     * the element in row 2, column 3
+     */
+    public float m23;
+    /**
+     * the element in row 3, column 0
+     */
+    public float m30;
+    /**
+     * the element in row 3, column 1
+     */
+    public float m31;
+    /**
+     * the element in row 0, column 2
+     */
+    public float m32;
+    /**
+     * the element in row 3, column 3
+     */
+    public float m33;
+    /**
+     * an instance of the zero matrix (all elements = 0)
+     */
     public static final Matrix4f ZERO = new Matrix4f(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
+    /**
+     * an instance of the identity matrix (diagonals = 1, other elements = 0)
+     */
     public static final Matrix4f IDENTITY = new Matrix4f();
 
     /**
@@ -640,6 +706,11 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         }
     }
 
+    /**
+     * Generate the transpose of this matrix.
+     *
+     * @return a new Matrix4f with its rows and columns transposed
+     */
     public Matrix4f transpose() {
         float[] tmp = new float[16];
         get(tmp, true);
@@ -754,6 +825,13 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         return fb;
     }
 
+    /**
+     * Copy the elements of this matrix to a float array.
+     *
+     * @param f   the array to fill (not null, length >= 16)
+     * @param columnMajor
+     *            true → column-major order, false → row-major order
+     */
     public void fillFloatArray(float[] f, boolean columnMajor) {
         if (columnMajor) {
             f[0] = m00;
@@ -975,6 +1053,12 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         m33 *= scalar;
     }
 
+    /**
+     * Multiply this matrix by a scalar.
+     *
+     * @param scalar the scaling factor
+     * @return a new Matrix4f with every element scaled
+     */
     public Matrix4f mult(float scalar) {
         Matrix4f out = new Matrix4f();
         out.set(this);
@@ -982,6 +1066,13 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         return out;
     }
 
+    /**
+     * Multiply this matrix by a scalar.
+     *
+     * @param scalar the scaling factor
+     * @param store storage for the result (not null, modified)
+     * @return a scaled matrix (store)
+     */
     public Matrix4f mult(float scalar, Matrix4f store) {
         store.set(this);
         store.multLocal(scalar);
@@ -1544,6 +1635,14 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         return adjoint(null);
     }
 
+    /**
+     * Set this matrix to the specified 3-D coordinate transform.  The
+     * effective sequence of operations is: scale, then rotate, then translate.
+     *
+     * @param position the desired translation (not null, unaffected)
+     * @param scale the desired scaling (not null, unaffected)
+     * @param rotMat the desired rotation (not null, unaffected)
+     */
     public void setTransform(Vector3f position, Vector3f scale, Matrix3f rotMat) {
         // Ordering:
         //    1. Scale
@@ -1651,6 +1750,12 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         return this;
     }
 
+    /**
+     * Calculate the sum of this matrix and another.
+     *
+     * @param mat the Matrix4f to add (not null, unaffected)
+     * @return a new Matrix4f
+     */
     public Matrix4f add(Matrix4f mat) {
         Matrix4f result = new Matrix4f();
         result.m00 = this.m00 + mat.m00;
@@ -1697,29 +1802,67 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         m33 += mat.m33;
     }
 
+    /**
+     * Interpret this matrix as a 3-D coordinate transform and determine its
+     * translation component.
+     *
+     * @return a new translation vector
+     */
     public Vector3f toTranslationVector() {
         return new Vector3f(m03, m13, m23);
     }
 
+    /**
+     * Interpret this matrix as a 3-D coordinate transform and determine its
+     * translation component.
+     *
+     * @param vector storage for the result (not null, modified)
+     * @return the translation vector (vector)
+     */
     public Vector3f toTranslationVector(Vector3f vector) {
         return vector.set(m03, m13, m23);
     }
 
+    /**
+     * Interpret this matrix as a 3-D coordinate transform and determine its
+     * rotation component.
+     *
+     * @return a new rotation Quaternion
+     */
     public Quaternion toRotationQuat() {
         Quaternion quat = new Quaternion();
         quat.fromRotationMatrix(toRotationMatrix());
         return quat;
     }
 
+    /**
+     * Interpret this matrix as a 3-D coordinate transform and determine its
+     * rotation component.
+     *
+     * @param q storage for the result (not null, modified)
+     * @return the rotation Quaternion (q)
+     */
     public Quaternion toRotationQuat(Quaternion q) {
         return q.fromRotationMatrix(m00, m01, m02, m10,
                 m11, m12, m20, m21, m22);
     }
 
+    /**
+     * Interpret this matrix as a 3-D coordinate transform and determine its
+     * rotation component.
+     *
+     * @return a new rotation matrix
+     */
     public Matrix3f toRotationMatrix() {
         return new Matrix3f(m00, m01, m02, m10, m11, m12, m20, m21, m22);
     }
 
+    /**
+     * Interpret this matrix as a 3-D coordinate transform and determine its
+     * rotation component.
+     *
+     * @param mat storage for the result (not null, modified)
+     */
     public void toRotationMatrix(Matrix3f mat) {
         mat.m00 = m00;
         mat.m01 = m01;
@@ -2041,6 +2184,12 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         vec.z = vx * m02 + vy * m12 + vz * m22;
     }
 
+    /**
+     * Interpret this matrix as a 3-D coordinate transform and apply its
+     * rotation component to the specified vector.
+     *
+     * @param vec the vector to rotate (not null, modified)
+     */
     public void rotateVect(Vector3f vec) {
         float vx = vec.x, vy = vec.y, vz = vec.z;
 
@@ -2209,6 +2358,13 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         return true;
     }
 
+    /**
+     * Serialize this matrix to the specified exporter, for example when
+     * saving to a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the exporter
+     */
     @Override
     public void write(JmeExporter e) throws IOException {
         OutputCapsule cap = e.getCapsule(this);
@@ -2230,6 +2386,13 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         cap.write(m33, "m33", 1);
     }
 
+    /**
+     * De-serialize this matrix from the specified importer, for example
+     * when loading from a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the importer
+     */
     @Override
     public void read(JmeImporter e) throws IOException {
         InputCapsule cap = e.getCapsule(this);
@@ -2348,6 +2511,11 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         multLocal(matrix4f);
     }
 
+    /**
+     * Create a copy of this matrix.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Matrix4f clone() {
         try {

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

@@ -153,6 +153,13 @@ public class Plane implements Savable, Cloneable, java.io.Serializable {
         return constant;
     }
 
+    /**
+     * Find the point in this plane that's nearest to the specified point.
+     *
+     * @param point location vector of the input point (not null, unaffected)
+     * @param store storage for the result (not null, modififed)
+     * @return a location in this plane (store)
+     */
     public Vector3f getClosestPoint(Vector3f point, Vector3f store) {
 //        float t = constant - normal.dot(point);
 //        return store.set(normal).multLocal(t).addLocal(point);
@@ -160,10 +167,24 @@ public class Plane implements Savable, Cloneable, java.io.Serializable {
         return store.set(normal).multLocal(t).addLocal(point);
     }
 
+    /**
+     * Find the point in this plane that's nearest to the specified point.
+     *
+     * @param point location vector of the input point (not null, unaffected)
+     * @return a new location vector in this plane
+     */
     public Vector3f getClosestPoint(Vector3f point) {
         return getClosestPoint(point, new Vector3f());
     }
 
+    /**
+     * Reflect the specified point in this plane.
+     *
+     * @param point location vector of the input point (not null, unaffected)
+     * @param store storage for the result (modififed if not null)
+     * @return a location vector for the reflected point (either store or a new
+     * vector)
+     */
     public Vector3f reflect(Vector3f point, Vector3f store) {
         if (store == null) {
             store = new Vector3f();
@@ -270,6 +291,13 @@ public class Plane implements Savable, Cloneable, java.io.Serializable {
                 + constant + "]";
     }
 
+    /**
+     * Serialize this plane to the specified exporter, for example when
+     * saving to a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the exporter
+     */
     @Override
     public void write(JmeExporter e) throws IOException {
         OutputCapsule capsule = e.getCapsule(this);
@@ -277,6 +305,13 @@ public class Plane implements Savable, Cloneable, java.io.Serializable {
         capsule.write(constant, "constant", 0);
     }
 
+    /**
+     * De-serialize this plane from the specified importer, for example
+     * when loading from a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the importer
+     */
     @Override
     public void read(JmeImporter e) throws IOException {
         InputCapsule capsule = e.getCapsule(this);
@@ -284,6 +319,11 @@ public class Plane implements Savable, Cloneable, java.io.Serializable {
         constant = capsule.readFloat("constant", 0);
     }
 
+    /**
+     * Create a copy of this plane.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Plane clone() {
         try {

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

@@ -57,13 +57,34 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * Represents the identity quaternion rotation (0, 0, 0, 1).
      */
     public static final Quaternion IDENTITY = new Quaternion();
+    /**
+     * another instance of the identity Quaternion (0, 0, 0, 1)
+     */
     public static final Quaternion DIRECTION_Z = new Quaternion();
+    /**
+     * The zero quaternion (0, 0, 0, 0) doesn't represent any rotation.
+     */
     public static final Quaternion ZERO = new Quaternion(0, 0, 0, 0);
 
     static {
         DIRECTION_Z.fromAxes(Vector3f.UNIT_X, Vector3f.UNIT_Y, Vector3f.UNIT_Z);
     }
-    protected float x, y, z, w;
+    /**
+     * the X component (not an angle!)
+     */
+    protected float x;
+    /**
+     * the Y component (not an angle!)
+     */
+    protected float y;
+    /**
+     * the Z component (not an angle!)
+     */
+    protected float z;
+    /**
+     * the W (real) component (not an angle!)
+     */
+    protected float w;
 
     /**
      * Constructor instantiates a new <code>Quaternion</code> object
@@ -93,18 +114,38 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
         this.w = w;
     }
 
+    /**
+     * Determine the X component.
+     *
+     * @return x
+     */
     public float getX() {
         return x;
     }
 
+    /**
+     * Determine the Y component.
+     *
+     * @return y
+     */
     public float getY() {
         return y;
     }
 
+    /**
+     * Determine the Z component.
+     *
+     * @return z
+     */
     public float getZ() {
         return z;
     }
 
+    /**
+     * Determine the W (real) component.
+     *
+     * @return w
+     */
     public float getW() {
         return w;
     }
@@ -317,6 +358,21 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
                 matrix.m11, matrix.m12, matrix.m20, matrix.m21, matrix.m22);
     }
 
+    /**
+     * Set this quaternion based on a rotation matrix with the specified
+     * elements.
+     *
+     * @param m00 the matrix element in row 0, column 0
+     * @param m01 the matrix element in row 0, column 1
+     * @param m02 the matrix element in row 0, column 2
+     * @param m10 the matrix element in row 1, column 0
+     * @param m11 the matrix element in row 1, column 1
+     * @param m12 the matrix element in row 1, column 2
+     * @param m20 the matrix element in row 2, column 0
+     * @param m21 the matrix element in row 2, column 1
+     * @param m22 the matrix element in row 2, column 2
+     * @return this Quaternion
+     */
     public Quaternion fromRotationMatrix(float m00, float m01, float m02,
             float m10, float m11, float m12, float m20, float m21, float m22) {
         // first normalize the forward (F), up (U) and side (S) vectors of the rotation matrix
@@ -1357,6 +1413,13 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
         return this;
     }
 
+    /**
+     * Serialize this quaternion to the specified exporter, for example when
+     * saving to a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the exporter
+     */
     @Override
     public void write(JmeExporter e) throws IOException {
         OutputCapsule cap = e.getCapsule(this);
@@ -1366,6 +1429,13 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
         cap.write(w, "w", 1);
     }
 
+    /**
+     * De-serialize this quaternion from the specified importer, for example
+     * when loading from a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the importer
+     */
     @Override
     public void read(JmeImporter e) throws IOException {
         InputCapsule cap = e.getCapsule(this);
@@ -1413,6 +1483,11 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
         return opposite(this);
     }
 
+    /**
+     * Create a copy of this quaternion.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Quaternion clone() {
         try {

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

@@ -63,7 +63,9 @@ public final class Ray implements Savable, Cloneable, Collidable, java.io.Serial
      */
     public Vector3f direction = new Vector3f(0, 0, 1);
     
-    
+    /**
+     * The length of the ray (defaults to +Infinity).
+     */
     public float limit = Float.POSITIVE_INFINITY;
 
     /**
@@ -493,11 +495,25 @@ public final class Ray implements Savable, Cloneable, Collidable, java.io.Serial
         direction.set(source.getDirection());
     }
 
+    /**
+     * Represent this ray as a String.  The format is:
+     *
+     * Ray [Origin: (X.X, Y.Y, Z.Z), Direction: (X.X, Y.Y, Z.Z)]
+     *
+     * @return a descriptive string of text (not null, not empty)
+     */
     @Override
     public String toString() {
         return getClass().getSimpleName() + " [Origin: " + origin + ", Direction: " + direction + "]";
     }
 
+    /**
+     * Serialize this ray to the specified exporter, for example when
+     * saving to a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the exporter
+     */
     @Override
     public void write(JmeExporter e) throws IOException {
         OutputCapsule capsule = e.getCapsule(this);
@@ -505,6 +521,13 @@ public final class Ray implements Savable, Cloneable, Collidable, java.io.Serial
         capsule.write(direction, "direction", Vector3f.ZERO);
     }
 
+    /**
+     * De-serialize this ray from the specified importer, for example
+     * when loading from a J3O file.
+     *
+     * @param e (not null)
+     * @throws IOException from the importer
+     */
     @Override
     public void read(JmeImporter e) throws IOException {
         InputCapsule capsule = e.getCapsule(this);
@@ -512,6 +535,11 @@ public final class Ray implements Savable, Cloneable, Collidable, java.io.Serial
         direction = (Vector3f) capsule.readSavable("direction", Vector3f.ZERO.clone());
     }
 
+    /**
+     * Create a copy of this ray.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Ray clone() {
         try {