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.

jme3-core/src/main/java/com/jme3/app/state/ConstantVerifierState.java

@@ -178,7 +178,7 @@ protected void checkValues() {
     }
 
     /**
-     *  Checks the specified 'constant' value against it's known good
+     *  Checks the specified 'constant' value against its known good
      *  value.  These should obviously be different instances for this to
      *  mean anything.
      */   

jme3-core/src/main/java/com/jme3/asset/AssetProcessor.java

@@ -45,7 +45,7 @@
  */
 public interface AssetProcessor {
     /**
-     * Applies post processing to an asset.
+     * Applies post-processing to an asset.
      * The method may return an object that is not the same
      * instance as the parameter object, and it could be from a different class.
      *

jme3-core/src/main/java/com/jme3/cinematic/Cinematic.java

@@ -54,7 +54,7 @@
 import java.util.logging.Logger;
 
 /**
- * An appstate for composing and playing cut scenes in a game. The cinematic
+ * An appstate for composing and playing cutscenes in a game. The cinematic
  * schedules CinematicEvents over a timeline. Once the Cinematic created it has
  * to be attached to the stateManager.
  *
@@ -71,16 +71,16 @@
  * Cinematic#enqueueCinematicEvent(com.jme3.cinematic.events.CinematicEvent)
  * that enqueue events one after the other according to their initialDuration
  *
- * a cinematic has convenient methods to handle the playback :
+ * A Cinematic has convenient methods to manage playback:
  * @see Cinematic#play()
  * @see Cinematic#pause()
  * @see Cinematic#stop()
  *
- * A cinematic is itself a CinematicEvent, meaning you can embed several
- * Cinematics. Embedded cinematics must not be added to the stateManager though.
+ * A Cinematic is itself a CinematicEvent, meaning you can embed several
+ * cinematics. Embedded cinematics must not be added to the stateManager though.
  *
- * Cinematic has a way to handle several point of view by creating CameraNode
- * over a cam and activating them on schedule.
+ * Cinematic can handle several points of view by creating camera nodes
+ * and activating them on schedule.
  * @see Cinematic#bindCamera(java.lang.String, com.jme3.renderer.Camera)
  * @see Cinematic#activateCamera(float, java.lang.String)
  * @see Cinematic#setActiveCamera(java.lang.String)
@@ -449,9 +449,8 @@ public KeyFrame addCinematicEvent(float timeStamp, CinematicEvent cinematicEvent
     }
 
     /**
-     * enqueue a cinematic event to a cinematic. This is a handy method when you
-     * want to chain event of a given duration without knowing their initial
-     * duration
+     * Enqueue a cinematic event to a Cinematic. This is handy when you
+     * want to chain events without knowing their durations.
      *
      * @param cinematicEvent the cinematic event to enqueue
      * @return the timestamp the event was scheduled.
@@ -715,7 +714,7 @@ public Node getScene() {
     }
 
     /**
-     * clear the cinematic of its events.
+     * Remove all events from the Cinematic.
      */
     public void clear() {
         dispose();

jme3-core/src/main/java/com/jme3/cinematic/events/AbstractCinematicEvent.java

@@ -92,6 +92,7 @@ public AbstractCinematicEvent(LoopMode loopMode) {
 
     /**
      * Construct a cinematic event with the given loopMode and the given initialDuration.
+     *
      * @param initialDuration the duration of the event at speed = 1.
      * @param loopMode the loop mode of the event.
      */
@@ -331,24 +332,27 @@ private List<CinematicEventListener> getListeners() {
     }
 
     /**
-     * Add a CinematicEventListener to this event.
+     * Adds a CinematicEventListener to this event.
+     *
      * @param listener CinematicEventListener
      */
     public void addListener(CinematicEventListener listener) {
         getListeners().add(listener);
     }
 
     /**
-     * Remove a CinematicEventListener from this event.
+     * Removes a CinematicEventListener from this event.
+     *
      * @param listener CinematicEventListener
      */
     public void removeListener(CinematicEventListener listener) {
         getListeners().remove(listener);
     }
 
     /**
-     * Fast-forward the event to the given timestamp. Time=0 is the start of the event.
-     * @param time the time to fast forward to.
+     * Fast-forwards the event to the given timestamp. Time=0 is the start of the event.
+     *
+     * @param time the time to fast-forward to.
      */
     @Override
     public void setTime(float time) {

jme3-core/src/main/java/com/jme3/cinematic/events/CinematicEvent.java

@@ -118,8 +118,8 @@ public interface CinematicEvent extends Savable {
     public float getInitialDuration();
 
     /**
-     * Sets the duration of the animation at speed = 1 in seconds
-     * 
+     * Sets the duration of the animation at speed = 1, in seconds.
+     *
      * @param initialDuration the desired duration (in de-scaled seconds)
      */
     public void setInitialDuration(float initialDuration);
@@ -138,8 +138,9 @@ public interface CinematicEvent extends Savable {
     public void initEvent(Application app, Cinematic cinematic);
 
     /**
-     * When this method is invoked, the event should fast forward to the given time according time 0 is the start of the event.
-     * @param time the time to fast forward to
+     * Fast-forwards to the given time, where time=0 is the start of the event.
+     *
+     * @param time the time to fast-forward to
      */
     public void setTime(float time);    
 

jme3-core/src/main/java/com/jme3/effect/shapes/EmitterMeshConvexHullShape.java

@@ -60,11 +60,11 @@ public EmitterMeshConvexHullShape(List<Mesh> meshes) {
     }
 
     /**
-     * This method fills the point with coordinates of randomly selected point inside a convex hull
-     * of randomly selected mesh.
+     * Randomly selects a point inside the convex hull
+     * of a randomly selected mesh.
+     *
      * @param store
-     *        the variable to store with coordinates of randomly selected selected point inside a convex hull
-     *        of randomly selected mesh
+     *        storage for the coordinates of the selected point
      */
     @Override
     public void getRandomPoint(Vector3f store) {
@@ -75,12 +75,12 @@ public void getRandomPoint(Vector3f store) {
     }
 
     /**
-     * This method fills the point with coordinates of randomly selected point inside a convex hull
-     * of randomly selected mesh.
-     * The normal param is not used.
+     * Randomly selects a point inside the convex hull
+     * of a randomly selected mesh.
+     * The {@code normal} argument is not used.
+     *
      * @param store
-     *        the variable to store with coordinates of randomly selected selected point inside a convex hull
-     *        of randomly selected mesh
+     *        storage for the coordinates of the selected point
      * @param normal
      *        not used in this class
      */

jme3-core/src/main/java/com/jme3/effect/shapes/EmitterMeshFaceShape.java

@@ -82,9 +82,10 @@ public void setMeshes(List<Mesh> meshes) {
     }
 
     /**
-     * This method fills the point with coordinates of randomly selected point on a random face.
+     * Randomly selects a point on a random face.
+     *
      * @param store
-     *        the variable to store with coordinates of randomly selected selected point on a random face
+     *        storage for the coordinates of the selected point
      */
     @Override
     public void getRandomPoint(Vector3f store) {
@@ -102,12 +103,13 @@ public void getRandomPoint(Vector3f store) {
     }
 
     /**
-     * This method fills the point with coordinates of randomly selected point on a random face.
-     * The normal param is filled with selected face's normal.
+     * Randomly selects a point on a random face.
+     * The {@code normal} argument is set to the normal of the selected face.
+     *
      * @param store
-     *        the variable to store with coordinates of randomly selected selected point on a random face
+     *        storage for the coordinates of the selected point
      * @param normal
-     *        filled with selected face's normal
+     *        storage for the normal of the selected face
      */
     @Override
     public void getRandomPointAndNormal(Vector3f store, Vector3f normal) {

jme3-core/src/main/java/com/jme3/environment/LightProbeFactory.java

@@ -43,9 +43,9 @@
 import java.util.concurrent.ScheduledThreadPoolExecutor;
 
 /**
- * This Factory creates LightProbes within a scene, given an EnvironmentCamera.
+ * Creates LightProbes within a scene, given an EnvironmentCamera.
  * 
- * Since the process can be long, you can provide a JobProgressListener that 
+ * Since this process can take a long time, you can provide a JobProgressListener that
  * will be notified of the ongoing generation process when calling the makeProbe method.
  * 
  * The process is as follows: 

jme3-core/src/main/java/com/jme3/environment/util/EnvMapUtils.java

@@ -105,7 +105,7 @@ private EnvMapUtils() {
      * right image
      * @param downImg the bottom side image, also called negative y (negY) or
      * down image
-     * @param upImg the up side image, also called positive y (posY) or up image
+     * @param upImg the top side image, also called positive y (posY) or up image
      * @param backImg the south side image, also called positive z (posZ) or
      * back image
      * @param frontImg the north side image, also called negative z (negZ) or
@@ -419,7 +419,7 @@ public static Vector3f[] getSphericalHarmonicsCoefficents(TextureCubeMap cubeMap
      * The method used is the one from this article:
      * http://graphics.stanford.edu/papers/envmap/envmap.pdf
      *
-     * Also good resources on spherical harmonics
+     * Another good resource for spherical harmonics:
      * http://dickyjim.wordpress.com/2013/09/04/spherical-harmonics-for-beginners/
      *
      * @param cubeMap the environment cube map to compute SH for

jme3-core/src/main/java/com/jme3/export/FormatVersion.java

@@ -44,7 +44,7 @@ public final class FormatVersion {
     public static final int VERSION = 2;
 
     /**
-     * Signature of the format. Currently "JME3" as ASCII
+     * Signature of the format: currently, "JME3" as ASCII.
      */
     public static final int SIGNATURE = 0x4A4D4533;