Started documenting top-level Phaser.Math functions and classes.

hexus · hexus · commit dca9f11f0fc4 · 2018-05-23T10:46:16.000+01:00
diff --git a/src/math/Average.js b/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)
 {
diff --git a/src/math/Between.js b/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} max - [description]
+ * @param {integer} min - The minimum value.
+ * @param {integer} max - The maximum value.
  *
- * @return {integer} [description]
+ * @return {integer} The random integer.
  */
 var Between = function (min, max)
 {
diff --git a/src/math/FromPercent.js b/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} [max] - [description]
+ * @param {number} min - The minimum value.
+ * @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)
 {
diff --git a/src/math/GetSpeed.js b/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
diff --git a/src/math/IsEvenStrict.js b/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)
 {
diff --git a/src/math/Linear.js b/src/math/Linear.js
@@ -10,11 +10,11 @@
  * @function Phaser.Math.Linear
  * @since 3.0.0
  *
- * @param {number} p0 - The first 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 {number} p0 - The first 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.
  *
- * @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)
 {
diff --git a/src/math/MaxAdd.js b/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} amount - [description]
- * @param {number} max - [description]
+ * @param {number} value - The value to add to.
+ * @param {number} amount - The amount to add.
+ * @param {number} max - The maximum value to return.
  *
- * @return {number} [description]
+ * @return {number} The resulting value.
  */
 var MaxAdd = function (value, amount, max)
 {
diff --git a/src/math/MinSub.js b/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} amount - [description]
- * @param {number} min - [description]
+ * @param {number} value - The value to subtract from.
+ * @param {number} amount - The amount to subtract.
+ * @param {number} min - The minimum value to return.
  *
- * @return {number} [description]
+ * @return {number} The resulting value.
  */
 var MinSub = function (value, amount, min)
 {
diff --git a/src/math/Percent.js b/src/math/Percent.js
@@ -13,10 +13,10 @@
  * @function Phaser.Math.Percent
  * @since 3.0.0
  *
- * @param {number} value - [description]
- * @param {number} min - [description]
- * @param {number} [max] - [description]
- * @param {number} [upperMax] - [description]
+ * @param {number} value - The value to determine the percentage of.
+ * @param {number} min - The minimum value.
+ * @param {number} [max] - The maximum value.
+ * @param {number} [upperMax] - The mid-way point in the range that represents 100%.
  *
  * @return {float} A value between 0 and 1 representing the percentage.
  */
diff --git a/src/math/RandomXY.js b/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 {float} scale - [description]
+ * @param {Phaser.Math.Vector2} vector - The Vector to compute random values for.
+ * @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)
 {
diff --git a/src/math/RandomXYZ.js b/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 {number} [radius=1] - [description]
+ * @param {Phaser.Math.Vector3} vec3 - The Vector to compute random values for.
+ * @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;
diff --git a/src/math/RandomXYZW.js b/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 {float} [scale=1] - [description]
+ * @param {Phaser.Math.Vector4} vec4 - The Vector to compute random values for.
+ * @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;
diff --git a/src/math/RotateAround.js b/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 {number} x - [description]
- * @param {number} y - [description]
- * @param {number} angle - [description]
+ * @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.
  *
- * @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)
 {
diff --git a/src/math/RotateAroundDistance.js b/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)
 {
diff --git a/src/math/RotateVec3.js b/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} axis - [description]
- * @param {float} radians - [description]
+ * @param {Phaser.Math.Vector3} vec - The vector to be rotated.
+ * @param {Phaser.Math.Vector3} axis - The axis to rotate around.
+ * @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)
 {
diff --git a/src/math/RoundTo.js b/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 {integer} [place=0] - [description]
+ * @param {number} value - The value to be rounded.
+ * @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)
 {
diff --git a/src/math/SmoothStep.js b/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} min - [description]
- * @param {number} max - [description]
+ * @param {number} x - The percentage of interpolation, between 0 and 1.
+ * @param {number} min - The minimum value.
+ * @param {number} max - The maximum value.
  *
- * @return {number} [description]
+ * @return {number} The smoothly interpolated value.
  */
 var SmoothStep = function (x, min, max)
 {
diff --git a/src/math/SmootherStep.js b/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} min - [description]
- * @param {number} max - [description]
+ * @param {number} x - The percentage of interpolation, between 0 and 1.
+ * @param {number} min - The minimum value.
+ * @param {number} max - The maximum value.
  *
- * @return {number} [description]
+ * @return {number} The smoothly interpolated value.
  */
 var SmootherStep = function (x, min, max)
 {
diff --git a/src/math/TransformXY.js b/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.
  */
diff --git a/src/math/Vector2.js b/src/math/Vector2.js
diff --git a/src/math/interpolation/LinearInterpolation.js b/src/math/interpolation/LinearInterpolation.js

Original file line number	Diff line number	Diff line change
`@@ -5,14 +5,14 @@`
`5`	`5`	`*/`
`6`	`6`
`7`	`7`	`/**`
`8`		`- * [description]`
	`8`	`+ * Calculate the mean average of the given values.`
`9`	`9`	`*`
`10`	`10`	`* @function Phaser.Math.Average`
`11`	`11`	`* @since 3.0.0`
`12`	`12`	`*`
`13`		`- * @param {number[]} values - [description]`
	`13`	`+ * @param {number[]} values - The values to average.`
`14`	`14`	`*`
`15`		`- * @return {number} [description]`
	`15`	`+ * @return {number} The average value.`
`16`	`16`	`*/`
`17`	`17`	`var Average = function (values)`
`18`	`18`	`{`
Original file line number	Diff line number	Diff line change
`@@ -5,15 +5,15 @@`
`5`	`5`	`*/`
`6`	`6`
`7`	`7`	`/**`
`8`		`- * [description]`
	`8`	+ * Compute a random integer between the `min` and `max` values, inclusive.
`9`	`9`	`*`
`10`	`10`	`* @function Phaser.Math.Between`
`11`	`11`	`* @since 3.0.0`
`12`	`12`	`*`
`13`		`- * @param {integer} min - [description]`
`14`		`- * @param {integer} max - [description]`
	`13`	`+ * @param {integer} min - The minimum value.`
	`14`	`+ * @param {integer} max - The maximum value.`
`15`	`15`	`*`
`16`		`- * @return {integer} [description]`
	`16`	`+ * @return {integer} The random integer.`
`17`	`17`	`*/`
`18`	`18`	`var Between = function (min, max)`
`19`	`19`	`{`
Original file line number	Diff line number	Diff line change
`@@ -13,10 +13,10 @@ var Clamp = require('./Clamp');`
`13`	`13`	`* @since 3.0.0`
`14`	`14`	`*`
`15`	`15`	`* @param {float} percent - A value between 0 and 1 representing the percentage.`
`16`		`- * @param {number} min - [description]`
`17`		`- * @param {number} [max] - [description]`
	`16`	`+ * @param {number} min - The minimum value.`
	`17`	`+ * @param {number} [max] - The maximum value.`
`18`	`18`	`*`
`19`		`- * @return {number} [description]`
	`19`	+ * @return {number} The value that is `percent` percent between `min` and `max`.
`20`	`20`	`*/`
`21`	`21`	`var FromPercent = function (percent, min, max)`
`22`	`22`	`{`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@`
`5`	`5`	`*/`
`6`	`6`
`7`	`7`	`/**`
`8`		`- * [description]`
	`8`	`+ * Calculate the speed required to cover a distance in the time given.`
`9`	`9`	`*`
`10`	`10`	`* @function Phaser.Math.GetSpeed`
`11`	`11`	`* @since 3.0.0`
Original file line number	Diff line number	Diff line change
`@@ -10,11 +10,11 @@`
`10`	`10`	`* @function Phaser.Math.Linear`
`11`	`11`	`* @since 3.0.0`
`12`	`12`	`*`
`13`		`- * @param {number} p0 - The first point`
`14`		`- * @param {number} p1 - The second point`
`15`		`- * @param {float} t -The percentage between p0 and p1 to return represented as a number between 0 and 1.`
	`13`	`+ * @param {number} p0 - The first point.`
	`14`	`+ * @param {number} p1 - The second point.`
	`15`	`+ * @param {float} t - The percentage between p0 and p1 to return, represented as a number between 0 and 1.`
`16`	`16`	`*`
`17`		`- * @return {number} The step t% of the way between p0 and p1`
	`17`	`+ * @return {number} The step t% of the way between p0 and p1.`
`18`	`18`	`*/`
`19`	`19`	`var Linear = function (p0, p1, t)`
`20`	`20`	`{`
Original file line number	Diff line number	Diff line change
`@@ -5,16 +5,16 @@`
`5`	`5`	`*/`
`6`	`6`
`7`	`7`	`/**`
`8`		`- * [description]`
	`8`	+ * Add an `amount` to a `value`, limiting the maximum result to `max`.
`9`	`9`	`*`
`10`	`10`	`* @function Phaser.Math.MaxAdd`
`11`	`11`	`* @since 3.0.0`
`12`	`12`	`*`
`13`		`- * @param {number} value - [description]`
`14`		`- * @param {number} amount - [description]`
`15`		`- * @param {number} max - [description]`
	`13`	`+ * @param {number} value - The value to add to.`
	`14`	`+ * @param {number} amount - The amount to add.`
	`15`	`+ * @param {number} max - The maximum value to return.`
`16`	`16`	`*`
`17`		`- * @return {number} [description]`
	`17`	`+ * @return {number} The resulting value.`
`18`	`18`	`*/`
`19`	`19`	`var MaxAdd = function (value, amount, max)`
`20`	`20`	`{`
Original file line number	Diff line number	Diff line change
`@@ -5,15 +5,19 @@`
`5`	`5`	`*/`
`6`	`6`
`7`	`7`	`/**`
`8`		`- * [description]`
	`8`	`+ * Compute a random unit vector.`
	`9`	`+ *`
	`10`	`+ * Computes random values for the given vector between -1 and 1 that can be used to represent a direction.`
	`11`	`+ *`
	`12`	`+ * Optionally accepts a scale value to scale the resulting vector by.`
`9`	`13`	`*`
`10`	`14`	`* @function Phaser.Math.RandomXY`
`11`	`15`	`* @since 3.0.0`
`12`	`16`	`*`
`13`		`- * @param {Phaser.Math.Vector2} vector - [description]`
`14`		`- * @param {float} scale - [description]`
	`17`	`+ * @param {Phaser.Math.Vector2} vector - The Vector to compute random values for.`
	`18`	`+ * @param {float} [scale=1] - The scale of the random values.`
`15`	`19`	`*`
`16`		`- * @return {Phaser.Math.Vector2} [description]`
	`20`	`+ * @return {Phaser.Math.Vector2} The given Vector.`
`17`	`21`	`*/`
`18`	`22`	`var RandomXY = function (vector, scale)`
`19`	`23`	`{`