clarify javadoc (#1713)

* clarify javadoc

* more javadoc clarification

* ListSort: more javadpc

* more javadoc refinements

* ConstantVerifierState:  "it's" -> "its"

Author: stephengold

jme3-android/src/main/java/com/jme3/util/AndroidBufferAllocator.java

@@ -80,7 +80,7 @@ public class AndroidBufferAllocator implements BufferAllocator {
     }
 
     /**
-     * This function search the inner direct buffer of the android specific wrapped buffer classes
+     * Searches the inner direct buffer of the Android-specific wrapped buffer classes
      * and destroys it using the reflection allocator method.
      *
      * @param toBeDestroyed The direct buffer that will be "cleaned".

jme3-bullet/src/common/java/com/jme3/bullet/animation/BoneLink.java

@@ -110,9 +110,9 @@ protected BoneLink() {
      * created)
      * @param bone the linked bone (not null, alias created)
      * @param collisionShape the desired shape (not null, alias created)
-     * @param linkConfig the link configuration (not null)
+     * @param mass the desired mass (>0)
      * @param localOffset the location of the body's center (in the bone's local
-     * coordinates, not null, unaffected)
+     *     coordinates, not null, unaffected)
      */
     BoneLink(DacLinks control, Joint bone, CollisionShape collisionShape,
             float mass, Vector3f localOffset) {

jme3-bullet/src/common/java/com/jme3/bullet/animation/DacConfiguration.java

@@ -91,11 +91,11 @@ abstract public class DacConfiguration extends AbstractPhysicsControl {
      */
     private float torsoMass = 1f;
     /**
-     * map linked bone names to masses
+     * Maps linked bone names to masses.
      */
     private Map<String, Float> blConfigMap = new HashMap<>(50);
     /**
-     * map linked bone names to ranges of motion for createSpatialData()
+     * Maps linked bone names to ranges of motion for createSpatialData().
      */
     private Map<String, RangeOfMotion> jointMap = new HashMap<>(50);
     /**

jme3-bullet/src/common/java/com/jme3/bullet/animation/DacLinks.java

@@ -883,7 +883,7 @@ public void prePhysicsTick(PhysicsSpace space, float timeStep) {
      * Add joints to connect the named bone/torso link with each of its
      * children. Also fill in the boneLinkList. Note: recursive!
      *
-     * @param parentName the parent bone/torso link (not null)
+     * @param parentLink the parent bone/torso link (not null)
      */
     private void addJoints(PhysicsLink parentLink) {
         List<String> childNames = childNames(parentLink);

jme3-bullet/src/common/java/com/jme3/bullet/animation/PhysicsLink.java

@@ -579,7 +579,7 @@ public void write(JmeExporter ex) throws IOException {
     /**
      * Create and configure a rigid body for this link.
      *
-     * @param linkConfig the link configuration (not null)
+     * @param mass the desired mass (>0)
      * @param collisionShape the desired shape (not null, alias created)
      * @return a new instance, not in any PhysicsSpace
      */

jme3-bullet/src/common/java/com/jme3/bullet/control/BetterCharacterControl.java

@@ -56,18 +56,16 @@
 import java.util.logging.Logger;
 
 /**
- * This class is intended to replace the CharacterControl class.
+ * Intended to replace the CharacterControl class.
  * <p>
  * A rigid body with cylinder collision shape is used and its velocity is set
  * continuously. A ray test is used to test whether the character is on the
  * ground.
  * <p>
  * The character keeps their own local coordinate system which adapts based on
- * the gravity working on the character so they will always stand upright.
+ * the gravity working on the character, so it will always stand upright.
  * <p>
  * Motion in the local X-Z plane is damped.
- * <p>
- * This class is shared between JBullet and Native Bullet.
  *
  * @author normenhansen
  */

jme3-core/src/main/java/com/jme3/anim/Joint.java

@@ -115,7 +115,7 @@ public final void update() {
     }
 
     /**
-     * Updates the model transforms for this bone, and, possibly the attach node
+     * Updates the model transforms for this bone and for the attachments node
      * if not null.
      * <p>
      * The model transform of this bone is computed by combining the parent's

jme3-core/src/main/java/com/jme3/animation/Bone.java

@@ -837,8 +837,8 @@ void blendAnimTransforms(Vector3f translation, Quaternion rotation, Vector3f sca
     }
 
     /**
-     * Sets local bind transform for bone.
-     * Call setBindingPose() after all of the skeleton bones' bind transforms are set to save them.
+     * Sets the local bind transform of the bone.
+     * Call setBindingPose() after all of the bones' bind transforms are set to save them.
      *
      * @param translation the desired bind translation (not null, unaffected)
      * @param rotation the desired bind rotation (not null, unaffected)

jme3-core/src/main/java/com/jme3/app/Application.java

@@ -59,11 +59,11 @@ public interface Application {
     public LostFocusBehavior getLostFocusBehavior();
 
     /**
-     * Change the application's behavior when unfocused.
+     * Changes the application's behavior when unfocused.
      *
      * By default, the application will
      * {@link LostFocusBehavior#ThrottleOnLostFocus throttle the update loop}
-     * so as to not take 100% CPU usage when it is not in focus, e.g.
+     * so as not to use 100% of the CPU when it is out of focus, e.g.
      * alt-tabbed, minimized, or obstructed by another window.
      *
      * @param lostFocusBehavior The new lost focus behavior to use.
@@ -82,15 +82,15 @@ public interface Application {
     public boolean isPauseOnLostFocus();
 
     /**
-     * Enable or disable pause on lost focus.
+     * Enables or disables pause on lost focus.
      * <p>
      * By default, pause on lost focus is enabled.
      * If enabled, the application will stop updating
      * when it loses focus or becomes inactive (e.g. alt-tab).
      * For online or real-time applications, this might not be preferable,
-     * so this feature should be set to disabled. For other applications,
-     * it is best to keep it on so that CPU usage is not used when
-     * not necessary.
+     * so this feature should be disabled. For other applications,
+     * it is best to keep it enabled so that CPU is not used
+     * unnecessarily.
      *
      * @param pauseOnLostFocus True to enable pause on lost focus, false
      * otherwise.

jme3-core/src/main/java/com/jme3/app/LegacyApplication.java

@@ -134,12 +134,12 @@ public LostFocusBehavior getLostFocusBehavior() {
     }
 
     /**
-     * Change the application's behavior when unfocused.
+     * Changes the application's behavior when unfocused.
      *
      * By default, the application will
      * {@link LostFocusBehavior#ThrottleOnLostFocus throttle the update loop}
-     * so as to not take 100% CPU usage when it is not in focus, e.g.
-     * alt-tabbed, minimized, or obstructed by another window.
+     * so as not to use 100% of the CPU when out of focus, e.g.
+     * alt-tabbed, minimized, or hidden by another window.
      *
      * @param lostFocusBehavior The new lost focus behavior to use.
      *
@@ -168,10 +168,9 @@ public boolean isPauseOnLostFocus() {
      * By default, pause on lost focus is enabled.
      * If enabled, the application will stop updating
      * when it loses focus or becomes inactive (e.g. alt-tab).
-     * For online or real-time applications, this might not be preferable,
-     * so this feature should be set to disabled. For other applications,
-     * it is best to keep it on so that CPU usage is not used when
-     * not necessary.
+     * For online or real-time applications, this might be undesirable,
+     * so this feature should be disabled. For other applications,
+     * it is best to keep it enabled so the CPU is not used unnecessarily.
      *
      * @param pauseOnLostFocus True to enable pause on lost focus, false
      * otherwise.