From a5e0213b0155bc54c843982d8d2fcd6de348f12a Mon Sep 17 00:00:00 2001
From: Stephen Gold <sgold@sonic.net>
Date: Sat, 18 Apr 2020 16:40:02 -0700
Subject: [PATCH] add some more missing javadoc (11 files in com.jme3.math)

---
 .../src/main/java/com/jme3/math/Matrix4f.java | 12 +++
 .../src/main/java/com/jme3/math/Plane.java    | 12 +++
 .../src/main/java/com/jme3/math/Ray.java      |  6 ++
 .../main/java/com/jme3/math/Rectangle.java    | 19 ++++
 .../src/main/java/com/jme3/math/Ring.java     | 19 ++++
 .../src/main/java/com/jme3/math/Spline.java   | 14 +++
 .../main/java/com/jme3/math/Transform.java    | 19 ++++
 .../src/main/java/com/jme3/math/Triangle.java | 19 ++++
 .../src/main/java/com/jme3/math/Vector2f.java | 48 +++++++++-
 .../src/main/java/com/jme3/math/Vector3f.java | 79 +++++++++++++++-
 .../src/main/java/com/jme3/math/Vector4f.java | 93 ++++++++++++++++++-
 11 files changed, 337 insertions(+), 3 deletions(-)

diff --git a/jme3-core/src/main/java/com/jme3/math/Matrix4f.java b/jme3-core/src/main/java/com/jme3/math/Matrix4f.java
index 685244588..cda01ceb9 100644
--- a/jme3-core/src/main/java/com/jme3/math/Matrix4f.java
+++ b/jme3-core/src/main/java/com/jme3/math/Matrix4f.java
@@ -974,6 +974,18 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
         m00 = m11 = m22 = m33 = 1.0f;
     }
 
+    /**
+     * Configure this matrix to represent a perspective-view frustrum or
+     * rectangular solid with the specified clipping planes.
+     *
+     * @param near the coordinate of the near plane
+     * @param far the coordinate of the far plane
+     * @param left the coordinate of the left plane
+     * @param right the coordinate of the right plane
+     * @param top the coordinate of the top plane
+     * @param bottom the coordinate of the bottom plane
+     * @param parallel true &rarr; parallel sides, false &rarr; perspective
+     */
     public void fromFrustum(float near, float far, float left, float right,
             float top, float bottom, boolean parallel) {
         loadIdentity();
diff --git a/jme3-core/src/main/java/com/jme3/math/Plane.java b/jme3-core/src/main/java/com/jme3/math/Plane.java
index cf6f37054..5d522f750 100644
--- a/jme3-core/src/main/java/com/jme3/math/Plane.java
+++ b/jme3-core/src/main/java/com/jme3/math/Plane.java
@@ -52,9 +52,21 @@ public class Plane implements Savable, Cloneable, java.io.Serializable {
     private static final Logger logger = Logger
             .getLogger(Plane.class.getName());
 
+    /**
+     * Describe the relationship between a point and a plane.
+     */
     public static enum Side {
+        /**
+         * a point that lies in the plane
+         */
         None,
+        /**
+         * a point on the side with positive pseudo-distance
+         */
         Positive,
+        /**
+         * a point on the side with negative pseudo-distance
+         */
         Negative
     }
 
diff --git a/jme3-core/src/main/java/com/jme3/math/Ray.java b/jme3-core/src/main/java/com/jme3/math/Ray.java
index 681c986ba..4dbcadd60 100644
--- a/jme3-core/src/main/java/com/jme3/math/Ray.java
+++ b/jme3-core/src/main/java/com/jme3/math/Ray.java
@@ -405,6 +405,12 @@ public final class Ray implements Savable, Cloneable, Collidable, java.io.Serial
         }
     }
 
+    /**
+     * Calculate the squared distance from this ray to the specified point.
+     *
+     * @param point location vector of the input point (not null, unaffected)
+     * @return the square of the minimum distance (&ge;0)
+     */
     public float distanceSquared(Vector3f point) {
         TempVars vars = TempVars.get();
 
diff --git a/jme3-core/src/main/java/com/jme3/math/Rectangle.java b/jme3-core/src/main/java/com/jme3/math/Rectangle.java
index 1c26df847..7ddf0f3f6 100644
--- a/jme3-core/src/main/java/com/jme3/math/Rectangle.java
+++ b/jme3-core/src/main/java/com/jme3/math/Rectangle.java
@@ -156,6 +156,13 @@ public final class Rectangle implements Savable, Cloneable, java.io.Serializable
         return result;
     }
 
+    /**
+     * Serialize this rectangle 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);
@@ -164,6 +171,13 @@ public final class Rectangle implements Savable, Cloneable, java.io.Serializable
         capsule.write(c, "c", Vector3f.ZERO);
     }
 
+    /**
+     * De-serialize this rectangle 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);
@@ -172,6 +186,11 @@ public final class Rectangle implements Savable, Cloneable, java.io.Serializable
         c = (Vector3f) capsule.readSavable("c", Vector3f.ZERO.clone());
     }
 
+    /**
+     * Create a copy of this rectangle.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Rectangle clone() {
         try {
diff --git a/jme3-core/src/main/java/com/jme3/math/Ring.java b/jme3-core/src/main/java/com/jme3/math/Ring.java
index 838db5a12..c8d89428e 100644
--- a/jme3-core/src/main/java/com/jme3/math/Ring.java
+++ b/jme3-core/src/main/java/com/jme3/math/Ring.java
@@ -194,6 +194,13 @@ public final class Ring implements Savable, Cloneable, java.io.Serializable {
         return result;
     }
 
+    /**
+     * Serialize this ring 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);
@@ -203,6 +210,13 @@ public final class Ring implements Savable, Cloneable, java.io.Serializable {
         capsule.write(outerRadius, "outerRadius", 1f);
     }
 
+    /**
+     * De-serialize this ring 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);
@@ -212,6 +226,11 @@ public final class Ring implements Savable, Cloneable, java.io.Serializable {
         outerRadius = capsule.readFloat("outerRadius", 1f);
     }
 
+    /**
+     * Create a copy of this ring.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Ring clone() {
         try {
diff --git a/jme3-core/src/main/java/com/jme3/math/Spline.java b/jme3-core/src/main/java/com/jme3/math/Spline.java
index 054fd50c3..54365773d 100644
--- a/jme3-core/src/main/java/com/jme3/math/Spline.java
+++ b/jme3-core/src/main/java/com/jme3/math/Spline.java
@@ -454,6 +454,13 @@ public class Spline implements Savable {
         return basisFunctionDegree;
     }
 
+    /**
+     * Serialize this spline to the specified exporter, for example when
+     * saving to a J3O file.
+     *
+     * @param ex (not null)
+     * @throws IOException from the exporter
+     */
     @Override
     public void write(JmeExporter ex) throws IOException {
         OutputCapsule oc = ex.getCapsule(this);
@@ -478,6 +485,13 @@ public class Spline implements Savable {
         oc.write(basisFunctionDegree, "basisFunctionDegree", 0);
     }
 
+    /**
+     * De-serialize this spline from the specified importer, for example
+     * when loading from a J3O file.
+     *
+     * @param im (not null)
+     * @throws IOException from the importer
+     */
     @Override
     @SuppressWarnings("unchecked")
     public void read(JmeImporter im) throws IOException {
diff --git a/jme3-core/src/main/java/com/jme3/math/Transform.java b/jme3-core/src/main/java/com/jme3/math/Transform.java
index 0f1d9f992..e03fd4f4a 100644
--- a/jme3-core/src/main/java/com/jme3/math/Transform.java
+++ b/jme3-core/src/main/java/com/jme3/math/Transform.java
@@ -377,6 +377,13 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
         return this;
     }
 
+    /**
+     * Serialize this transform 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);
@@ -385,6 +392,13 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
         capsule.write(scale, "scale", Vector3f.UNIT_XYZ);
     }
 
+    /**
+     * De-serialize this transform 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);
@@ -394,6 +408,11 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
         scale.set((Vector3f) capsule.readSavable("scale", Vector3f.UNIT_XYZ));
     }
 
+    /**
+     * Create a copy of this transform.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Transform clone() {
         try {
diff --git a/jme3-core/src/main/java/com/jme3/math/Triangle.java b/jme3-core/src/main/java/com/jme3/math/Triangle.java
index e798f8aae..e87390c71 100644
--- a/jme3-core/src/main/java/com/jme3/math/Triangle.java
+++ b/jme3-core/src/main/java/com/jme3/math/Triangle.java
@@ -345,6 +345,13 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
         return store.normalizeLocal();
     }
 
+    /**
+     * Serialize this triangle 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 {
         e.getCapsule(this).write(pointa, "pointa", Vector3f.ZERO);
@@ -352,6 +359,13 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
         e.getCapsule(this).write(pointc, "pointc", Vector3f.ZERO);
     }
 
+    /**
+     * De-serialize this triangle 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 {
         pointa = (Vector3f) e.getCapsule(this).readSavable("pointa", Vector3f.ZERO.clone());
@@ -359,6 +373,11 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
         pointc = (Vector3f) e.getCapsule(this).readSavable("pointc", Vector3f.ZERO.clone());
     }
 
+    /**
+     * Create a copy of this triangle.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Triangle clone() {
         try {
diff --git a/jme3-core/src/main/java/com/jme3/math/Vector2f.java b/jme3-core/src/main/java/com/jme3/math/Vector2f.java
index 3a5b4bf8c..b90b788d3 100644
--- a/jme3-core/src/main/java/com/jme3/math/Vector2f.java
+++ b/jme3-core/src/main/java/com/jme3/math/Vector2f.java
@@ -46,8 +46,13 @@ import java.util.logging.Logger;
 public final class Vector2f implements Savable, Cloneable, java.io.Serializable {
     static final long serialVersionUID = 1;
     private static final Logger logger = Logger.getLogger(Vector2f.class.getName());
-
+    /**
+     * shared instance of the all-zero vector (0,0) - Do not modify!
+     */
     public static final Vector2f ZERO = new Vector2f(0f, 0f);
+    /**
+     * shared instance of the all-ones vector (1,1) - Do not modify!
+     */
     public static final Vector2f UNIT_XY = new Vector2f(1f, 1f);
     /**
      * the x value of the vector.
@@ -595,19 +600,41 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
         return angle;
     }
 
+    /**
+     * Determine the X component of this vector.
+     *
+     * @return x
+     */
     public float getX() {
         return x;
     }
 
+    /**
+     * Alter the X component of this vector.
+     *
+     * @param x the desired value
+     * @return this vector, modified
+     */
     public Vector2f setX(float x) {
         this.x = x;
         return this;
     }
 
+    /**
+     * Determine the Y component of this vector.
+     *
+     * @return y
+     */
     public float getY() {
         return y;
     }
 
+    /**
+     * Alter the Y component of this vector.
+     *
+     * @param y the desired value
+     * @return this vector, modified
+     */
     public Vector2f setY(float y) {
         this.y = y;
         return this;
@@ -649,6 +676,11 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
         return hash;
     }
 
+    /**
+     * Create a copy of this vector.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Vector2f clone() {
         try {
@@ -764,6 +796,13 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
         out.writeFloat(y);
     }
 
+    /**
+     * Serialize this vector 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);
@@ -771,6 +810,13 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
         capsule.write(y, "y", 0);
     }
 
+    /**
+     * De-serialize this vector 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);
diff --git a/jme3-core/src/main/java/com/jme3/math/Vector3f.java b/jme3-core/src/main/java/com/jme3/math/Vector3f.java
index 9e015053d..c1d52b40a 100644
--- a/jme3-core/src/main/java/com/jme3/math/Vector3f.java
+++ b/jme3-core/src/main/java/com/jme3/math/Vector3f.java
@@ -52,17 +52,42 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
 
     static final long serialVersionUID = 1;
     private static final Logger logger = Logger.getLogger(Vector3f.class.getName());
-
+    /**
+     * shared instance of the all-zero vector (0,0,0) - Do not modify!
+     */
     public final static Vector3f ZERO = new Vector3f(0, 0, 0);
+    /**
+     * shared instance of the all-NaN vector (NaN,NaN,NaN) - Do not modify!
+     */
     public final static Vector3f NAN = new Vector3f(Float.NaN, Float.NaN, Float.NaN);
+    /**
+     * shared instance of the +X direction (1,0,0) - Do not modify!
+     */
     public final static Vector3f UNIT_X = new Vector3f(1, 0, 0);
+    /**
+     * shared instance of the +Y direction (0,1,0) - Do not modify!
+     */
     public final static Vector3f UNIT_Y = new Vector3f(0, 1, 0);
+    /**
+     * shared instance of the +Z direction (0,0,1) - Do not modify!
+     */
     public final static Vector3f UNIT_Z = new Vector3f(0, 0, 1);
+    /**
+     * shared instance of the all-ones vector (1,1,1) - Do not modify!
+     */
     public final static Vector3f UNIT_XYZ = new Vector3f(1, 1, 1);
+    /**
+     * shared instance of the all-plus-infinity vector (+Inf,+Inf,+Inf)
+     * - Do not modify!
+     */
     public final static Vector3f POSITIVE_INFINITY = new Vector3f(
             Float.POSITIVE_INFINITY,
             Float.POSITIVE_INFINITY,
             Float.POSITIVE_INFINITY);
+    /**
+     * shared instance of the all-negative-infinity vector (-Inf,-Inf,-Inf)
+     * - Do not modify!
+     */
     public final static Vector3f NEGATIVE_INFINITY = new Vector3f(
             Float.NEGATIVE_INFINITY,
             Float.NEGATIVE_INFINITY,
@@ -917,6 +942,11 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
         }
     }
 
+    /**
+     * Create a copy of this vector.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Vector3f clone() {
         try {
@@ -1027,6 +1057,13 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
         return "(" + x + ", " + y + ", " + z + ")";
     }
 
+    /**
+     * Serialize this vector 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);
@@ -1035,6 +1072,13 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
         capsule.write(z, "z", 0);
     }
 
+    /**
+     * De-serialize this vector 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);
@@ -1043,28 +1087,61 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
         z = capsule.readFloat("z", 0);
     }
 
+    /**
+     * Determine the X component of this vector.
+     *
+     * @return x
+     */
     public float getX() {
         return x;
     }
 
+    /**
+     * Alter the X component of this vector.
+     *
+     * @param x the desired value
+     * @return this vector, modified
+     */
     public Vector3f setX(float x) {
         this.x = x;
         return this;
     }
 
+    /**
+     * Determine the Y component of this vector.
+     *
+     * @return y
+     */
     public float getY() {
         return y;
     }
 
+    /**
+     * Alter the Y component of this vector.
+     *
+     * @param y the desired value
+     * @return this vector, modified
+     */
     public Vector3f setY(float y) {
         this.y = y;
         return this;
     }
 
+    /**
+     * Determine the Z component of this vector.
+     *
+     * @return z
+     */
     public float getZ() {
         return z;
     }
 
+    /**
+     * Alter the Z component of this vector.
+     *
+     * @param z the desired value
+     * @return this vector, modified
+     */
     public Vector3f setZ(float z) {
         this.z = z;
         return this;
diff --git a/jme3-core/src/main/java/com/jme3/math/Vector4f.java b/jme3-core/src/main/java/com/jme3/math/Vector4f.java
index bf75f8795..d08aa7eba 100644
--- a/jme3-core/src/main/java/com/jme3/math/Vector4f.java
+++ b/jme3-core/src/main/java/com/jme3/math/Vector4f.java
@@ -48,19 +48,47 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
     static final long serialVersionUID = 1;
 
     private static final Logger logger = Logger.getLogger(Vector4f.class.getName());
-
+    /**
+     * shared instance of the all-zero vector (0,0,0,0) - Do not modify!
+     */
     public final static Vector4f ZERO = new Vector4f(0, 0, 0, 0);
+    /**
+     * shared instance of the all-NaN vector (NaN,NaN,NaN,NaN) - Do not modify!
+     */
     public final static Vector4f NAN = new Vector4f(Float.NaN, Float.NaN, Float.NaN, Float.NaN);
+    /**
+     * shared instance of the +X direction (1,0,0,0) - Do not modify!
+     */
     public final static Vector4f UNIT_X = new Vector4f(1, 0, 0, 0);
+    /**
+     * shared instance of the +Y direction (0,1,0,0) - Do not modify!
+     */
     public final static Vector4f UNIT_Y = new Vector4f(0, 1, 0, 0);
+    /**
+     * shared instance of the +Z direction (0,0,1,0) - Do not modify!
+     */
     public final static Vector4f UNIT_Z = new Vector4f(0, 0, 1, 0);
+    /**
+     * shared instance of the +W direction (0,0,0,1) - Do not modify!
+     */
     public final static Vector4f UNIT_W = new Vector4f(0, 0, 0, 1);
+    /**
+     * shared instance of the all-ones vector (1,1,1,1) - Do not modify!
+     */
     public final static Vector4f UNIT_XYZW = new Vector4f(1, 1, 1, 1);
+    /**
+     * shared instance of the all-plus-infinity vector (+Inf,+Inf,+Inf,+Inf)
+     * - Do not modify!
+     */
     public final static Vector4f POSITIVE_INFINITY = new Vector4f(
             Float.POSITIVE_INFINITY,
             Float.POSITIVE_INFINITY,
             Float.POSITIVE_INFINITY,
             Float.POSITIVE_INFINITY);
+    /**
+     * shared instance of the all-negative-infinity vector (-Inf,-Inf,-Inf,-Inf)
+     * - Do not modify!
+     */
     public final static Vector4f NEGATIVE_INFINITY = new Vector4f(
             Float.NEGATIVE_INFINITY,
             Float.NEGATIVE_INFINITY,
@@ -824,6 +852,11 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
         return true;
     }
 
+    /**
+     * Create a copy of this vector.
+     *
+     * @return a new instance, equivalent to this one
+     */
     @Override
     public Vector4f clone() {
         try {
@@ -942,6 +975,13 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
         return "(" + x + ", " + y + ", " + z + ", " + w + ")";
     }
 
+    /**
+     * Serialize this vector 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);
@@ -951,6 +991,13 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
         capsule.write(w, "w", 0);
     }
 
+    /**
+     * De-serialize this vector 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);
@@ -960,37 +1007,81 @@ public final class Vector4f implements Savable, Cloneable, java.io.Serializable
         w = capsule.readFloat("w", 0);
     }
 
+    /**
+     * Determine the X component of this vector.
+     *
+     * @return x
+     */
     public float getX() {
         return x;
     }
 
+    /**
+     * Alter the X component of this vector.
+     *
+     * @param x the desired value
+     * @return this vector, modified
+     */
     public Vector4f setX(float x) {
         this.x = x;
         return this;
     }
 
+    /**
+     * Determine the Y component of this vector.
+     *
+     * @return y
+     */
     public float getY() {
         return y;
     }
 
+    /**
+     * Alter the Y component of this vector.
+     *
+     * @param y the desired value
+     * @return this vector, modified
+     */
     public Vector4f setY(float y) {
         this.y = y;
         return this;
     }
 
+    /**
+     * Determine the Z component of this vector.
+     *
+     * @return z
+     */
     public float getZ() {
         return z;
     }
 
+    /**
+     * Alter the Z component of this vector.
+     *
+     * @param z the desired value
+     * @return this vector, modified
+     */
     public Vector4f setZ(float z) {
         this.z = z;
         return this;
     }
 
+    /**
+     * Determine the W component of this vector.
+     *
+     * @return w
+     */
     public float getW() {
         return w;
     }
 
+    /**
+     * Alter the W component of this vector.
+     *
+     * @param w the desired value
+     * @return this vector, modified
+     */
     public Vector4f setW(float w) {
         this.w = w;
         return this;