Merge branch 'master' of https://github.com/photonstorm/phaser

src/data/DataManagerPlugin.js

@@ -20,7 +20,7 @@ var PluginCache = require('../plugins/PluginCache');
  * @constructor
  * @since 3.0.0
  *
- * @param {Phaser.Scene} scene - [description]
+ * @param {Phaser.Scene} scene - A reference to the Scene that this DataManager belongs to.
  */
 var DataManagerPlugin = new Class({
 
@@ -33,7 +33,7 @@ var DataManagerPlugin = new Class({
         DataManager.call(this, scene, scene.sys.events);
 
         /**
-         * [description]
+         * A reference to the Scene that this DataManager belongs to.
          *
          * @name Phaser.Data.DataManagerPlugin#scene
          * @type {Phaser.Scene}
@@ -42,7 +42,7 @@ var DataManagerPlugin = new Class({
         this.scene = scene;
 
         /**
-         * [description]
+         * A reference to the Scene's Systems.
          *
          * @name Phaser.Data.DataManagerPlugin#systems
          * @type {Phaser.Scenes.Systems}

src/math/Average.js

@@ -5,14 +5,14 @@
  */
 
 /**
- * [description]
+ * Calculate the mean average of the given values.
  *
  * @function Phaser.Math.Average
  * @since 3.0.0
  *
- * @param {number[]} values - [description]
+ * @param {number[]} values - The values to average.
  *
- * @return {number} [description]
+ * @return {number} The average value.
  */
 var Average = function (values)
 {

src/math/Between.js

@@ -5,15 +5,15 @@
  */
 
 /**
- * [description]
+ * Compute a random integer between the `min` and `max` values, inclusive.
  *
  * @function Phaser.Math.Between
  * @since 3.0.0
  *
- * @param {integer} min - [description]
+ * @param {integer} min - The minimum value.
- * @param {integer} max - [description]
+ * @param {integer} max - The maximum value.
  *
- * @return {integer} [description]
+ * @return {integer} The random integer.
  */
 var Between = function (min, max)
 {

src/math/FromPercent.js

@@ -13,10 +13,10 @@ var Clamp = require('./Clamp');
  * @since 3.0.0
  *
  * @param {float} percent - A value between 0 and 1 representing the percentage.
- * @param {number} min - [description]
+ * @param {number} min - The minimum value.
- * @param {number} [max] - [description]
+ * @param {number} [max] - The maximum value.
  *
- * @return {number} [description]
+ * @return {number} The value that is `percent` percent between `min` and `max`.
  */
 var FromPercent = function (percent, min, max)
 {

src/math/GetSpeed.js

@@ -5,7 +5,7 @@
  */
 
 /**
- * [description]
+ * Calculate the speed required to cover a distance in the time given.
  *
  * @function Phaser.Math.GetSpeed
  * @since 3.0.0

src/math/IsEvenStrict.js

@@ -5,14 +5,14 @@
  */
 
 /**
- * [description]
+ * Check if a given value is an even number using a strict type check.
  *
  * @function Phaser.Math.IsEvenStrict
  * @since 3.0.0
  *
- * @param {number} value - [description]
+ * @param {number} value - The number to perform the check with.
  *
- * @return {boolean} [description]
+ * @return {boolean} Whether the number is even or not.
  */
 var IsEvenStrict = function (value)
 {

src/math/Linear.js

@@ -10,11 +10,11 @@
  * @function Phaser.Math.Linear
  * @since 3.0.0
  *
- * @param {number} p0 - The first point
+ * @param {number} p0 - The first point.
- * @param {number} p1 - The second point
+ * @param {number} p1 - The second point.
- * @param {float} t -The percentage between p0 and p1 to return represented as a number between 0 and 1.
+ * @param {float} t - The percentage between p0 and p1 to return, represented as a number between 0 and 1.
  *
- * @return {number} The step t% of the way between p0 and p1
+ * @return {number} The step t% of the way between p0 and p1.
  */
 var Linear = function (p0, p1, t)
 {

src/math/MaxAdd.js

@@ -5,16 +5,16 @@
  */
 
 /**
- * [description]
+ * Add an `amount` to a `value`, limiting the maximum result to `max`.
  *
  * @function Phaser.Math.MaxAdd
  * @since 3.0.0
  *
- * @param {number} value - [description]
+ * @param {number} value - The value to add to.
- * @param {number} amount - [description]
+ * @param {number} amount - The amount to add.
- * @param {number} max - [description]
+ * @param {number} max - The maximum value to return.
  *
- * @return {number} [description]
+ * @return {number} The resulting value.
  */
 var MaxAdd = function (value, amount, max)
 {

src/math/MinSub.js

@@ -5,16 +5,16 @@
  */
 
 /**
- * [description]
+ * Subtract an `amount` from `value`, limiting the minimum result to `min`.
  *
  * @function Phaser.Math.MinSub
  * @since 3.0.0
  *
- * @param {number} value - [description]
+ * @param {number} value - The value to subtract from.
- * @param {number} amount - [description]
+ * @param {number} amount - The amount to subtract.
- * @param {number} min - [description]
+ * @param {number} min - The minimum value to return.
  *
- * @return {number} [description]
+ * @return {number} The resulting value.
  */
 var MinSub = function (value, amount, min)
 {

src/math/Percent.js

@@ -13,10 +13,10 @@
  * @function Phaser.Math.Percent
  * @since 3.0.0
  *
- * @param {number} value - [description]
+ * @param {number} value - The value to determine the percentage of.
- * @param {number} min - [description]
+ * @param {number} min - The minimum value.
- * @param {number} [max] - [description]
+ * @param {number} [max] - The maximum value.
- * @param {number} [upperMax] - [description]
+ * @param {number} [upperMax] - The mid-way point in the range that represents 100%.
  *
  * @return {float} A value between 0 and 1 representing the percentage.
  */

src/math/RandomXY.js

@@ -5,15 +5,19 @@
  */
 
 /**
- * [description]
+ * Compute a random unit vector.
+ *
+ * Computes random values for the given vector between -1 and 1 that can be used to represent a direction.
+ *
+ * Optionally accepts a scale value to scale the resulting vector by.
  *
  * @function Phaser.Math.RandomXY
  * @since 3.0.0
  *
- * @param {Phaser.Math.Vector2} vector - [description]
+ * @param {Phaser.Math.Vector2} vector - The Vector to compute random values for.
- * @param {float} scale - [description]
+ * @param {float} [scale=1] - The scale of the random values.
  *
- * @return {Phaser.Math.Vector2} [description]
+ * @return {Phaser.Math.Vector2} The given Vector.
  */
 var RandomXY = function (vector, scale)
 {

src/math/RandomXYZ.js

@@ -4,17 +4,16 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
-//  Position Vector randomly in a spherical area defined by the given radius
 /**
- * [description]
+ * Compute a random position vector in a spherical area, optionally defined by the given radius.
  *
  * @function Phaser.Math.RandomXYZ
  * @since 3.0.0
  *
- * @param {Phaser.Math.Vector3} vec3 - [description]
+ * @param {Phaser.Math.Vector3} vec3 - The Vector to compute random values for.
- * @param {number} [radius=1] - [description]
+ * @param {number} [radius=1] - The radius.
  *
- * @return {Phaser.Math.Vector3} [description]
+ * @return {Phaser.Math.Vector3} The given Vector.
  */
 var RandomXYZ = function (vec3, radius)
 {
@@ -23,7 +22,7 @@ var RandomXYZ = function (vec3, radius)
     var r = Math.random() * 2 * Math.PI;
     var z = (Math.random() * 2) - 1;
     var zScale = Math.sqrt(1 - z * z) * radius;
-    
+
     vec3.x = Math.cos(r) * zScale;
     vec3.y = Math.sin(r) * zScale;
     vec3.z = z * radius;

src/math/RandomXYZW.js

@@ -5,21 +5,21 @@
  */
 
 /**
- * [description]
+ * Compute a random four-dimensional vector.
  *
  * @function Phaser.Math.RandomXYZW
  * @since 3.0.0
  *
- * @param {Phaser.Math.Vector4} vec4 - [description]
+ * @param {Phaser.Math.Vector4} vec4 - The Vector to compute random values for.
- * @param {float} [scale=1] - [description]
+ * @param {float} [scale=1] - The scale of the random values.
  *
- * @return {Phaser.Math.Vector4} [description]
+ * @return {Phaser.Math.Vector4} The given Vector.
  */
 var RandomXYZW = function (vec4, scale)
 {
     if (scale === undefined) { scale = 1; }
 
-    // Not spherical; should fix this for more uniform distribution
+    // TODO: Not spherical; should fix this for more uniform distribution
     vec4.x = (Math.random() * 2 - 1) * scale;
     vec4.y = (Math.random() * 2 - 1) * scale;
     vec4.z = (Math.random() * 2 - 1) * scale;

src/math/RotateAround.js

@@ -5,17 +5,17 @@
  */
 
 /**
- * [description]
+ * Rotate a `point` around `x` and `y` by the given `angle`.
  *
  * @function Phaser.Math.RotateAround
  * @since 3.0.0
  *
- * @param {(Phaser.Geom.Point|object)} point - [description]
+ * @param {(Phaser.Geom.Point|object)} point - The point to be rotated.
- * @param {number} x - [description]
+ * @param {number} x - The horizontal coordinate to rotate around.
- * @param {number} y - [description]
+ * @param {number} y - The vertical coordinate to rotate around.
- * @param {number} angle - [description]
+ * @param {number} angle - The angle of rotation in radians.
  *
- * @return {Phaser.Geom.Point} [description]
+ * @return {Phaser.Geom.Point} The given point, rotated by the given angle around the given coordinates.
  */
 var RotateAround = function (point, x, y, angle)
 {

src/math/RotateAroundDistance.js

@@ -10,13 +10,13 @@
  * @function Phaser.Math.RotateAroundDistance
  * @since 3.0.0
  *
- * @param {(Phaser.Geom.Point|object)} point - The Point to be rotated.
+ * @param {(Phaser.Geom.Point|object)} point - The point to be rotated.
  * @param {number} x - The horizontal coordinate to rotate around.
  * @param {number} y - The vertical coordinate to rotate around.
  * @param {number} angle - The angle of rotation in radians.
  * @param {number} distance - [description]
  *
- * @return {Phaser.Geom.Point} [description]
+ * @return {Phaser.Geom.Point} The given point.
  */
 var RotateAroundDistance = function (point, x, y, angle, distance)
 {

src/math/RotateVec3.js

@@ -15,17 +15,17 @@ var tmpVec3 = new Vector3();
 /**
  * Rotates a vector in place by axis angle.
  *
- * This is the same as transforming a point by an 
+ * This is the same as transforming a point by an
  * axis-angle quaternion, but it has higher precision.
  *
  * @function Phaser.Math.RotateVec3
  * @since 3.0.0
  *
- * @param {Phaser.Math.Vector3} vec - [description]
+ * @param {Phaser.Math.Vector3} vec - The vector to be rotated.
- * @param {Phaser.Math.Vector3} axis - [description]
+ * @param {Phaser.Math.Vector3} axis - The axis to rotate around.
- * @param {float} radians - [description]
+ * @param {float} radians - The angle of rotation in radians.
  *
- * @return {Phaser.Math.Vector3} [description]
+ * @return {Phaser.Math.Vector3} The given vector.
  */
 var RotateVec3 = function (vec, axis, radians)
 {

src/math/RoundTo.js

@@ -5,16 +5,16 @@
  */
 
 /**
- * [description]
+ * Round a value to a given decimal place.
  *
  * @function Phaser.Math.RoundTo
  * @since 3.0.0
  *
- * @param {number} value - [description]
+ * @param {number} value - The value to be rounded.
- * @param {integer} [place=0] - [description]
+ * @param {integer} [place=0] - The decimal place to round to.
  * @param {integer} [base=10] - [description]
  *
- * @return {number} [description]
+ * @return {number} The rounded value.
  */
 var RoundTo = function (value, place, base)
 {

src/math/SmoothStep.js

@@ -5,16 +5,18 @@
  */
 
 /**
- * [description]
+ * Smoothly interpolate between two values.
+ *
+ * Computes a smooth step interpolation between `min` and `max` by `x`.
  *
  * @function Phaser.Math.SmoothStep
  * @since 3.0.0
  *
- * @param {number} x - [description]
+ * @param {number} x - The percentage of interpolation, between 0 and 1.
- * @param {number} min - [description]
+ * @param {number} min - The minimum value.
- * @param {number} max - [description]
+ * @param {number} max - The maximum value.
  *
- * @return {number} [description]
+ * @return {number} The smoothly interpolated value.
  */
 var SmoothStep = function (x, min, max)
 {

src/math/SmootherStep.js

@@ -5,16 +5,20 @@
  */
 
 /**
- * [description]
+ * Smoothly interpolate between two values.
+ *
+ * Computes a smooth step interpolation between `min` and `max` by `x`.
+ *
+ * Produces an even smoother interpolation than {@link Phaser.Math.SmoothStep}.
  *
  * @function Phaser.Math.SmootherStep
  * @since 3.0.0
  *
- * @param {number} x - [description]
+ * @param {number} x - The percentage of interpolation, between 0 and 1.
- * @param {number} min - [description]
+ * @param {number} min - The minimum value.
- * @param {number} max - [description]
+ * @param {number} max - The maximum value.
  *
- * @return {number} [description]
+ * @return {number} The smoothly interpolated value.
  */
 var SmootherStep = function (x, min, max)
 {

src/math/TransformXY.js

@@ -20,7 +20,7 @@ var Vector2 = require('./Vector2');
  * @param {number} rotation - Rotation of the transform point, in radians.
  * @param {number} scaleX - Horizontal scale of the transform point.
  * @param {number} scaleY - Vertical scale of the transform point.
- * @param {(Phaser.Math.Vector2|Phaser.Geom.Point|object)} [output] - [description]
+ * @param {(Phaser.Math.Vector2|Phaser.Geom.Point|object)} [output] - The output vector, point or object for the translated coordinates.
  *
  * @return {(Phaser.Math.Vector2|Phaser.Geom.Point|object)} The translated point.
  */

src/math/Vector2.js

@@ -12,14 +12,16 @@ var Class = require('../utils/Class');
 /**
  * @typedef {object} Vector2Like
  *
- * @property {number} x - [description]
+ * @property {number} x - The x component.
- * @property {number} y - [description]
+ * @property {number} y - The y component.
  */
 
 /**
  * @classdesc
  * A representation of a vector in 2D space.
  *
+ * A two-component vector.
+ *
  * @class Vector2
  * @memberOf Phaser.Math
  * @constructor
@@ -82,7 +84,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * Copy the components of a given vector, into this Vector.
+     * Copy the components of a given Vector into this Vector.
      *
      * @method Phaser.Math.Vector2#copy
      * @since 3.0.0
@@ -118,7 +120,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * Set the x and y components of the this Vector to the given x and y values.
+     * Set the `x` and `y` components of the this Vector to the given `x` and `y` values.
      *
      * @method Phaser.Math.Vector2#set
      * @since 3.0.0
@@ -176,7 +178,9 @@ var Vector2 = new Class({
     },
 
     /**
-     * Check if this Vector is equal to a given Vector.
+     * Check whether this Vector is equal to a given Vector.
+     *
+     * Performs a strict equality check against each Vector's components.
      *
      * @method Phaser.Math.Vector2#equals
      * @since 3.0.0
@@ -213,7 +217,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * Add a given Vector to this Vector. Addition is element-wise.
+     * Add a given Vector to this Vector. Addition is component-wise.
      *
      * @method Phaser.Math.Vector2#add
      * @since 3.0.0
@@ -231,7 +235,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * Subtract the given Vector from this Vector. Subtraction is element-wise.
+     * Subtract the given Vector from this Vector. Subtraction is component-wise.
      *
      * @method Phaser.Math.Vector2#subtract
      * @since 3.0.0
@@ -249,7 +253,9 @@ var Vector2 = new Class({
     },
 
     /**
-     * Perform an element-wise multiplication between this Vector and the given Vector.
+     * Perform a component-wise multiplication between this Vector and the given Vector.
+     *
+     * Multiplies this Vector by the given Vector.
      *
      * @method Phaser.Math.Vector2#multiply
      * @since 3.0.0
@@ -293,7 +299,9 @@ var Vector2 = new Class({
     },
 
     /**
-     * Perform an element-wise division between this Vector and the given Vector. This Vector is divided by the given Vector.
+     * Perform a component-wise division between this Vector and the given Vector.
+     *
+     * Divides this Vector by the given Vector.
      *
      * @method Phaser.Math.Vector2#divide
      * @since 3.0.0
@@ -311,7 +319,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * Negate the x and y components of this Vector.
+     * Negate the `x` and `y` components of this Vector.
      *
      * @method Phaser.Math.Vector2#negate
      * @since 3.0.0
@@ -327,14 +335,14 @@ var Vector2 = new Class({
     },
 
     /**
-     * Calculate the distance between this Vector, and the given Vector.
+     * Calculate the distance between this Vector and the given Vector.
      *
      * @method Phaser.Math.Vector2#distance
      * @since 3.0.0
      *
      * @param {Phaser.Math.Vector2} src - The Vector to calculate the distance to.
      *
-     * @return {number} The distance to the given Vector from this Vector.
+     * @return {number} The distance from this Vector to the given Vector.
      */
     distance: function (src)
     {
@@ -345,14 +353,14 @@ var Vector2 = new Class({
     },
 
     /**
-     * The distance between this Vector, and the given Vector, squared.
+     * Calculate the distance between this Vector, and the given Vector, squared.
      *
      * @method Phaser.Math.Vector2#distanceSq
      * @since 3.0.0
      *
      * @param {Phaser.Math.Vector2} src - The Vector to calculate the distance to.
      *
-     * @return {number} The distance to this Vector and the given Vector, squared.
+     * @return {number} The distance from this Vector to the given Vector, squared.
      */
     distanceSq: function (src)
     {
@@ -363,7 +371,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * The length (or magnitude) of this Vector.
+     * Calculate the length (or magnitude) of this Vector.
      *
      * @method Phaser.Math.Vector2#length
      * @since 3.0.0
@@ -395,7 +403,9 @@ var Vector2 = new Class({
     },
 
     /**
-     * Normalise this Vector, that is, make it a unit length vector (magnitude of 1) in the same direction.
+     * Normalize this Vector.
+     *
+     * Makes the vector a unit length vector (magnitude of 1) in the same direction.
      *
      * @method Phaser.Math.Vector2#normalize
      * @since 3.0.0
@@ -411,6 +421,7 @@ var Vector2 = new Class({
         if (len > 0)
         {
             len = 1 / Math.sqrt(len);
+
             this.x = x * len;
             this.y = y * len;
         }
@@ -419,10 +430,7 @@ var Vector2 = new Class({
     },
 
     /**
-    * Right-hand normalize (make unit length) this Vector
+     * Right-hand normalize (make unit length) this Vector.
-    */
-    /**
-     * [description]
      *
      * @method Phaser.Math.Vector2#normalizeRightHand
      * @since 3.0.0
@@ -440,14 +448,14 @@ var Vector2 = new Class({
     },
 
     /**
-     * Perform a dot product between this Vector and the given Vector
+     * Calculate the dot product of this Vector and the given Vector.
      *
      * @method Phaser.Math.Vector2#dot
      * @since 3.0.0
      *
      * @param {Phaser.Math.Vector2} src - The Vector2 to dot product with this Vector2.
      *
-     * @return {number} The result of the dot product
+     * @return {number} The dot product of this Vector and the given Vector.
      */
     dot: function (src)
     {
@@ -470,13 +478,15 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Linearly interpolate between this Vector and the given Vector.
+     *
+     * Interpolates this Vector towards the given Vector.
      *
      * @method Phaser.Math.Vector2#lerp
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} src - [description]
+     * @param {Phaser.Math.Vector2} src - The Vector2 to interpolate towards.
-     * @param {number} [t=0] - [description]
+     * @param {number} [t=0] - The interpolation percentage, between 0 and 1.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -494,12 +504,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Transform this Vector with the given Matrix.
      *
      * @method Phaser.Math.Vector2#transformMat3
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Matrix3} mat - [description]
+     * @param {Phaser.Math.Matrix3} mat - The Matrix3 to transform this Vector2 with.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -516,12 +526,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Transform this Vector with the given Matrix.
      *
      * @method Phaser.Math.Vector2#transformMat4
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Matrix4} mat - [description]
+     * @param {Phaser.Math.Matrix4} mat - The Matrix4 to transform this Vector2 with.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */

src/math/Vector3.js

@@ -11,16 +11,18 @@ var Class = require('../utils/Class');
 
 /**
  * @classdesc
- * [description]
+ * A representation of a vector in 3D space.
+ *
+ * A three-component vector.
  *
  * @class Vector3
  * @memberOf Phaser.Math
  * @constructor
  * @since 3.0.0
  *
- * @param {number} [x] - [description]
+ * @param {number} [x] - The x component of this Vector.
- * @param {number} [y] - [description]
+ * @param {number} [y] - The y component of this Vector.
- * @param {number} [z] - [description]
+ * @param {number} [z] - The z component of this Vector.
  */
 var Vector3 = new Class({
 
@@ -36,6 +38,7 @@ var Vector3 = new Class({
          * @default 0
          * @since 3.0.0
          */
+        this.x = 0;
 
         /**
          * The y component of this Vector.
@@ -45,6 +48,7 @@ var Vector3 = new Class({
          * @default 0
          * @since 3.0.0
          */
+        this.y = 0;
 
         /**
          * The z component of this Vector.
@@ -54,6 +58,7 @@ var Vector3 = new Class({
          * @default 0
          * @since 3.0.0
          */
+        this.z = 0;
 
         if (typeof x === 'object')
         {
@@ -70,12 +75,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Set this Vector to point up.
+     *
+     * Sets the y component of the vector to 1, and the others to 0.
      *
      * @method Phaser.Math.Vector3#up
      * @since 3.0.0
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     up: function ()
     {
@@ -87,7 +94,7 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Make a clone of this Vector3.
      *
      * @method Phaser.Math.Vector3#clone
      * @since 3.0.0
@@ -108,7 +115,7 @@ var Vector3 = new Class({
      * @param {Phaser.Math.Vector3} a - [description]
      * @param {Phaser.Math.Vector3} b - [description]
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     crossVectors: function (a, b)
     {
@@ -127,7 +134,9 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Check whether this Vector is equal to a given Vector.
+     *
+     * Performs a strict equality check against each Vector's components.
      *
      * @method Phaser.Math.Vector3#equals
      * @since 3.0.0
@@ -142,14 +151,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Copy the components of a given Vector into this Vector.
      *
      * @method Phaser.Math.Vector3#copy
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} src - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} src - The Vector to copy the components from.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     copy: function (src)
     {
@@ -161,16 +170,16 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Set the `x`, `y`, and `z` components of this Vector to the given `x`, `y`, and `z` values.
      *
      * @method Phaser.Math.Vector3#set
      * @since 3.0.0
      *
-     * @param {(number|object)} x - [description]
+     * @param {(number|object)} x - The x value to set for this Vector, or an object containing x, y and z components.
-     * @param {number} [y] - [description]
+     * @param {number} [y] - The y value to set for this Vector.
-     * @param {number} [z] - [description]
+     * @param {number} [z] - The z value to set for this Vector.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     set: function (x, y, z)
     {
@@ -191,14 +200,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Add a given Vector to this Vector. Addition is component-wise.
      *
      * @method Phaser.Math.Vector3#add
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to add to this Vector.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     add: function (v)
     {
@@ -210,14 +219,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Subtract the given Vector from this Vector. Subtraction is component-wise.
      *
      * @method Phaser.Math.Vector3#subtract
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to subtract from this Vector.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     subtract: function (v)
     {
@@ -229,14 +238,16 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Perform a component-wise multiplication between this Vector and the given Vector.
+     *
+     * Multiplies this Vector by the given Vector.
      *
      * @method Phaser.Math.Vector3#multiply
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to multiply this Vector by.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     multiply: function (v)
     {
@@ -248,14 +259,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Scale this Vector by the given value.
      *
      * @method Phaser.Math.Vector3#scale
      * @since 3.0.0
      *
-     * @param {float} scale - [description]
+     * @param {number} scale - The value to scale this Vector by.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     scale: function (scale)
     {
@@ -276,14 +287,16 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Perform a component-wise division between this Vector and the given Vector.
+     *
+     * Divides this Vector by the given Vector.
      *
      * @method Phaser.Math.Vector3#divide
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to divide this Vector by.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     divide: function (v)
     {
@@ -295,12 +308,12 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Negate the `x`, `y` and `z` components of this Vector.
      *
      * @method Phaser.Math.Vector3#negate
      * @since 3.0.0
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     negate: function ()
     {
@@ -312,14 +325,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the distance between this Vector and the given Vector.
      *
      * @method Phaser.Math.Vector3#distance
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to calculate the distance to.
      *
-     * @return {number} [description]
+     * @return {number} The distance from this Vector to the given Vector.
      */
     distance: function (v)
     {
@@ -331,14 +344,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the distance between this Vector, and the given Vector, squared.
      *
      * @method Phaser.Math.Vector3#distanceSq
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to calculate the distance to.
      *
-     * @return {number} [description]
+     * @return {number} The distance from this Vector to the given Vector, squared.
      */
     distanceSq: function (v)
     {
@@ -350,12 +363,12 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the length (or magnitude) of this Vector.
      *
      * @method Phaser.Math.Vector3#length
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The length of this Vector.
      */
     length: function ()
     {
@@ -367,12 +380,12 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the length of this Vector squared.
      *
      * @method Phaser.Math.Vector3#lengthSq
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The length of this Vector, squared.
      */
     lengthSq: function ()
     {
@@ -384,14 +397,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Normalize this Vector.
+     *
+     * Makes the vector a unit length vector (magnitude of 1) in the same direction.
      *
      * @method Phaser.Math.Vector3#normalize
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - [description]
+     * @return {Phaser.Math.Vector3} This Vector3.
-     *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
      */
     normalize: function ()
     {
@@ -413,12 +426,12 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the dot product of this Vector and the given Vector.
      *
      * @method Phaser.Math.Vector3#dot
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector3} v - [description]
+     * @param {Phaser.Math.Vector3} v - The Vector3 to dot product with this Vector3.
      *
      * @return {number} [description]
      */
@@ -435,7 +448,7 @@ var Vector3 = new Class({
      *
      * @param {Phaser.Math.Vector3} v - [description]
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     cross: function (v)
     {
@@ -454,15 +467,17 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Linearly interpolate between this Vector and the given Vector.
+     *
+     * Interpolates this Vector towards the given Vector.
      *
      * @method Phaser.Math.Vector3#lerp
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector3} v - [description]
+     * @param {Phaser.Math.Vector3} v - The Vector3 to interpolate towards.
-     * @param {number} [t=0] - [description]
+     * @param {number} [t=0] - The interpolation percentage, between 0 and 1.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     lerp: function (v, t)
     {
@@ -480,14 +495,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Transform this Vector with the given Matrix.
      *
      * @method Phaser.Math.Vector3#transformMat3
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Matrix3} mat - [description]
+     * @param {Phaser.Math.Matrix3} mat - The Matrix3 to transform this Vector3 with.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     transformMat3: function (mat)
     {
@@ -504,14 +519,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Transform this Vector with the given Matrix.
      *
      * @method Phaser.Math.Vector3#transformMat4
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Matrix4} mat - [description]
+     * @param {Phaser.Math.Matrix4} mat - The Matrix4 to transform this Vector3 with.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     transformMat4: function (mat)
     {
@@ -533,9 +548,9 @@ var Vector3 = new Class({
      * @method Phaser.Math.Vector3#transformCoordinates
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Matrix4} mat - [description]
+     * @param {Phaser.Math.Matrix4} mat - The Matrix4 to transform this Vector3 with.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     transformCoordinates: function (mat)
     {
@@ -557,14 +572,14 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Transform this Vector with the given Quaternion.
      *
      * @method Phaser.Math.Vector3#transformQuat
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Quaternion} q - [description]
+     * @param {Phaser.Math.Quaternion} q - The Quaternion to transform this Vector with.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     transformQuat: function (q)
     {
@@ -598,9 +613,9 @@ var Vector3 = new Class({
      * @method Phaser.Math.Vector3#project
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Matrix4} mat - [description]
+     * @param {Phaser.Math.Matrix4} mat - The Matrix4 to multiply this Vector3 with.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     project: function (mat)
     {
@@ -651,7 +666,7 @@ var Vector3 = new Class({
      * @param {Phaser.Math.Vector4} viewport - Screen x, y, width and height in pixels.
      * @param {Phaser.Math.Matrix4} invProjectionView - Combined projection and view matrix.
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     unproject: function (viewport, invProjectionView)
     {
@@ -672,12 +687,12 @@ var Vector3 = new Class({
     },
 
     /**
-     * [description]
+     * Make this Vector the zero vector (0, 0, 0).
      *
      * @method Phaser.Math.Vector3#reset
      * @since 3.0.0
      *
-     * @return {Phaser.Math.Vector3} This Vector3 object.
+     * @return {Phaser.Math.Vector3} This Vector3.
      */
     reset: function ()
     {

src/math/Vector4.js

@@ -11,17 +11,19 @@ var Class = require('../utils/Class');
 
 /**
  * @classdesc
- * [description]
+ * A representation of a vector in 4D space.
+ *
+ * A four-component vector.
  *
  * @class Vector4
  * @memberOf Phaser.Math
  * @constructor
  * @since 3.0.0
  *
- * @param {number} [x] - [description]
+ * @param {number} [x] - The x component of this Vector.
- * @param {number} [y] - [description]
+ * @param {number} [y] - The y component of this Vector.
- * @param {number} [z] - [description]
+ * @param {number} [z] - The z component of this Vector.
- * @param {number} [w] - [description]
+ * @param {number} [w] - The w component of this Vector.
  */
 var Vector4 = new Class({
 
@@ -37,6 +39,7 @@ var Vector4 = new Class({
          * @default 0
          * @since 3.0.0
          */
+        this.x = 0;
 
         /**
          * The y component of this Vector.
@@ -46,6 +49,7 @@ var Vector4 = new Class({
          * @default 0
          * @since 3.0.0
          */
+        this.y = 0;
 
         /**
          * The z component of this Vector.
@@ -55,6 +59,7 @@ var Vector4 = new Class({
          * @default 0
          * @since 3.0.0
          */
+        this.z = 0;
 
         /**
          * The w component of this Vector.
@@ -64,6 +69,7 @@ var Vector4 = new Class({
          * @default 0
          * @since 3.0.0
          */
+        this.w = 0;
 
         if (typeof x === 'object')
         {
@@ -82,12 +88,12 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Make a clone of this Vector4.
      *
      * @method Phaser.Math.Vector4#clone
      * @since 3.0.0
      *
-     * @return {Phaser.Math.Vector4} [description]
+     * @return {Phaser.Math.Vector4} A clone of this Vector4.
      */
     clone: function ()
     {
@@ -95,14 +101,14 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Copy the components of a given Vector into this Vector.
      *
      * @method Phaser.Math.Vector4#copy
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector4} src - [description]
+     * @param {Phaser.Math.Vector4} src - The Vector to copy the components from.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     copy: function (src)
     {
@@ -115,7 +121,9 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Check whether this Vector is equal to a given Vector.
+     *
+     * Performs a strict quality check against each Vector's components.
      *
      * @method Phaser.Math.Vector4#equals
      * @since 3.0.0
@@ -130,17 +138,17 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Set the `x`, `y`, `z` and `w` components of the this Vector to the given `x`, `y`, `z` and `w` values.
      *
      * @method Phaser.Math.Vector4#set
      * @since 3.0.0
      *
-     * @param {number} x - [description]
+     * @param {(number|object)} x - The x value to set for this Vector, or an object containing x, y, z and w components.
-     * @param {number} y - [description]
+     * @param {number} y - The y value to set for this Vector.
-     * @param {number} z - [description]
+     * @param {number} z - The z value to set for this Vector.
-     * @param {number} w - [description]
+     * @param {number} w - The z value to set for this Vector.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     set: function (x, y, z, w)
     {
@@ -163,14 +171,14 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Add a given Vector to this Vector. Addition is component-wise.
      *
      * @method Phaser.Math.Vector4#add
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to add to this Vector.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     add: function (v)
     {
@@ -183,14 +191,14 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Subtract the given Vector from this Vector. Subtraction is component-wise.
      *
      * @method Phaser.Math.Vector4#subtract
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to subtract from this Vector.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     subtract: function (v)
     {
@@ -203,14 +211,14 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Scale this Vector by the given value.
      *
      * @method Phaser.Math.Vector4#scale
      * @since 3.0.0
      *
-     * @param {number} scale - [description]
+     * @param {number} scale - The value to scale this Vector by.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     scale: function (scale)
     {
@@ -223,12 +231,12 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the length (or magnitude) of this Vector.
      *
      * @method Phaser.Math.Vector4#length
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The length of this Vector.
      */
     length: function ()
     {
@@ -241,12 +249,12 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the length of this Vector squared.
      *
      * @method Phaser.Math.Vector4#lengthSq
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The length of this Vector, squared.
      */
     lengthSq: function ()
     {
@@ -259,12 +267,14 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Normalize this Vector.
+     *
+     * Makes the vector a unit length vector (magnitude of 1) in the same direction.
      *
      * @method Phaser.Math.Vector4#normalize
      * @since 3.0.0
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     normalize: function ()
     {
@@ -288,14 +298,14 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the dot product of this Vector and the given Vector.
      *
      * @method Phaser.Math.Vector4#dot
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector4} v - [description]
+     * @param {Phaser.Math.Vector4} v - The Vector4 to dot product with this Vector4.
      *
-     * @return {number} [description]
+     * @return {number} The dot product of this Vector and the given Vector.
      */
     dot: function (v)
     {
@@ -303,15 +313,17 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Linearly interpolate between this Vector and the given Vector.
+     *
+     * Interpolates this Vector towards the given Vector.
      *
      * @method Phaser.Math.Vector4#lerp
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector4} v - [description]
+     * @param {Phaser.Math.Vector4} v - The Vector4 to interpolate towards.
-     * @param {number} [t=0] - [description]
+     * @param {number} [t=0] - The interpolation percentage, between 0 and 1.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     lerp: function (v, t)
     {
@@ -331,14 +343,16 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Perform a component-wise multiplication between this Vector and the given Vector.
+     *
+     * Multiplies this Vector by the given Vector.
      *
      * @method Phaser.Math.Vector4#multiply
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to multiply this Vector by.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     multiply: function (v)
     {
@@ -351,14 +365,16 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Perform a component-wise division between this Vector and the given Vector.
+     *
+     * Divides this Vector by the given Vector.
      *
      * @method Phaser.Math.Vector4#divide
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to divide this Vector by.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     divide: function (v)
     {
@@ -371,14 +387,14 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the distance between this Vector and the given Vector.
      *
      * @method Phaser.Math.Vector4#distance
      * @since 3.0.0
      *
      * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description]
      *
-     * @return {number} [description]
+     * @return {number} The distance from this Vector to the given Vector.
      */
     distance: function (v)
     {
@@ -391,14 +407,14 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the distance between this Vector, and the given Vector, squared.
      *
      * @method Phaser.Math.Vector4#distanceSq
      * @since 3.0.0
      *
-     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description]
+     * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to calculate the distance to.
      *
-     * @return {number} [description]
+     * @return {number} The distance from this Vector to the given Vector, squared.
      */
     distanceSq: function (v)
     {
@@ -411,12 +427,12 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Negate the `x`, `y`, `z` and `w` components of this Vector.
      *
      * @method Phaser.Math.Vector4#negate
      * @since 3.0.0
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     negate: function ()
     {
@@ -429,14 +445,14 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Transform this Vector with the given Matrix.
      *
      * @method Phaser.Math.Vector4#transformMat4
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Matrix4} mat - [description]
+     * @param {Phaser.Math.Matrix4} mat - The Matrix4 to transform this Vector4 with.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     transformMat4: function (mat)
     {
@@ -454,21 +470,20 @@ var Vector4 = new Class({
         return this;
     },
 
-    //  TODO: is this really the same as Vector3?
-    //  Also, what about this: http://molecularmusings.wordpress.com/2013/05/24/a-faster-quaternion-vector-multiplication/
-
     /**
-     * [description]
+     * Transform this Vector with the given Quaternion.
      *
      * @method Phaser.Math.Vector4#transformQuat
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Quaternion} q - [description]
+     * @param {Phaser.Math.Quaternion} q - The Quaternion to transform this Vector with.
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     transformQuat: function (q)
     {
+        // TODO: is this really the same as Vector3?
+        // Also, what about this: http://molecularmusings.wordpress.com/2013/05/24/a-faster-quaternion-vector-multiplication/
         // benchmarks: http://jsperf.com/quaternion-transform-vec3-implementations
         var x = this.x;
         var y = this.y;
@@ -493,12 +508,12 @@ var Vector4 = new Class({
     },
 
     /**
-     * [description]
+     * Make this Vector the zero vector (0, 0, 0, 0).
      *
      * @method Phaser.Math.Vector4#reset
      * @since 3.0.0
      *
-     * @return {Phaser.Math.Vector4} This Vector4 object.
+     * @return {Phaser.Math.Vector4} This Vector4.
      */
     reset: function ()
     {

src/math/Wrap.js

@@ -5,16 +5,16 @@
  */
 
 /**
- * [description]
+ * Wrap the given `value` between `min` and `max.
  *
  * @function Phaser.Math.Wrap
  * @since 3.0.0
  *
- * @param {number} value - [description]
+ * @param {number} value - The value to wrap.
- * @param {number} min - [description]
+ * @param {number} min - The minimum value.
- * @param {number} max - [description]
+ * @param {number} max - The maximum value.
  *
- * @return {number} [description]
+ * @return {number} The wrapped value.
  */
 var Wrap = function (value, min, max)
 {

src/math/angle/Between.js

@@ -5,17 +5,19 @@
  */
 
 /**
- * [description]
+ * Calculate the angle between two sets of coordinates (points).
+ *
+ * Calculates the angle of the vector from the first point to the second point.
  *
  * @function Phaser.Math.Angle.Between
  * @since 3.0.0
  *
- * @param {number} x1 - [description]
+ * @param {number} x1 - The x coordinate of the first point.
- * @param {number} y1 - [description]
+ * @param {number} y1 - The y coordinate of the first point.
- * @param {number} x2 - [description]
+ * @param {number} x2 - The x coordinate of the second point.
- * @param {number} y2 - [description]
+ * @param {number} y2 - The y coordinate of the second point.
  *
- * @return {number} [description]
+ * @return {number} The angle in radians.
  */
 var Between = function (x1, y1, x2, y2)
 {

src/math/angle/BetweenPoints.js

@@ -5,15 +5,17 @@
  */
 
 /**
- * [description]
+ * Calculate the angle between two points.
+ *
+ * Calculates the angle of the vector from the first point to the second point.
  *
  * @function Phaser.Math.Angle.BetweenPoints
  * @since 3.0.0
  *
- * @param {(Phaser.Geom.Point|object)} point1 - [description]
+ * @param {(Phaser.Geom.Point|object)} point1 - The first point.
- * @param {(Phaser.Geom.Point|object)} point2 - [description]
+ * @param {(Phaser.Geom.Point|object)} point2 - The second point.
  *
- * @return {number} [description]
+ * @return {number} The angle in radians.
  */
 var BetweenPoints = function (point1, point2)
 {

src/math/angle/BetweenPointsY.js

@@ -10,10 +10,10 @@
  * @function Phaser.Math.Angle.BetweenPointsY
  * @since 3.0.0
  *
- * @param {(Phaser.Geom.Point|object)} point1 - [description]
+ * @param {(Phaser.Geom.Point|object)} point1 - The first point.
- * @param {(Phaser.Geom.Point|object)} point2 - [description]
+ * @param {(Phaser.Geom.Point|object)} point2 - The second point.
  *
- * @return {number} [description]
+ * @return {number} The angle in radians.
  */
 var BetweenPointsY = function (point1, point2)
 {

src/math/angle/BetweenY.js

@@ -10,12 +10,12 @@
  * @function Phaser.Math.Angle.BetweenY
  * @since 3.0.0
  *
- * @param {number} x1 - [description]
+ * @param {number} x1 - The x coordinate of the first point.
- * @param {number} y1 - [description]
+ * @param {number} y1 - The y coordinate of the first point.
- * @param {number} x2 - [description]
+ * @param {number} x2 - The x coordinate of the second point.
- * @param {number} y2 - [description]
+ * @param {number} y2 - The y coordinate of the second point.
  *
- * @return {number} [description]
+ * @return {number} The angle in radians.
  */
 var BetweenY = function (x1, y1, x2, y2)
 {

src/math/angle/Normalize.js

@@ -5,14 +5,16 @@
  */
 
 /**
- * [description]
+ * Normalize the given angle.
+ *
+ * [description] TODO: Needs elaborating
  *
  * @function Phaser.Math.Angle.Normalize
  * @since 3.0.0
  *
- * @param {number} angle - [description]
+ * @param {number} angle - The angle to normalize, in radians.
  *
- * @return {number} [description]
+ * @return {number} The normalized angle, in radians.
  */
 var Normalize = function (angle)
 {

src/math/angle/Reverse.js

@@ -7,14 +7,14 @@
 var Normalize = require('./Normalize');
 
 /**
- * [description]
+ * Reverse the given angle.
  *
  * @function Phaser.Math.Angle.Reverse
  * @since 3.0.0
  *
- * @param {number} angle - [description]
+ * @param {number} angle - The angle to reverse, in radians.
  *
- * @return {number} [description]
+ * @return {number} The reversed angle, in radians.
  */
 var Reverse = function (angle)
 {

src/math/angle/ShortestBetween.js

@@ -6,6 +6,7 @@
 
 /**
  * Gets the shortest angle between `angle1` and `angle2`.
+ *
  * Both angles must be in the range -180 to 180, which is the same clamped
  * range that `sprite.angle` uses, so you can pass in two sprite angles to
  * this method and get the shortest angle back between the two of them.
@@ -14,6 +15,8 @@
  * greater than 0 then it's a counter-clockwise rotation, if < 0 then it's
  * a clockwise rotation.
  *
+ * TODO: Wrap the angles in this function?
+ *
  * @function Phaser.Math.Angle.ShortestBetween
  * @since 3.0.0
  *

src/math/angle/Wrap.js

@@ -7,14 +7,16 @@
 var MathWrap = require('../Wrap');
 
 /**
- * [description]
+ * Wrap an angle.
+ *
+ * Wraps the angle to a value in the range of -PI to PI.
  *
  * @function Phaser.Math.Angle.Wrap
  * @since 3.0.0
  *
- * @param {number} angle - [description]
+ * @param {number} angle - The angle to wrap, in radians.
  *
- * @return {number} [description]
+ * @return {number} The wrapped angle, in radians.
  */
 var Wrap = function (angle)
 {

src/math/angle/WrapDegrees.js

@@ -7,14 +7,16 @@
 var Wrap = require('../Wrap');
 
 /**
- * [description]
+ * Wrap an angle in degrees.
+ *
+ * Wraps the angle to a value in the range of -180 to 180.
  *
  * @function Phaser.Math.Angle.WrapDegrees
  * @since 3.0.0
  *
- * @param {number} angle - [description]
+ * @param {number} angle - The angle to wrap, in degrees.
  *
- * @return {number} [description]
+ * @return {number} The wrapped angle, in degrees.
  */
 var WrapDegrees = function (angle)
 {

src/math/interpolation/LinearInterpolation.js

@@ -14,7 +14,7 @@ var Linear = require('../Linear');
  * @see https://en.wikipedia.org/wiki/Linear_interpolation
  *
  * @param {number[]} v - The input array of values to interpolate between.
- * @param {!number} k - The percentage of interploation, between 0 and 1.
+ * @param {!number} k - The percentage of interpolation, between 0 and 1.
  *
  * @return {!number} The interpolated value.
  */

src/plugins/BasePlugin.js

@@ -6,23 +6,17 @@
 
 var Class = require('../utils/Class');
 
-//  A Scene Level Plugin is installed into every Scene and belongs to that Scene.
-//  It can listen for Scene events and respond to them.
-//  It can map itself to a Scene property, or into the Scene Systems, or both.
-//  
-//  A Global Plugin is installed just once into the Game owned Plugin Manager.
-//  It can listen for Game events and respond to them.
-
 /**
  * @classdesc
- * [description]
+ * A Global Plugin is installed just once into the Game owned Plugin Manager.
+ * It can listen for Game events and respond to them.
  *
  * @class BasePlugin
  * @memberOf Phaser.Plugins
  * @constructor
  * @since 3.8.0
  *
- * @param {Phaser.Game} game - [description]
+ * @param {Phaser.Game} game - A reference to the Game instance this plugin is running under.
  */
 var BasePlugin = new Class({
 
@@ -33,7 +27,7 @@ var BasePlugin = new Class({
         /**
          * A handy reference to the Plugin Manager that is responsible for this plugin.
          * Can be used as a route to gain access to game systems and  events.
-         * 
+         *
          * @name Phaser.Plugins.BasePlugin#pluginManager
          * @type {Phaser.Plugins.PluginManager}
          * @protected

src/plugins/ScenePlugin.js

@@ -19,7 +19,7 @@ var Class = require('../utils/Class');
  * @constructor
  * @since 3.8.0
  *
- * @param {Phaser.Game} game - [description]
+ * @param {Phaser.Game} game - A reference to the Scene that has installed this plugin.
  */
 var ScenePlugin = new Class({
 

src/sound/BaseSoundManager.js

@@ -13,10 +13,10 @@ var NOOP = require('../utils/NOOP');
 /**
  * @callback EachActiveSoundCallback
  *
- * @param {Phaser.Sound.BaseSoundManager} manager - [description]
+ * @param {Phaser.Sound.BaseSoundManager} manager - The SoundManager
- * @param {Phaser.Sound.BaseSound} sound - [description]
+ * @param {Phaser.Sound.BaseSound} sound - The current active Sound
- * @param {number} index - [description]
+ * @param {number} index - The index of the current active Sound
- * @param {Phaser.Sound.BaseSound[]} sounds - [description]
+ * @param {Phaser.Sound.BaseSound[]} sounds - All sounds
  */
 
 /**
@@ -527,7 +527,7 @@ var BaseSoundManager = new Class({
      * @private
      * @since 3.0.0
      *
-     * @param {EachActiveSoundCallback} callback - Callback function. (sound: ISound, index: number, array: ISound[]) => void
+     * @param {EachActiveSoundCallback} callback - Callback function. (manager: Phaser.Sound.BaseSoundManager, sound: Phaser.Sound.BaseSound, index: number, sounds: Phaser.Manager.BaseSound[]) => void
      * @param {*} [scope] - Callback context.
      */
     forEachActiveSound: function (callback, scope)