new javadoc for Matrix3f (#1727)

* Matrix3f:  begin revising the javadoc

* Matrix3f:  further revision of the javadoc

* Matrix3f:  still more revision of the javadoc

* Matrix3f:  final touches on the javadoc

* Matrix3f:  multLocal() can return null

* Matrix3f:  final tweaks

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2021 jMonkeyEngine
+ * Copyright (c) 2009-2022 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -39,10 +39,18 @@ import java.nio.FloatBuffer;
 import java.util.logging.Logger;
 
 /**
- * <code>Matrix3f</code> defines a 3x3 matrix. Matrix data is maintained
- * internally and is accessible via the get and set methods. Convenience methods
- * are used for matrix operations as well as generating a matrix from a given
- * set of values.
+ * A 3x3 matrix composed of 9 single-precision elements, used to represent
+ * linear transformations of 3-D coordinates, such as rotations, reflections,
+ * and scaling.
+ *
+ * <p>Element numbering is (row, column), so m01 is the element in row 0,
+ * column 1.
+ *
+ * <p>For pure rotations, the {@link com.jme3.math.Quaternion} class provides a
+ * more efficient representation.
+ *
+ * <p>With one exception, the methods with names ending in "Local" modify the
+ * current instance. They are used to avoid creating garbage.
  *
  * @author Mark Powell
  * @author Joshua Slack
@@ -53,70 +61,70 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
 
     private static final Logger logger = Logger.getLogger(Matrix3f.class.getName());
     /**
-     * the element in row 0, column 0
+     * The element in row 0, column 0.
      */
     protected float m00;
     /**
-     * the element in row 0, column 1
+     * The element in row 0, column 1.
      */
     protected float m01;
     /**
-     * the element in row 0, column 2
+     * The element in row 0, column 2.
      */
     protected float m02;
     /**
-     * the element in row 1, column 0
+     * The element in row 1, column 0.
      */
     protected float m10;
     /**
-     * the element in row 1, column 1
+     * The element in row 1, column 1.
      */
     protected float m11;
     /**
-     * the element in row 1, column 2
+     * The element in row 1, column 2.
      */
     protected float m12;
     /**
-     * the element in row 2, column 0
+     * The element in row 2, column 0.
      */
     protected float m20;
     /**
-     * the element in row 2, column 1
+     * The element in row 2, column 1.
      */
     protected float m21;
     /**
-     * the element in row 2, column 2
+     * The element in row 2, column 2.
      */
     protected float m22;
     /**
-     * an instance of the zero matrix (all elements = 0)
+     * Shared instance of the all-zero matrix. Do not modify!
      */
     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)
+     * Shared instance of the identity matrix (diagonals = 1, other elements =
+     * 0). Do not modify!
      */
     public static final Matrix3f IDENTITY = new Matrix3f();
 
     /**
-     * Constructor instantiates a new <code>Matrix3f</code> object. The
-     * initial values for the matrix is that of the identity matrix.
+     * Instantiates an identity matrix (diagonals = 1, other elements = 0).
      */
     public Matrix3f() {
         loadIdentity();
     }
 
     /**
-     * constructs a matrix with the given values.
+     * Instantiates a matrix with specified elements.
      *
-     * @param m00 0x0 in the matrix.
-     * @param m01 0x1 in the matrix.
-     * @param m02 0x2 in the matrix.
-     * @param m10 1x0 in the matrix.
-     * @param m11 1x1 in the matrix.
-     * @param m12 1x2 in the matrix.
-     * @param m20 2x0 in the matrix.
-     * @param m21 2x1 in the matrix.
-     * @param m22 2x2 in the 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 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 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
      */
     public Matrix3f(float m00, float m01, float m02, float m10, float m11,
             float m12, float m20, float m21, float m22) {
@@ -132,18 +140,17 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Copy constructor that creates a new <code>Matrix3f</code> object that
-     * is the same as the provided matrix.
+     * Instantiates a copy of the matrix argument. If the argument is null, an
+     * identity matrix is produced.
      *
-     * @param mat
-     *            the matrix to copy.
+     * @param mat the matrix to copy (unaffected) or null for identity
      */
     public Matrix3f(Matrix3f mat) {
         set(mat);
     }
 
     /**
-     * Takes the absolute value of all matrix fields locally.
+     * Replaces all 9 elements with their absolute values.
      */
     public void absoluteLocal() {
         m00 = FastMath.abs(m00);
@@ -158,13 +165,11 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>copy</code> transfers the contents of a given matrix to this
-     * matrix. If a null matrix is supplied, this matrix is set to the identity
-     * matrix.
+     * Copies the matrix argument. If the argument is null, the current instance
+     * is set to identity (diagonals = 1, other elements = 0).
      *
-     * @param matrix
-     *            the matrix to copy.
-     * @return this
+     * @param matrix the matrix to copy (unaffected) or null for identity
+     * @return the (modified) current instance (for chaining)
      */
     public Matrix3f set(Matrix3f matrix) {
         if (null == matrix) {
@@ -184,12 +189,12 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>get</code> retrieves a value from the matrix at the given position.
+     * Returns the element at the specified position. The matrix is unaffected.
      *
-     * @param i   the row index.
-     * @param j   the column index.
-     * @return the value at (i, j).
-     * @throws IllegalArgumentException if either index is invalid
+     * @param i the row index (0, 1, or 2)
+     * @param j the column index (0, 1, or 2)
+     * @return the value of the element at (i, j)
+     * @throws IllegalArgumentException if either index isn't 0, 1, or 2
      */
     @SuppressWarnings("fallthrough")
     public float get(int i, int j) {
@@ -228,14 +233,17 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>get(float[])</code> returns the matrix in row-major or column-major order.
+     * Copies the matrix to the specified array. The matrix is unaffected.
      *
-     * @param data
-     *      The array to return the data into. This array can be 9 or 16 floats in size.
-     *      Only the upper 3x3 are assigned to in the case of a 16 element array.
-     * @param rowMajor
-     *      True for row major storage in the array (translation in elements 3, 7, 11 for a 4x4),
-     *      false for column major (translation in elements 12, 13, 14 for a 4x4).
+     * <p>If the array has 16 elements, then the matrix is treated as if it
+     * contained the 1st 3 rows and 1st 3 columns of a 4x4 matrix.
+     *
+     * @param data storage for the elements (not null, length=9 or 16)
+     * @param rowMajor true to store the elements in row-major order (m00, m01,
+     *     ...) or false to store them in column-major order (m00, m10, ...)
+     * @throws IndexOutOfBoundsException if {@code data} doesn't have 9 or 16
+     *     elements
+     * @see #fillFloatArray(float[], boolean)
      */
     public void get(float[] data, boolean rowMajor) {
         if (data.length == 9) {
@@ -288,14 +296,11 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Normalize this matrix and store the result in the store parameter that is
-     * returned.
-     *
-     * Note that the original matrix is not altered.
+     * Normalizes the matrix and returns the result in the argument. The current
+     * instance is unaffected, unless it's {@code store}.
      *
-     * @param store the matrix to store the result of the normalization. If this
-     * parameter is null a new one is created
-     * @return the normalized matrix
+     * @param store storage for the result, or null for a new Matrix3f
+     * @return either {@code store} or a new Matrix3f
      */
     public Matrix3f normalize(Matrix3f store) {
         if (store == null) {
@@ -327,34 +332,40 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Normalize this matrix
+     * Normalizes the matrix and returns the (modified) current instance.
      *
-     * @return this matrix once normalized.
+     * @return the (modified) current instance (for chaining)
      */
     public Matrix3f normalizeLocal() {
         return normalize(this);
     }
 
     /**
-     * <code>getColumn</code> returns one of three columns specified by the
-     * parameter. This column is returned as a <code>Vector3f</code> object.
+     * Returns the specified column. The matrix is unaffected.
+     *
+     * <p>If the matrix is a pure rotation, each column contains one of the
+     * basis vectors.
      *
-     * @param i   the column to retrieve. Must be between 0 and 2.
-     * @return the column specified by the index.
+     * @param i the column index (0, 1, or 2)
+     * @return a new Vector3f
+     * @throws IllegalArgumentException if {@code i} isn't 0, 1, or 2
+     * @see Quaternion#getRotationColumn(int)
      */
     public Vector3f getColumn(int i) {
         return getColumn(i, null);
     }
 
     /**
-     * <code>getColumn</code> returns one of three columns specified by the
-     * parameter. This column is returned as a <code>Vector3f</code> object.
+     * Returns the specified column. The matrix is unaffected.
      *
-     * @param i   the column to retrieve. Must be between 0 and 2.
-     * @param store
-     *            the vector object to store the result in. if null, a new one
-     *            is created.
-     * @return the column specified by the index.
+     * <p>If the matrix is a pure rotation, each column contains one of the
+     * basis vectors.
+     *
+     * @param i the column index (0, 1, or 2)
+     * @param store storage for the result, or null for a new Vector3f
+     * @return either {@code store} or a new Vector3f
+     * @throws IllegalArgumentException if {@code i} isn't 0, 1, or 2
+     * @see Quaternion#getRotationColumn(int, com.jme3.math.Vector3f)
      */
     public Vector3f getColumn(int i, Vector3f store) {
         if (store == null) {
@@ -384,25 +395,23 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>getColumn</code> returns one of three rows as specified by the
-     * parameter. This row is returned as a <code>Vector3f</code> object.
+     * Returns the specified row. The matrix is unaffected.
      *
-     * @param i   the row to retrieve. Must be between 0 and 2.
-     * @return the row specified by the index.
+     * @param i the row index (0, 1, or 2)
+     * @return a new Vector3f
+     * @throws IllegalArgumentException if {@code i} isn't 0, 1, or 2
      */
     public Vector3f getRow(int i) {
         return getRow(i, null);
     }
 
     /**
-     * <code>getRow</code> returns one of three rows as specified by the
-     * parameter. This row is returned as a <code>Vector3f</code> object.
+     * Returns the specified row. The matrix is unaffected.
      *
-     * @param i   the row to retrieve. Must be between 0 and 2.
-     * @param store
-     *            the vector object to store the result in. if null, a new one
-     *            is created.
-     * @return the row specified by the index.
+     * @param i the row index (0, 1, or 2)
+     * @param store storage for the result, or null for a new Vector3f
+     * @return either {@code store} or a new Vector3f
+     * @throws IllegalArgumentException if {@code i} isn't 0, 1, or 2
      */
     public Vector3f getRow(int i, Vector3f store) {
         if (store == null) {
@@ -432,10 +441,10 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>toFloatBuffer</code> returns a FloatBuffer object that contains
-     * the matrix data.
+     * Copies the matrix to a new FloatBuffer. The matrix is unaffected.
      *
-     * @return matrix data as a FloatBuffer.
+     * @return a new, rewound FloatBuffer containing all 9 elements in row-major
+     *     order (m00, m01, ...)
      */
     public FloatBuffer toFloatBuffer() {
         FloatBuffer fb = BufferUtils.createFloatBuffer(9);
@@ -448,16 +457,14 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>fillFloatBuffer</code> fills a FloatBuffer object with the matrix
-     * data.
+     * Copies the matrix to the specified FloatBuffer, starting at its current
+     * position. The matrix is unaffected.
      *
-     * @param fb
-     *            the buffer to fill, starting at current position. Must have
-     *            room for 9 more floats.
-     * @param columnMajor
-     *            true &rarr; column-major order, false &rarr; row-major order
-     * @return matrix data as a FloatBuffer. (position is advanced by 9 and any
-     *         limit set is not changed).
+     * @param fb storage for the elements (not null, must have space to put 9
+     *     more floats)
+     * @param columnMajor true to store the elements in column-major order (m00,
+     *     m10, ...) or false to store them in row-major order (m00, m01, ...)
+     * @return {@code fb}, its position advanced by 9
      */
     public FloatBuffer fillFloatBuffer(FloatBuffer fb, boolean columnMajor) {
 //        if (columnMajor){
@@ -481,11 +488,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Copy all elements of this matrix to a float array.
+     * Copy the matrix to the 1st 9 elements of the specified array. The matrix
+     * is unaffected.
      *
-     * @param f   the array to fill (not null, length&ge;9)
-     * @param columnMajor
-     *            true &rarr; column-major order, false &rarr; row-major order
+     * @param f storage for the elements (not null, length&ge;9)
+     * @param columnMajor true to store the elements in column-major order (m00,
+     *     m10, ...) or false to store them in row-major order (m00, m01, ...)
+     * @see #get(float[], boolean)
      */
     public void fillFloatArray(float[] f, boolean columnMajor) {
         if (columnMajor) {
@@ -512,13 +521,12 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>setColumn</code> sets a particular column of this matrix to that
-     * represented by the provided vector.
+     * Sets the specified column.
      *
-     * @param i   the column to set.
-     * @param column
-     *            the data to set.
-     * @return this
+     * @param i which column to set (0, 1, or 2)
+     * @param column the desired element values (unaffected) or null for none
+     * @return the current instance (for chaining)
+     * @throws IllegalArgumentException if {@code i} isn't 0, 1, or 2
      */
     public Matrix3f setColumn(int i, Vector3f column) {
         if (column == null) {
@@ -549,13 +557,12 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>setRow</code> sets a particular row of this matrix to that
-     * represented by the provided vector.
+     * Sets the specified row.
      *
-     * @param i   the row to set.
-     * @param row
-     *            the data to set.
-     * @return this
+     * @param i which row to set (0, 1, or 2)
+     * @param row the desired element values (unaffected) or null for none
+     * @return the current instance (for chaining)
+     * @throws IllegalArgumentException if {@code i} isn't 0, 1, or 2
      */
     public Matrix3f setRow(int i, Vector3f row) {
         if (row == null) {
@@ -586,15 +593,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>set</code> places a given value into the matrix at the given
-     * position.
+     * Sets the specified element.
      *
-     * @param i   the row index.
-     * @param j   the column index.
-     * @param value
-     *            the value for (i, j).
-     * @return this
-     * @throws IllegalArgumentException if either index is invalid
+     * @param i the row index (0, 1, or 2)
+     * @param j the column index (0, 1, or 2)
+     * @param value desired value for the element at (i, j)
+     * @return the (modified) current instance (for chaining)
+     * @throws IllegalArgumentException if either index isn't 0, 1, or 2
      */
     @SuppressWarnings("fallthrough")
     public Matrix3f set(int i, int j, float value) {
@@ -642,13 +647,12 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>set</code> sets the values of the matrix to those supplied by the
-     * 3x3 two-dimensional array.
+     * Copies all 9 elements from the specified 2-dimensional array.
      *
-     * @param matrix
-     *            the new values of the matrix.
-     * @throws IllegalArgumentException if the matrix is not 3x3
-     * @return this
+     * @param matrix the input array (not null, length=3, the first element
+     *     having length=3, the other elements having length&ge;3, unaffected)
+     * @return the (modified) current instance (for chaining)
+     * @throws IllegalArgumentException if the array is the wrong size
      */
     public Matrix3f set(float[][] matrix) {
         if (matrix.length != 3 || matrix[0].length != 3) {
@@ -670,11 +674,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Recreate Matrix using the provided axis.
+     * Configures from the specified column vectors. If the vectors form an
+     * orthonormal basis, the result will be a pure rotation matrix.
      *
-     * @param uAxis  Vector3f
-     * @param vAxis  Vector3f
-     * @param wAxis  Vector3f
+     * @param uAxis the desired value for column 0 (not null, unaffected)
+     * @param vAxis the desired value for column 1 (not null, unaffected)
+     * @param wAxis the desired value for column 2 (not null, unaffected)
+     * @see Quaternion#fromAxes(com.jme3.math.Vector3f[])
      */
     public void fromAxes(Vector3f uAxis, Vector3f vAxis, Vector3f wAxis) {
         m00 = uAxis.x;
@@ -691,26 +697,24 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>set</code> sets the values of this matrix from an array of
-     * values assuming that the data is rowMajor order;
+     * Copies all 9 elements from the array argument, in row-major order.
      *
-     * @param matrix
-     *            the matrix to set the value to.
-     * @return this
+     * @param matrix the input array (not null, length=9, unaffected)
+     * @return the (modified) current instance (for chaining)
+     * @throws IllegalArgumentException if the array has length != 9
      */
     public Matrix3f set(float[] matrix) {
         return set(matrix, true);
     }
 
     /**
-     * <code>set</code> sets the values of this matrix from an array of
-     * values;
+     * Copies all 9 elements from the specified array.
      *
-     * @param matrix
-     *            the matrix to set the value to.
-     * @param rowMajor
-     *            whether the incoming data is in row or column major order.
-     * @return this
+     * @param matrix the input array (not null, length=9, unaffected)
+     * @param rowMajor true to read the elements in row-major order (m00, m01,
+     *     ...) or false to read them in column-major order (m00, m10, ...)
+     * @return the (modified) current instance (for chaining)
+     * @throws IllegalArgumentException if the array has length != 9
      */
     public Matrix3f set(float[] matrix, boolean rowMajor) {
         if (matrix.length != 9) {
@@ -743,21 +747,17 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>set</code> defines the values of the matrix based on a supplied
-     * <code>Quaternion</code>. It should be noted that all previous values
-     * will be overridden.
+     * Configures as a rotation matrix equivalent to the argument.
      *
-     * @param quaternion
-     *            the quaternion to create a rotational matrix from.
-     * @return this
+     * @param quaternion the input quaternion (not null, unaffected)
+     * @return the current instance (for chaining)
      */
     public Matrix3f set(Quaternion quaternion) {
         return quaternion.toRotationMatrix(this);
     }
 
     /**
-     * <code>loadIdentity</code> sets this matrix to the identity matrix.
-     * Where all values are zero except those along the diagonal which are one.
+     * Configures as an identity matrix (diagonals = 1, other elements = 0).
      */
     public void loadIdentity() {
         m01 = m02 = m10 = m12 = m20 = m21 = 0;
@@ -765,7 +765,9 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * @return true if this matrix is identity
+     * Tests for exact identity. The matrix is unaffected.
+     *
+     * @return true if equal to {@link #IDENTITY}, otherwise false
      */
     public boolean isIdentity() {
         return (m00 == 1 && m01 == 0 && m02 == 0)
@@ -774,14 +776,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>fromAngleAxis</code> sets this matrix4f to the values specified
-     * by an angle and an axis of rotation.  This method creates an object, so
-     * use fromAngleNormalAxis if your axis is already normalized.
+     * Sets all 9 elements to form a pure rotation matrix with the specified
+     * rotation angle and axis of rotation. This method creates garbage, so use
+     * {@link #fromAngleNormalAxis(float, com.jme3.math.Vector3f)} if the axis
+     * is known to be normalized.
      *
-     * @param angle
-     *            the angle to rotate (in radians).
-     * @param axis
-     *            the axis of rotation.
+     * @param angle the desired rotation angle (in radians)
+     * @param axis the desired axis of rotation (not null, unaffected)
      */
     public void fromAngleAxis(float angle, Vector3f axis) {
         Vector3f normAxis = axis.normalize();
@@ -789,13 +790,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>fromAngleNormalAxis</code> sets this matrix4f to the values
-     * specified by an angle and a normalized axis of rotation.
+     * Sets all 9 elements to form a rotation matrix with the specified rotation
+     * angle and normalized axis of rotation. If the axis might not be
+     * normalized, use {@link #fromAngleAxis(float, com.jme3.math.Vector3f)}
+     * instead.
      *
-     * @param angle
-     *            the angle to rotate (in radians).
-     * @param axis
-     *            the axis of rotation (already normalized).
+     * @param angle the desired rotation angle (in radians)
+     * @param axis the desired axis of rotation (not null, length=1, unaffected)
      */
     public void fromAngleNormalAxis(float angle, Vector3f axis) {
         float fCos = FastMath.cos(angle);
@@ -823,28 +824,33 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>mult</code> multiplies this matrix by a given matrix. The result
-     * matrix is returned as a new object. If the given matrix is null, a null
-     * matrix is returned.
+     * Multiplies with the argument matrix and returns the product as a new
+     * instance. The current instance is unaffected.
+     *
+     * <p>Note that matrix multiplication is noncommutative, so generally
+     * q * p != p * q.
      *
-     * @param mat
-     *            the matrix to multiply this matrix by.
-     * @return the result matrix.
+     * @param mat the right factor (not null, unaffected)
+     * @return {@code this} times {@code mat} (a new Matrix3f)
      */
     public Matrix3f mult(Matrix3f mat) {
         return mult(mat, null);
     }
 
     /**
-     * <code>mult</code> multiplies this matrix by a given matrix. The result
-     * matrix is returned as a new object.
+     * Multiplies with the specified matrix and returns the product in a 3rd
+     * matrix. The current instance is unaffected unless it's {@code product}.
      *
-     * @param mat
-     *            the matrix to multiply this matrix by.
-     * @param product
-     *            the matrix to store the result in. if null, a new matrix3f is
-     *            created.  It is safe for mat and product to be the same object.
-     * @return a matrix3f object containing the result of this operation
+     * <p>Note that matrix multiplication is noncommutative, so generally
+     * q * p != p * q.
+     *
+     * <p>It is safe for {@code mat} and {@code product} to be the same object.
+     *
+     * @param mat the right factor (not null, unaffected unless it's {@code
+     *     product})
+     * @param product storage for the product, or null for a new Matrix3f
+     * @return {@code this} times {@code mat} (either {@code product} or a new
+     *     Matrix3f)
      */
     public Matrix3f mult(Matrix3f mat, Matrix3f product) {
         float temp00, temp01, temp02;
@@ -878,28 +884,32 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>mult</code> multiplies this matrix by a given
-     * <code>Vector3f</code> object. The result vector is returned. If the
-     * given vector is null, null will be returned.
+     * Applies the linear transformation to the vector argument and returns the
+     * result as a new vector. The matrix is unaffected.
+     *
+     * <p>This can also be described as multiplying the matrix by a column
+     * vector.
      *
-     * @param vec
-     *            the vector to multiply this matrix by.
-     * @return the result vector.
+     * @param vec the coordinates to transform (not null, unaffected)
+     * @return a new Vector3f
      */
     public Vector3f mult(Vector3f vec) {
         return mult(vec, null);
     }
 
     /**
-     * Multiplies this 3x3 matrix by the 1x3 Vector vec and stores the result in
-     * product.
+     * Applies the linear transformation to specified vector and stores the
+     * result in another vector. The matrix is unaffected.
      *
-     * @param vec
-     *            The Vector3f to multiply.
-     * @param product
-     *            The Vector3f to store the result, it is safe for this to be
-     *            the same as vec.
-     * @return The given product vector.
+     * <p>This can also be described as multiplying the matrix by a column
+     * vector.
+     *
+     * <p>It is safe for {@code vec} and {@code product} to be the same object.
+     *
+     * @param vec the coordinates to transform (not null, unaffected unless it's
+     *     {@code product})
+     * @param product storage for the result, or null for a new Vector3f
+     * @return either {@code product} or a new Vector3f
      */
     public Vector3f mult(Vector3f vec, Vector3f product) {
         if (null == product) {
@@ -917,12 +927,11 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>multLocal</code> multiplies this matrix internally by
-     * a given float scale factor.
+     * Multiplies by the scalar argument and returns the (modified) current
+     * instance.
      *
-     * @param scale
-     *            the value to scale by.
-     * @return this Matrix3f
+     * @param scale the scaling factor
+     * @return the (modified) current instance (for chaining)
      */
     public Matrix3f multLocal(float scale) {
         m00 *= scale;
@@ -938,14 +947,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>multLocal</code> multiplies this matrix by a given
-     * <code>Vector3f</code> object. The result vector is stored inside the
-     * passed vector, then returned . If the given vector is null, null will be
-     * returned.
+     * Applies the linear transformation to the vector argument and returns the
+     * (modified) argument. If the argument is null, null is returned.
+     *
+     * <p>Despite the name, the current instance is unaffected.
      *
-     * @param vec
-     *            the vector to multiply this matrix by.
-     * @return The passed vector after multiplication
+     * @param vec the vector to transform (modified if not null)
+     * @return {@code vec} or null
      */
     public Vector3f multLocal(Vector3f vec) {
         if (vec == null) {
@@ -960,23 +968,24 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>mult</code> multiplies this matrix by a given matrix. The result
-     * matrix is saved in the current matrix. If the given matrix is null,
-     * nothing happens. The current matrix is returned. This is equivalent to
-     * this*=mat
+     * Multiplies by the matrix argument and returns the (modified) current
+     * instance.
      *
-     * @param mat
-     *            the matrix to multiply this matrix by.
-     * @return This matrix, after the multiplication
+     * <p>Note that matrix multiplication is noncommutative, so generally
+     * q * p != p * q.
+     *
+     * @param mat the right factor (not null, unaffected unless it's
+     *     {@code this})
+     * @return the (modified) current instance
      */
     public Matrix3f multLocal(Matrix3f mat) {
         return mult(mat, this);
     }
 
     /**
-     * Transposes this matrix in place. Returns this matrix for chaining
+     * Transposes the matrix and returns the (modified) current instance.
      *
-     * @return This matrix after transpose
+     * @return the (modified) current instance
      */
     public Matrix3f transposeLocal() {
 //        float[] tmp = new float[9];
@@ -999,19 +1008,26 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Inverts this matrix as a new Matrix3f.
+     * Returns the multiplicative inverse as a new matrix. If the current
+     * instance is singular, an all-zero matrix is returned. In either case, the
+     * current instance is unaffected.
      *
-     * @return The new inverse matrix
+     * @return a new Matrix3f
      */
     public Matrix3f invert() {
         return invert(null);
     }
 
     /**
-     * Inverts this matrix and stores it in the given store.
+     * Returns the multiplicative inverse in the specified storage. If the
+     * current instance is singular, an all-zero matrix is returned. In either
+     * case, the current instance is unaffected.
+     *
+     * <p>If {@code this} and {@code store} are the same object, the result is
+     * undefined. Use {@link #invertLocal()} instead.
      *
-     * @param store storage for the result (modified if not null)
-     * @return The store
+     * @param store storage for the result, or null for a new Matrix3f
+     * @return either {@code store} or a new Matrix3f
      */
     public Matrix3f invert(Matrix3f store) {
         if (store == null) {
@@ -1038,9 +1054,10 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Inverts this matrix locally.
+     * Inverts the matrix and returns the (modified) current instance. If the
+     * current instance is singular, all elements will be set to zero.
      *
-     * @return this
+     * @return the (modified) current instance (for chaining)
      */
     public Matrix3f invertLocal() {
         float det = determinant();
@@ -1073,20 +1090,23 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Returns a new matrix representing the adjoint of this matrix.
+     * Returns the adjoint as a new matrix. The current instance is unaffected.
      *
-     * @return The adjoint matrix
+     * @return a new Matrix3f
      */
     public Matrix3f adjoint() {
         return adjoint(null);
     }
 
     /**
-     * Places the adjoint of this matrix in store (creates store if null.)
+     * Returns the adjoint in the specified storage. The current instance is
+     * unaffected.
+     *
+     * <p>If {@code this} and {@code store} are the same object, the result is
+     * undefined.
      *
-     * @param store
-     *            The matrix to store the result in.  If null, a new matrix is created.
-     * @return store
+     * @param store storage for the result, or null for a new Matrix3f
+     * @return either {@code store} or a new Matrix3f
      */
     public Matrix3f adjoint(Matrix3f store) {
         if (store == null) {
@@ -1107,7 +1127,7 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>determinant</code> generates the determinant of this matrix.
+     * Returns the determinant. The matrix is unaffected.
      *
      * @return the determinant
      */
@@ -1120,9 +1140,9 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Sets all of the values in this matrix to zero.
+     * Sets all elements to zero.
      *
-     * @return this matrix
+     * @return the (modified) current instance (for chaining)
      */
     public Matrix3f zero() {
         m00 = m01 = m02 = m10 = m11 = m12 = m20 = m21 = m22 = 0.0f;
@@ -1130,10 +1150,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>transpose</code> <b>locally</b> transposes this Matrix.
-     * This is inconsistent with general value vs local semantics, but is
-     * preserved for backwards compatibility. Use transposeNew() to transpose
-     * to a new object (value).
+     * Transposes the matrix and returns the (modified) current instance.
+     *
+     * <p>This method is inconsistent with JME naming conventions, but has been
+     * preserved for backwards compatibility. To preserve the current instance,
+     * {@link #transposeNew()}.
+     *
+     * <p>TODO deprecate in favor of transposeLocal()
      *
      * @return this object for chaining.
      */
@@ -1142,9 +1165,10 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>transposeNew</code> returns a transposed version of this matrix.
+     * Returns the transpose as a new instance. The current instance is
+     * unaffected.
      *
-     * @return The new Matrix3f object.
+     * @return a new Matrix3f
      */
     public Matrix3f transposeNew() {
         Matrix3f ret = new Matrix3f(m00, m10, m20, m01, m11, m21, m02, m12, m22);
@@ -1152,8 +1176,8 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>toString</code> returns a string representation of this matrix.
-     * For example, an identity matrix would be represented by:
+     * Returns a string representation. The current instance is unaffected. For
+     * example, an identity matrix would be represented by:
      * <pre>
      * Matrix3f
      * [
@@ -1193,11 +1217,10 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>hashCode</code> returns the hash code value as an integer and is
-     * supported for the benefit of hashing based collection classes such as
-     * Hashtable, HashMap, HashSet etc.
+     * Returns a hash code. If two matrices are logically equivalent, they will
+     * return the same hash code. The current instance is unaffected.
      *
-     * @return the hashcode for this instance of Matrix4f.
+     * @return the hash-code value
      * @see java.lang.Object#hashCode()
      */
     @Override
@@ -1219,10 +1242,11 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * are these two matrices the same? they are is they both have the same mXX values.
+     * Tests for exact equality with the argument, distinguishing -0 from 0. The
+     * current instance is unaffected.
      *
-     * @param o   the object to compare for equality
-     * @return true if they are equal
+     * @param o the object to compare (may be null, unaffected)
+     * @return true if equal, otherwise false
      */
     @Override
     public boolean equals(Object o) {
@@ -1269,10 +1293,10 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Serialize this matrix to the specified exporter, for example when
-     * saving to a J3O file.
+     * Serializes to the specified exporter, for example when saving to a J3O
+     * file. The current instance is unaffected.
      *
-     * @param e (not null)
+     * @param e the exporter to use (not null)
      * @throws IOException from the exporter
      */
     @Override
@@ -1290,10 +1314,10 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * De-serialize this matrix from the specified importer, for example
-     * when loading from a J3O file.
+     * De-serializes from the specified importer, for example when loading from a
+     * J3O file.
      *
-     * @param importer (not null)
+     * @param importer the importer to use (not null)
      * @throws IOException from the importer
      */
     @Override
@@ -1311,16 +1335,15 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * A function for creating a rotation matrix that rotates a vector called
-     * "start" into another vector called "end".
+     * Configures a rotation matrix that rotates the specified start direction
+     * to the specified end direction.
+     *
+     * <p>See Tomas Möller, John F. Hughes "Efficiently Building a Matrix to
+     * Rotate One Vector to Another" Journal of Graphics Tools, 4(4):1-4, 1999.
      *
-     * @param start
-     *            normalized non-zero starting vector
-     * @param end
-     *            normalized non-zero ending vector
+     * @param start the start direction (not null, length=1, unaffected)
+     * @param end the end direction (not null, length=1, unaffected)
      *
-     * See Tomas M�ller, John Hughes "Efficiently Building a Matrix to Rotate
-     *      One Vector to Another" Journal of Graphics Tools, 4(4):1-4, 1999.
      */
     public void fromStartEndVectors(Vector3f start, Vector3f end) {
         Vector3f v = new Vector3f();
@@ -1403,11 +1426,10 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>scale</code> scales the operation performed by this matrix on a
-     * per-component basis.
+     * Scales each column by the corresponding element of the argument.
      *
-     * @param scale
-     *         The scale applied to each of the X, Y and Z output values.
+     * @param scale the scale factors: X scales column 0, Y scales column 1, Z
+     *     scales column 2 (not null, unaffected)
      */
     public void scale(Vector3f scale) {
         m00 *= scale.x;
@@ -1421,6 +1443,12 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
         m22 *= scale.z;
     }
 
+    /**
+     * Tests for an identity matrix, with 0.0001 tolerance. The current instance
+     * is unaffected.
+     *
+     * @return true if all elements are within 0.0001 of an identity matrix
+     */
     static boolean equalIdentity(Matrix3f mat) {
         if (Math.abs(mat.m00 - 1) > 1e-4) {
             return false;
@@ -1457,9 +1485,9 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Create a copy of this matrix.
+     * Creates a copy. The current instance is unaffected.
      *
-     * @return a new instance, equivalent to this one
+     * @return a new instance, equivalent to the current one
      */
     @Override
     public Matrix3f clone() {