jme3-bullet: add and improve comments, mostly JavaDoc

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

@@ -207,7 +207,7 @@ public abstract class AbstractPhysicsControl implements PhysicsControl, 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/BetterCharacterControl.java

@@ -277,14 +277,15 @@ public class BetterCharacterControl extends AbstractPhysicsControl implements Ph
      * 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)
      */
@@ -293,9 +294,9 @@ public class BetterCharacterControl extends AbstractPhysicsControl implements Ph
     }
 
     /**
-     * Check if the character is on the ground. This is determined by a ray test
+     * Test whether the character is supported. Uses a ray test from the center
-     * in the center of the character and might return false even if the
+     * of the character and might return false even if the character is not
-     * character is not falling yet.
+     * falling yet.
      *
      * @return true if on the ground, otherwise false
      */
@@ -307,8 +308,8 @@ public class BetterCharacterControl extends AbstractPhysicsControl implements Ph
      * 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
+     * can in fact unduck and only do so when its possible. You can test the
-     * state of the unducking by checking isDucked().
+     * state using isDucked().
      *
      * @param enabled true→duck, false→unduck
      */

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

@@ -187,7 +187,7 @@ public class GhostControl extends PhysicsGhostObject implements PhysicsControl,
      * 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

@@ -199,7 +199,7 @@ public class RigidBodyControl extends PhysicsRigidBody implements PhysicsControl
      * 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

@@ -257,7 +257,7 @@ public class VehicleControl extends PhysicsVehicle implements PhysicsControl, Jm
      * 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 @@ public class BulletCharacterDebugControl extends AbstractPhysicsDebugControl {
     }
 
     /**
-     * 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 class PhysicsSpace {
     }
 
     /**
-     * Add all physics controls and joints in the specified subtree of the scene
+     * Add all collision objects and joints in the specified subtree of the
-     * graph to this space (e.g. after loading from disk). Note: recursive!
+     * scene graph to this space (e.g. after loading from disk). Note:
+     * recursive!
      *
      * @param spatial the root of the subtree (not null)
      */

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

@@ -36,7 +36,7 @@ import com.jme3.scene.Spatial;
 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 abstract class PhysicsCollisionObject implements Savable {
     }
 
     /**
-     * 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 class PhysicsRayTestResult {
     /**
      * 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 @@ package com.jme3.bullet.collision;
 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 class PhysicsSweepTestResult {
     }
 
     /**
-     * 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,8 +63,8 @@ public class BoxCollisionShape extends CollisionShape {
     /**
      * Instantiate a box shape with the specified half extents.
      *
-     * @param halfExtents the desired half extents (not null, no negative
+     * @param halfExtents the desired unscaled half extents (not null, no
-     * component, alias created)
+     * negative component, alias created)
      */
     public BoxCollisionShape(Vector3f halfExtents) {
         this.halfExtents = halfExtents;
@@ -72,7 +72,7 @@ public class BoxCollisionShape extends CollisionShape {
     }
 
     /**
-     * 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 @@ import java.util.logging.Logger;
 
 /**
  * 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 class CapsuleCollisionShape extends CollisionShape{
     /**
      * 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 @@ import java.util.logging.Logger;
 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,
+     * copy of collision margin (in physics-space units, &gt;0, default=0)
-     * default=0)
      */
     protected float margin = 0.0f;
 
@@ -87,7 +86,7 @@ public abstract class CollisionShape implements Savable {
 //    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 abstract class CollisionShape implements Savable {
     /**
      * 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 abstract class CollisionShape implements Savable {
     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 class CylinderCollisionShape extends CollisionShape {
     /**
      * Instantiate a Z-axis cylinder shape with the specified half extents.
      *
-     * @param halfExtents the desired half extents (not null, no negative
+     * @param halfExtents the desired unscaled half extents (not null, no
-     * component, alias created)
+     * negative component, alias created)
      */
     public CylinderCollisionShape(Vector3f halfExtents) {
         this.halfExtents = halfExtents;
@@ -80,8 +80,8 @@ public class CylinderCollisionShape extends CollisionShape {
     /**
      * Instantiate a cylinder shape around the specified axis.
      *
-     * @param halfExtents the desired half extents (not null, no negative
+     * @param halfExtents the desired unscaled half extents (not null, no 
-     * component, alias created)
+     * 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,7 +64,8 @@ public class HullCollisionShape extends CollisionShape {
      * 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);
@@ -72,10 +73,11 @@ public class HullCollisionShape extends CollisionShape {
     }
 
     /**
-     * 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.Level;
 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 class SphereCollisionShape extends CollisionShape {
     }
 
     /**
-     * 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 abstract class PhysicsJoint implements Savable {
     /**
      * 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 abstract class PhysicsJoint implements Savable {
     /**
      * 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 class PhysicsCharacter extends PhysicsCollisionObject {
     }
 
     /**
-     * @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 class PhysicsCharacter extends PhysicsCollisionObject {
     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

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

@@ -128,7 +128,8 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
     /**
      * Directly alter the location of this object's center.
      *
-     * @param location the desired location (not null, unaffected)
+     * @param location the desired location (in physics-space coordinates, not
+     * null, unaffected)
      */
     public void setPhysicsLocation(Vector3f location) {
         setPhysicsLocation(objectId, location);
@@ -139,8 +140,8 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
     /**
      * Directly alter this object's orientation.
      *
-     * @param rotation the desired orientation (rotation matrix, not null,
+     * @param rotation the desired orientation (a rotation matrix in
-     * unaffected)
+     * physics-space coordinates, not null, unaffected)
      */
     public void setPhysicsRotation(Matrix3f rotation) {
         setPhysicsRotation(objectId, rotation);
@@ -164,8 +165,8 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
      * Copy the location of this object's center.
      *
      * @param trans storage for the result (modified if not null)
-     * @return the physics location (either the provided storage or a new
+     * @return a location vector (in physics-space coordinates, either
-     * vector, not null)
+     * the provided storage or a new vector, not null)
      */
     public Vector3f getPhysicsLocation(Vector3f trans) {
         if (trans == null) {
@@ -181,8 +182,8 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
      * Copy this object's orientation to a quaternion.
      *
      * @param rot storage for the result (modified if not null)
-     * @return the physics orientation (either the provided storage or a new
+     * @return an orientation (in physics-space coordinates, either the provided
-     * quaternion, not null)
+     * storage or a new quaternion, not null)
      */
     public Quaternion getPhysicsRotation(Quaternion rot) {
         if (rot == null) {
@@ -198,8 +199,8 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
      * Copy this object's orientation to a matrix.
      *
      * @param rot storage for the result (modified if not null)
-     * @return the orientation (either the provided storage or a new matrix, not
+     * @return an orientation (in physics-space coordinates, either the provided
-     * null)
+     * storage or a new matrix, not null)
      */
     public Matrix3f getPhysicsRotationMatrix(Matrix3f rot) {
         if (rot == null) {
@@ -258,9 +259,6 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
 
     /**
      * Access a list of overlapping objects.
-     * <p>
-     * Another object overlaps with this one if and if only their
-     * CollisionShapes overlap.
      *
      * @return an internal list which may get reused (not null)
      */
@@ -285,7 +283,7 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
     }
 
     /**
-     * Count how many CollisionObjects this object overlaps.
+     * Count how many collision objects this object overlaps.
      *
      * @return count (&ge;0)
      */

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

@@ -198,8 +198,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Directly alter this body's orientation.
      *
-     * @param rotation the desired orientation (quaternion, not null,
+     * @param rotation the desired orientation (quaternion, in physics-space
-     * unaffected)
+     * coordinates, not null, unaffected)
      */
     public void setPhysicsRotation(Quaternion rotation) {
         setPhysicsRotation(objectId, rotation);
@@ -211,8 +211,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
      * Copy the location of this body's center of mass.
      *
      * @param trans storage for the result (modified if not null)
-     * @return the location (either the provided storage or a new vector, not
+     * @return the location (in physics-space coordinates, either the provided 
-     * null)
+     * storage or a new vector, not null)
      */
     public Vector3f getPhysicsLocation(Vector3f trans) {
         if (trans == null) {
@@ -250,7 +250,7 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     private native void setInverseInertiaLocal(long objectId, Vector3f gravity);
 
     /**
-     * Read the principal components of the local inverse inertia tensor.
+     * Copy the principal components of the local inverse inertia tensor.
      *
      * @param trans storage for the result (modified if not null)
      * @return a vector (either the provided storage or a new vector, not null)
@@ -271,8 +271,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
      * Copy this body's orientation to a matrix.
      *
      * @param rot storage for the result (modified if not null)
-     * @return the orientation (either the provided storage or a new matrix, not
+     * @return the orientation (in physics-space coordinates, either the 
-     * null)
+     * provided storage or a new matrix, not null)
      */
     public Matrix3f getPhysicsRotationMatrix(Matrix3f rot) {
         if (rot == null) {
@@ -473,7 +473,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Copy this body's gravitational acceleration.
      *
-     * @return a new acceleration vector (not null)
+     * @return a new acceleration vector (in physics-space coordinates, not 
+     * null)
      */
     public Vector3f getGravity() {
         return getGravity(null);
@@ -483,8 +484,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
      * Copy this body's gravitational acceleration.
      *
      * @param gravity storage for the result (modified if not null)
-     * @return an acceleration vector (either the provided storage or a new
+     * @return an acceleration vector (in physics-space coordinates, either the 
-     * vector, not null)
+     * provided storage or a new vector, not null)
      */
     public Vector3f getGravity(Vector3f gravity) {
         if (gravity == null) {
@@ -619,7 +620,7 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Copy this body's angular velocity.
      *
-     * @return a new velocity vector (not null)
+     * @return a new velocity vector (in physics-space coordinates, not null)
      */
     public Vector3f getAngularVelocity() {
         Vector3f vec = new Vector3f();
@@ -632,7 +633,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Copy this body's angular velocity.
      *
-     * @param vec storage for the result (not null, modified)
+     * @param vec storage for the result (in physics-space coordinates, not 
+     * null, modified)
      */
     public void getAngularVelocity(Vector3f vec) {
         getAngularVelocity(objectId, vec);
@@ -653,7 +655,7 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Copy the linear velocity of this body's center of mass.
      *
-     * @return a new velocity vector (not null)
+     * @return a new velocity vector (in physics-space coordinates, not null)
      */
     public Vector3f getLinearVelocity() {
         Vector3f vec = new Vector3f();
@@ -666,7 +668,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Copy the linear velocity of this body's center of mass.
      *
-     * @param vec storage for the result (not null, modified)
+     * @param vec storage for the result (in physics-space coordinates, not 
+     * null, modified)
      */
     public void getLinearVelocity(Vector3f vec) {
         getLinearVelocity(objectId, vec);
@@ -691,7 +694,7 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
      * To apply an impulse, use applyImpulse, use applyContinuousForce to apply
      * continuous force.
      *
-     * @param force the force
+     * @param force the force (not null, unaffected)
      * @param location the location of the force
      */
     public void applyForce(Vector3f force, Vector3f location) {
@@ -708,7 +711,7 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
      * To apply an impulse, use
      * {@link #applyImpulse(com.jme3.math.Vector3f, com.jme3.math.Vector3f)}.
      *
-     * @param force the force
+     * @param force the force (not null, unaffected)
      */
     public void applyCentralForce(Vector3f force) {
         applyCentralForce(objectId, force);
@@ -724,7 +727,7 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
      * To apply an impulse, use
      * {@link #applyImpulse(com.jme3.math.Vector3f, com.jme3.math.Vector3f)}.
      *
-     * @param torque the torque
+     * @param torque the torque (not null, unaffected)
      */
     public void applyTorque(Vector3f torque) {
         applyTorque(objectId, torque);
@@ -736,8 +739,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Apply an impulse to the body the next physics update.
      *
-     * @param impulse applied impulse
+     * @param impulse applied impulse (not null, unaffected)
-     * @param rel_pos location relative to object
+     * @param rel_pos location relative to object (not null, unaffected)
      */
     public void applyImpulse(Vector3f impulse, Vector3f rel_pos) {
         applyImpulse(objectId, impulse, rel_pos);
@@ -870,9 +873,9 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     private native float getAngularSleepingThreshold(long objectId);
 
     /**
-     * Read the X-component of this body's angular factor.
+     * Read this body's angular factor for the X axis.
      *
-     * @return the X-component of the angular factor
+     * @return the angular factor
      */
     public float getAngularFactor() {
         return getAngularFactor(null).getX();
@@ -882,7 +885,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
      * Copy this body's angular factors.
      *
      * @param store storage for the result (modified if not null)
-     * @return a vector (either the provided storage or a new vector, not null)
+     * @return the angular factor for each axis (either the provided storage or 
+     * new vector, not null)
      */
     public Vector3f getAngularFactor(Vector3f store) {
         // Done this way to prevent breaking the API.
@@ -920,7 +924,7 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Copy this body's linear factors.
      *
-     * @return a new vector (not null)
+     * @return the linear factor for each axis (not null)
      */
     public Vector3f getLinearFactor() {
         Vector3f vec = new Vector3f();

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

@@ -74,7 +74,7 @@ public class PhysicsVehicle extends PhysicsRigidBody {
      */
     protected long rayCasterId = 0;
     /**
-     * tuning parameters
+     * tuning parameters applied when a wheel is created
      */
     protected VehicleTuning tuning = new VehicleTuning();
     /**
@@ -615,7 +615,7 @@ public class PhysicsVehicle extends PhysicsRigidBody {
      *
      * @param vector storage for the result (modified if not null)
      * @return a direction vector (in physics-space coordinates, either the
-     * provided storage or a new vector)
+     * provided storage or a new vector, not null)
      */
     public Vector3f getForwardVector(Vector3f vector) {
         if (vector == null) {

jme3-bullet/src/main/java/com/jme3/bullet/objects/infos/RigidBodyMotionState.java

@@ -168,7 +168,7 @@ public class RigidBodyMotionState {
      * coordinates.
      *
      * @param applyPhysicsLocal true→match local coordinates,
-     * false→match world coordinates (default is false)
+     * false→match world coordinates (default=false)
      */
     public void setApplyPhysicsLocal(boolean applyPhysicsLocal) {
         this.applyPhysicsLocal = applyPhysicsLocal;

jme3-bullet/src/main/java/com/jme3/bullet/util/NativeMeshUtil.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2018 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -39,18 +39,26 @@ import java.nio.ByteBuffer;
 import java.nio.FloatBuffer;
 
 /**
+ * A utility class for interfacing with Native Bullet.
  *
  * @author normenhansen
  */
 public class NativeMeshUtil {
     
+    /**
+     * Pass a mesh to Native Bullet.
+     *
+     * @param mesh the JME mesh to pass (not null)
+     * @return the unique identifier of the resulting btTriangleIndexVertexArray
+     * (not 0)
+     */
     public static long getTriangleIndexVertexArray(Mesh mesh){
         ByteBuffer triangleIndexBase = BufferUtils.createByteBuffer(mesh.getTriangleCount() * 3 * 4);
         ByteBuffer vertexBase = BufferUtils.createByteBuffer(mesh.getVertexCount() * 3 * 4);
         int numVertices = mesh.getVertexCount();
-        int vertexStride = 12; //3 verts * 4 bytes per.
+        int vertexStride = 12; //3 verts * 4 bytes each
         int numTriangles = mesh.getTriangleCount();
-        int triangleIndexStride = 12; //3 index entries * 4 bytes each.
+        int triangleIndexStride = 12; //3 index entries * 4 bytes each
 
         IndexBuffer indices = mesh.getIndicesAsList();
         FloatBuffer vertices = mesh.getFloatBuffer(Type.Position);
@@ -72,6 +80,18 @@ public class NativeMeshUtil {
         return createTriangleIndexVertexArray(triangleIndexBase, vertexBase, numTriangles, numVertices, vertexStride, triangleIndexStride);
     }
     
+    /**
+     * Instantiate a btTriangleIndexVertexArray. Native method.
+     *
+     * @param triangleIndexBase index buffer (not null)
+     * @param vertexBase vertex buffer (not null)
+     * @param numTraingles the number of triangles in the mesh (≥0)
+     * @param numVertices the number of vertices in the mesh (≥0)
+     * @param vertextStride (in bytes, >0)
+     * @param triangleIndexStride (in bytes, >0)
+     * @return the unique identifier of the resulting btTriangleIndexVertexArray
+     * (not 0)
+     */
     public static native long createTriangleIndexVertexArray(ByteBuffer triangleIndexBase, ByteBuffer vertexBase, int numTraingles, int numVertices, int vertextStride, int triangleIndexStride);
     
 }