jme3-core: correct/clarify javadoc

jMonkeyEngine · Dec 13, 2022 · 9d5eeee · 9d5eeee
1 parent 076f249
commit 9d5eeee
Show file tree

Hide file tree

Showing 9 changed files with 235 additions and 197 deletions.
diff --git a/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java b/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java
@@ -114,7 +114,7 @@ protected float getTransitionWeight() {
     }
 
     /**
-     * @param maxTransitionWeight The max transition weight. Must be &gt= 0 and &lt=1 (default=1)
+     * @param maxTransitionWeight The max transition weight. Must be &gt;0 and &lt;1 (default=1)
      */
     public void setMaxTransitionWeight(double maxTransitionWeight) {
         assert maxTransitionWeight >= 0 && maxTransitionWeight <= 1;

diff --git a/jme3-core/src/main/java/com/jme3/material/RenderState.java b/jme3-core/src/main/java/com/jme3/material/RenderState.java
@@ -311,7 +311,6 @@ public enum BlendMode {
          * Result.rgb = Source Alpha * Source Color +
          *          (1 - Source Alpha) * Dest Color -&gt; (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA)
          * Result.a = 1 * Source Alpha + 1 * Dest Alpha -&gt; (GL_ONE, GL_ONE)
-         * 
          */
         AlphaSumA,
         /**
@@ -600,9 +599,12 @@ public RenderState clone() {
     }
 
     /**
-     * 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 void setWireframe(boolean wireframe) {
      * @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 void setStencil(boolean enabled,
     /**
      * 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 void setDepthFunc(TestFunction depthFunc) {
      * 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 TestFunction getBackStencilFunction() {
     }
 
     /**
-     * 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 BlendEquation getBlendEquation() {
     }
 
     /**
-     * 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 BlendEquationAlpha getBlendEquationAlpha() {
     }
 
     /**
-     * Retrieve the blend mode.
+     * Returns the blend mode.
      *
      * @return the blend mode.
      */
@@ -1244,7 +1258,7 @@ public BlendMode getBlendMode() {
     }
 
     /**
-     * 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 BlendFunc getCustomSfactorRGB() {
     }
 
     /**
-     * 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 BlendFunc getCustomDfactorRGB() {
     }
 
     /**
-     * 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 BlendFunc getCustomSfactorAlpha() {
     }
 
     /**
-     * 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.

diff --git a/jme3-core/src/main/java/com/jme3/math/Matrix3f.java b/jme3-core/src/main/java/com/jme3/math/Matrix3f.java
@@ -767,7 +767,8 @@ public void loadIdentity() {
     /**
      * 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 Matrix3f transposeNew() {
 
     /**
      * 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 Matrix3f transposeNew() {
      * ]
      * </pre>
      *
-     * @return the string representation
+     * @return the string representation (not null, not empty)
      */
     @Override
     public String toString() {
@@ -1217,10 +1218,10 @@ public String toString() {
     }
 
     /**
-     * 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 int hashCode() {
     }
 
     /**
-     * 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) {