jme3-bullet: add and improve comments, mostly JavaDoc

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

@@ -214,7 +214,7 @@ public Control cloneForSpatial(Spatial spatial) {
      * shallow-cloned control into a deep-cloned one, using the specified cloner
      * and original to resolve copied fields.
      *
-     * @param cloner the cloner currently cloning this control (not null)
+     * @param cloner the cloner that's cloning this control (not null)
      * @param original the control from which this control was shallow-cloned
      * (unused)
      */

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

@@ -275,14 +275,15 @@ public void jump() {
      * coordinate system, which normally is always z-forward (in world
      * coordinates, parent coordinates when set to applyLocalPhysics)
      *
-     * @param jumpForce the desired jump force (not null, unaffected)
+     * @param jumpForce the desired jump force (not null, unaffected,
+     * default=5*mass in +Y direction)
      */
     public void setJumpForce(Vector3f jumpForce) {
         this.jumpForce.set(jumpForce);
     }
 
     /**
-     * Access the jump force. The default is 5 * character mass in Y direction.
+     * Access the jump force.
      *
      * @return the pre-existing vector (not null)
      */
@@ -291,9 +292,9 @@ public Vector3f getJumpForce() {
     }
 
     /**
-     * Check if the character is on the ground. This is determined by a ray test
-     * in the center of the character and might return false even if the
-     * character is not falling yet.
+     * Test whether the character is supported. Uses a ray test from the center
+     * of the character and might return false even if the character is not
+     * falling yet.
      *
      * @return true if on the ground, otherwise false
      */
@@ -305,8 +306,8 @@ public boolean isOnGround() {
      * Toggle character ducking. When ducked the characters capsule collision
      * shape height will be multiplied by duckedFactor to make the capsule
      * smaller. When unducking, the character will check with a ray test if it
-     * can in fact unduck and only do so when its possible. You can check the
-     * state of the unducking by checking isDucked().
+     * can in fact unduck and only do so when its possible. You can test the
+     * state using isDucked().
      *
      * @param enabled true→duck, false→unduck
      */

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

@@ -180,7 +180,7 @@ public Object jmeClone() {
      * shallow-cloned control into a deep-cloned one, using the specified cloner
      * and original to resolve copied fields.
      *
-     * @param cloner the cloner currently cloning this control (not null)
+     * @param cloner the cloner that's cloning this control (not null)
      * @param original the control from which this control was shallow-cloned
      * (unused)
      */

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

@@ -176,7 +176,7 @@ public Object jmeClone() {
      * shallow-cloned control into a deep-cloned one, using the specified cloner
      * and original to resolve copied fields.
      *
-     * @param cloner the cloner currently cloning this control (not null)
+     * @param cloner the cloner that's cloning this control (not null)
      * @param original the control from which this control was shallow-cloned
      * (unused)
      */

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

@@ -211,7 +211,7 @@ public Object jmeClone() {
      * shallow-cloned control into a deep-cloned one, using the specified cloner
      * and original to resolve copied fields.
      *
-     * @param cloner the cloner currently cloning this control (not null)
+     * @param cloner the cloner that's cloning this control (not null)
      * @param original the control from which this control was shallow-cloned
      * (unused)
      */

jme3-bullet/src/common/java/com/jme3/bullet/debug/BulletCharacterDebugControl.java

@@ -122,7 +122,7 @@ protected void controlUpdate(float tpf) {
     }
 
     /**
-     * Render this control. Invoked once port per frame, provided the
+     * Render this control. Invoked once per frame, provided the
      * control is enabled and added to a scene. Should be invoked only by a
      * subclass or by AbstractControl.
      *

jme3-bullet/src/main/java/com/jme3/bullet/PhysicsSpace.java

@@ -595,8 +595,9 @@ public void removeCollisionObject(PhysicsCollisionObject obj) {
     }
 
     /**
-     * Add all physics controls and joints in the specified subtree of the scene
-     * graph to this space (e.g. after loading from disk). Note: recursive!
+     * Add all collision objects and joints in the specified subtree of the
+     * scene graph to this space (e.g. after loading from disk). Note:
+     * recursive!
      *
      * @param spatial the root of the subtree (not null)
      */
@@ -1245,7 +1246,7 @@ public float getAccuracy() {
      * <p>
      * In general, the smaller the time step, the more accurate (and
      * compute-intensive) the simulation will be. Bullet works best with a
-     * timestep of no more than 1/60 second.
+     * time step of no more than 1/60 second.
      *
      * @param accuracy the desired time step (in seconds, &gt;0, default=1/60)
      */

jme3-bullet/src/main/java/com/jme3/bullet/collision/PhysicsCollisionEvent.java

@@ -36,7 +36,7 @@
 import java.util.EventObject;
 
 /**
- * An event that describes a collision in the physics world.
+ * Describe a collision in the physics world.
  * <p>
  * Do not retain this object, as it will be reused after the collision() method
  * returns. Copy any data you need during the collide() method.

jme3-bullet/src/main/java/com/jme3/bullet/collision/PhysicsCollisionObject.java

@@ -236,7 +236,8 @@ public int getCollideWithGroups() {
     }
 
     /**
-     * Initialize the user pointer and collision-group information of this object.
+     * Initialize the user pointer and collision-group information of this
+     * object.
      */
     protected void initUserPointer() {
         Logger.getLogger(this.getClass().getName()).log(Level.FINE, "initUserPointer() objectId = {0}", Long.toHexString(objectId));

jme3-bullet/src/main/java/com/jme3/bullet/collision/PhysicsRayTestResult.java

@@ -76,7 +76,7 @@ public PhysicsCollisionObject getCollisionObject() {
     /**
      * Access the normal vector at the point of contact.
      *
-     * @return the pre-existing vector (not null)
+     * @return a pre-existing unit vector (not null)
      */
     public Vector3f getHitNormalLocal() {
         return hitNormalLocal;

jme3-bullet/src/main/java/com/jme3/bullet/collision/PhysicsSweepTestResult.java

@@ -34,7 +34,7 @@
 import com.jme3.math.Vector3f;
 
 /**
- * Contains the results of a PhysicsSpace rayTest
+ * Represent the results of a Bullet sweep test.
  *
  * @author normenhansen
  */
@@ -57,6 +57,10 @@ public class PhysicsSweepTestResult {
      */
     private boolean normalInWorldSpace;
 
+    /**
+     * A private constructor to inhibit instantiation of this class by Java.
+     * These results are instantiated exclusively by native code.
+     */
     public PhysicsSweepTestResult() {
     }
 
@@ -86,7 +90,8 @@ public Vector3f getHitNormalLocal() {
     }
 
     /**
-     * Read the hit fraction.
+     * Read the fraction of fraction of the way between the transforms (from=0,
+     * to=1, ≥0, ≤1)
      *
      * @return fraction (from=0, to=1, ≥0, ≤1)
      */

jme3-bullet/src/main/java/com/jme3/bullet/collision/shapes/BoxCollisionShape.java

@@ -63,16 +63,16 @@ public BoxCollisionShape() {
     /**
      * Instantiate a box shape with the specified half extents.
      *
-     * @param halfExtents the desired half extents (not null, no negative
-     * component, alias created)
+     * @param halfExtents the desired unscaled half extents (not null, no
+     * negative component, alias created)
      */
     public BoxCollisionShape(Vector3f halfExtents) {
         this.halfExtents = halfExtents;
         createShape();
     }
 
     /**
-     * Access the half extents.
+     * Access the half extents of the box.
      *
      * @return the pre-existing instance (not null, no negative component)
      */

jme3-bullet/src/main/java/com/jme3/bullet/collision/shapes/CapsuleCollisionShape.java

@@ -42,7 +42,7 @@
 
 /**
  * A capsule collision shape based on Bullet's btCapsuleShapeX, btCapsuleShape,
- * or btCapsuleShapeZ.
+ * or btCapsuleShapeZ. These shapes have no margin and cannot be scaled.
  *
  * @author normenhansen
  */
@@ -97,7 +97,7 @@ public CapsuleCollisionShape(float radius, float height, int axis) {
     /**
      * Read the radius of the capsule.
      *
-     * @return radius (≥0)
+     * @return the radius (≥0)
      */
     public float getRadius() {
         return radius;

jme3-bullet/src/main/java/com/jme3/bullet/collision/shapes/CollisionShape.java

@@ -50,7 +50,7 @@
 public abstract class CollisionShape implements Savable {
 
     /**
-     * unique identifier of the Bullet shape
+     * unique identifier of the btCollisionShape
      * <p>
      * Constructors are responsible for setting this to a non-zero value. After
      * that, the id never changes.
@@ -61,8 +61,7 @@ public abstract class CollisionShape implements Savable {
      */
     protected Vector3f scale = new Vector3f(1, 1, 1);
     /**
-     * copy of collision margin (in physics-space units, &gt;0,
-     * default=0)
+     * copy of collision margin (in physics-space units, &gt;0, default=0)
      */
     protected float margin = 0.0f;
 
@@ -87,7 +86,7 @@ public CollisionShape() {
 //    private native void calculateLocalInertia(long objectId, long shapeId, float mass);
 
     /**
-     * Read the id of the Bullet shape.
+     * Read the id of the btCollisionShape.
      *
      * @return the unique identifier (not zero)
      */
@@ -128,7 +127,7 @@ public Vector3f getScale() {
     /**
      * Read the collision margin for this shape.
      *
-     * @return the margin distance (in physics-space units, &gt;0)
+     * @return the margin distance (in physics-space units, &ge;0)
      */
     public float getMargin() {
         return getMargin(objectId);
@@ -137,7 +136,7 @@ public float getMargin() {
     private native float getMargin(long objectId);
 
     /**
-     * Alter the collision margin for this shape. CAUTION: Margin is applied
+     * Alter the collision margin of this shape. CAUTION: Margin is applied
      * differently, depending on the type of shape. Generally the collision
      * margin expands the object, creating a gap. Don't set the collision margin
      * to zero.

jme3-bullet/src/main/java/com/jme3/bullet/collision/shapes/CylinderCollisionShape.java

@@ -54,7 +54,7 @@ public class CylinderCollisionShape extends CollisionShape {
      */
     protected Vector3f halfExtents;
     /**
-     * main (height) axis (0→X, 1→Y, 2→Z)
+     * copy of main (height) axis (0→X, 1→Y, 2→Z)
      */
     protected int axis;
 
@@ -68,8 +68,8 @@ public CylinderCollisionShape() {
     /**
      * Instantiate a Z-axis cylinder shape with the specified half extents.
      *
-     * @param halfExtents the desired half extents (not null, no negative
-     * component, alias created)
+     * @param halfExtents the desired unscaled half extents (not null, no
+     * negative component, alias created)
      */
     public CylinderCollisionShape(Vector3f halfExtents) {
         this.halfExtents = halfExtents;
@@ -80,8 +80,8 @@ public CylinderCollisionShape(Vector3f halfExtents) {
     /**
      * Instantiate a cylinder shape around the specified axis.
      *
-     * @param halfExtents the desired half extents (not null, no negative
-     * component, alias created)
+     * @param halfExtents the desired unscaled half extents (not null, no 
+     * negative component, alias created)
      * @param axis which local axis: 0→X, 1→Y, 2→Z
      */
     public CylinderCollisionShape(Vector3f halfExtents, int axis) {

jme3-bullet/src/main/java/com/jme3/bullet/collision/shapes/HeightfieldCollisionShape.java

@@ -84,7 +84,7 @@ public class HeightfieldCollisionShape extends CollisionShape {
      * buffer for passing height data to Bullet
      * <p>
      * A Java reference must persist after createShape() completes, or else the
-     * buffer might get garbaged collected.
+     * buffer might get garbage collected.
      */    
     protected ByteBuffer bbuf;
 //    protected FloatBuffer fbuf;

jme3-bullet/src/main/java/com/jme3/bullet/collision/shapes/HullCollisionShape.java

@@ -64,18 +64,20 @@ public HullCollisionShape() {
      * performance and stability, use the mesh should have no more than 100
      * vertices.
      *
-     * @param mesh a mesh on which to base the shape (not null)
+     * @param mesh a mesh on which to base the shape (not null, at least one
+     * vertex)
      */
     public HullCollisionShape(Mesh mesh) {
         this.points = getPoints(mesh);
         createShape();
     }
 
     /**
-     * Instantiate a collision shape based on the specified JME mesh.
+     * Instantiate a collision shape based on the specified array of
+     * coordinates.
      *
      * @param points an array of coordinates on which to base the shape (not
-     * null, length a multiple of 3)
+     * null, not empty, length a multiple of 3)
      */
     public HullCollisionShape(float[] points) {
         this.points = points;

jme3-bullet/src/main/java/com/jme3/bullet/collision/shapes/SphereCollisionShape.java

@@ -41,7 +41,8 @@
 import java.util.logging.Logger;
 
 /**
- * A spherical collision shape based on Bullet's btSphereShape.
+ * A spherical collision shape based on Bullet's btSphereShape. These shapes
+ * have no margin and cannot be scaled.
  *
  * @author normenhansen
  */
@@ -70,7 +71,7 @@ public SphereCollisionShape(float radius) {
     }
 
     /**
-     * Read the radius of this shape.
+     * Read the radius of the sphere.
      *
      * @return the radius (≥0)
      */

jme3-bullet/src/main/java/com/jme3/bullet/joints/PhysicsJoint.java

@@ -162,7 +162,7 @@ public PhysicsRigidBody getBodyB() {
     /**
      * Access the local offset of the joint connection point in node A.
      *
-     * @return the pre-existing vector
+     * @return the pre-existing vector (not null)
      */
     public Vector3f getPivotA() {
         return pivotA;
@@ -171,7 +171,7 @@ public Vector3f getPivotA() {
     /**
      * Access the local offset of the joint connection point in node A.
      *
-     * @return the pre-existing vector
+     * @return the pre-existing vector (not null)
      */
     public Vector3f getPivotB() {
         return pivotB;

jme3-bullet/src/main/java/com/jme3/bullet/objects/PhysicsCharacter.java

@@ -287,7 +287,8 @@ public float getJumpSpeed() {
     }
 
     /**
-     * @deprecated Deprecated in bullet 2.86.1. Use setGravity(Vector3f) instead.
+     * @deprecated Deprecated in bullet 2.86.1. Use setGravity(Vector3f)
+     * instead.
      * @param value the desired upward component of the acceleration (typically
      * negative)
      */
@@ -308,7 +309,8 @@ public void setGravity(Vector3f value) {
     private native void setGravity(long characterId, Vector3f gravity);
 
     /**
-     * @deprecated Deprecated in bullet 2.86.1. Use getGravity(Vector3f) instead.
+     * @deprecated Deprecated in bullet 2.86.1. Use getGravity(Vector3f)
+     * instead.
      * @return the upward component of the acceleration (typically negative)
      */
     @Deprecated