new javadoc for Transform (#1706)

* Transform: javadoc frag not a complete sentence, but punctuated like one

* Transform:  clarify which objects get modified and which are unaffected

* Transform: document the nullability of arguments and results

* refer to components consistently, distinguish "scale" from "scaling"

* Transform: clarify the return values

* Transform: when there's a single argument, refer to it as "the argument"

* Transform: use capital letters when referring to axes

* Transform:  standardize the terminology for caller-provided storage

* Transform:  rephrase "given value" to be more consistent

* Transform: simplify the javadoc, avoid "this Transform"

* Transform:  tidy the whitespace

* Transform:  a cleanup pass over the javadoc

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

@@ -40,7 +40,7 @@ import java.io.IOException;
  * A 3-D coordinate transform composed of translation, rotation, and scaling.
  * The order of application is: scale then rotate then translate.
  *
- * Started Date: Jul 16, 2004<br><br>
+ * <p>Started July 16, 2004
  *
  * @author Jack Lindamood
  * @author Joshua Slack
@@ -49,24 +49,24 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
 
     static final long serialVersionUID = 1;
     /**
-     * shared instance of the identity transform - Do not modify!
+     * Shared instance of the identity transform. Do not modify!
      */
     public static final Transform IDENTITY = new Transform();
     /**
-     * rotation component
+     * Rotation component.
      */
     private Quaternion rot = new Quaternion();
     /**
-     * translation offsets for each axis
+     * Translation component: an offset for each local axis.
      */
     private Vector3f translation = new Vector3f();
     /**
-     * scale factors for each axis
+     * Scaling component: a scale factor for each local axis.
      */
     private Vector3f scale = new Vector3f(1, 1, 1);
 
     /**
-     * Instantiate a coordinate transform without any scaling.
+     * Instantiates a coordinate transform without scaling.
      *
      * @param translation the desired translation (not null, unaffected)
      * @param rot the desired rotation (not null, unaffected)
@@ -77,11 +77,11 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Instantiate a coordinate transform with scaling.
+     * Instantiates a coordinate transform with scaling.
      *
      * @param translation the desired translation (not null, unaffected)
      * @param rot the desired rotation (not null, unaffected)
-     * @param scale the desired scale factor (not null, unaffected)
+     * @param scale the desired scaling (not null, unaffected)
      */
     public Transform(Vector3f translation, Quaternion rot, Vector3f scale) {
         this(translation, rot);
@@ -89,7 +89,7 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Instantiate a translation-only transform.
+     * Instantiates a translation-only transform.
      *
      * @param translation the desired translation (not null, unaffected)
      */
@@ -98,7 +98,7 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Instantiate a rotation-only transform.
+     * Instantiates a rotation-only transform.
      *
      * @param rot the desired rotation (not null, unaffected)
      */
@@ -107,17 +107,18 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Instantiate an identity transform.
+     * Instantiates an identity transform: no translation, no rotation, and no
+     * scaling.
      */
     public Transform() {
         this(Vector3f.ZERO, Quaternion.IDENTITY);
     }
 
     /**
-     * Sets this rotation to the given Quaternion value.
+     * Sets the rotation component to the argument.
      *
-     * @param rot The new rotation for this Transform.
-     * @return this
+     * @param rot the desired rotation value (not null, unaffected)
+     * @return the (modified) current instance (for chaining)
      */
     public Transform setRotation(Quaternion rot) {
         this.rot.set(rot);
@@ -125,10 +126,10 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Sets this translation to the given value.
+     * Sets the translation component to the argument.
      *
-     * @param trans The new translation for this Transform.
-     * @return this
+     * @param trans the desired offsets (not null, unaffected)
+     * @return the (modified) current instance (for chaining)
      */
     public Transform setTranslation(Vector3f trans) {
         this.translation.set(trans);
@@ -136,19 +137,19 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Return the translation vector in this Transform.
+     * Returns the translation component.
      *
-     * @return translation vector.
+     * @return the pre-existing instance (not null)
      */
     public Vector3f getTranslation() {
         return translation;
     }
 
     /**
-     * Sets this scale to the given value.
+     * Sets the scaling component to the argument.
      *
-     * @param scale The new scale for this Transform.
-     * @return this
+     * @param scale the desired scale factors (not null, unaffected)
+     * @return the (modified) current instance (for chaining)
      */
     public Transform setScale(Vector3f scale) {
         this.scale.set(scale);
@@ -156,10 +157,10 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Sets this scale to the given value.
+     * Sets the scaling component to the argument. This yields uniform scaling.
      *
-     * @param scale The new scale for this Transform.
-     * @return this
+     * @param scale the desired scale factor for all local axes
+     * @return the (modified) current instance (for chaining)
      */
     public Transform setScale(float scale) {
         this.scale.set(scale, scale, scale);
@@ -167,21 +168,23 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Return the scale vector in this Transform.
+     * Returns the scaling component.
      *
-     * @return scale vector.
+     * @return the pre-existing instance (not null)
      */
     public Vector3f getScale() {
         return scale;
     }
 
     /**
-     * Stores this translation value into the given vector3f. If trans is null,
-     * a new vector3f is created to hold the value. The value, once stored, is
-     * returned.
+     * Copies the translation component to the argument. If the argument is
+     * null, a new Vector3f is created to hold the value. Either way, the
+     * current instance is unaffected, unless the argument is its scaling
+     * component.
      *
-     * @param trans The store location for this transform's translation.
-     * @return The value of this transform's translation.
+     * @param trans storage for the result (modified if not null)
+     * @return the translation offsets (either <code>trans</code> or a new
+     *     Vector3f)
      */
     public Vector3f getTranslation(Vector3f trans) {
         if (trans == null) {
@@ -192,12 +195,12 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Stores this rotation value into the given Quaternion. If quat is null, a
-     * new Quaternion is created to hold the value. The value, once stored, is
-     * returned.
+     * Copies the rotation component to the argument. If the argument is null, a
+     * new Quaternion is created to hold the value. Either way, the current
+     * instance is unaffected.
      *
-     * @param quat The store location for this transform's rotation.
-     * @return The value of this transform's rotation.
+     * @param quat storage for the result (modified if not null)
+     * @return the rotation value (either <code>quat</code> or a new Quaternion)
      */
     public Quaternion getRotation(Quaternion quat) {
         if (quat == null) {
@@ -208,21 +211,21 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Return the rotation quaternion in this Transform.
+     * Returns the rotation component.
      *
-     * @return rotation quaternion.
+     * @return the pre-existing instance (not null)
      */
     public Quaternion getRotation() {
         return rot;
     }
 
     /**
-     * Stores this scale value into the given vector3f. If scale is null, a new
-     * vector3f is created to hold the value. The value, once stored, is
-     * returned.
+     * Copies the scaling component to the argument. If the argument is null, a
+     * new Vector3f is created to hold the value. Either way, the current
+     * instance is unaffected, unless the argument is its translation component.
      *
-     * @param scale The store location for this transform's scale.
-     * @return The value of this transform's scale.
+     * @param scale storage for the result (modified if not null)
+     * @return the scale factors (either <code>scale</code> or a new Vector3f)
      */
     public Vector3f getScale(Vector3f scale) {
         if (scale == null) {
@@ -233,27 +236,30 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Sets this transform to the interpolation between the first transform and
-     * the second by delta amount.
+     * Interpolates quickly between the specified transforms, using
+     * {@link Quaternion#nlerp(com.jme3.math.Quaternion, float)} and
+     * {@link Vector3f#interpolateLocal(com.jme3.math.Vector3f, com.jme3.math.Vector3f, float)}.
      *
-     * @param t1 The beginning transform.
-     * @param t2 The ending transform.
-     * @param delta An amount between 0 and 1 representing how far to
-     * interpolate from t1 to t2.
+     * @param t1 the desired value when <code>delta</code>=0 (not null,
+     *     unaffected unless it's <code>this</code>)
+     * @param t2 the desired value when <code>delta</code>=1 (not null,
+     *     unaffected unless it's <code>this</code>)
+     * @param delta the fractional change amount
      */
     public void interpolateTransforms(Transform t1, Transform t2, float delta) {
-        this.rot.set(t1.rot); 
+        this.rot.set(t1.rot);
         this.rot.nlerp(t2.rot, delta);
         this.translation.interpolateLocal(t1.translation, t2.translation, delta);
         this.scale.interpolateLocal(t1.scale, t2.scale, delta);
     }
 
     /**
-     * Changes the values of this Transform according to its parent. Very similar
-     * to the concept of Node/Spatial transforms.
+     * Combines with the argument and returns the (modified) current instance.
+     * This method is used to combine Node and Spatial transforms.
      *
-     * @param parent The parent Transform.
-     * @return This Transform, after combining.
+     * @param parent the parent transform (not null, unaffected unless it's
+     *     <code>this</code>)
+     * @return the (modified) current instance (for chaining)
      */
     public Transform combineWithParent(Transform parent) {
         //applying parent scale to local scale
@@ -272,12 +278,12 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Sets this transform's translation to the given x,y,z values.
+     * Sets the translation component to the specified values.
      *
-     * @param x This transform's new x translation.
-     * @param y This transform's new y translation.
-     * @param z This transform's new z translation.
-     * @return this
+     * @param x the desired X offset
+     * @param y the desired Y offset
+     * @param z the desired Z offset
+     * @return the (modified) current instance (for chaining)
      */
     public Transform setTranslation(float x, float y, float z) {
         translation.set(x, y, z);
@@ -285,12 +291,12 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Sets this transform's scale to the given x,y,z values.
+     * Sets the scaling component to the specified values.
      *
-     * @param x This transform's new x scale.
-     * @param y This transform's new y scale.
-     * @param z This transform's new z scale.
-     * @return this
+     * @param x the desired X scale factor
+     * @param y the desired Y scale factor
+     * @param z the desired Z scale factor
+     * @return the (modified) current instance (for chaining)
      */
     public Transform setScale(float x, float y, float z) {
         scale.set(x, y, z);
@@ -298,11 +304,15 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Transform the specified coordinates.
+     * Transforms the specified coordinates and returns the result in
+     * <code>store</code>. If the <code>store</code> is null, a new Vector3f is
+     * created to hold the value. Either way, the current instance is
+     * unaffected, unless <code>store</code> is its translation or scaling.
      *
      * @param in the coordinates to transform (not null, unaffected)
      * @param store storage for the result (modified if not null)
-     * @return the transformed coordinates (either store or a new vector)
+     * @return the transformed coordinates (either <code>store</code> or a new
+     *     Vector3f)
      */
     public Vector3f transformVector(final Vector3f in, Vector3f store) {
         if (store == null) {
@@ -315,11 +325,17 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Apply the inverse transform to the specified coordinates.
+     * Applies the inverse transform to the specified coordinates and returns
+     * the result in <code>store</code>. If the <code>store</code> is null, a
+     * new Vector3f is created to hold the value. Either way, the current
+     * instance is unaffected, unless <code>store</code> is its translation or
+     * scaling.
      *
-     * @param in the coordinates to transform (not null, unaffected)
+     * @param in the coordinates to transform (not null, unaffected unless it's
+     *     <code>store</code>)
      * @param store storage for the result (modified if not null)
-     * @return the transformed coordinates (either store or a new vector)
+     * @return the transformed coordinates (either <code>store</code> or a new
+     *     Vector3f)
      */
     public Vector3f transformInverseVector(final Vector3f in, Vector3f store) {
         if (store == null) {
@@ -338,19 +354,21 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Create an equivalent transform matrix.
+     * Creates an equivalent transform matrix. The current instance is
+     * unaffected.
      *
-     * @return a new 4x4 matrix
+     * @return a new Matrix4f
      */
     public Matrix4f toTransformMatrix() {
         return toTransformMatrix(null);
     }
 
     /**
-     * Convert to an equivalent transform matrix.
+     * Converts to an equivalent transform matrix. The current instance is
+     * unaffected.
      *
      * @param store storage for the result (modified if not null)
-     * @return a 4x4 matrix (either store or a new vector)
+     * @return a transform matrix (either <code>store</code> or a new Matrix4f)
      */
     public Matrix4f toTransformMatrix(Matrix4f store) {
         if (store == null) {
@@ -363,7 +381,9 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Configure based on a transform matrix.
+     * Sets the current instance from a transform matrix. Any shear in the
+     * matrix is lost -- in other words, it may not be possible to recreate the
+     * original matrix from the result.
      *
      * @param mat the input matrix (not null, unaffected)
      */
@@ -376,9 +396,9 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Create an inverse of this Transform.
+     * Returns the inverse. The current instance is unaffected.
      *
-     * @return a new instance
+     * @return a new Transform
      */
     public Transform invert() {
         Transform t = new Transform();
@@ -387,7 +407,8 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Loads the identity.  Equal to translation=0,0,0 scale=1,1,1 rot=0,0,0,1.
+     * Sets the current instance to the identity transform: translation=(0,0,0)
+     * scaling=(1,1,1) rotation=(0,0,0,1).
      */
     public void loadIdentity() {
         translation.set(0, 0, 0);
@@ -396,9 +417,9 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Test for exact identity.
+     * Tests for exact identity. The current instance is unaffected.
      *
-     * @return true if exactly equal to {@link #IDENTITY}, otherwise false
+     * @return true if equal to {@link #IDENTITY}, otherwise false
      */
     public boolean isIdentity() {
         return translation.x == 0f && translation.y == 0f && translation.z == 0f
@@ -407,7 +428,8 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Generate the hash code for this instance.
+     * Returns a hash code. If two transforms are logically equivalent, they
+     * will return the same hash code. The current instance is unaffected.
      *
      * @return a 32-bit value for use in hashing
      */
@@ -421,7 +443,8 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Test for exact equality with another object.
+     * Tests for exact equality with the argument, distinguishing -0 from 0. The
+     * current instance is unaffected.
      *
      * @param obj the object to compare to (may be null, unaffected)
      * @return true if the objects are exactly equal, otherwise false
@@ -441,13 +464,14 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Represent this Transform as a String. The format is:
+     * Returns a string representation. The current instance is unaffected. The
+     * format is:
      *
      * [TX.XXXX, TY.YYYY, TZ.ZZZZ]
      * [RX.XXXX, RY.YYYY, RZ.ZZZZ, RW.WWWW]
      * [SX.XXXX, SY.YYYY, SZ.ZZZZ]
      *
-     * @return a descriptive string of text (not null, not empty)
+     * @return the string representation (not null, not empty)
      */
     @Override
     public String toString() {
@@ -458,10 +482,10 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Sets this Transform to be equal to the given Transform.
+     * Copies all 3 components from the argument.
      *
-     * @param matrixQuat The Transform to be equal to.
-     * @return this
+     * @param matrixQuat The Transform to copy (not null, unaffected)
+     * @return the (modified) current instance (for chaining)
      */
     public Transform set(Transform matrixQuat) {
         this.translation.set(matrixQuat.translation);
@@ -471,8 +495,8 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Serialize this transform to the specified exporter, for example when
-     * saving to a J3O file.
+     * Serializes to the argument, for example when saving to a J3O file. The
+     * current instance is unaffected.
      *
      * @param e (not null)
      * @throws IOException from the exporter
@@ -486,8 +510,8 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * De-serialize this transform from the specified importer, for example
-     * when loading from a J3O file.
+     * De-serializes from the argument, for example when loading from a J3O
+     * file.
      *
      * @param e (not null)
      * @throws IOException from the importer
@@ -502,9 +526,9 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Create a copy of this Transform.
+     * 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 Transform clone() {