com.jme3.math: add/tweak some javadoc

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

@@ -171,9 +171,9 @@ public class Plane implements Savable, Cloneable, java.io.Serializable {
     /**
      * 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 point the location of the input point (not null, unaffected)
      * @param store storage for the result (not null, modified)
-     * @return a location in this plane (store)
+     * @return the location of the nearest point (store)
      */
     public Vector3f getClosestPoint(Vector3f point, Vector3f store) {
 //        float t = constant - normal.dot(point);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -37,8 +37,10 @@ import com.jme3.util.TempVars;
 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>
- * Represents a translation, rotation and scale in one object.
  *
  * @author Jack Lindamood
  * @author Joshua Slack
@@ -46,31 +48,67 @@ import java.io.IOException;
 public final class Transform implements Savable, Cloneable, java.io.Serializable {
 
     static final long serialVersionUID = 1;
-
+    /**
+     * shared instance of the identity transform - Do not modify!
+     */
     public static final Transform IDENTITY = new Transform();
-
+    /**
+     * rotation component
+     */
     private Quaternion rot = new Quaternion();
+    /**
+     * translation offsets for each axis
+     */
     private Vector3f translation = new Vector3f();
+    /**
+     * scale factors for each axis
+     */
     private Vector3f scale = new Vector3f(1, 1, 1);
 
+    /**
+     * Instantiate a coordinate transform without any scaling.
+     *
+     * @param translation the desired translation (not null, unaffected)
+     * @param rot the desired rotation (not null, unaffected)
+     */
     public Transform(Vector3f translation, Quaternion rot) {
         this.translation.set(translation);
         this.rot.set(rot);
     }
 
+    /**
+     * Instantiate 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)
+     */
     public Transform(Vector3f translation, Quaternion rot, Vector3f scale) {
         this(translation, rot);
         this.scale.set(scale);
     }
 
+    /**
+     * Instantiate a translation-only transform.
+     *
+     * @param translation the desired translation (not null, unaffected)
+     */
     public Transform(Vector3f translation) {
         this(translation, Quaternion.IDENTITY);
     }
 
+    /**
+     * Instantiate a rotation-only transform.
+     *
+     * @param rot the desired rotation (not null, unaffected)
+     */
     public Transform(Quaternion rot) {
         this(Vector3f.ZERO, rot);
     }
 
+    /**
+     * Instantiate an identity transform.
+     */
     public Transform() {
         this(Vector3f.ZERO, Quaternion.IDENTITY);
     }
@@ -259,6 +297,13 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
         return this;
     }
 
+    /**
+     * Transform the specified coordinates.
+     *
+     * @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)
+     */
     public Vector3f transformVector(final Vector3f in, Vector3f store) {
         if (store == null) {
             store = new Vector3f();
@@ -269,6 +314,13 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
         return rot.mult(store.set(in).multLocal(scale), store).addLocal(translation);
     }
 
+    /**
+     * Apply the inverse transform to the specified coordinates.
+     *
+     * @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)
+     */
     public Vector3f transformInverseVector(final Vector3f in, Vector3f store) {
         if (store == null) {
             store = new Vector3f();
@@ -285,10 +337,21 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
         return store;
     }
 
+    /**
+     * Create an equivalent transform matrix.
+     *
+     * @return a new 4x4 matrix
+     */
     public Matrix4f toTransformMatrix() {
         return toTransformMatrix(null);
     }
 
+    /**
+     * Convert to an equivalent transform matrix.
+     *
+     * @param store storage for the result (modified if not null)
+     * @return a 4x4 matrix (either store or a new vector)
+     */
     public Matrix4f toTransformMatrix(Matrix4f store) {
         if (store == null) {
             store = new Matrix4f();
@@ -299,6 +362,11 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
         return store;
     }
 
+    /**
+     * Configure based on a transform matrix.
+     *
+     * @param mat the input matrix (not null, unaffected)
+     */
     public void fromTransformMatrix(Matrix4f mat) {
         TempVars vars = TempVars.get();
         translation.set(mat.toTranslationVector(vars.vect1));
@@ -307,6 +375,11 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
         vars.release();
     }
 
+    /**
+     * Create an inverse of this Transform.
+     *
+     * @return a new instance
+     */
     public Transform invert() {
         Transform t = new Transform();
         t.fromTransformMatrix(toTransformMatrix().invertLocal());
@@ -333,6 +406,11 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
                 && rot.w == 1f && rot.x == 0f && rot.y == 0f && rot.z == 0f;
     }
 
+    /**
+     * Generate the hash code for this instance.
+     *
+     * @return a 32-bit value for use in hashing
+     */
     @Override
     public int hashCode() {
         int hash = 7;
@@ -342,6 +420,12 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
         return hash;
     }
 
+    /**
+     * Test for exact equality with another object.
+     *
+     * @param obj the object to compare to (may be null, unaffected)
+     * @return true if the objects are exactly equal, otherwise false
+     */
     @Override
     public boolean equals(Object obj) {
         if (obj == null) {
@@ -356,6 +440,15 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
                 && this.rot.equals(other.rot);
     }
 
+    /**
+     * Represent this Transform as a String. 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)
+     */
     @Override
     public String toString() {
         return getClass().getSimpleName()
@@ -409,9 +502,9 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Create a copy of this transform.
+     * Create a copy of this Transform.
      *
-     * @return a new instance, equivalent to this one
+     * @return a new instance equivalent to this one
      */
     @Override
     public Transform clone() {