clarify comments and javadoc (#1743)

* correct more comments and javadoc

* more typos in comments/javadoc

* more typos in javadoc/comments

* javadoc and inline comments

jme3-android/src/main/java/com/jme3/input/android/AndroidSensorJoyInput.java

@@ -282,7 +282,7 @@ public class AndroidSensorJoyInput implements SensorEventListener {
      * Surface.ROTATION_270 = device in rotated 270deg counterclockwise
      *
      * When the Manifest locks the orientation, this value will not change during
-     * gametime, but if the orientation of the screen is based off the sensor,
+     * game time, but if the orientation of the screen is based off the sensor,
      * this value will change as the device is rotated.
      * @return Current device rotation amount
      */

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

@@ -127,7 +127,7 @@ public final class AnimControl extends AbstractControl implements Cloneable, Jme
         // Note cloneForSpatial() never actually cloned the animation map... just its reference       
         HashMap<String, Animation> newMap = new HashMap<>();
          
-        // animationMap is cloned, but only ClonableTracks will be cloned as they need a reference to a cloned spatial
+        // animationMap is cloned, but only cloneable tracks will be cloned as they need a reference to a cloned spatial
         for( Map.Entry<String, Animation> e : animationMap.entrySet() ) {
             newMap.put(e.getKey(), cloner.clone(e.getValue()));
         }

jme3-core/src/main/java/com/jme3/audio/AudioKey.java

@@ -55,8 +55,8 @@ public class AudioKey extends AssetKey<AudioData> {
      * Create a new AudioKey.
      * 
      * @param name Name of the asset
-     * @param stream If true, the audio will be streamed from harddrive,
-     * otherwise it will be buffered entirely and then played.
+     * @param stream If true, the audio will be streamed.
+     *     Otherwise, it will be buffered entirely and then played.
      * @param streamCache If stream is true, then this specifies if
      * the stream cache is used. When enabled, the audio stream will
      * be read entirely but not decoded, allowing features such as 
@@ -71,8 +71,8 @@ public class AudioKey extends AssetKey<AudioData> {
      * Create a new AudioKey
      *
      * @param name Name of the asset
-     * @param stream If true, the audio will be streamed from harddrive,
-     * otherwise it will be buffered entirely and then played.
+     * @param stream If true, the audio will be streamed.
+     *     Otherwise, it will be buffered entirely and then played.
      */
     public AudioKey(String name, boolean stream){
         super(name);

jme3-core/src/main/java/com/jme3/font/BitmapText.java

@@ -234,7 +234,7 @@ public class BitmapText extends Node {
     }
 
     /**
-     * Define area where bitmaptext will be rendered
+     * Define the area where the BitmapText will be rendered.
      * @param rect position and size box where text is rendered
      */
     public void setBox(Rectangle rect) {
@@ -251,7 +251,7 @@ public class BitmapText extends Node {
     }
 
     /**
-     * @return height of whole textblock
+     * @return height of whole text block
      */
     public float getHeight() {
         if (needRefresh) {
@@ -276,7 +276,7 @@ public class BitmapText extends Node {
         if (textBox != null) {
             return Math.max(letters.getTotalWidth(), textBox.width);
         }
-      //  Please note that BitMaptext.getLineWidth() might differ from Font.getLineWidth() -->   scale it with Font.getPreferredSize()/BitMaptext.getSize()
+      //  Please note that BitmapText.getLineWidth() might differ from Font.getLineWidth() -->   scale it with Font.getPreferredSize()/BitmapText.getSize()
         return letters.getTotalWidth();
     }
 

jme3-core/src/main/java/com/jme3/font/Letters.java

@@ -119,7 +119,7 @@ class Letters {
         while (!l.isTail()) {
             if (l.isInvalid()) {
                 l.update(block);
-                // Without a textblock the next line returns always false = no textwrap at all will be applied
+                // Without a text block, the next line always returns false = no text wrap will be applied.
                 if (l.isInvalid(block)) {
                     switch (block.getLineWrapMode()) {
                     case Character:
@@ -169,7 +169,7 @@ class Letters {
                         l.clip(block);
 
                         // Clear the rest up to the next line feed.
-                        // = for texts attached to a textblock all coming characters are cleared except a linefeed is explicitly used
+                        // = for texts attached to a text block, all coming characters are cleared except a linefeed is explicitly used
                         for( LetterQuad q = l.getNext(); !q.isTail() && !q.isLineFeed(); q = q.getNext() ) {
                             q.setBitmapChar(null);
                             q.update(block);
@@ -193,7 +193,7 @@ class Letters {
 
     private void align() {
         if (block.getTextBox() == null) {
-            // Without a textblock there is no alignment.
+            // Without a text block, there is no alignment.
             return;
 
             // For unbounded left-to-right texts the letters will simply be shown starting from

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

@@ -1466,7 +1466,7 @@ public final class Quaternion implements Savable, Cloneable, java.io.Serializabl
      * code.
      *
      * @param out the object to write to (not null)
-     * @throws IOException if the ObjectOuput cannot write a float
+     * @throws IOException if the ObjectOutput cannot write a float
      * @see java.io.Externalizable
      */
     public void writeExternal(ObjectOutput out) throws IOException {

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

@@ -38,7 +38,7 @@ import java.io.IOException;
 
 /**
  * A 3-D coordinate transform composed of translation, rotation, and scaling.
- * The order of application is: scale then rotate then translate.
+ * The order of application is: scale, then rotate, then translate.
  *
  * <p>Started July 16, 2004
  *

jme3-core/src/main/java/com/jme3/renderer/opengl/GLRenderer.java

@@ -2264,8 +2264,8 @@ public final class GLRenderer implements Renderer {
         switch (mode) {
             case BorderClamp:
             case Clamp:
+                // fall through
             case EdgeClamp:
-                // Falldown intentional.
                 return GL.GL_CLAMP_TO_EDGE;
             case Repeat:
                 return GL.GL_REPEAT;

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

@@ -932,7 +932,7 @@ public class VertexBuffer extends NativeObject implements Savable, Cloneable {
         int outPos = outIndex * components;
         int elementSz = components;
         if (format == Format.Half) {
-            // because half is stored as ByteBuffer but it's 2 bytes long
+            // because half is stored as ByteBuffer, but it's 2 bytes long
             inPos *= 2;
             outPos *= 2;
             elementSz *= 2;

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

@@ -115,7 +115,7 @@ public class CameraControl extends AbstractControl {
                     camera.setRotation(spatial.getWorldRotation());
                     break;
                 case CameraToSpatial:
-                    // set the localtransform, so that the worldtransform would be equal to the camera's transform.
+                    // Set the local transform so that the world transform would be equal to the camera's transform.
                     // Location:
                     TempVars vars = TempVars.get();
 

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

@@ -60,7 +60,7 @@ import java.util.concurrent.ConcurrentHashMap;
 public final class BufferUtils {
 
     /**
-     * The field should be final to support thread-safe.
+     * Should be final for thread safety.
      */
     private static final BufferAllocator allocator = BufferAllocatorFactory.create();
 

jme3-core/src/main/java/com/jme3/util/mikktspace/MikkTSpaceContext.java

@@ -70,7 +70,7 @@ public interface MikkTSpaceContext {
     public void getTexCoord(float texOut[], int face, int vert);
 
     /**
-     * The call-backsetTSpaceBasic() is sufficient for basic normal mapping.
+     * The callback setTSpaceBasic() is sufficient for basic normal mapping.
      * This function is used to return the tangent and sign to the application.
      * tangent is a unit length vector. For normal maps it is sufficient to use
      * the following simplified version of the bitangent which is generated at

jme3-core/src/main/java/com/jme3/util/mikktspace/MikktspaceTangentGenerator.java

@@ -43,17 +43,17 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 
 /**
- * This tangent generator is Highly experimental.
- * This is the Java translation of The mikktspace generator made by Morten S. Mikkelsen
+ * This tangent generator is highly experimental.
+ * This is the Java translation of the mikktspace generator made by Morten S. Mikkelsen
  * C Source code can be found here
  * https://developer.blender.org/diffusion/B/browse/master/intern/mikktspace/mikktspace.c
  * https://developer.blender.org/diffusion/B/browse/master/intern/mikktspace/mikktspace.h
  * 
- * MikkTspace looks like the new standard of tangent generation in 3D software.
+ * Mikktspace looks like the new standard of tangent generation in 3-D software.
  * Xnormal, Blender, Substance painter, and many more use it.
  * 
  * Usage is :
- * MikkTSpaceTangentGenerator.generate(spatial);
+ * MikktspaceTangentGenerator.generate(spatial);
  * 
  * 
  * 

jme3-examples/src/main/java/jme3test/light/TestLightControlDirectional.java

@@ -49,7 +49,7 @@ import com.jme3.util.TempVars;
 
 /**
  * Creates a directional light controlled by rotating a node. The light will shine on a surrounding sphere.
- * The light will rotate upon each axis before working on a random axis and then reverting to the x
+ * The light will rotate on each axis, then on a random axis, then return to the X
  * axis.
  *
  * @author Markil 3

jme3-examples/src/main/java/jme3test/light/TestLightControlSpot.java

@@ -49,7 +49,7 @@ import com.jme3.util.TempVars;
 
 /**
  * Creates a spotlight controlled by rotating a node. The light will shine on a surrounding sphere.
- * The light will rotate upon each axis before working on a random axis and then reverting to the x
+ * The light will rotate on each axis, then on a random axis, then return to the X
  * axis.
  *
  * @author Markil 3

jme3-examples/src/main/java/jme3test/model/anim/TestAnimationFactory.java

@@ -51,7 +51,7 @@ public class TestAnimationFactory extends SimpleApplication {
         // 6 seconds in duration, named "anim", running at 25 frames per second
         AnimFactory animationFactory = new AnimFactory(6f, "anim", 25f);
         
-        //creating a translation keyFrame at time = 3 with a translation on the x axis of 5 WU        
+        // Create a translation keyFrame at time = 3 with a translation on the X axis of 5 WU.
         animationFactory.addTimeTranslation(3, new Vector3f(5, 0, 0));
         //resetting the translation to the start position at time = 6
         animationFactory.addTimeTranslation(6, new Vector3f(0, 0, 0));

jme3-examples/src/main/java/jme3test/post/TestSSAO2.java

@@ -76,7 +76,7 @@ public class TestSSAO2 extends SimpleApplication {
 
 
 
-        // show normals as material
+        // A special Material to visualize mesh normals:
         //Material mat = new Material(assetManager, "Common/MatDefs/Misc/ShowNormals.j3md");
         for (int f = 10; f > 3; f--) {
             for (int y = -f; y < f; y++) {

jme3-examples/src/main/java/jme3test/stress/TestBatchLod.java

@@ -64,7 +64,7 @@ public class TestBatchLod extends SimpleApplication {
         mat.setBoolean("VertexLighting", true);
         teapot.setMaterial(mat);
 
-        // show normals as material
+        // A special Material to visualize mesh normals:
         //Material mat = new Material(assetManager, "Common/MatDefs/Misc/ShowNormals.j3md");
         flyCam.setMoveSpeed(5);
         for (int y = -5; y < 5; y++) {

jme3-examples/src/main/java/jme3test/stress/TestLodStress.java

@@ -67,7 +67,7 @@ public class TestLodStress extends SimpleApplication {
         mat.setBoolean("VertexLighting", true);
         teapot.setMaterial(mat);
         
-       // show normals as material
+        // A special Material to visualize mesh normals:
         //Material mat = new Material(assetManager, "Common/MatDefs/Misc/ShowNormals.j3md");
 
         for (int y = -10; y < 10; y++){

jme3-examples/src/main/java/jme3test/terrain/TerrainTestAndroid.java

@@ -179,9 +179,9 @@ public class TerrainTestAndroid extends SimpleApplication {
                 triPlanar = !triPlanar;
                 if (triPlanar) {
                     matRock.setBoolean("useTriPlanarMapping", true);
-                    // planar textures don't use the mesh's texture coordinates but real world coordinates,
-                    // so we need to convert these texture coordinate scales into real world scales so it looks
-                    // the same when we switch to/from tri-planar mode
+                    // Planar textures don't use the mesh's texture coordinates but real-world coordinates,
+                    // so we need to convert these texture-coordinate scales into real-world scales so it looks
+                    // the same when we switch to tri-planar mode.
                     matRock.setFloat("Tex1Scale", 1f / (512f / grassScale));
                     matRock.setFloat("Tex2Scale", 1f / (512f / dirtScale));
                     matRock.setFloat("Tex3Scale", 1f / (512f / rockScale));

jme3-examples/src/main/java/jme3test/tools/TestSaveGame.java

@@ -52,27 +52,27 @@ public class TestSaveGame extends SimpleApplication {
     @Override
     public void simpleInitApp() {
 
-        //node that is used to store player data
+        // Create a Node to store player data.
         Node myPlayer = new Node();
         myPlayer.setName("PlayerNode");
         myPlayer.setUserData("name", "Mario");
         myPlayer.setUserData("health", 100.0f);
         myPlayer.setUserData("points", 0);
 
-        //the actual model would be attached to this node
+        // Attach the model to the Node.
         Spatial model = assetManager.loadModel("Models/Oto/Oto.mesh.xml");
         myPlayer.attachChild(model);
 
-        //before saving the game, the model should be detached so it's not saved along with the node
+        // Before saving the game, detach the model since it doesn't need to be saved.
         myPlayer.detachAllChildren();
         SaveGame.saveGame("mycompany/mygame", "savegame_001", myPlayer);
 
-        //later the game is loaded again
+        // Later, the game is loaded again ...
         Node player = (Node) SaveGame.loadGame("mycompany/mygame", "savegame_001");
         player.attachChild(model);
         rootNode.attachChild(player);
 
-        //and the data is available
+        // and the player data are available.
         System.out.println("Name: " + player.getUserData("name"));
         System.out.println("Health: " + player.getUserData("health"));
         System.out.println("Points: " + player.getUserData("points"));
@@ -80,6 +80,6 @@ public class TestSaveGame extends SimpleApplication {
         AmbientLight al = new AmbientLight();
         rootNode.addLight(al);
         
-        //note you can also implement your own classes that implement the Savable interface.
+        // Note that your custom classes can also implement the Savable interface.
     }
 }

jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpKernel.java

@@ -272,7 +272,7 @@ public class UdpKernel extends AbstractKernel
         {
             log.log( Level.FINE, "Kernel started for connection:{0}.", address );
 
-            // An atomic is safest and costs almost nothing
+            // An atomic is safest and costs almost nothing.
             while( go.get() ) {
                 try {
                     // Could reuse the packet, but I don't see the

jme3-plugins/src/ogre/java/com/jme3/scene/plugins/ogre/MeshLoader.java

@@ -341,7 +341,7 @@ public class MeshLoader extends DefaultHandler implements AssetLoader {
             float sum = w0 + w1 + w2 + w3;
             if (sum != 1f) {
                 weightsFloatData.position(weightsFloatData.position() - 4);
-                // compute new vals based on sum
+                // Compute new weights based on sum.
                 float sumToB = sum == 0 ? 0 : 1f / sum;
                 weightsFloatData.put(w0 * sumToB);
                 weightsFloatData.put(w1 * sumToB);
@@ -716,7 +716,7 @@ public class MeshLoader extends DefaultHandler implements AssetLoader {
             geom = null;
             mesh = null;
         } else if (qName.equals("submeshes") && !submeshNamesHack) {
-            // IMPORTANT: restore sharedmesh, for use with shared boneweights
+            // IMPORTANT: restore shared mesh, for use with shared bone weights
             geom = null;
             mesh = sharedMesh;
             usesSharedVerts = false;

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

@@ -86,8 +86,8 @@ public class FaultHeightMap extends AbstractHeightMap {
     private int faultShape; // The type of fault
 
     /**
-     * Constructor creates the fault. For faulttype other than STEP, a range can
-     * be provided. For faultshape circle, min and max radii can be provided.
+     * Constructor creates the fault. For faultType other than STEP, a range can
+     * be provided. For faultShape circle, min and max radii can be provided.
      * Don't forget to reload the map if you have set parameters after the constructor
      * call.
      * @param size The size of the heightmap

jme3-vr/src/main/java/com/jme3/app/VREnvironment.java

@@ -43,7 +43,7 @@ public class VREnvironment {
     private VRBounds bounds             = null;
 
     /**
-     * The underlying system VR API. By default set to {@link VRConstants#SETTING_VRAPI_OPENVR_VALUE}.
+     * The underlying system VR API. By default, set to {@link VRConstants#SETTING_VRAPI_OPENVR_VALUE}.
      */
     public int vrBinding = VRConstants.SETTING_VRAPI_OPENVR_VALUE;
 

jme3-vr/src/main/java/com/jme3/input/vr/AbstractVRMouseManager.java

@@ -49,7 +49,7 @@ public abstract class AbstractVRMouseManager implements VRMouseManager {
     public void initialize() {
         logger.config("Initializing VR mouse manager.");
 
-        // load default mouseimage
+        // load default mouse image
         mouseImage = new Picture("mouse");
         setImage("Common/Util/mouse.png");
         // hide default cursor by making it invisible