jme3-bullet: add and improve comments, mostly JavaDoc

jme3-bullet/src/common/java/com/jme3/bullet/PhysicsTickListener.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
@@ -32,22 +32,29 @@
 package com.jme3.bullet;
 
 /**
- * Implement this interface to be called from the physics thread on a physics update.
+ * Callback interface from the physics thread, used to clear/apply forces.
+ * <p>
+ * This interface is shared between JBullet and Native Bullet.
+ *
  * @author normenhansen
  */
 public interface PhysicsTickListener {
 
     /**
-     * Called before the physics is actually stepped, use to apply forces etc.
-     * @param space the physics space
-     * @param tpf the time per frame in seconds 
+     * Callback from Bullet, invoked just before the physics is stepped. A good
+     * time to clear/apply forces.
+     *
+     * @param space the space that is about to be stepped (not null)
+     * @param tpf the time per physics step (in seconds, &ge;0)
      */
     public void prePhysicsTick(PhysicsSpace space, float tpf);
 
     /**
-     * Called after the physics has been stepped, use to check for forces etc.
-     * @param space the physics space
-     * @param tpf the time per frame in seconds
+     * Callback from Bullet, invoked just after the physics has been stepped,
+     * use to check for forces etc.
+     *
+     * @param space the space that was just stepped (not null)
+     * @param tpf the time per physics step (in seconds, &ge;0)
      */
     public void physicsTick(PhysicsSpace space, float tpf);
 

jme3-bullet/src/common/java/com/jme3/bullet/collision/PhysicsCollisionGroupListener.java

@@ -32,18 +32,25 @@
 package com.jme3.bullet.collision;
 
 /**
+ * Interface to receive notifications whenever an object in a particular
+ * collision group is about to collide.
+ * <p>
+ * This interface is shared between JBullet and Native Bullet.
  *
  * @author normenhansen
  */
 public interface PhysicsCollisionGroupListener {
 
     /**
-     * Called when two physics objects of the registered group are about to collide, <i>called from physics thread</i>.<br>
-     * This is only called when the collision will happen based on the collisionGroup and collideWithGroups
-     * settings in the PhysicsCollisionObject. That is the case when <b>one</b> of the parties has the
-     * collisionGroup of the other in its collideWithGroups set.<br>
-     * @param nodeA CollisionObject #1
-     * @param nodeB CollisionObject #2
+     * Invoked when two physics objects of the registered group are about to
+     * collide. <i>invoked on the physics thread</i>.<br>
+     * This is only invoked when the collision will happen based on the
+     * collisionGroup and collideWithGroups settings in the
+     * PhysicsCollisionObject. That is the case when <b>one</b> of the parties
+     * has the collisionGroup of the other in its collideWithGroups set.
+     *
+     * @param nodeA collision object #1
+     * @param nodeB collision object #2
      * @return true if the collision should happen, false otherwise
      */
     public boolean collide(PhysicsCollisionObject nodeA, PhysicsCollisionObject nodeB);

jme3-bullet/src/common/java/com/jme3/bullet/collision/PhysicsCollisionListener.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
@@ -32,16 +32,24 @@
 package com.jme3.bullet.collision;
 
 /**
- * Interface for Objects that want to be informed about collision events in the physics space
+ * Interface to receive notifications whenever an object in a particular physics
+ * space collides.
+ * <p>
+ * This interface is shared between JBullet and Native Bullet.
+ *
  * @author normenhansen
  */
 public interface PhysicsCollisionListener {
 
     /**
-     * Called when a collision happened in the PhysicsSpace, <i>called from render thread</i>.
-     * 
-     * Do not store the event object as it will be cleared after the method has finished.
-     * @param event the CollisionEvent
+     * Invoked when a collision happened in the PhysicsSpace. <i>Invoked on the
+     * render thread.</i>
+     * <p>
+     * Do not retain the event object, as it will be reused after the
+     * collision() method returns. Copy any data you need during the collide()
+     * method.
+     *
+     * @param event the event that occurred (not null, reusable)
      */
     public void collision(PhysicsCollisionEvent event);
 

jme3-bullet/src/common/java/com/jme3/bullet/collision/RagdollCollisionListener.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
@@ -34,11 +34,22 @@
 import com.jme3.animation.Bone;
 
 /**
+ * Interface to receive notifications whenever a KinematicRagdollControl
+ * collides with another physics object.
+ * <p>
+ * This interface is shared between JBullet and Native Bullet.
  *
  * @author Nehon
  */
 public interface RagdollCollisionListener {
 
+    /**
+     * Invoked when a collision involving a KinematicRagdollControl occurs.
+     *
+     * @param bone the ragdoll bone that collided (not null)
+     * @param object the collision object that collided with the bone (not null)
+     * @param event other event details (not null)
+     */    
     public void collide(Bone bone, PhysicsCollisionObject object, PhysicsCollisionEvent event);
 
 }

jme3-bullet/src/common/java/com/jme3/bullet/collision/shapes/infos/ChildCollisionShape.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,31 +39,69 @@
 import java.io.IOException;
 
 /**
+ * An element of a CompoundCollisionShape, consisting of a (non-compound) child
+ * shape, offset and rotated with respect to its parent.
+ * <p>
+ * This class is shared between JBullet and Native Bullet.
  *
  * @author normenhansen
  */
 public class ChildCollisionShape implements Savable {
 
+    /**
+     * translation relative to parent shape (not null)
+     */
     public Vector3f location;
+    /**
+     * rotation relative to parent shape (not null)
+     */
     public Matrix3f rotation;
+    /**
+     * base shape (not null, not a compound shape)
+     */
     public CollisionShape shape;
 
+    /**
+     * No-argument constructor needed by SavableClassUtil. Do not invoke
+     * directly!
+     */
     public ChildCollisionShape() {
     }
 
+    /**
+     * Instantiate a child shape for use in a compound shape.
+     *
+     * @param location translation relative to the parent (not null, alias
+     * created)
+     * @param rotation rotation relative to the parent (not null, alias created)
+     * @param shape the base shape (not null, not a compound shape, alias
+     * created)
+     */
     public ChildCollisionShape(Vector3f location, Matrix3f rotation, CollisionShape shape) {
         this.location = location;
         this.rotation = rotation;
         this.shape = shape;
     }
 
+    /**
+     * Serialize this shape, for example when saving to a J3O file.
+     *
+     * @param ex exporter (not null)
+     * @throws IOException from exporter
+     */
     public void write(JmeExporter ex) throws IOException {
         OutputCapsule capsule = ex.getCapsule(this);
         capsule.write(location, "location", new Vector3f());
         capsule.write(rotation, "rotation", new Matrix3f());
         capsule.write(shape, "shape", new BoxCollisionShape(new Vector3f(1, 1, 1)));
     }
 
+    /**
+     * De-serialize this shape, for example when loading from a J3O file.
+     *
+     * @param im importer (not null)
+     * @throws IOException from importer
+     */
     public void read(JmeImporter im) throws IOException {
         InputCapsule capsule = im.getCapsule(this);
         location = (Vector3f) capsule.readSavable("location", new Vector3f());