added JSDOC to methods (see #49)

js/Quaternion.js

@@ -18,6 +18,17 @@ define( function( require ) {
   require( 'DOT/Matrix3' );
   require( 'DOT/Util' );
 
+  /**
+   * Quaternion defines hypercomplex numbers of the form {x, y, z, w}
+   * Quaternion are useful to represent rotation, the xyzw values of a Quaternion can be thought as rotation axis vector described by xyz and a rotation angle described by w.
+   * @public
+   *
+   * @param {number} x
+   * @param {number} y
+   * @param {number} z
+   * @param {number} w
+   * @constructor
+   */
   function Quaternion( x, y, z, w ) {
     this.setXYZW( x, y, z, w );
 
@@ -29,8 +40,18 @@ define( function( require ) {
   Quaternion.prototype = {
     constructor: Quaternion,
 
-    isQuaternion: true,
-
+    isQuaternion: true, // {boolean}
+
+    /**
+     * Sets the x,y,z,w values of the quaternion
+     *
+     * @public
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} w
+     */
     setXYZW: function( x, y, z, w ) {
       this.x = x !== undefined ? x : 0;
       this.y = y !== undefined ? y : 0;
@@ -42,15 +63,37 @@ define( function( require ) {
      * Immutables
      *----------------------------------------------------------------------------*/
 
+    /**
+     * Addition of this quaternion and another quaternion, returning a copy.
+     * @public
+     *
+     * @param {Quaternion} quat
+     * @returns {Quaternion}
+     */
     plus: function( quat ) {
       return new Quaternion( this.x + quat.x, this.y + quat.y, this.z + quat.z, this.w + quat.w );
     },
 
+    /**
+     * Multiplication of this quaternion by a scalar, returning a copy.
+     * @public
+     *
+     * @param {number} s
+     * @returns {Quaternion}
+     */
     timesScalar: function( s ) {
       return new Quaternion( this.x * s, this.y * s, this.z * s, this.w * s );
     },
 
-    // standard quaternion multiplication (hamilton product)
+    /**
+     * Multiplication of this quaternion by another quaternion, returning a copy.
+     * Multiplication is also known at the Hamilton Product (an extension of the cross product for vectors)
+     * The product of two rotation quaternions will be equivalent to a rotation by the first quaternion followed by the second quaternion rotation,
+     * @public
+     *
+     * @param {Quaternion} quat
+     * @returns {Quaternion}
+     */
     timesQuaternion: function( quat ) {
       // TODO: note why this is the case? product noted everywhere is the other one mentioned!
       // mathematica-style
@@ -81,6 +124,14 @@ define( function( require ) {
        */
     },
 
+    /**
+     * Multiply this quaternion by a vector v, returning a new vector3
+     * When a versor, a rotation quaternion, and a vector which lies in the plane of the versor are multiplied, the result is a new vector of the same length but turned by the angle of the versor.
+     * @public
+     *
+     * @param {Vector3} v
+     * @returns {Vector3}
+     */
     timesVector3: function( v ) {
       if ( v.magnitude() === 0 ) {
         return new dot.Vector3();
@@ -94,24 +145,55 @@ define( function( require ) {
       );
     },
 
+    /**
+     * The magnitude of this quaternion, i.e. $\sqrt{x^2+y^2+v^2+w^2}$,  returns a non negative number
+     * @public
+     *
+     * @returns {number}
+     */
     magnitude: function() {
       return Math.sqrt( this.magnitudeSquared() );
     },
 
+    /**
+     * The square of the magnitude of this quaternion, returns a non negative number
+     * @public
+     *
+     * @returns {number}
+     */
     magnitudeSquared: function() {
       return this.x * this.x + this.y * this.y + this.z * this.z + this.w * this.w;
     },
 
+    /**
+     * Normalizes this quaternion (rescales to where the magnitude is 1), returning a new quaternion
+     * @public
+     *
+     * @returns {Quaternion}
+     */
     normalized: function() {
       var magnitude = this.magnitude();
       assert && assert( magnitude !== 0, 'Cannot normalize a zero-magnitude quaternion' );
       return this.timesScalar( 1 / magnitude );
     },
 
+    /**
+     * Returns a new quaternion pointing in the opposite direction of this quaternion
+     * @public
+     *
+     * @returns {Quaternion}
+     */
     negated: function() {
       return new Quaternion( -this.x, -this.y, -this.z, -this.w );
     },
 
+    /**
+     * Convert a quaternion to a rotation matrix
+     * This quaternion does not need to be of magnitude 1
+     * @public
+     *
+     * @returns {Matrix3}
+     */
     toRotationMatrix: function() {
       // see http://en.wikipedia.org/wiki/Rotation_matrix#Quaternion
 
@@ -142,6 +224,14 @@ define( function( require ) {
     }
   };
 
+  /**
+   * Function returns a quaternion given euler angles
+   *
+   * @param {number} yaw - rotation about the z-axis
+   * @param {number} roll - rotation about the  x-axis
+   * @param {number} pitch - rotation about the y-axis
+   * @returns {Quaternion}
+   */
   Quaternion.fromEulerAngles = function( yaw, roll, pitch ) {
     var sinPitch = Math.sin( pitch * 0.5 );
     var cosPitch = Math.cos( pitch * 0.5 );
@@ -163,6 +253,14 @@ define( function( require ) {
     );
   };
 
+  /**
+   * Convert a rotation matrix to a quaternion,
+   * returning a new Quaternion (of magnitude one)
+   * @public
+   *
+   * @param  {Matrix3} matrix
+   * @returns {Quaternion}
+   */
   Quaternion.fromRotationMatrix = function( matrix ) {
     var v00 = matrix.m00();
     var v01 = matrix.m01();
@@ -220,16 +318,24 @@ define( function( require ) {
   /**
    * Find a quaternion that transforms a unit vector A into a unit vector B. There
    * are technically multiple solutions, so this only picks one.
+   * @public
    *
-   * @param a Unit vector A
-   * @param b Unit vector B
-   * @return A quaternion s.t. Q * A = B
+   * @param {Vector3} a - Unit vector A
+   * @param {Vector3} b - Unit vector B
+   * @return {Quaternion} A quaternion s.t. Q * A = B
    */
   Quaternion.getRotationQuaternion = function( a, b ) {
     return Quaternion.fromRotationMatrix( dot.Matrix3.rotateAToB( a, b ) );
   };
 
-  // spherical linear interpolation - blending two quaternions
+  /**
+   * spherical linear interpolation - blending two quaternions with a scalar parameter (ranging from 0 to 1).
+   * @public
+   * @param {Quaternion} a
+   * @param {Quaternion} b
+   * @param {number} t - amount of change , between 0 and 1 - 0 is at a, 1 is at b
+   * @returns {Quaternion}
+   */
   Quaternion.slerp = function( a, b, t ) {
     // if they are identical, just return one of them
     if ( a.x === b.x && a.y === b.y && a.z === b.z && a.w === b.w ) {