clarify javadoc (#1713)

* clarify javadoc

* more javadoc clarification

* ListSort: more javadpc

* more javadoc refinements

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

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 @@ public class BoneLink extends PhysicsLink {
      * 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 class DacLinks
      * 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 @@ abstract public class PhysicsLink
     /**
      * 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.Level;
 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 class Joint implements Savable, JmeCloneable, HasLocalTransform {
     }
 
     /**
-     * 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 @@ public final class Bone implements Savable, JmeCloneable {
     }
 
     /**
-     * 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 class LegacyApplication implements Application, SystemListener {
     }
 
     /**
-     * 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 class LegacyApplication implements Application, SystemListener {
      * 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 @@ public class ConstantVerifierState extends BaseAppState {
     }
  
     /**
-     *  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 @@ import com.jme3.shader.Shader;
  */
 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.Level;
 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 @@ import java.util.logging.Logger;
  * 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 class Cinematic extends AbstractCinematicEvent implements AppState {
     }
 
     /**
-     * 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 class Cinematic extends AbstractCinematicEvent implements AppState {
     }
 
     /**
-     * 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 abstract class AbstractCinematicEvent implements CinematicEvent {
 
     /**
      * 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,7 +332,8 @@ public abstract class AbstractCinematicEvent implements CinematicEvent {
     }
 
     /**
-     * Add a CinematicEventListener to this event.
+     * Adds a CinematicEventListener to this event.
+     *
      * @param listener CinematicEventListener
      */
     public void addListener(CinematicEventListener listener) {
@@ -339,7 +341,8 @@ public abstract class AbstractCinematicEvent implements CinematicEvent {
     }
 
     /**
-     * Remove a CinematicEventListener from this event.
+     * Removes a CinematicEventListener from this event.
+     *
      * @param listener CinematicEventListener
      */
     public void removeListener(CinematicEventListener listener) {
@@ -347,8 +350,9 @@ public abstract class AbstractCinematicEvent implements CinematicEvent {
     }
 
     /**
-     * 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 class EmitterMeshConvexHullShape extends EmitterMeshFaceShape {
     }
 
     /**
-     * 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 class EmitterMeshConvexHullShape extends EmitterMeshFaceShape {
     }
 
     /**
-     * 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 class EmitterMeshFaceShape extends EmitterMeshVertexShape {
     }
 
     /**
-     * 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 class EmitterMeshFaceShape extends EmitterMeshVertexShape {
     }
 
     /**
-     * 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 com.jme3.texture.TextureCubeMap;
 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 @@ public class 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 class EnvMapUtils {
      * 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;
     

jme3-core/src/main/java/com/jme3/input/InputManager.java

@@ -657,7 +657,7 @@ public class InputManager implements RawInputListener {
 
     /**
      * Clears all the input mappings from this InputManager.
-     * Consequently, also clears all of the
+     * Consequently, this clears all of the
      * InputListeners as well.
      */
     public void clearMappings() {
@@ -975,7 +975,8 @@ public class InputManager implements RawInputListener {
 
     /**
      * Add a listener that reports when a joystick has been added or removed.
-     * Currently only implemented in LWJGL3
+     * Currently implemented only in LWJGL3.
+     *
      * @param listener the listener
      * @return true
      */

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

@@ -420,8 +420,8 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Adds each r,g,b,a of this <code>ColorRGBA</code> by the r,g,b,a the given
-     * color and returns the result (this).
+     * Adds each component to the corresponding component of the argument
+     * and returns the result (this).
      * Used as a way of combining colors and lights.
      *
      * @param c The color to add.

jme3-core/src/main/java/com/jme3/opencl/Device.java

@@ -151,8 +151,8 @@ public interface Device {
     /**
      * Returns the default compute device address space
      * size specified as an unsigned integer value
-     * in bits. Currently supported values are 32
-     * or 64 bits.
+     * in bits. The values currently supported are 32
+     * and 64.
      *
      * @return the size of an address
      */

jme3-core/src/main/java/com/jme3/opencl/Event.java

@@ -34,7 +34,7 @@ package com.jme3.opencl;
 /**
  * Wrapper for an OpenCL Event object.
  * Events are returned from kernel launches and all asynchronous operations.
- * They allow to test if the action has completed and to block until the operation
+ * They allow us to test whether an action has completed and block until the operation
  * is done.
  *
  * @author shaman

jme3-core/src/main/java/com/jme3/opencl/Image.java

@@ -42,7 +42,7 @@ import java.util.Objects;
  * format and buffer structure.
  * <br>
  * The image is specified by the {@link ImageDescriptor}, specifying
- * the extend and dimension of the image, and {@link ImageFormat}, specifying
+ * the type and dimensions of the image, and {@link ImageFormat}, specifying
  * the type of each pixel.
  * <br>
  * An image is created from scratch using

jme3-core/src/main/java/com/jme3/post/Filter.java

@@ -76,9 +76,8 @@ public abstract class Filter implements Savable {
     }
 
     /**
-     * Inner class Pass
-     * Pass are like filters in filters.
-     * Some filters will need multiple passes before the final render
+     * Passes are like filters within filters.
+     * Some filters will need multiple passes before the final render.
      */
     public class Pass {
 
@@ -276,7 +275,7 @@ public abstract class Filter implements Savable {
     }
 
     /**
-     * Initialization of sub classes filters
+     * Initialization of filter subclasses.
      * This method is called once when the filter is added to the FilterPostProcessor
      * It should contain Material initializations and extra passes initialization
      * @param manager the assetManager
@@ -437,8 +436,8 @@ public abstract class Filter implements Savable {
      * Override this method and return true if you want the scene (input) texture
      * to use bilinear filtering or false to use nearest filtering.
      * 
-     * Typically filters that perform samples <em>in between</em> pixels 
-     * should enable filtering.
+     * Typically, filters that perform samples <em>in between</em> pixels
+     * should enable bilinear filtering.
      * 
      * @return true to use linear filtering, false to use nearest filtering.
      */

jme3-core/src/main/java/com/jme3/renderer/Camera.java

@@ -1251,9 +1251,10 @@ public class Camera implements Savable, Cloneable {
 
     /**
      * Provides access to the view projection matrix.
-     * @return The result of multiplying the projection matrix by the view
+     *
+     *  @return The result of multiplying the projection matrix by the view
      *     matrix. This matrix is required for rendering an object. It is
-     *     precomputed so as to not compute it every time an object is rendered.
+     *     precomputed to avoid computing it every time an object is rendered.
      */
     public Matrix4f getViewProjectionMatrix() {
         return viewProjectionMatrix;

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

@@ -343,8 +343,8 @@ public class BatchNode extends GeometryGroupNode {
     }
 
     /**
-     * Sets the material to the all the batches of this BatchNode
-     * use setMaterial(Material material,int batchIndex) to set a material to a specific batch
+     * Sets the material to the all the batches of this BatchNode.
+     * Use setMaterial(Material material,int batchIndex) to set a material to a specific batch.
      *
      * @param material the material to use for this geometry
      */
@@ -354,9 +354,9 @@ public class BatchNode extends GeometryGroupNode {
     }
 
     /**
-     * Returns the material that is used for the first batch of this BatchNode
+     * Returns the material that is used for the first batch of this BatchNode.
      * <p>
-     * use getMaterial(Material material,int batchIndex) to get a material from a specific batch
+     * Use getMaterial(Material material,int batchIndex) to get a material from a specific batch.
      *
      * @return the material that is used for the first batch of this BatchNode
      * @see #setMaterial(com.jme3.material.Material)

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

@@ -83,8 +83,8 @@ public abstract class Spatial implements Savable, Cloneable, Collidable,
         Inherit,
         /**
          * Do not draw if we are not at least partially within the view frustum
-         * of the camera. This is determined via the defined
-         * Camera planes whether or not this Spatial should be culled.
+         * of the camera. The defined
+         * Camera planes determine whether this Spatial should be culled.
          */
         Dynamic,
         /**

jme3-core/src/main/java/com/jme3/scene/control/BillboardControl.java

@@ -180,8 +180,8 @@ public class BillboardControl extends AbstractControl {
     }
 
     /**
-     * Rotate the billboard so it points directly opposite the direction the
-     * camera's facing
+     * Rotates the billboard so it points directly opposite the direction the
+     * camera is facing.
      *
      * @param camera
      *            Camera

jme3-core/src/main/java/com/jme3/scene/shape/AbstractBox.java

@@ -165,9 +165,9 @@ public abstract class AbstractBox extends Mesh {
      * the box extends in both directions from the center for each extent.
      * 
      * @param center the center of the box.
-     * @param x the x extent of the box, in each directions.
-     * @param y the y extent of the box, in each directions.
-     * @param z the z extent of the box, in each directions.
+     * @param x the X extent of the box in each direction.
+     * @param y the Y extent of the box in each direction.
+     * @param z the Z extent of the box in each direction.
      */
     public final void updateGeometry(Vector3f center, float x, float y, float z) {
         if (center != null) {this.center.set(center); }

jme3-core/src/main/java/com/jme3/scene/shape/Cylinder.java

@@ -70,9 +70,9 @@ public class Cylinder extends Mesh {
     }
 
     /**
-     * Creates a new Cylinder. By default, its center is the origin. Usually, a
-     * higher sample number creates a better looking cylinder, but at the cost
-     * of more vertex information.
+     * Creates a Cylinder. By default, its center is the origin. More
+     * samples create a better looking cylinder, at the cost
+     * of more vertex data.
      *
      * @param axisSamples
      *            Number of triangle samples along the axis.
@@ -89,14 +89,13 @@ public class Cylinder extends Mesh {
     }
 
     /**
-     * Creates a new Cylinder. By default, its center is the origin. Usually, a
-     * higher sample number creates a better looking cylinder, but at the cost
-     * of more vertex information. <br>
-     * If the cylinder is closed the texture is split into axisSamples parts:
-     * top most and bottom most part is used for top and bottom of the cylinder,
-     * rest of the texture for the cylinder wall. The middle of the top is
-     * mapped to texture coordinates (0.5, 1), bottom to (0.5, 0). Thus you need
-     * a suitably distorted texture.
+     * Creates a Cylinder. By default, its center is the origin. More
+     * samples create a better looking cylinder, at the cost
+     * of more vertex data. <br>
+     * If the cylinder is closed, the texture is split into axisSamples parts:
+     * the topmost and bottommost parts are used for top and bottom of the cylinder,
+     * and the rest of the texture is used for the cylinder wall. The middle of the top is
+     * mapped to texture coordinates (0.5, 1), bottom to (0.5, 0). Thus, it requires
      *
      * @param axisSamples
      *            Number of triangle samples along the axis.
@@ -115,14 +114,13 @@ public class Cylinder extends Mesh {
     }
 
     /**
-     * Creates a new Cylinder. By default its center is the origin. Usually, a
-     * higher sample number creates a better looking cylinder, but at the cost
-     * of more vertex information. <br>
-     * If the cylinder is closed the texture is split into axisSamples parts:
-     * top most and bottom most part is used for top and bottom of the cylinder,
-     * rest of the texture for the cylinder wall. The middle of the top is
-     * mapped to texture coordinates (0.5, 1), bottom to (0.5, 0). Thus you need
-     * a suitably distorted texture.
+     * Creates a new Cylinder. By default, its center is the origin. More
+     * samples create a better looking cylinder, at the cost
+     * of more vertex data. <br>
+     * If the cylinder is closed, the texture is split into axisSamples parts:
+     * the topmost and bottommost parts are used for top and bottom of the cylinder,
+     * and the rest of the texture is used for the cylinder wall. The middle of the top is
+     * mapped to texture coordinates (0.5, 1), bottom to (0.5, 0). Thus, it requires
      *
      * @param axisSamples The number of vertices samples along the axis. It is equal to the number of segments + 1; so 
      * that, for instance, 4 samples mean the cylinder will be made of 3 segments.

jme3-core/src/main/java/com/jme3/shader/Glsl100ShaderGenerator.java

@@ -230,7 +230,7 @@ public class Glsl100ShaderGenerator extends ShaderGenerator {
      * 
      *
      *<br>
-     * All of this is embed in a #if conditional statement if needed
+     * All of this is embedded in a #if conditional statement if necessary.
      */
     @Override
     protected void generateNodeMainSection(StringBuilder source, ShaderNode shaderNode, String nodeSource, ShaderGenerationInfo info) {

jme3-core/src/main/java/com/jme3/shader/Glsl150ShaderGenerator.java

@@ -104,8 +104,8 @@ public class Glsl150ShaderGenerator extends Glsl100ShaderGenerator {
      * Fragment shader outputs are declared before the "void main(){" with the
      * "out" keyword.
      *
-     * after the "void main(){", the vertex output are declared and initialized
-     * and the fragment outputs are declared
+     * After the "void main(){", the vertex output are declared and initialized
+     * and the fragment outputs are declared.
      */
     @Override
     protected void generateStartOfMainSection(StringBuilder source, ShaderGenerationInfo info, Shader.ShaderType type) {

jme3-core/src/main/java/com/jme3/shadow/AbstractShadowFilter.java

@@ -207,8 +207,8 @@ public abstract class AbstractShadowFilter<T extends AbstractShadowRenderer> ext
     }
 
     /**
-     * Sets the shadow edges thickness. default is 1, setting it to lower values
-     * can help to reduce the jagged effect of the shadow edges
+     * Sets the shadow edges thickness. Default is 10. Setting it to lower values
+     * can help reduce the jagged effect of shadow edges.
      *
      * @param edgesThickness the desired thickness (in tenths of a pixel, default=10)
      */

jme3-core/src/main/java/com/jme3/shadow/AbstractShadowRenderer.java

@@ -759,8 +759,8 @@ public abstract class AbstractShadowRenderer implements SceneProcessor, Savable,
     }
 
     /**
-     * Sets the shadow edges thickness. default is 10, setting it to lower values
-     * can help to reduce the jagged effect of the shadow edges
+     * Sets the shadow edges thickness. Default is 10. Setting it to lower values
+     * can help reduce the jagged effect of shadow edges.
      *
      * @param edgesThickness the desired thickness (in tenths of a pixel, default=10)
      */

jme3-core/src/main/java/com/jme3/shadow/DirectionalLightShadowFilter.java

@@ -67,15 +67,15 @@ public class DirectionalLightShadowFilter extends AbstractShadowFilter<Direction
     }
     
     /**
-     * Creates a DirectionalLightShadowFilter Shadow Filter More info on the
+     * Creates a DirectionalLight shadow filter. More info on the
      * technique at <a
      * href="http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html">http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html</a>
      *
-     * @param assetManager the application asset manager
-     * @param shadowMapSize the size of the rendered shadowmaps (512,1024,2048,
-     * etc...)
-     * @param nbSplits the number of shadow maps rendered (the more shadow maps
-     * the more quality, the less fps).
+     * @param assetManager the application's asset manager
+     * @param shadowMapSize the size of the rendered shadowmaps (512, 1024, 2048,
+     *     etcetera)
+     * @param nbSplits the number of shadow maps rendered (More shadow maps mean
+     *     better quality, fewer frames per second.)
      */
     public DirectionalLightShadowFilter(AssetManager assetManager, int shadowMapSize, int nbSplits) {
         super(assetManager, shadowMapSize, new DirectionalLightShadowRenderer(assetManager, shadowMapSize, nbSplits));
@@ -110,13 +110,15 @@ public class DirectionalLightShadowFilter extends AbstractShadowFilter<Direction
     }
 
     /**
-     * Adjust the repartition of the different shadow maps in the shadow extend
-     * usually goes from 0.0 to 1.0 a low value give a more linear repartition
-     * resulting in a constant quality in the shadow over the extends, but near
-     * shadows could look very jagged a high value give a more logarithmic
-     * repartition resulting in a high quality for near shadows, but the quality
-     * quickly decrease over the extend. The default value is 0.65
-     * (the theoretical optimum).
+     * Adjusts the partition of the shadow extend into shadow maps.
+     * Lambda is usually between 0 and 1.
+     * A low value gives a more linear partition,
+     * resulting in consistent shadow quality over the extend,
+     * but near shadows could look very jagged.
+     * A high value gives a more logarithmic partition,
+     * resulting in high quality for near shadows,
+     * but quality decreases rapidly with distance.
+     * The default value is 0.65 (the theoretical optimum).
      *
      * @param lambda the lambda value.
      */
@@ -135,7 +137,7 @@ public class DirectionalLightShadowFilter extends AbstractShadowFilter<Direction
     /**
      * Enables the stabilization of the shadow's edges. (default is true)
      * This prevents shadow edges from flickering when the camera moves.
-     * However it can lead to some shadow quality loss in some particular scenes.
+     * However, it can lead to some loss of shadow quality in particular scenes.
      *
      * @param stabilize true to stabilize, false to disable stabilization
      */

jme3-core/src/main/java/com/jme3/shadow/DirectionalLightShadowRenderer.java

@@ -82,14 +82,14 @@ public class DirectionalLightShadowRenderer extends AbstractShadowRenderer {
     }
 
     /**
-     * Create a DirectionalLightShadowRenderer More info on the technique at <a
+     * Creates a DirectionalLight shadow renderer. More info on the technique at <a
      * href="https://developer.nvidia.com/gpugems/GPUGems3/gpugems3_ch10.html">https://developer.nvidia.com/gpugems/GPUGems3/gpugems3_ch10.html</a>
      *
-     * @param assetManager the application asset manager
-     * @param shadowMapSize the size of the rendered shadowmaps (512,1024,2048,
-     * etc...)
-     * @param nbSplits the number of shadow maps rendered (the more shadow maps
-     * the more quality, the less fps).
+     * @param assetManager the application's asset manager
+     * @param shadowMapSize the size of the rendered shadowmaps (512, 1024, 2048,
+     *     etcetera)
+     * @param nbSplits the number of shadow maps rendered (More shadow maps yield
+     *     better quality, fewer fps.)
      */
     public DirectionalLightShadowRenderer(AssetManager assetManager, int shadowMapSize, int nbSplits) {
         super(assetManager, shadowMapSize, nbSplits);
@@ -243,11 +243,16 @@ public class DirectionalLightShadowRenderer extends AbstractShadowRenderer {
     }
 
     /**
-     * Adjust the repartition of the different shadow maps in the shadow extend.
+     * Adjusts the partition of the shadow extend into shadow maps.
      * Lambda is usually between 0 and 1.
-     * A low value give a more linear repartition resulting in a constant quality in the shadow over the extends, but near shadows could look very jagged.
-     * A high value give a more logarithmic repartition resulting in a high quality for near shadows, but the quality quickly decrease over the extend.
+     * A low value gives a more linear partition,
+     * resulting in consistent shadow quality over the extend,
+     * but near shadows could look very jagged.
+     * A high value gives a more logarithmic partition,
+     * resulting in high quality for near shadows,
+     * but quality decreases rapidly with distance.
      * The default value is 0.65 (the theoretical optimum).
+     *
      * @param lambda the lambda value.
      */
     public void setLambda(float lambda) {
@@ -264,7 +269,7 @@ public class DirectionalLightShadowRenderer extends AbstractShadowRenderer {
     /**
      * Enables the stabilization of the shadow's edges. (default is true)
      * This prevents shadow edges from flickering when the camera moves.
-     * However it can lead to some shadow quality loss in some particular scenes.
+     * However, it can lead to some loss of shadow quality in particular scenes.
      *
      * @param stabilize true to stabilize, false to disable stabilization
      */

jme3-core/src/main/java/com/jme3/shadow/PssmShadowFilter.java

@@ -80,11 +80,13 @@ public class PssmShadowFilter extends Filter {
     }
     
     /**
-     * Creates a PSSM Shadow Filter.
+     * Creates a PSSM shadow filter.
      * More info on the technique at <a href="http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html">http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html</a>
-     * @param manager the application asset manager
-     * @param size the size of the rendered shadowmaps (512,1024,2048, etc...)
-     * @param nbSplits the number of shadow maps rendered (the more shadow maps the more quality, the less fps). 
+     *
+     * @param manager the application's asset manager
+     * @param size the size of the rendered shadowmaps (512, 1024, 2048, etcetera)
+     * @param nbSplits the number of shadow maps rendered (More shadow maps mean
+     *     better quality, fewer frames per second.)
      */
     public PssmShadowFilter(AssetManager manager, int size, int nbSplits) {
         super("Post Shadow");
@@ -160,11 +162,16 @@ public class PssmShadowFilter extends Filter {
     }
 
     /**
-     * Adjust the repartition of the different shadow maps in the shadow extend
-     * usually goes from 0.0 to 1.0
-     * a low value give a more linear repartition resulting in a constant quality in the shadow over the extends, but near shadows could look very jagged
-     * a high value give a more logarithmic repartition resulting in a high quality for near shadows, but the quality quickly decrease over the extend.
-     * the default value is set to 0.65f (theoretic optimal value).
+     * Adjusts the partition of the shadow extend into shadow maps.
+     * Lambda is usually between 0 and 1.
+     * A low value gives a more linear partition,
+     * resulting in consistent shadow quality over the extend,
+     * but near shadows could look very jagged.
+     * A high value gives a more logarithmic partition,
+     * resulting in high quality for near shadows,
+     * but quality decreases rapidly with distance.
+     * The default value is 0.65 (the theoretical optimum).
+     *
      * @param lambda the lambda value.
      */
     public void setLambda(float lambda) {
@@ -219,8 +226,10 @@ public class PssmShadowFilter extends Filter {
     }
 
     /**
-     * Sets the shadow edges thickness. default is 1, setting it to lower values can help to reduce the jagged effect of the shadow edges
-     * @param edgesThickness the desired thickness (in tenths of a pixel, default=10)
+     * Sets the shadow edges thickness. Default is 1.
+     * Setting it to lower values can help to reduce the jagged effect of the shadow edges.
+     *
+     *  @param edgesThickness the desired thickness (in tenths of a pixel, default=10)
      */
     public void setEdgesThickness(int edgesThickness) {
         pssmRenderer.setEdgesThickness(edgesThickness);

jme3-core/src/main/java/com/jme3/shadow/PssmShadowRenderer.java

@@ -605,11 +605,16 @@ public class PssmShadowRenderer implements SceneProcessor {
     }
 
     /**
-     * Adjust the repartition of the different shadow maps in the shadow extend
-     * usually goes from 0.0 to 1.0
-     * a low value give a more linear repartition resulting in a constant quality in the shadow over the extends, but near shadows could look very jagged
-     * a high value give a more logarithmic repartition resulting in a high quality for near shadows, but the quality quickly decrease over the extend.
-     * the default value is set to 0.65f (theoretic optimal value).
+     * Adjusts the partition of the shadow extend into shadow maps.
+     * Lambda is usually between 0 and 1.
+     * A low value gives a more linear repartition,
+     * resulting in consistent shadow quality over the extend,
+     * but near shadows could look very jagged.
+     * A high value gives a more logarithmic repartition,
+     * resulting in high quality for near shadows,
+     * but quality decreases rapidly with distance.
+     * The default value is 0.65 (the theoretical optimum).
+     *
      * @param lambda the lambda value.
      */
     public void setLambda(float lambda) {

jme3-core/src/main/java/com/jme3/shadow/ShadowUtil.java

@@ -710,7 +710,7 @@ public class ShadowUtil {
     /**
      * Populates the outputGeometryList with the geometry of the
      * inputGeometryList that are in the radius of a light.
-     * The array of camera must be an array of 6 cameras initialized so they represent the light viewspace of a pointlight
+     * The array must contain 6 cameras, initialized to represent the viewspace of a point light.
      *
      * @param inputGeometryList The list containing all geometries to check
      * against the camera frustum

jme3-core/src/main/java/com/jme3/texture/Image.java

@@ -598,7 +598,7 @@ public class Image extends NativeObject implements Savable /*, Cloneable*/ {
 
     /**
      * Internal use only.
-     * The renderer stores the texture state set from the last texture
+     * The renderer stores the texture state set from the last texture,
      * so it doesn't have to change it unless necessary. 
      * 
      * @return The image parameter state.

jme3-core/src/main/java/com/jme3/texture/image/ImageRaster.java

@@ -138,7 +138,7 @@ public abstract class ImageRaster {
      * such as {@link com.jme3.texture.Image.Format#Luminance8}) then a color to grayscale
      * conversion is done first, before writing the result into the image.
      * <p>
-     * If the image does not have some of the components in the color (such
+     * If the image lacks some components (such
      * as alpha, or any of the color components), then these components
      * will be ignored. The only exception to this is luminance formats
      * for which the color is converted to luminance first (see above).

jme3-core/src/main/java/com/jme3/texture/image/LastTextureState.java

@@ -35,8 +35,8 @@ import com.jme3.renderer.Renderer;
 import com.jme3.texture.Texture;
 
 /**
- * Stores / caches texture state parameters so they don't have to be set 
- * each time by the {@link Renderer}.
+ * Stores/caches texture-state parameters so the {@link Renderer} doesn't have to
+ * set them each time.
  * 
  * @author Kirill Vainer
  */

jme3-core/src/main/java/com/jme3/util/ListSort.java

@@ -53,11 +53,11 @@ import java.util.Comparator;
  * list changes
  *
  * {@code
- * Disclaimer : I was intrigued by the use of val >>> 1 in java 7 Timsort class
- * instead of val / 2 (integer division). Micro benching revealed that val >>> 1
- * is twice faster than val / 2 in java 6 and has similar perf in java 7. The
- * following code uses val >>> 1 when ever a value needs to be divided by 2 and
- * rounded to its floor
+ * Disclaimer : I was intrigued by the use of val >>> 1 in the Java7 Timsort
+ * in place of val / 2 (integer division). Micro benching revealed that val >>> 1
+ * is twice as fast as val / 2 in Java6 and has similar perf in Java7. The
+ * following code uses val >>> 1 whenever a value needs to be divided by 2 and
+ * rounded to its floor.
  * }
  *
  * @author Nehon
@@ -75,14 +75,14 @@ public class ListSort<T> {
     private Comparator<T> comparator;
     
     /**
-     * attribute temp vars for merging. This was used to unroll the merge_lo &
+     * Attribute temp vars for merging. This was used to unroll the merge_lo &
      * merge_hi function of original implementations that used massive labeled
-     * goto branching and was almost unreadable
+     * goto branching and was almost unreadable.
      */
     int iterA, iterB, dest, lengthA, lengthB;
     
     /**
-     * Number of runs to merge
+     * Number of runs to merge.
      */
     private int nbRuns = 0;
 
@@ -92,13 +92,13 @@ public class ListSort<T> {
      * class + array was a convoluted pain.
      */
     /**
-     * array of start indices in the original array for runs : run i starting
-     * index is at runIndices[i]
+     * Array of run start indices in the original array: starting
+     * index of run 'i' is at runIndices[i].
      */
     private int[] runsIndices = null;
     /**
-     * array of runs length in the original array : run i length is at
-     * runLength[i]
+     * Array of run lengths in the original array: length of run 'i' is at
+     * runLength[i].
      */
     private int[] runsLength = null;
     /**
@@ -109,12 +109,12 @@ public class ListSort<T> {
     /**
      * MIN_GALLOP set to 7 constant as described in listsort.txt. this magic
      * number indicates how many wins should trigger the switch from binary
-     * search to galloping mode
+     * search to galloping mode.
      */
     private static final int MIN_GALLOP = 7;
     /**
-     * This variable allows to adjust when switching to galloping mode. lowered
-     * when the data are "naturally" structured, raised when data are random.
+     * Controls switching to galloping mode. It is lowered
+     * when the data are "naturally" ordered and raised when they are random.
      */
     private int minGallop = MIN_GALLOP;
 
@@ -670,9 +670,9 @@ public class ListSort<T> {
      * lenA <= lenB. See listsort.txt for more info.
      *
      * @param idxA index of first element in run A
-     * @param lengthA length of run A
+     * @param lenA length of run A
      * @param idxB index of first element in run B
-     * @param lengthB length of run B
+     * @param lenB length of run B
      */
     private void mergeLow(int idxA, int lenA, int idxB, int lenB) {
         
@@ -822,9 +822,9 @@ public class ListSort<T> {
      * lenA >= lenB. See listsort.txt for more info.
      *
      * @param idxA index of first element in run A
-     * @param lengthA length of run A
+     * @param lenA length of run A
      * @param idxB index of first element in run B
-     * @param lengthB length of run B
+     * @param lenB length of run B
      */
     private void mergeHigh(int idxA, int lenA, int idxB, int lenB) {
         

jme3-core/src/main/java/com/jme3/util/clone/JmeCloneable.java

@@ -95,7 +95,7 @@ public interface JmeCloneable extends Cloneable {
      *              This is provided for the very rare case that this object needs
      *              to refer to its original for some reason.  In general, all of
      *              the relevant values should have been transferred during the
-     *              shallow clone and this object need merely clone what it wants.
+     *              shallow clone, and this object need only clone what it wants.
      */
     public void cloneFields( Cloner cloner, Object original ); 
 }

jme3-core/src/test/java/com/jme3/collision/CollisionUtil.java

@@ -77,7 +77,7 @@ final class CollisionUtil {
      * 
      * @param a First collidable
      * @param b Second collidable
-     * @param expect Number of expected results
+     * @param expected the expected number of results
      */
     public static void checkCollision(Collidable a, Collidable b, int expected) {
         checkCollisionBase(a, b, expected);

jme3-core/src/tools/java/jme3tools/optimize/LodGenerator.java

@@ -111,14 +111,7 @@ public class LodGenerator {
     final private Mesh mesh;
 
     /**
-     * Describe the way triangles will be removed. <br> PROPORTIONAL :
-     * Percentage of triangles to be removed from the mesh. Valid range is a
-     * number between 0.0 and 1.0 <br> CONSTANT : Triangle count to be removed
-     * from the mesh. Pass only integers or it will be rounded. <br>
-     * COLLAPSE_COST : Reduces the vertices, until the cost is bigger then the
-     * given value. Collapse cost is equal to the amount of artifact the
-     * reduction causes. This generates the best Lod output, but the collapse
-     * cost depends on implementation.
+     * Enumerate criteria for removing triangles.
      */
     public enum TriangleReductionMethod {
 
@@ -129,17 +122,17 @@ public class LodGenerator {
          */
         PROPORTIONAL,
         /**
-         * Triangle count to be removed from the mesh.
+         * Number of triangles to be removed from the mesh.
          *
-         * Pass only integers or it will be rounded.
+         * Pass an integer or it will be rounded.
          */
         CONSTANT,
         /**
-         * Reduces the vertices, until the cost is bigger then the given value.
+         * Collapses vertices until the cost exceeds the given value.
          *
-         * Collapse cost is equal to the amount of artifact the reduction
-         * causes. This generates the best Lod output, but the collapse cost
-         * depends on implementation.
+         * Collapse cost indicates how much inaccuracy the
+         * reduction causes. This generates the best LOD output, but the collapse
+         * cost is implementation-dependant.
          */
         COLLAPSE_COST
     };
@@ -256,7 +249,7 @@ public class LodGenerator {
     };
 
     /**
-     * Construct a LodGenerator for the given mesh
+     * Constructs an LodGenerator for the given Mesh.
      *
      * @param mesh the mesh for which to generate LODs.
      */
@@ -266,7 +259,7 @@ public class LodGenerator {
     }
 
     /**
-     * Construct a LodGenerator for the given geometry
+     * Constructs an LodGenerator for the given Geometry.
      *
      * @param geom the geometry for which to generate LODs.
      */
@@ -599,8 +592,8 @@ public class LodGenerator {
      * {@link TriangleReductionMethod} and a list of reduction values.<br> for
      * each value a LOD will be generated. <p> <strong>Important note: </strong>
      * some meshes cannot be decimated, so the result of this method can vary
-     * depending of the given mesh. Also the reduction values are indicative and
-     * the produces mesh will not always meet the required reduction.
+     * depending on the given mesh. Also, the reduction values are approximate, and
+     * the algorithm won't always achieve the specified reduction.
      *
      * @param reductionMethod the reduction method to use
      * @param reductionValues the reduction value to use for each LOD level.

jme3-core/src/tools/java/jme3tools/shader/ShaderDebug.java

@@ -44,7 +44,8 @@ public class ShaderDebug {
     }
 
     /**
-     * Append the line numbers to the source code of a shader to output it
+     * Prepend line numbers to the source code of a shader, for output.
+     *
      * @param source the source
      * @return the formatted source code
      */

jme3-desktop/src/main/java/com/jme3/system/NativeLibrary.java

@@ -100,9 +100,9 @@ final class NativeLibrary {
     /**
      * The filename that the library should be extracted as.
      * 
-     * In some cases can be different than {@link #getPathInNativesJar() path in natives jar},
+     * In some cases, this differs from the {@link #getPathInNativesJar() path in the natives jar},
      * since the names of the libraries specified in the jars are often incorrect.
-     * If set to <code>null</code>, then the same name as the filename in 
+     * If set to <code>null</code>, then the filename in the
      * natives jar shall be used.
      * 
      * @return the name that should be given to the extracted file.

jme3-desktop/src/main/java/com/jme3/system/NativeLibraryLoader.java

@@ -204,9 +204,9 @@ public final class NativeLibraryLoader {
     /**
      * Determines whether native Bullet is on the classpath.
      * 
-     * Currently the context extracts the native bullet libraries, so
-     * this method is needed to determine if it is needed.
-     * Ideally, native bullet should be responsible for its own natives.
+     * Currently, the context extracts the native Bullet libraries, so
+     * this method is needed to determine if they are needed.
+     * Ideally, native Bullet would be responsible for its own natives.
      * 
      * @return True native bullet is on the classpath, false otherwise.
      */

jme3-examples/src/main/java/jme3test/helloworld/HelloPhysics.java

@@ -51,7 +51,7 @@ import com.jme3.texture.Texture;
 import com.jme3.texture.Texture.WrapMode;
 
 /**
- * Example 12 - how to give objects physical properties so they bounce and fall.
+ * Example 12 - how to give objects physical properties, so they bounce and fall.
  * @author base code by double1984, updated by zathras
  */
 public class HelloPhysics extends SimpleApplication {
@@ -69,7 +69,7 @@ public class HelloPhysics extends SimpleApplication {
   private Material stone_mat;
   private Material floor_mat;
 
-  /** Prepare geometries for bricks and cannon balls. */
+  /** Prepare geometries for bricks and cannonballs. */
   private static final Box    box;
   private static final Sphere sphere;
   private static final Box    floor;
@@ -115,7 +115,7 @@ public class HelloPhysics extends SimpleApplication {
   }
 
   /**
-   * Every time the shoot action is triggered, a new cannon ball is produced.
+   * Every time the shoot action is triggered, a new cannonball is produced.
    * The ball is set up to fly from the camera position in the camera direction.
    */
   final private ActionListener actionListener = new ActionListener() {
@@ -176,7 +176,7 @@ public class HelloPhysics extends SimpleApplication {
     }
   }
 
-  /** This method creates one individual physical brick. */
+  /** Creates one physical brick. */
   private void makeBrick(Vector3f loc) {
     /* Create a brick geometry and attach it to the scene graph. */
     Geometry brick_geo = new Geometry("brick", box);
@@ -191,7 +191,7 @@ public class HelloPhysics extends SimpleApplication {
     bulletAppState.getPhysicsSpace().add(brick_phy);
   }
 
-  /** This method creates one individual physical cannon ball.
+  /** Creates one physical cannonball.
    * By default, the ball is accelerated and flies
    * from the camera position in the camera direction.*/
    public void makeCannonBall() {

jme3-lwjgl3/src/main/java/com/jme3/opencl/lwjgl/LwjglPlatform.java

@@ -76,8 +76,6 @@ public final class LwjglPlatform implements Platform {
      * Copied from the old release.
      *
      * @param device_type the device type
-     * @param filter the device filter
-     *
      * @return the available devices
      */
     private long[] getDevices(int device_type) {

jme3-networking/src/main/java/com/jme3/network/service/ClientServiceManager.java

@@ -76,7 +76,7 @@ public class ClientServiceManager extends ServiceManager<ClientServiceManager> {
     }
 
     /**
-     *  Adds all of the specified ClientServices and initializes them.  If the service manager
+     *  Adds the specified services and initializes them.  If the service manager
      *  has already been started then the services will also be started.
      *  This is a convenience method that delegates to addService(), thus each
      *  service will be initialized (and possibly started) in sequence rather

jme3-networking/src/main/java/com/jme3/network/service/HostedServiceManager.java

@@ -83,7 +83,7 @@ public class HostedServiceManager extends ServiceManager<HostedServiceManager> {
     }
 
     /**
-     *  Adds all of the specified HostedServices and initializes them.  If the service manager
+     *  Adds the specified services and initializes them.  If the service manager
      *  has already been started then the services will also be started.
      *  This is a convenience method that delegates to addService(), thus each
      *  service will be initialized (and possibly started) in sequence rather

jme3-networking/src/main/java/com/jme3/network/util/AbstractMessageDelegator.java

@@ -133,7 +133,7 @@ public abstract class AbstractMessageDelegator<S extends MessageConnection>
      *  only works with methods that actually have arguments.
      *  This implementation returns the last element of the method's
      *  getParameterTypes() array, thus supporting both 
-     *  method(connection, messageType) as well as just method(messageType)
+     *  method(connection, messageType) and method(messageType)
      *  calling forms.
      */
     protected Class getMessageType( Method m ) {

jme3-plugins/src/gltf/java/com/jme3/scene/plugins/gltf/ExtensionLoader.java

@@ -36,20 +36,20 @@ import com.google.gson.JsonElement;
 import java.io.IOException;
 
 /**
- * Base Interface for extension loading implementation.
+ * Interface to handle a glTF extension.
  *
  * Created by Nehon on 20/08/2017.
  */
 public interface ExtensionLoader {
 
     /**
-     * Implement this methods to handle a gltf extension reading
+     * Handles a glTF extension.
      *
      * @param loader     the GltfLoader with all the data structures
      * @param parentName the name of the element being read
      * @param parent     the element being read
      * @param extension  the content of the extension found in the element being read
-     * @param input      an object containing already loaded data from the element, this is most probably a JME object
+     * @param input      an object containing already loaded data from the element, probably a JME object
      * @return An object of the same type as input, containing the data from the input object and the eventual additional data read from the extension
      * @throws IOException for various error conditions
      */

jme3-plugins/src/gltf/java/com/jme3/scene/plugins/gltf/ExtrasLoader.java

@@ -34,15 +34,15 @@ package com.jme3.scene.plugins.gltf;
 import com.google.gson.JsonElement;
 
 /**
- * Base Interface for extra loading implementation.
+ * Interface to handle a glTF extra.
  * Created by Nehon on 30/08/2017.
  */
 public interface ExtrasLoader {
 
     /**
-     * Implement this methods to handle gltf extra reading
-     * Note that this method will be invoked every time an "extras" element will be found in the gltf file.
-     * You can check the parentName to know where the "extras" element has been found.
+     * Handles a glTF extra.
+     * This method will be invoked every time an "extras" element is found in the glTF file.
+     * The parentName indicates where the "extras" element was found.
      *
      * @param loader     the GltfLoader with all the data structures
      * @param parentName the name of the element being read

jme3-terrain/src/main/java/com/jme3/terrain/geomipmap/LODGeomap.java

@@ -57,7 +57,7 @@ import java.nio.ShortBuffer;
  * mesh, minus one outer edge around it. Then it builds the edges in counter-clockwise order,
  * starting at the bottom right and working up, then left across the top, then down across the
  * left, then right across the bottom.
- * It needs to know what its neighbour's LODs are so it can stitch the edges.
+ * It needs to know what its neighbour's LODs are, so it can stitch the edges.
  * It creates degenerate polygons in order to keep the winding order of the polygons and to move
  * the strip to a new position while still maintaining the continuity of the overall mesh. These
  * degenerates are removed quickly by the video card.

jme3-terrain/src/main/java/com/jme3/terrain/heightmap/CombinerHeightMap.java

@@ -34,13 +34,12 @@ package com.jme3.terrain.heightmap;
 import java.util.logging.Logger;
 
 /**
- * <code>CombinerHeightMap</code> generates a new height map based on
+ * Generates a new height map based on
  * two provided height maps. These maps can either be added together
  * or subtracted from each other. Each heightmap has a weight to
- * determine how much one will affect the other. By default it is set to
- * 0.5, 0.5, meaning the two heightmaps are averaged evenly. This
- * value can be adjusted at will, as long as the two factors are equal
- * to 1.0.
+ * determine how much one will affect the other. By default, it is set to
+ * 0.5, 0.5, meaning the two heightmaps have equal weight. This
+ * value can be adjusted at will, as long as the two factors sum to 1.
  *
  * @author Mark Powell
  * @version $Id$

jme3-terrain/src/main/java/com/jme3/terrain/heightmap/FluidSimHeightMap.java

@@ -228,11 +228,11 @@ public class FluidSimHeightMap extends AbstractHeightMap {
 
     /**
      * Sets the number of times the fluid simulation should be iterated over
-     * the heightmap. The more often this is, the less features (hills, etc)
+     * the heightmap. The more iterations, the fewer features (hills, etcetera)
      * the terrain will have, and the smoother it will be.
      *
      * @param iterations
-     *            the number of iterations to do
+     *            the number of iterations to perform
      * @throws Exception
      *             if iterations is not greater than zero
      */

jme3-terrain/src/main/java/com/jme3/terrain/heightmap/ImageBasedHeightMap.java

@@ -58,7 +58,7 @@ public class ImageBasedHeightMap extends AbstractHeightMap {
     /**
      * Creates a HeightMap from an Image. The image will be converted to
      * grayscale, and the grayscale values will be used to generate the height
-     * map. White is highest point while black is lowest point.
+     * map. White is the highest point, and black is the lowest point.
      * 
      * Currently, the Image used must be square (width == height), but future
      * work could rescale the image.

jme3-vr/src/main/java/com/jme3/input/vr/lwjgl_openvr/LWJGLOpenVRViewManager.java

@@ -308,7 +308,7 @@ public class LWJGLOpenVRViewManager extends AbstractVRViewManager {
     }
 
     /**
-     * Replaces rootNode as the main cameras scene with the distortion mesh
+     * Replaces rootNode with the distortion mesh as the main camera's scene.
      */
     private void setupVRScene() {
 

jme3-vr/src/main/java/com/jme3/input/vr/openvr/OpenVRViewManager.java

@@ -317,7 +317,7 @@ public class OpenVRViewManager extends AbstractVRViewManager {
     }
 
     /**
-     * Replaces rootNode as the main cameras scene with the distortion mesh
+     * Replaces rootNode with the distortion mesh as the main camera's scene.
      */
     private void setupVRScene(){
         if (environment != null){

jme3-vr/src/main/java/com/jme3/input/vr/osvr/OSVRViewManager.java

@@ -365,7 +365,7 @@ public class OSVRViewManager extends AbstractVRViewManager{
     }
 
     /**
-     * Replaces rootNode as the main cameras scene with the distortion mesh
+     * Replaces rootNode with the distortion mesh as the main camera's scene.
      */
     private void setupVRScene(){
         if (environment != null){

jme3-vr/src/main/java/com/jme3/shadow/DirectionalLightShadowFilterVR.java

@@ -65,22 +65,24 @@ public class DirectionalLightShadowFilterVR extends AbstractShadowFilterVR<Direc
      * href="http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html">http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html</a>
      *
      * @param assetManager the application asset manager
-     * @param shadowMapSize the size of the rendered shadowmaps (512,1024,2048,
-     * etc...)
-     * @param nbSplits the number of shadow maps rendered (the more shadow maps
-     * the more quality, the less fps).
+     * @param shadowMapSize the size of the rendered shadowmaps (512, 1024, 2048,
+     *     etcetera)
+     * @param nbSplits the number of shadow maps rendered (More shadow maps yield
+     *     better quality, fewer fps.)
      */
     public DirectionalLightShadowFilterVR(AssetManager assetManager, int shadowMapSize, int nbSplits) {
         super(assetManager, shadowMapSize, new DirectionalLightShadowRendererVR(assetManager, shadowMapSize, nbSplits));
     }
 
     /**
-     * Creates a DirectionalLightShadowFilter Shadow Filter More info on the
+     * Creates a DirectionalLight shadow filter. More info on the
      * technique at <a
      * href="http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html">http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html</a>.
-     * @param assetManager the application asset manager
+     *
+     *  @param assetManager the application's asset manager
      * @param shadowMapSize the size of the rendered shadowmaps (512, 1024, 2048, etc...)
-     * @param nbSplits the number of shadow maps rendered (the more shadow maps the more quality, the less fps).
+     * @param nbSplits the number of shadow maps rendered (More shadow maps yield
+     *     better quality, fewer fps.)
      * @param useMatDef the material to attach to this filter.
      */
     public DirectionalLightShadowFilterVR(AssetManager assetManager, int shadowMapSize, int nbSplits, String useMatDef) {
@@ -116,13 +118,15 @@ public class DirectionalLightShadowFilterVR extends AbstractShadowFilterVR<Direc
     }
 
     /**
-     * Adjust the repartition of the different shadow maps in the shadow extend
-     * usually goes from 0.0 to 1.0 a low value give a more linear repartition
-     * resulting in a constant quality in the shadow over the extends, but near
-     * shadows could look very jagged a high value give a more logarithmic
-     * repartition resulting in a high quality for near shadows, but the quality
-     * quickly decrease over the extend. the default value is set to 0.65f
-     * (theoretic optimal value).
+     * Adjusts the partition of the shadow extend into shadow maps.
+     * Lambda is usually between 0 and 1.
+     * A low value gives a more linear partition,
+     * resulting in consistent shadow quality over the extend,
+     * but near shadows could look very jagged.
+     * A high value gives a more logarithmic partition,
+     * resulting in high quality for near shadows,
+     * but quality decreases rapidly with distance.
+     * The default value is 0.65 (the theoretical optimum).
      *
      * @param lambda the lambda value.
      */
@@ -142,8 +146,9 @@ public class DirectionalLightShadowFilterVR extends AbstractShadowFilterVR<Direc
     /**
      * Enables the stabilization of the shadow's edges. (default is <code>true</code>)
      * This prevents shadow edges from flickering when the camera moves.
-     * However it can lead to some shadow quality loss in some particular scenes.
-     * @param stabilize <code>true</code> if the stabilization has to be enabled and <code>false</code> otherwise.
+     * However, it can lead to some loss of shadow quality in particular scenes.
+     *
+     *  @param stabilize <code>true</code> if the stabilization has to be enabled and <code>false</code> otherwise.
      * @see #isEnabledStabilization()
      */
     public void setEnabledStabilization(boolean stabilize) {

jme3-vr/src/main/java/com/jme3/shadow/DirectionalLightShadowRendererVR.java

@@ -84,14 +84,14 @@ public class DirectionalLightShadowRendererVR extends AbstractShadowRendererVR {
     }
 
     /**
-     * Create a DirectionalLightShadowRenderer More info on the technique at <a
+     * Creates a DirectionalLight shadow renderer. More info on the technique at <a
      * href="http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html">http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html</a>
      *
-     * @param assetManager the application asset manager
-     * @param shadowMapSize the size of the rendered shadowmaps (512,1024,2048,
-     * etc...)
-     * @param nbSplits the number of shadow maps rendered (the more shadow maps
-     * the more quality, the less fps).
+     * @param assetManager the application's asset manager
+     * @param shadowMapSize the size of the rendered shadowmaps (512, 1024, 2048,
+     *     etcetera)
+     * @param nbSplits the number of shadow maps rendered (More shadow maps yield
+     *     better quality, fewer fps.)
      */
     public DirectionalLightShadowRendererVR(AssetManager assetManager, int shadowMapSize, int nbSplits) {
         super(assetManager, shadowMapSize, nbSplits);
@@ -238,11 +238,16 @@ public class DirectionalLightShadowRendererVR extends AbstractShadowRendererVR {
     }
 
     /**
-     * Adjust the repartition of the different shadow maps in the shadow extend.
+     * Adjusts the partition of the shadow extend into shadow maps.
      * Lambda is usually between 0 and 1.
-     * A low value give a more linear repartition resulting in a constant quality in the shadow over the extends, but near shadows could look very jagged
-     * A high value give a more logarithmic repartition resulting in a high quality for near shadows, but the quality quickly decrease over the extend.
+     * A low value gives a more linear partition,
+     * resulting in consistent shadow quality over the extend,
+     * but near shadows could look very jagged.
+     * A high value gives a more logarithmic partition,
+     * resulting in high quality for near shadows,
+     * but quality decreases rapidly with distance.
      * The default value is 0.65 (the theoretical optimum).
+     *
      * @param lambda the lambda value.
      */
     public void setLambda(float lambda) {
@@ -260,8 +265,9 @@ public class DirectionalLightShadowRendererVR extends AbstractShadowRendererVR {
     /**
      * Enables the stabilization of the shadow's edges. (default is true)
      * This prevents shadow edges from flickering when the camera moves.
-     * However it can lead to some shadow quality loss in some particular scenes.
-     * @param stabilize  <code>true</code> if stabilization has to be enabled and <code>false</code> otherwise.
+     * However, it can lead to some loss of shadow quality in particular scenes.
+     *
+     *  @param stabilize  <code>true</code> if stabilization has to be enabled and <code>false</code> otherwise.
      */
     public void setEnabledStabilization(boolean stabilize) {
         this.stabilize = stabilize;

jme3-vr/src/main/java/com/jme3/shadow/InstancedDirectionalShadowFilter.java

@@ -21,8 +21,9 @@ public class InstancedDirectionalShadowFilter extends DirectionalLightShadowFilt
      * Create a new instanced version of the {@link DirectionalLightShadowFilterVR directional light shadow filter}.
      * @param application the application that this filter is attached to.
      * @param camera
-     * @param shadowMapSize the size of the rendered shadowmaps (512, 1024, 2048, etc...)
-     * @param nbSplits the number of shadow maps rendered (the more shadow maps the more quality, the less fps).
+     * @param shadowMapSize the size of the rendered shadowmaps (512, 1024, 2048, etcetera)
+     * @param nbSplits the number of shadow maps rendered (More shadow maps yield
+     *     better quality, fewer frames per second.)
      * @param instancedRendering <code>true</code> if this filter has to use instance rendering and <code>false</code> otherwise.
      * @param rightCamera the camera used as right eye in stereo rendering mode.
      */