gistfile1.diff

Index: src/jbullet/com/jme3/bullet/joints/ConeJoint.java
===================================================================
--- src/jbullet/com/jme3/bullet/joints/ConeJoint.java	(revision 8953)
+++ src/jbullet/com/jme3/bullet/joints/ConeJoint.java	(working copy)
@@ -44,10 +44,19 @@
 import java.io.IOException;
 
 /**
- * <i>From bullet manual:</i><br>
- * To create ragdolls, the conve twist constraint is very useful for limbs like the upper arm.
- * It is a special point to point constraint that adds cone and twist axis limits.
- * The x-axis serves as twist axis.
+ * 
+ * The Cone Joint is a special point to point constraint that adds
+ * cone and twist axis limits. It can be used to simulate human-like
+ * joints in ragdolls, such the hips and upper arm.
+ * 
+ * The axis of symmetry of the cone relative to each of the shapes it
+ * connects defaults to the x-axis.
+ * 
+ * See the <a href="http://bulletphysics.com/Bullet/BulletFull/
+classbtConeTwistConstraint.html"> bullet api refence</a> or the <a href=
+  "http://bulletphysics.com/ftp/pub/test/physics/Bullet_User_Manual.pdf">
+ * bullet manual</a> for more information.
+ * 
  * @author normenhansen
  */
 public class ConeJoint extends PhysicsJoint {
@@ -75,6 +84,12 @@
     /**
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
+     * @param rotA rotate the axis of symmetry of the cone from its
+     *        default of Vector3f.UNIT_X relative to node A.  rotA
+     *        must be a rotation matrix.
+     * @param rotB rotate the axis of symmetry of the cone from its
+     *        default of Vector3f.UNIT_X relative to node B.  rotB
+     *        must be a rotation matrix.
      */
     public ConeJoint(PhysicsRigidBody nodeA, PhysicsRigidBody nodeB, Vector3f pivotA, Vector3f pivotB, Matrix3f rotA, Matrix3f rotB) {
         super(nodeA, nodeB, pivotA, pivotB);
@@ -82,7 +97,26 @@
         this.rotB = rotB;
         createJoint();
     }
-
+    
+    /**
+     * Specify the shape of the ConeJoint's cone, as well as the twist
+     * limits.
+     * 
+     * See the <a
+       href="http://bulletphysics.org/mediawiki-1.5.8/index.php/Constraints">
+       bullet wiki </a> for examples.
+     * @param swingSpan1 when the axis of symmetry of the cone is at
+     * its default of Vector3f.UNIT_X, swingSpan1 is the half angle of
+     * the apex of the isosceles triangle made by projecting the cone
+     * onto the XY plane. Value can range from 0 to (Math.PI / 2)
+     * @param swingSpan2 when the axis of symmetry of the cone is at
+     * its default of Vector3f.UNIT_X, swingSpan2 is the half angle of
+     * the apex of the isosceles triangle made by projecting the cone
+     * onto the XZ plane. Value can range from 0 to (Math.PI / 2)
+     * @param twistSpan Maximum angle in radians that the two
+     * connected bodies can twist along the axis of symmetry of the
+     * cone. \ Value can range from 0 to (Math.PI * 2)
+     */
     public void setLimit(float swingSpan1, float swingSpan2, float twistSpan) {
         this.swingSpan1 = swingSpan1;
         this.swingSpan2 = swingSpan2;
@@ -90,6 +124,14 @@
         ((ConeTwistConstraint) constraint).setLimit(swingSpan1, swingSpan2, twistSpan);
     }
 
+    /** 
+     * Sets weather the cone joint constraint should constrict the
+     * translational degrees of freedom as in the {@link Point2PointJoint} 
+     * or leave the translational degrees of freedom free and only
+     * affect rotational degrees of freedom.
+     * @param value if true, leave translational DOFs free; if false,
+     *        constrain them as in {@link Point2PointJoint}.
+     */
     public void setAngularOnly(boolean value) {
         angularOnly = value;
         ((ConeTwistConstraint) constraint).setAngularOnly(value);