jme3-core: correct/clarify javadoc

jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java

@@ -114,7 +114,7 @@ public abstract class BlendableAction extends Action {
     }
 
     /**
-     * @param maxTransitionWeight The max transition weight. Must be &gt= 0 and &lt=1 (default=1)
+     * @param maxTransitionWeight The max transition weight. Must be >0 and <1 (default=1)
      */
     public void setMaxTransitionWeight(double maxTransitionWeight) {
         assert maxTransitionWeight >= 0 && maxTransitionWeight <= 1;

jme3-core/src/main/java/com/jme3/material/RenderState.java

@@ -311,7 +311,6 @@ public class RenderState implements Cloneable, Savable {
          * Result.rgb = Source Alpha * Source Color +
          *          (1 - Source Alpha) * Dest Color -> (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA)
          * Result.a = 1 * Source Alpha + 1 * Dest Alpha -> (GL_ONE, GL_ONE)
-         * 
          */
         AlphaSumA,
         /**
@@ -600,9 +599,12 @@ public class RenderState implements Cloneable, Savable {
     }
 
     /**
-     * returns true if the given renderState is equal to this one
-     * @param o the renderState to compare to
-     * @return true if the renderStates are equal
+     * Tests for equivalence with the argument. If {@code o} is null, false is
+     * returned. Either way, the current instance is unaffected.
+     *
+     * @param o the object to compare (may be null, unaffected)
+     * @return true if {@code this} and {@code o} are equivalent,
+     *     otherwise false
      */
     @Override
     public boolean equals(Object o) {
@@ -901,7 +903,7 @@ public class RenderState implements Cloneable, Savable {
      * @see <a href="http://www.opengl.org/resources/faq/technical/polygonoffset.htm">http://www.opengl.org/resources/faq/technical/polygonoffset.htm</a>
      * @param factor scales the maximum Z slope, with respect to X or Y of the polygon
      * @param units scales the minimum resolvable depth buffer value
-     **/
+     */
     public void setPolyOffset(float factor, float units) {
         applyPolyOffset = true;
         if (factor == 0 && units == 0) {
@@ -966,6 +968,7 @@ public class RenderState implements Cloneable, Savable {
     /**
      * Set the depth comparison function to the given TestFunction
      * default is LessOrEqual (GL_LEQUAL)
+     *
      * @see TestFunction
      * @see RenderState#setDepthTest(boolean) 
      * @param depthFunc the depth comparison function
@@ -980,6 +983,7 @@ public class RenderState implements Cloneable, Savable {
      * Sets the mesh line width.
      * Use this in conjunction with {@link #setWireframe(boolean)} or with a mesh in
      * {@link com.jme3.scene.Mesh.Mode#Lines} mode.
+     *
      * @param lineWidth the line width.
      */
     public void setLineWidth(float lineWidth) {
@@ -1153,71 +1157,81 @@ public class RenderState implements Cloneable, Savable {
     }
 
     /**
-     * Sets the front stencil mask
-     * @param frontStencilMask
+     * Sets the front stencil mask.
+     *
+     * @param frontStencilMask the desired bitmask (default=0x7fffffff)
      */
     public void setFrontStencilMask(int frontStencilMask) {
         this.frontStencilMask = frontStencilMask;
     }
 
     /**
-     *  Sets the back stencil mask
-     * @param backStencilMask
+     * Sets the back stencil mask.
+     *
+     * @param backStencilMask the desired bitmask (default=0x7fffffff)
      */
     public void setBackStencilMask(int backStencilMask) {
         this.backStencilMask = backStencilMask;
     }
 
     /**
-     * Sets the front stencil reference
-     * @param frontStencilReference
+     * Sets the front stencil reference.
+     *
+     * @param frontStencilReference the desired reference (default=0x0)
      */
     public void setFrontStencilReference(int frontStencilReference) {
         this.frontStencilReference = frontStencilReference;
     }
 
     /**
-     *  Sets the back stencil reference
-     * @param backStencilReference
+     * Sets the back stencil reference.
+     *
+     * @param backStencilReference the desired bitmask (default=0x0)
      */
     public void setBackStencilReference(int backStencilReference) {
         this.backStencilReference = backStencilReference;
     }
 
     /**
-     * Returns the front stencil mask
-     * @return
+     * Returns the front stencil mask.
+     *
+     * @return the bitmask applied before comparing the front stencil to its
+     *     reference value
      */
     public int getFrontStencilMask() {
         return frontStencilMask;
     }
 
     /**
-     * Returns the front stencil reference
-     * @return
+     * Returns the front stencil reference.
+     *
+     * @return the reference value for the front stencil
      */
     public int getFrontStencilReference() {
         return frontStencilReference;
     }
 
     /**
-     * Returns the back stencil mask
-     * @return
+     * Returns the back stencil mask.
+     *
+     * @return the bitmask applied before comparing the back stencil to its
+     *     reference value
      */
     public int getBackStencilMask() {
         return backStencilMask;
     }
 
     /**
-     * Returns the back stencil reference
-     * @return
+     * Returns the back stencil reference.
+     *
+     * @return the reference value for the back stencil
      */
     public int getBackStencilReference() {
         return backStencilReference;
     }
 
     /**
-     * Retrieve the blend equation.
+     * Returns the blend equation.
      *
      * @return the blend equation.
      */
@@ -1226,7 +1240,7 @@ public class RenderState implements Cloneable, Savable {
     }
     
     /**
-     * Retrieve the blend equation used for the alpha component.
+     * Returns the blend equation used for the alpha component.
      *
      * @return the blend equation for the alpha component.
      */
@@ -1235,7 +1249,7 @@ public class RenderState implements Cloneable, Savable {
     }
 
     /**
-     * Retrieve the blend mode.
+     * Returns the blend mode.
      *
      * @return the blend mode.
      */
@@ -1244,7 +1258,7 @@ public class RenderState implements Cloneable, Savable {
     }
     
     /**
-     * Provides the source factor for the RGB components in 
+     * Returns the source factor for the RGB components in
      * <code>BlendMode.Custom</code>.
      * 
      * @return the custom source factor for RGB components.
@@ -1254,7 +1268,7 @@ public class RenderState implements Cloneable, Savable {
     }
     
     /**
-     * Provides the destination factor for the RGB components in 
+     * Returns the destination factor for the RGB components in
      * <code>BlendMode.Custom</code>.
      * 
      * @return the custom destination factor for RGB components.
@@ -1264,7 +1278,7 @@ public class RenderState implements Cloneable, Savable {
     }
     
     /**
-     * Provides the source factor for the alpha component in 
+     * Returns the source factor for the alpha component in
      * <code>BlendMode.Custom</code>.
      * 
      * @return the custom destination factor for alpha component.
@@ -1274,7 +1288,7 @@ public class RenderState implements Cloneable, Savable {
     }
     
     /**
-     * Provides the destination factor for the alpha component in 
+     * Returns the destination factor for the alpha component in
      * <code>BlendMode.Custom</code>.
      * 
      * @return the custom destination factor for alpha component.

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

@@ -767,7 +767,8 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     /**
      * Tests for exact identity. The matrix is unaffected.
      *
-     * @return true if equal to {@link #IDENTITY}, otherwise false
+     * @return true if all diagonals = 1 and all other elements = 0 or -0,
+     * otherwise false
      */
     public boolean isIdentity() {
         return (m00 == 1 && m01 == 0 && m02 == 0)
@@ -1177,7 +1178,7 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
 
     /**
      * Returns a string representation of the matrix, which is unaffected. For
-     * example, an identity matrix would be represented by:
+     * example, the identity matrix is represented by:
      * <pre>
      * Matrix3f
      * [
@@ -1187,7 +1188,7 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
      * ]
      * </pre>
      *
-     * @return the string representation
+     * @return the string representation (not null, not empty)
      */
     @Override
     public String toString() {
@@ -1217,10 +1218,10 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Returns a hash code. If two matrices are logically equivalent, they will
-     * return the same hash code. The current instance is unaffected.
+     * Returns a hash code. If two matrices have identical values, they will
+     * have the same hash code. The matrix is unaffected.
      *
-     * @return the hash-code value
+     * @return a 32-bit value for use in hashing
      * @see java.lang.Object#hashCode()
      */
     @Override
@@ -1242,11 +1243,13 @@ public final class Matrix3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Tests for exact equality with the argument, distinguishing -0 from 0. The
-     * current instance is unaffected.
+     * Tests for exact equality with the argument, distinguishing -0 from 0. If
+     * {@code o} is null, false is returned. Either way, the current instance is
+     * unaffected.
      *
      * @param o the object to compare (may be null, unaffected)
-     * @return true if equal, otherwise false
+     * @return true if {@code this} and {@code o} have identical values,
+     *     otherwise false
      */
     @Override
     public boolean equals(Object o) {

jme3-core/src/main/java/com/jme3/math/Matrix4f.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,15 +39,15 @@ import java.nio.FloatBuffer;
 import java.util.logging.Logger;
 
 /**
- * <code>Matrix4f</code> represents a single-precision 4x4 matrix for use as a
- * 3-D coordinate transform or perspective transform. It provides convenience
- * methods for loading data from many sources.
+ * A 4x4 matrix composed of 16 single-precision elements, used to represent
+ * linear or perspective transformations of 3-D coordinates.
  *
- * The rightmost column (column 3) stores the translation vector. Element
+ * <p>The rightmost column (column 3) stores the translation vector. Element
  * numbering is (row,column), so m03 is the row 0, column 3, which is the X
- * translation. This means that the implicit storage order is column-major.
- * However, the get() and set() functions on float arrays default to row-major
- * order!
+ * translation.
+ *
+ * <p>Methods with names ending in "Local" modify the current instance. They are
+ * used to avoid creating garbage.
  *
  * @author Mark Powell
  * @author Joshua Slack
@@ -58,67 +58,67 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
 
     private static final Logger logger = Logger.getLogger(Matrix4f.class.getName());
     /**
-     * the element in row 0, column 0
+     * The element in row 0, column 0.
      */
     public float m00;
     /**
-     * the element in row 0, column 1
+     * The element in row 0, column 1.
      */
     public float m01;
     /**
-     * the element in row 0, column 2
+     * The element in row 0, column 2.
      */
     public float m02;
     /**
-     * the element in row 0, column 3 (the X translation)
+     * The element in row 0, column 3 (the X translation).
      */
     public float m03;
     /**
-     * the element in row 1, column 0
+     * The element in row 1, column 0.
      */
     public float m10;
     /**
-     * the element in row 1, column 1
+     * The element in row 1, column 1.
      */
     public float m11;
     /**
-     * the element in row 1, column 2
+     * The element in row 1, column 2.
      */
     public float m12;
     /**
-     * the element in row 1, column 3 (the Y translation)
+     * The element in row 1, column 3 (the Y translation).
      */
     public float m13;
     /**
-     * the element in row 2, column 0
+     * The element in row 2, column 0.
      */
     public float m20;
     /**
-     * the element in row 2, column 1
+     * The element in row 2, column 1.
      */
     public float m21;
     /**
-     * the element in row 2, column 2
+     * The element in row 2, column 2.
      */
     public float m22;
     /**
-     * the element in row 2, column 3 (the Z translation)
+     * The element in row 2, column 3 (the Z translation).
      */
     public float m23;
     /**
-     * the element in row 3, column 0
+     * The element in row 3, column 0.
      */
     public float m30;
     /**
-     * the element in row 3, column 1
+     * The element in row 3, column 1.
      */
     public float m31;
     /**
-     * the element in row 3, column 2
+     * The element in row 3, column 2.
      */
     public float m32;
     /**
-     * the element in row 3, column 3
+     * The element in row 3, column 3.
      */
     public float m33;
     /**
@@ -131,8 +131,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     public static final Matrix4f IDENTITY = new Matrix4f();
 
     /**
-     * Create a <code>Matrix4f</code> initialized to identity (diagonals = 1,
-     * other elements = 0).
+     * Instantiates an identity matrix (diagonals = 1, other elements = 0).
      */
     public Matrix4f() {
         loadIdentity();
@@ -933,7 +932,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Load identity (diagonals = 1, other elements = 0).
+     * Configures as an identity matrix (diagonals = 1, other elements = 0).
      */
     public void loadIdentity() {
         m01 = m02 = m03 = 0.0f;
@@ -1040,9 +1039,9 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Multiply in place, by the specified scalar.
+     * Multiplies in place by the scalar argument.
      *
-     * @param scalar the scale factor to apply to all elements
+     * @param scalar the scaling factor to apply to all elements
      */
     public void multLocal(float scalar) {
         m00 *= scalar;
@@ -1541,9 +1540,10 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Invert in place.
+     * Inverts in place. If the current instance is singular, the matrix is
+     * zeroed.
      *
-     * @return this matrix (inverted)
+     * @return the (inverted) current instance (for chaining)
      */
     public Matrix4f invertLocal() {
 
@@ -1717,9 +1717,9 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Set all elements to zero.
+     * Sets all elements to zero.
      *
-     * @return this (zeroed)
+     * @return the (modified) current instance (for chaining)
      */
     public Matrix4f zero() {
         m00 = m01 = m02 = m03 = 0.0f;
@@ -1790,10 +1790,10 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Determine the translation component of this 3-D coordinate transform.
+     * Returns the translation component of the coordinate transform.
      *
      * @param vector storage for the result (not null, modified)
-     * @return vector
+     * @return the translation component (in {@code vector}) for chaining
      */
     public Vector3f toTranslationVector(Vector3f vector) {
         return vector.set(m03, m13, m23);
@@ -1811,10 +1811,10 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Determine the rotation component of this 3-D coordinate transform.
+     * Returns the rotation component of the coordinate transform.
      *
      * @param q storage for the result (not null, modified)
-     * @return q
+     * @return the rotation component (in {@code q}) for chaining
      */
     public Quaternion toRotationQuat(Quaternion q) {
         return q.fromRotationMatrix(m00, m01, m02, m10,
@@ -1831,7 +1831,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Determine the rotation component of this 3-D coordinate transform.
+     * Determines the rotation component of the coordinate transform.
      *
      * @param mat storage for the result (not null, modified)
      */
@@ -1859,10 +1859,10 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Determine the scale component of this 3-D coordinate transform.
+     * Determines the scale component of the coordinate transform.
      *
      * @param store storage for the result (not null, modified)
-     * @return store
+     * @return the scale factors (in {@code store}) for chaining
      */
     public Vector3f toScaleVector(Vector3f store) {
         float scaleX = (float) Math.sqrt(m00 * m00 + m10 * m10 + m20 * m20);
@@ -1873,7 +1873,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Alter the scale component of this 3-D coordinate transform.
+     * Alters the scale component of the coordinate transform.
      *
      * @param x the desired scale factor for the X axis
      * @param y the desired scale factor for the Y axis
@@ -1907,7 +1907,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Alter the scale component of this 3-D coordinate transform.
+     * Alters the scale component of the coordinate transform.
      *
      * @param scale the desired scale factors (not null, unaffected)
      */
@@ -1946,7 +1946,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Alter the translation component of this 3-D coordinate transform.
+     * Alters the translation component of the coordinate transform.
      *
      * @param translation the desired translation (not null, unaffected)
      */
@@ -2142,7 +2142,8 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Represent as a String. For example, identity would be represented by:
+     * Returns a string representation of the matrix, which is unaffected. For
+     * example, the identity matrix is represented by:
      * <pre>
      * Matrix4f
      * [
@@ -2153,7 +2154,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
      * ]
      * </pre>
      *
-     * @return the string representation of this object.
+     * @return the string representation (not null, not empty)
      */
     @Override
     public String toString() {
@@ -2198,11 +2199,10 @@ public final class Matrix4f 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 have identical values, they will
+     * have the same hash code. The matrix is unaffected.
      *
-     * @return the hashcode for this instance of Matrix4f.
+     * @return a 32-bit value for use in hashing
      * @see java.lang.Object#hashCode()
      */
     @Override
@@ -2232,10 +2232,13 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Test for equality with the specified object.
+     * Tests for exact equality with the argument, distinguishing -0 from 0. If
+     * {@code o} is null, false is returned. Either way, the current instance is
+     * unaffected.
      *
-     * @param o the object to compare, or null
-     * @return true if this and o are equal, otherwise false
+     * @param o the object to compare (may be null, unaffected)
+     * @return true if {@code this} and {@code o} have identical values,
+     *     otherwise false
      */
     @Override
     public boolean equals(Object o) {
@@ -2458,7 +2461,7 @@ public final class Matrix4f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Create a copy.
+     * Creates a copy. The current instance is unaffected.
      *
      * @return a new instance with the same element values
      */

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

@@ -103,7 +103,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
     }
 
     /**
-     * Instantiates a quaternion with specified components.
+     * Instantiates a quaternion with the specified components.
      *
      * @param x the desired X component
      * @param y the desired Y component
@@ -930,7 +930,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      *
      * @param q the quaternion to add (not null, unaffected unless it's
      *     {@code this})
-     * @return the (modified) current instance
+     * @return the (modified) current instance (for chaining)
      */
     public Quaternion addLocal(Quaternion q) {
         this.x += q.x;
@@ -994,7 +994,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * However, if {@code this} and {@code storeResult} are the same object, the result
      * is undefined.
      *
-     * @param q the right factor (not null, unaffected unless it's {@code res})
+     * @param q the right factor (not null, unaffected unless it's {@code storeResult})
      * @param storeResult storage for the product, or null for a new Quaternion
      * @return {@code this * q} (either {@code storeResult} or a new Quaternion)
      */
@@ -1348,13 +1348,13 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
     }
 
     /**
-     * Returns a string representation. The current instance is unaffected. The
-     * format is:
-     *
-     * <p>(X.XXXX, Y.YYYY, Z.ZZZZ, W.WWWW)
+     * Returns a string representation of the quaternion, which is unaffected.
+     * For example, the identity quaternion is represented by:
+     * <pre>
+     * (0.0, 0.0, 0.0, 1.0)
+     * </pre>
      *
-     * @return the string representation
-     * @see java.lang.Object#toString()
+     * @return the string representation (not null, not empty)
      */
     @Override
     public String toString() {
@@ -1362,11 +1362,13 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
     }
 
     /**
-     * Tests for exact equality with the argument, distinguishing -0 from 0. The
-     * current instance is unaffected.
+     * Tests for exact equality with the argument, distinguishing -0 from 0. If
+     * {@code o} is null, false is returned. Either way, the current instance is
+     * unaffected.
      *
      * @param o the object to compare (may be null, unaffected)
-     * @return true if equal, otherwise false
+     * @return true if {@code this} and {@code o} have identical values,
+     *     otherwise false
      */
     @Override
     public boolean equals(Object o) {
@@ -1425,10 +1427,10 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
     }
 
     /**
-     * Returns a hash code. If two quaternions are logically equivalent, they
-     * will return the same hash code. The current instance is unaffected.
+     * Returns a hash code. If two quaternions have identical values, they
+     * will have the same hash code. The current instance is unaffected.
      *
-     * @return the hash code value
+     * @return a 32-bit value for use in hashing
      * @see java.lang.Object#hashCode()
      */
     @Override

jme3-core/src/main/java/com/jme3/math/Transform.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
@@ -428,8 +428,8 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Returns a hash code. If two transforms are logically equivalent, they
-     * will return the same hash code. The current instance is unaffected.
+     * Returns a hash code. If two transforms have identical values, they
+     * will have the same hash code. The current instance is unaffected.
      *
      * @return a 32-bit value for use in hashing
      */
@@ -443,11 +443,13 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Tests for exact equality with the argument, distinguishing -0 from 0. The
-     * current instance is unaffected.
+     * Tests for exact equality with the argument, distinguishing -0 from 0. If
+     * {@code obj} is null, false is returned. Either way, 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
+     * @param obj the object to compare (may be null, unaffected)
+     * @return true if {@code this} and {@code obj} have identical values,
+     *     otherwise false
      */
     @Override
     public boolean equals(Object obj) {
@@ -464,12 +466,12 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Returns a string representation. The current instance is unaffected. The
-     * format is:
+     * Returns a string representation of the transform, which is unaffected.
+     * For example, the identity transform is represented by:
      * <pre>
-     * Transform[ TX.XXXX, TY.YYYY, TZ.ZZZZ]
-     * [ R.XXXX, R.YYYY, R.ZZZZ, R.WWWW]
-     * [ S.XXXX , S.YYYY, S.ZZZZ]
+     * Transform[ 0.0, 0.0, 0.0]
+     * [ 0.0, 0.0, 0.0, 1.0]
+     * [ 1.0 , 1.0, 1.0]
      * </pre>
      *
      * @return the string representation (not null, not empty)

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2022 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -37,33 +37,43 @@ import com.jme3.export.Savable;
 import java.io.IOException;
 
 /**
- * <code>Triangle</code> defines a triangle in terms of its vertex locations,
- * with auxiliary storage for its centroid, normal vector, projection, and
- * index.
+ * Describes a triangle in terms of its vertex locations, with auxiliary storage
+ * for its centroid, normal vector, projection, and index.
  *
  * @author Mark Powell
  * @author Joshua Slack
  */
 public class Triangle extends AbstractTriangle implements Savable, Cloneable, java.io.Serializable {
     static final long serialVersionUID = 1;
-
+    /**
+     * The location of the first vertex in winding order.
+     */
     private Vector3f pointA = new Vector3f();
+    /**
+     * The location of the 2nd vertex in winding order.
+     */
     private Vector3f pointB = new Vector3f();
+    /**
+     * The location of the 3rd vertex in winding order.
+     */
     private Vector3f pointC = new Vector3f();
     private transient Vector3f center;
     private transient Vector3f normal;
     private float projection;
+    /**
+     * The index of the triangle, used to identify it in an OBBTree.
+     */
     private int index;
 
     /**
-     * Instantiate a zero-size Triangle at the origin.
+     * Instantiate a zero-size triangle at the origin.
      */
     public Triangle() {
     }
 
     /**
-     * Instantiate a <Code>Triangle</code> with the specified vertex locations.
-     * Vertices should be listed in the desired winding order, typically
+     * Instantiates a triangle with the specified vertex locations. Vertices
+     * should be listed in the desired winding order, typically
      * counter-clockwise.
      *
      * @param p1 the location of the first vertex (not null, unaffected)
@@ -77,7 +87,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Access the location of the indexed vertex.
+     * Accesses the location of the indexed vertex.
      *
      * @param i the index of the vertex to access (0, 1, or 2)
      * @return a pre-existing location vector, or null if the index is invalid
@@ -96,7 +106,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Access the location of the first vertex.
+     * Accesses the location of the first vertex.
      *
      * @return the pre-existing location vector (not null)
      */
@@ -106,7 +116,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Access the location of the 2nd vertex.
+     * Accesses the location of the 2nd vertex.
      *
      * @return the pre-existing location vector (not null)
      */
@@ -116,7 +126,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Access the location of the 3rd vertex.
+     * Accesses the location of the 3rd vertex.
      *
      * @return the pre-existing location vector (not null)
      */
@@ -126,7 +136,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the location of the indexed vertex and delete the stored centroid
+     * Alters the location of the indexed vertex and deletes the stored centroid
      * and normal.
      *
      * @param i the index of the vertex to alter (0, 1, or 2)
@@ -150,7 +160,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the location of the indexed vertex and delete the stored centroid
+     * Alters the location of the indexed vertex and deletes the stored centroid
      * and normal.
      *
      * @param i the index of the vertex to alter (0, 1, or 2)
@@ -176,8 +186,8 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the location of the first vertex and delete the stored centroid and
-     * normal.
+     * Alters the location of the first vertex and deletes the stored centroid
+     * and normal.
      *
      * @param v the desired location (not null, unaffected)
      */
@@ -189,7 +199,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the location of the 2nd vertex and delete the stored centroid and
+     * Alters the location of the 2nd vertex and deletes the stored centroid and
      * normal.
      *
      * @param v the desired location (not null, unaffected)
@@ -202,7 +212,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the location of the 3rd vertex and delete the stored centroid and
+     * Alters the location of the 3rd vertex and deletes the stored centroid and
      * normal.
      *
      * @param v the desired location (not null, unaffected)
@@ -215,8 +225,8 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the locations of all 3 vertices and delete the stored centroid and
-     * normal.
+     * Alters the locations of all 3 vertices and deletes the stored centroid
+     * and normal.
      *
      * @param v1 the desired location of the first vertex (not null, unaffected)
      * @param v2 the desired location of the 2nd vertex (not null, unaffected)
@@ -233,7 +243,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Recalculate the stored centroid based on the current vertex locations.
+     * Recalculates the stored centroid based on the current vertex locations.
      */
     public void calculateCenter() {
         if (center == null) {
@@ -245,7 +255,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Recalculate the stored normal based on the current vertex locations.
+     * Recalculates the stored normal based on the current vertex locations.
      */
     public void calculateNormal() {
         if (normal == null) {
@@ -258,7 +268,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Access the stored centroid (the average of the 3 vertex locations)
+     * Accesses the stored centroid (the average of the 3 vertex locations)
      * calculating it if it is null.
      *
      * @return the coordinates of the center (an internal vector subject to
@@ -272,7 +282,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the stored centroid without affecting the stored normal or any
+     * Alters the stored centroid without affecting the stored normal or any
      * vertex locations.
      *
      * @param center the desired value (alias created if not null)
@@ -282,7 +292,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Access the stored normal, updating it if it is null.
+     * Accesses the stored normal, updating it if it is null.
      *
      * @return unit normal vector (an internal vector subject to re-use)
      */
@@ -294,7 +304,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the stored normal without affecting the stored centroid or any
+     * Alters the stored normal without affecting the stored centroid or any
      * vertex locations.
      *
      * @param normal the desired value (alias created if not null)
@@ -304,7 +314,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Read the projection of the vertices relative to the line origin.
+     * Returns the projection of the vertices relative to the line origin.
      *
      * @return the stored projection value
      */
@@ -313,7 +323,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the projection of the vertices relative to the line origin.
+     * Alters the projection of the vertices relative to the line origin.
      *
      * @param projection the desired projection value
      */
@@ -322,7 +332,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Read the index of this triangle, used to identify it in an OBBTree.
+     * Returns the index of this triangle, used to identify it in an OBBTree.
      *
      * @return the stored index
      */
@@ -331,7 +341,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Alter the index of this triangle, used to identify it in an OBBTree.
+     * Alters the index of this triangle, used to identify it in an OBBTree.
      *
      * @param index the desired index
      */
@@ -351,7 +361,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Serialize this triangle to the specified exporter, for example when
+     * Serializes this triangle to the specified exporter, for example when
      * saving to a J3O file.
      *
      * @param e (not null)
@@ -365,7 +375,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * De-serialize this triangle from the specified importer, for example when
+     * De-serializes this triangle from the specified importer, for example when
      * loading from a J3O file.
      *
      * @param importer (not null)
@@ -379,7 +389,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja
     }
 
     /**
-     * Create a copy of this triangle.
+     * Creates a copy of this triangle.
      *
      * @return a new instance, equivalent to this one
      */

jme3-core/src/main/java/com/jme3/math/Vector3f.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
@@ -37,7 +37,7 @@ import java.util.logging.Logger;
 
 /**
  * A vector composed of 3 single-precision components, used to represent
- * locations, offsets, and directions in 3-dimensional space.
+ * locations, offsets, velocities, and directions in 3-dimensional space.
  *
  * <p>Methods with names ending in "Local" modify the current instance. They are
  * used to cut down on the creation of new instances.
@@ -177,12 +177,12 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
 
     /**
      * Adds a specified vector and returns the sum in a 3rd vector. The current
-     * instance is unaffected unless it's <code>result</code>.
+     * instance is unaffected unless it's {@code result}.
      *
      * @param vec the vector to add (not null, unaffected unless it's
-     *     <code>result</code>)
+     *     {@code result})
      * @param result storage for the sum (not null)
-     * @return <code>result</code> (for chaining)
+     * @return {@code result} (for chaining)
      */
     public Vector3f add(Vector3f vec, Vector3f result) {
         result.x = x + vec.x;
@@ -195,7 +195,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * Adds the argument and returns the (modified) current instance. If the
      * argument is null, null is returned.
      *
-     * @param vec the vector to add (unaffected unless it's <code>this</code>)
+     * @param vec the vector to add (unaffected unless it's {@code this})
      *     or null for none
      * @return the (modified) current instance or null
      */
@@ -298,7 +298,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * new instance. The current instance is unaffected.
      *
      * @param v the right factor (not null, unaffected)
-     * @return <code>this</code> cross <code>v</code> (a new Vector3f)
+     * @return {@code this} cross {@code v} (a new Vector3f)
      */
     public Vector3f cross(Vector3f v) {
         return cross(v, null);
@@ -307,13 +307,13 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
     /**
      * Calculates a cross product with a specified vector and returns the
      * product in a 3rd vector. The current instance is unaffected unless it's
-     * <code>result</code>.
+     * {@code result}.
      *
      * @param v the right factor (not null, unaffected unless it's
-     *     <code>result</code>)
+     *     {@code result})
      * @param result storage for the product, or null for a new Vector3f
-     * @return <code>this</code> cross <code>v</code> (either
-     *     <code>result</code> or a new Vector3f)
+     * @return {@code this} cross {@code v} (either {@code result} or a new
+     *     Vector3f)
      */
     public Vector3f cross(Vector3f v, Vector3f result) {
         return cross(v.x, v.y, v.z, result);
@@ -322,14 +322,14 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
     /**
      * Calculates a cross product with specified components and returns the
      * product in the specified vector. The current instance is unaffected
-     * unless it's <code>result</code>.
+     * unless it's {@code result}.
      *
      * @param otherX the X component of the right factor
      * @param otherY the Y component of the right factor
      * @param otherZ the Z component of the right factor
      * @param result storage for the product, or null for a new Vector3f
-     * @return <code>this</code> cross <code>v</code> (either
-     *     <code>result</code> or a new Vector3f)
+     * @return {@code this} cross (X,Y,Z) (either {@code result} or a new
+     *     Vector3f)
      */
     public Vector3f cross(float otherX, float otherY, float otherZ, Vector3f result) {
         if (result == null) {
@@ -489,11 +489,11 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
     /**
      * Multiplies with the specified scalar and returns the product in the
      * specified vector. The current instance is unaffected, unless it's
-     * <code>product</code>.
+     * {@code product}.
      *
      * @param scalar the scaling factor
      * @param product storage for the product, or null for a new Vector3f
-     * @return either <code>product</code> or a new Vector3f
+     * @return either {@code product} or a new Vector3f
      */
     public Vector3f mult(float scalar, Vector3f product) {
         if (null == product) {
@@ -523,7 +523,7 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * Multiplies component-wise by the argument and returns the (modified)
      * current instance. If the argument is null, null is returned.
      *
-     * @param vec the scale vector (unaffected unless it's <code>this</code>) or
+     * @param vec the scale vector (unaffected unless it's {@code this}) or
      *     null for none
      * @return the (modified) current instance (for chaining) or null
      */
@@ -587,12 +587,12 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * Multiplies component-wise with the specified vector and returns the
      * product in a 3rd vector. If the argument is null, null is returned.
      * Either way, the current instance is unaffected, unless it's
-     * <code>store</code>.
+     * {@code store}.
      *
-     * @param vec the scale vector (unaffected unless it's <code>store</code>)
+     * @param vec the scale vector (unaffected unless it's {@code store})
      *     or null for none
      * @param store storage for the product, or null for a new Vector3f
-     * @return either <code>store</code> or a new Vector3f or null
+     * @return either {@code store} or a new Vector3f or null
      */
     public Vector3f mult(Vector3f vec, Vector3f store) {
         if (null == vec) {
@@ -659,8 +659,8 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Divides component-wise by the specified components and returns the quotient
-     * as a new instance. The current instance is unaffected.
+     * Divides component-wise by the specified components and returns the
+     * quotient as a new instance. The current instance is unaffected.
      *
      * @param x the divisor for the X component
      * @param y the divisor for the Y component
@@ -675,7 +675,8 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * Divides component-wise by the argument and returns the (modified) current
      * instance.
      *
-     * @param divisor the divisor (not null, unaffected)
+     * @param divisor the divisor (not null, unaffected unless it's
+     * {@code this})
      * @return the (modified) current instance (for chaining)
      */
     public Vector3f divideLocal(Vector3f divisor) {
@@ -721,8 +722,8 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * Subtracts the argument and returns the (modified) current instance. If
      * the argument is null, null is returned.
      *
-     * @param vec the vector to subtract (unaffected unless it's
-     *     <code>this</code>) or null for none
+     * @param vec the vector to subtract (unaffected unless it's {@code this})
+     *     or null for none
      * @return the (modified) current instance or null
      */
     public Vector3f subtractLocal(Vector3f vec) {
@@ -739,12 +740,12 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
     /**
      * Subtracts the specified vector and returns the difference in a 3rd
      * vector. The current instance is unaffected unless it's
-     * <code>result</code>.
+     * {@code result}.
      *
      * @param vec the vector to subtract (not null, unaffected unless it's
-     *     <code>result</code>)
+     *     {@code result})
      * @param result storage for the difference, or null for a new Vector3f
-     * @return either <code>result</code> or a new Vector3f
+     * @return either {@code result} or a new Vector3f
      */
     public Vector3f subtract(Vector3f vec, Vector3f result) {
         if (result == null) {
@@ -1010,7 +1011,8 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
      * unaffected.
      *
      * @param o the object to compare (may be null, unaffected)
-     * @return true if equal, otherwise false
+     * @return true if {@code this} and {@code o} have identical values,
+     *     otherwise false
      */
     @Override
     public boolean equals(Object o) {
@@ -1061,10 +1063,10 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Returns a hash code. If two vectors are logically equivalent, they will
-     * return the same hash code. The current instance is unaffected.
+     * Returns a hash code. If two vectors have identical values, they will
+     * have the same hash code. The current instance is unaffected.
      *
-     * @return the hash code value
+     * @return a 32-bit value for use in hashing
      */
     @Override
     public int hashCode() {
@@ -1076,12 +1078,13 @@ public final class Vector3f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Returns a string representation. The current instance is unaffected. The
-     * format is:
-     *
-     * <p>(XX.XXXX, YY.YYYY, ZZ.ZZZZ)
+     * Returns a string representation of the vector, which is unaffected.
+     * For example, the +X direction vector is represented by:
+     * <pre>
+     * (1.0, 0.0, 0.0)
+     * </pre>
      *
-     * @return the string representation
+     * @return the string representation (not null, not empty)
      */
     @Override
     public String toString() {

jme3-core/src/main/java/com/jme3/system/JmeDialogsFactory.java

@@ -33,19 +33,20 @@ package com.jme3.system;
 
 public interface JmeDialogsFactory {
     /**
-     * Set a function to handler app settings. 
-     * The default implementation shows a settings dialog if available.
-     * @param handler handler function that accepts as argument an instance of AppSettings 
-     * to transform and a boolean with the value of true if the settings are expected to be loaded from 
-     * the user registry. The handler function returns false if the configuration is interrupted (eg.the the dialog was closed)
-     * or true otherwise.
+     * Set a function to handle app settings. The default implementation shows a
+     * settings dialog if available.
+     *
+     * @param settings the settings object to edit
+     * @param loadFromRegistry if true, copy the settings, otherwise merge them
+     * @return true to continue, false to exit the application
      */
     public boolean showSettingsDialog(AppSettings settings, boolean loadFromRegistry);    
 
     /**
-     * Set function to handle errors. 
-     * The default implementation show a dialog if available.
-     * @param handler Consumer to which the error is passed as String
+     * Set function to handle errors. The default implementation show a dialog
+     * if available.
+     *
+     * @param message text to be displayed in the dialog
      */
     public void showErrorDialog(String message);  
 }