a bit of documentation.

src/Physics/babylon.physicsEngine.ts

@@ -30,6 +30,7 @@
          * default is 1/60. 
          * To slow it down, enter 1/600 for example.
          * To speed it up, 1/30
+         * @param {number} newTimeStep the new timestep to apply to this world.
          */
         public setTimeStep(newTimeStep: number = 1 / 60) {
             this._physicsPlugin.setTimeStep(newTimeStep);
@@ -69,6 +70,11 @@
         private _impostors: Array<PhysicsImpostor> = [];
         private _joints: Array<PhysicsImpostorJoint> = [];
 
+        /**
+         * Adding a new impostor for the impostor tracking.
+         * This will be done by the impostor itself.
+         * @param {PhysicsImpostor} impostor the impostor to add
+         */
         public addImpostor(impostor: PhysicsImpostor) {
             this._impostors.push(impostor);
             //if no parent, generate the body
@@ -77,6 +83,11 @@
             }
         }
 
+        /**
+         * Remove an impostor from the engine.
+         * This impostor and its mesh will not longer be updated by the physics engine.
+         * @param {PhysicsImpostor} impostor the impostor to remove
+         */
         public removeImpostor(impostor: PhysicsImpostor) {
             var index = this._impostors.indexOf(impostor);
             if (index > -1) {
@@ -88,7 +99,13 @@
                 }
             }
         }
-
+        
+        /**
+         * Add a joint to the physics engine
+         * @param {PhysicsImpostor} mainImpostor the main impostor to which the joint is added.
+         * @param {PhysicsImpostor} connectedImpostor the impostor that is connected to the main impostor using this joint
+         * @param {PhysicsJoint} the joint that will connect both impostors.
+         */
         public addJoint(mainImpostor: PhysicsImpostor, connectedImpostor: PhysicsImpostor, joint: PhysicsJoint) {
             var impostorJoint = {
                 mainImpostor: mainImpostor,

src/Physics/babylon.physicsJoint.ts

@@ -11,6 +11,10 @@ module BABYLON {
         nativeParams?: any;
     }
 
+    /**
+     * This is a holder class for the physics joint created by the physics plugin.
+     * It holds a set of functions to control the underlying joint.
+     */
     export class PhysicsJoint {
 
         private _physicsJoint;
@@ -37,8 +41,13 @@ module BABYLON {
             this._physicsPlugin = physicsPlugin;
         }
         
-        public executeNativeFunction(func : (physicsJoint:any) => void) {
-            func(this._physicsJoint)
+        /**
+         * Execute a function that is physics-plugin specific.
+         * @param {Function} func the function that will be executed. 
+         *                        It accepts two parameters: the physics world and the physics joint.
+         */
+        public executeNativeFunction(func : (world: any, physicsJoint:any) => void) {
+            func(this._physicsPlugin.world, this._physicsJoint)
         }
 
 
@@ -63,41 +72,77 @@ module BABYLON {
         public static SpringJoint = 9;
     }
 
+    /**
+     * A class representing a physics distance joint.
+     */
     export class DistanceJoint extends PhysicsJoint {
         constructor(jointData: DistanceJointData) {
             super(PhysicsJoint.DistanceJoint, jointData);
         }
 
+        /**
+         * Update the predefined distance.
+         */
         public updateDistance(maxDistance: number, minDistance?: number) {
             this._physicsPlugin.updateDistanceJoint(this, maxDistance, minDistance);
         }
     }
 
+    /**
+     * This class represents a single hinge physics joint
+     */
     export class HingeJoint extends PhysicsJoint implements IMotorEnabledJoint {
         
         constructor(jointData:PhysicsJointData) {
             super(PhysicsJoint.HingeJoint, jointData);
         }
         
+        /**
+         * Set the motor values.
+         * Attention, this function is plugin specific. Engines won't react 100% the same.
+         * @param {number} force the force to apply
+         * @param {number} maxForce max force for this motor.
+         */
         public setMotor(force?: number, maxForce?: number) {
             this._physicsPlugin.setMotor(this, force, maxForce);
         }
         
+        /**
+         * Set the motor's limits.
+         * Attention, this function is plugin specific. Engines won't react 100% the same.
+         */
         public setLimit(upperLimit: number, lowerLimit?: number) {
             this._physicsPlugin.setLimit(this, upperLimit, lowerLimit);
         }
     }
     
+    /**
+     * This class represents a dual hinge physics joint (same as wheel joint)
+     */
     export class Hinge2Joint extends PhysicsJoint implements IMotorEnabledJoint {
         
         constructor(jointData:PhysicsJointData) {
             super(PhysicsJoint.Hinge2Joint, jointData);
         }
         
+        /**
+         * Set the motor values.
+         * Attention, this function is plugin specific. Engines won't react 100% the same.
+         * @param {number} force the force to apply
+         * @param {number} maxForce max force for this motor.
+         * @param {motorIndex} the motor's index, 0 or 1.
+         */
         public setMotor(force?: number, maxForce?: number, motorIndex: number = 0) {
             this._physicsPlugin.setMotor(this, force, maxForce, motorIndex);
         }
         
+        /**
+         * Set the motor limits.
+         * Attention, this function is plugin specific. Engines won't react 100% the same.
+         * @param {number} upperLimit the upper limit
+         * @param {number} lowerLimit lower limit
+         * @param {motorIndex} the motor's index, 0 or 1.
+         */
         public setLimit(upperLimit: number, lowerLimit?: number, motorIndex: number = 0) {
             this._physicsPlugin.setLimit(this, upperLimit, lowerLimit, motorIndex);
         }