Merge pull request phaserjs#3614 from Fabadiculous/docs

Docs for DegToRad, RadToDeg, Rotate, Within, RoundAwayFromZero and IsEven

Author: photonstorm

src/math/DegToRad.js

@@ -7,14 +7,14 @@
 var CONST = require('./const');
 
 /**
- * [description]
+ * Convert the given angle from degrees, to the equivalent angle in radians.
  *
  * @function Phaser.Math.DegToRad
  * @since 3.0.0
  *
- * @param {integer} degrees - [description]
+ * @param {integer} degrees - The angle (in degrees) to convert to radians.
  *
- * @return {float} [description]
+ * @return {float} The given angle converted to radians.
  */
 var DegToRad = function (degrees)
 {

src/math/IsEven.js

@@ -5,14 +5,14 @@
  */
 
 /**
- * [description]
+ * Check if a given value is an even number.
  *
  * @function Phaser.Math.IsEven
  * @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 IsEven = function (value)
 {

src/math/RadToDeg.js

@@ -7,14 +7,14 @@
 var CONST = require('./const');
 
 /**
- * [description]
+ * Convert the given angle in radians, to the equivalent angle in degrees.
  *
  * @function Phaser.Math.RadToDeg
  * @since 3.0.0
  *
- * @param {float} radians - [description]
+ * @param {float} radians - The angle in radians to convert ot degrees.
  *
- * @return {integer} [description]
+ * @return {integer} The given angle converted to degrees.
  */
 var RadToDeg = function (radians)
 {

src/math/Rotate.js

@@ -5,15 +5,15 @@
  */
 
 /**
- * [description]
+ * Rotate a given point by a given angle around the origin (0, 0), in an anti-clockwise direction.
  *
  * @function Phaser.Math.Rotate
  * @since 3.0.0
  *
- * @param {(Phaser.Geom.Point|object)} point - [description]
- * @param {number} angle - [description]
+ * @param {(Phaser.Geom.Point|object)} point - The point to be rotated.
+ * @param {number} angle - The angle to be rotated by in an anticlockwise direction.
  *
- * @return {Phaser.Geom.Point} [description]
+ * @return {Phaser.Geom.Point} The given point, rotated by the given angle in an anticlockwise direction.
  */
 var Rotate = function (point, angle)
 {

src/math/RoundAwayFromZero.js

@@ -5,14 +5,14 @@
  */
 
 /**
- * [description]
+ * Round a given number so it is further away from zero. That is, positive numbers are rounded up, and negative numbers are rounded down.
  *
  * @function Phaser.Math.RoundAwayFromZero
  * @since 3.0.0
  *
- * @param {number} value - [description]
+ * @param {number} value - The number to round.
  *
- * @return {number} [description]
+ * @return {number} The rounded number, rounded away from zero.
  */
 var RoundAwayFromZero = function (value)
 {

src/math/Vector2.js

@@ -18,15 +18,15 @@ var Class = require('../utils/Class');
 
 /**
  * @classdesc
- * [description]
+ * A representation of a vector in 2D space.
  *
  * @class Vector2
  * @memberOf Phaser.Math
  * @constructor
  * @since 3.0.0
  *
- * @param {number} [x] - [description]
- * @param {number} [y] - [description]
+ * @param {number} [x] - The x component of this Vector.
+ * @param {number} [y] - The y component of this Vector.
  */
 var Vector2 = new Class({
 
@@ -69,7 +69,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Make a clone of this Vector2.
      *
      * @method Phaser.Math.Vector2#clone
      * @since 3.0.0
@@ -82,12 +82,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Copy the components of a given vector, into this Vector.
      *
      * @method Phaser.Math.Vector2#copy
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} src - [description]
+     * @param {Phaser.Math.Vector2} src - The Vector to copy the components from.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -100,12 +100,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Set the component values of this Vector from a given Vector2Like object.
      *
      * @method Phaser.Math.Vector2#setFromObject
      * @since 3.0.0
      *
-     * @param {Vector2Like} obj - [description]
+     * @param {Vector2Like} obj - The object containing the component values to set for this Vector.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -118,13 +118,13 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * 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
      *
-     * @param {number} x - [description]
-     * @param {number} [y=x] - [description]
+     * @param {number} x - The x value to set for this Vector.
+     * @param {number} [y=x] - The y value to set for this Vector.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -144,8 +144,8 @@ var Vector2 = new Class({
      * @method Phaser.Math.Vector2#setTo
      * @since 3.4.0
      *
-     * @param {number} x - [description]
-     * @param {number} [y=x] - [description]
+     * @param {number} x - The x value to set for this Vector.
+     * @param {number} [y=x] - The y value to set for this Vector.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -176,27 +176,27 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Check if this Vector is equal to a given Vector.
      *
      * @method Phaser.Math.Vector2#equals
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} v - [description]
+     * @param {Phaser.Math.Vector2} v - The vector to compare with this Vector.
      *
-     * @return {boolean} [description]
+     * @return {boolean} Whether the given Vector is equal to this Vector.
      */
     equals: function (v)
     {
         return ((this.x === v.x) && (this.y === v.y));
     },
 
     /**
-     * [description]
+     * Calculate the angle between this Vector and the positive x-axis, in radians.
      *
      * @method Phaser.Math.Vector2#angle
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The angle between this Vector, and the positive x-axis, given in radians.
      */
     angle: function ()
     {
@@ -213,12 +213,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Add a given Vector to this Vector. Addition is element-wise.
      *
      * @method Phaser.Math.Vector2#add
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} src - [description]
+     * @param {Phaser.Math.Vector2} src - The Vector to add to this Vector.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -231,12 +231,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Subtract the given Vector from this Vector. Subtraction is element-wise.
      *
      * @method Phaser.Math.Vector2#subtract
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} src - [description]
+     * @param {Phaser.Math.Vector2} src - The Vector to subtract from this Vector.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -249,12 +249,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Perform an element-wise multiplication between this Vector and the given Vector.
      *
      * @method Phaser.Math.Vector2#multiply
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} src - [description]
+     * @param {Phaser.Math.Vector2} src - The Vector to multiply this Vector by.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -267,12 +267,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Scale this Vector by the given value.
      *
      * @method Phaser.Math.Vector2#scale
      * @since 3.0.0
      *
-     * @param {number} value - [description]
+     * @param {number} value - The value to scale this Vector by.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -293,12 +293,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Perform an element-wise division between this Vector and the given Vector. This Vector is divided by the given Vector.
      *
      * @method Phaser.Math.Vector2#divide
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} src - [description]
+     * @param {Phaser.Math.Vector2} src - The Vector to divide this Vector by.
      *
      * @return {Phaser.Math.Vector2} This Vector2.
      */
@@ -311,7 +311,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Negate the x and y components of this Vector.
      *
      * @method Phaser.Math.Vector2#negate
      * @since 3.0.0
@@ -327,14 +327,14 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the distance between this Vector, and the given Vector.
      *
      * @method Phaser.Math.Vector2#distance
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} src - [description]
+     * @param {Phaser.Math.Vector2} src - The Vector to calculate the distance to.
      *
-     * @return {number} [description]
+     * @return {number} The distance to the given Vector from this Vector.
      */
     distance: function (src)
     {
@@ -345,14 +345,14 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * The distance between this Vector, and the given Vector, squared.
      *
      * @method Phaser.Math.Vector2#distanceSq
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} src - [description]
+     * @param {Phaser.Math.Vector2} src - The Vector to calculate the distance to.
      *
-     * @return {number} [description]
+     * @return {number} The distance to this Vector and the given Vector, squared.
      */
     distanceSq: function (src)
     {
@@ -363,12 +363,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * The length (or magnitude) of this Vector.
      *
      * @method Phaser.Math.Vector2#length
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The length of this Vector.
      */
     length: function ()
     {
@@ -379,12 +379,12 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Calculate the length of this Vector squared.
      *
      * @method Phaser.Math.Vector2#lengthSq
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The length of this Vector, squared.
      */
     lengthSq: function ()
     {
@@ -395,7 +395,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Normalise this Vector, that is, make it a unit length vector (magnitude of 1) in the same direction.
      *
      * @method Phaser.Math.Vector2#normalize
      * @since 3.0.0
@@ -440,14 +440,14 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Perform a dot product between this Vector and the given Vector
      *
      * @method Phaser.Math.Vector2#dot
      * @since 3.0.0
      *
-     * @param {Phaser.Math.Vector2} src - [description]
+     * @param {Phaser.Math.Vector2} src - The Vector2 to dot product with this Vector2.
      *
-     * @return {number} [description]
+     * @return {number} The result of the dot product
      */
     dot: function (src)
     {
@@ -538,7 +538,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * [description]
+     * Make this Vector the zero vector (0, 0).
      *
      * @method Phaser.Math.Vector2#reset
      * @since 3.0.0