jme3-core: document a few places where normalization is assumed (#2026)

* jme3-core:  document a few places where normalization is assumed

* Spatial:  document the assumption in setLocalRotation()

* Spatial:  document the argument to setLocalTransform()

* javadoc:  say "approximately equal to 1"

* document assumptions of transformVector() and transformInverseVector()

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

@@ -1095,6 +1095,10 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * Rotates the argument vector and returns the result as a new vector. The
      * current instance is unaffected.
      *
+     * <p>The quaternion is assumed to be normalized (norm=1). No error checking
+     * is performed; the caller must ensure that the norm is approximately equal
+     * to 1.
+     *
      * <p>Despite the name, the result differs from the mathematical definition
      * of vector-quaternion multiplication.
      *
@@ -1109,6 +1113,10 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * Rotates the argument vector. Despite the name, the current instance is
      * unaffected.
      *
+     * <p>The quaternion is assumed to be normalized (norm=1). No error checking
+     * is performed; the caller must ensure that the norm is approximately equal
+     * to 1.
+     *
      * <p>Despite the name, the result differs from the mathematical definition
      * of vector-quaternion multiplication.
      *
@@ -1177,6 +1185,10 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * Rotates a specified vector and returns the result in another vector. The
      * current instance is unaffected.
      *
+     * <p>The quaternion is assumed to be normalized (norm=1). No error checking
+     * is performed; the caller must ensure that the norm is approximately equal
+     * to 1.
+     *
      * <p>It is safe for {@code v} and {@code store} to be the same object.
      *
      * <p>Despite the name, the result differs from the mathematical definition

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2022 jMonkeyEngine
+ * Copyright (c) 2009-2023 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -257,8 +257,8 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
      * 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 (not null, unaffected unless it's
-     *     <code>this</code>)
+     * @param parent the parent transform (not null, {@code parent.rot.norm()}
+     *     approximately equal to 1, unaffected unless it's <code>this</code>)
      * @return the (modified) current instance (for chaining)
      */
     public Transform combineWithParent(Transform parent) {
@@ -308,6 +308,10 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
      * <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.
+     * <p>
+     * The transform's quaternion is assumed to be normalized. No error checking
+     * is performed; the caller should ensure that {@code rot.norm()} is
+     * approximately equal to 1.
      *
      * @param in the coordinates to transform (not null, unaffected)
      * @param store storage for the result (modified if not null)
@@ -330,6 +334,10 @@ public final class Transform implements Savable, Cloneable, java.io.Serializable
      * new Vector3f is created to hold the value. Either way, the current
      * instance is unaffected, unless <code>store</code> is its translation or
      * scaling.
+     * <p>
+     * The transform's quaternion is assumed to be normalized. No error checking
+     * is performed; the caller should ensure that {@code rot.norm()} is
+     * approximately equal to 1.
      *
      * @param in the coordinates to transform (not null, unaffected unless it's
      *     <code>store</code>)

jme3-core/src/main/java/com/jme3/scene/Spatial.java

@@ -1063,8 +1063,8 @@ public abstract class Spatial implements Savable, Cloneable, Collidable,
     /**
      * <code>setLocalRotation</code> sets the local rotation of this node.
      *
-     * @param quaternion
-     *            the new local rotation.
+     * @param quaternion the new local rotation (not null,
+     *     {@code quaternion.norm()} approximately equal to 1, unaffected)
      */
     public void setLocalRotation(Quaternion quaternion) {
         localTransform.setRotation(quaternion);
@@ -1152,6 +1152,9 @@ public abstract class Spatial implements Savable, Cloneable, Collidable,
     /**
      * <code>setLocalTransform</code> sets the local transform of this
      * spatial.
+     *
+     * @param t the desired local transform (not null, {@code t.rot.norm()}
+     *     approximately equal to 1, unaffected)
      */
     @Override
     public void setLocalTransform(Transform t) {