From faaadb357ee6f2083f761953b6335ae683f92ba6 Mon Sep 17 00:00:00 2001
From: Richard Davey <rich@photonstorm.com>
Date: Mon, 1 Oct 2018 12:01:59 +0100
Subject: [PATCH] Completed Actions jsdocs

---
 src/actions/Call.js                 |  2 +-
 src/actions/PlaceOnCircle.js        | 10 ++++++----
 src/actions/PlaceOnEllipse.js       | 10 ++++++----
 src/actions/PlaceOnRectangle.js     | 15 ++++++---------
 src/actions/PlaceOnTriangle.js      |  9 +++++----
 src/actions/RandomCircle.js         |  6 ++++--
 src/actions/RandomEllipse.js        |  6 ++++--
 src/actions/RandomLine.js           |  6 ++++--
 src/actions/RandomRectangle.js      |  4 ++--
 src/actions/RandomTriangle.js       |  6 ++++--
 src/actions/RotateAroundDistance.js |  2 +-
 src/actions/ShiftPosition.js        | 14 ++++++++------
 src/actions/SmoothStep.js           | 12 +++++++-----
 src/actions/SmootherStep.js         | 12 +++++++-----
 src/actions/Spread.js               | 21 +++++++++++++++------
 src/actions/ToggleVisible.js        |  3 ++-
 16 files changed, 82 insertions(+), 56 deletions(-)

diff --git a/src/actions/Call.js b/src/actions/Call.js
index d67bd0f77..d07c5381f 100644
--- a/src/actions/Call.js
+++ b/src/actions/Call.js
@@ -7,7 +7,7 @@
 /**
  * @callback CallCallback
  *
- * @param {Phaser.GameObjects.GameObject} item - [description]
+ * @param {Phaser.GameObjects.GameObject} item - The Game Object to run the callback on.
  */
 
 /**
diff --git a/src/actions/PlaceOnCircle.js b/src/actions/PlaceOnCircle.js
index 1d5fd0b76..5bdfd5a8d 100644
--- a/src/actions/PlaceOnCircle.js
+++ b/src/actions/PlaceOnCircle.js
@@ -5,7 +5,9 @@
  */
 
 /**
- * [description]
+ * Takes an array of Game Objects and positions them on evenly spaced points around the perimeter of a Circle.
+ * 
+ * If you wish to pass a `Phaser.GameObjects.Circle` Shape to this function, you should pass its `geom` property.
  *
  * @function Phaser.Actions.PlaceOnCircle
  * @since 3.0.0
@@ -13,9 +15,9 @@
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {Phaser.Geom.Circle} circle - [description]
- * @param {number} [startAngle=0] - [description]
- * @param {number} [endAngle=6.28] - [description]
+ * @param {Phaser.Geom.Circle} circle - The Circle to position the Game Objects on.
+ * @param {number} [startAngle=0] - Optional angle to start position from, in radians.
+ * @param {number} [endAngle=6.28] - Optional angle to stop position at, in radians.
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/PlaceOnEllipse.js b/src/actions/PlaceOnEllipse.js
index 0b20abc5f..d16cc0225 100644
--- a/src/actions/PlaceOnEllipse.js
+++ b/src/actions/PlaceOnEllipse.js
@@ -5,7 +5,9 @@
  */
 
 /**
- * [description]
+ * Takes an array of Game Objects and positions them on evenly spaced points around the perimeter of an Ellipse.
+ * 
+ * If you wish to pass a `Phaser.GameObjects.Ellipse` Shape to this function, you should pass its `geom` property.
  *
  * @function Phaser.Actions.PlaceOnEllipse
  * @since 3.0.0
@@ -13,9 +15,9 @@
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {Phaser.Geom.Ellipse} ellipse - [description]
- * @param {number} [startAngle=0] - [description]
- * @param {number} [endAngle=6.28] - [description]
+ * @param {Phaser.Geom.Ellipse} ellipse - The Ellipse to position the Game Objects on.
+ * @param {number} [startAngle=0] - Optional angle to start position from, in radians.
+ * @param {number} [endAngle=6.28] - Optional angle to stop position at, in radians.
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/PlaceOnRectangle.js b/src/actions/PlaceOnRectangle.js
index 71ffe8934..9a112a9cb 100644
--- a/src/actions/PlaceOnRectangle.js
+++ b/src/actions/PlaceOnRectangle.js
@@ -8,14 +8,11 @@ var MarchingAnts = require('../geom/rectangle/MarchingAnts');
 var RotateLeft = require('../utils/array/RotateLeft');
 var RotateRight = require('../utils/array/RotateRight');
 
-//  Place the items in the array around the perimeter of the given rectangle.
-
-//  Placement starts from the top-left of the rectangle, and proceeds in a
-//  clockwise direction. If the shift parameter is given you can offset where
-//  placement begins.
-
 /**
- * [description]
+ * Takes an array of Game Objects and positions them on evenly spaced points around the perimeter of a Rectangle.
+ * 
+ * Placement starts from the top-left of the rectangle, and proceeds in a clockwise direction.
+ * If the `shift` parameter is given you can offset where placement begins.
  *
  * @function Phaser.Actions.PlaceOnRectangle
  * @since 3.0.0
@@ -23,8 +20,8 @@ var RotateRight = require('../utils/array/RotateRight');
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {Phaser.Geom.Rectangle} rect - [description]
- * @param {integer} [shift=1] - [description]
+ * @param {Phaser.Geom.Rectangle} rect - The Rectangle to position the Game Objects on.
+ * @param {integer} [shift=1] - An optional positional offset.
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/PlaceOnTriangle.js b/src/actions/PlaceOnTriangle.js
index 0be4676fb..028a1cef0 100644
--- a/src/actions/PlaceOnTriangle.js
+++ b/src/actions/PlaceOnTriangle.js
@@ -4,11 +4,12 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
-// var GetPointsOnLine = require('../geom/line/GetPointsOnLine');
 var BresenhamPoints = require('../geom/line/BresenhamPoints');
 
 /**
- * [description]
+ * Takes an array of Game Objects and positions them on evenly spaced points around the edges of a Triangle.
+ * 
+ * If you wish to pass a `Phaser.GameObjects.Triangle` Shape to this function, you should pass its `geom` property.
  *
  * @function Phaser.Actions.PlaceOnTriangle
  * @since 3.0.0
@@ -16,8 +17,8 @@ var BresenhamPoints = require('../geom/line/BresenhamPoints');
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {Phaser.Geom.Triangle} triangle - [description]
- * @param {number} [stepRate=1] - [description]
+ * @param {Phaser.Geom.Triangle} triangle - The Triangle to position the Game Objects on.
+ * @param {number} [stepRate=1] - An optional step rate, to increase or decrease the packing of the Game Objects on the lines.
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/RandomCircle.js b/src/actions/RandomCircle.js
index ffe17d93b..c49b15358 100644
--- a/src/actions/RandomCircle.js
+++ b/src/actions/RandomCircle.js
@@ -7,7 +7,9 @@
 var Random = require('../geom/circle/Random');
 
 /**
- * [description]
+ * Takes an array of Game Objects and positions them at random locations within the Circle.
+ * 
+ * If you wish to pass a `Phaser.GameObjects.Circle` Shape to this function, you should pass its `geom` property.
  *
  * @function Phaser.Actions.RandomCircle
  * @since 3.0.0
@@ -15,7 +17,7 @@ var Random = require('../geom/circle/Random');
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {Phaser.Geom.Circle} circle - [description]
+ * @param {Phaser.Geom.Circle} circle - The Circle to position the Game Objects within.
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/RandomEllipse.js b/src/actions/RandomEllipse.js
index 466038550..1f3397be0 100644
--- a/src/actions/RandomEllipse.js
+++ b/src/actions/RandomEllipse.js
@@ -7,7 +7,9 @@
 var Random = require('../geom/ellipse/Random');
 
 /**
- * [description]
+ * Takes an array of Game Objects and positions them at random locations within the Ellipse.
+ * 
+ * If you wish to pass a `Phaser.GameObjects.Ellipse` Shape to this function, you should pass its `geom` property.
  *
  * @function Phaser.Actions.RandomEllipse
  * @since 3.0.0
@@ -15,7 +17,7 @@ var Random = require('../geom/ellipse/Random');
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {Phaser.Geom.Ellipse} ellipse - [description]
+ * @param {Phaser.Geom.Ellipse} ellipse - The Ellipse to position the Game Objects within.
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/RandomLine.js b/src/actions/RandomLine.js
index 461f4c869..52e2c5209 100644
--- a/src/actions/RandomLine.js
+++ b/src/actions/RandomLine.js
@@ -7,7 +7,9 @@
 var Random = require('../geom/line/Random');
 
 /**
- * [description]
+ * Takes an array of Game Objects and positions them at random locations on the Line.
+ * 
+ * If you wish to pass a `Phaser.GameObjects.Line` Shape to this function, you should pass its `geom` property.
  *
  * @function Phaser.Actions.RandomLine
  * @since 3.0.0
@@ -15,7 +17,7 @@ var Random = require('../geom/line/Random');
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {Phaser.Geom.Line} line - [description]
+ * @param {Phaser.Geom.Line} line - The Line to position the Game Objects randomly on.
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/RandomRectangle.js b/src/actions/RandomRectangle.js
index 0b4e753a8..687afc3fd 100644
--- a/src/actions/RandomRectangle.js
+++ b/src/actions/RandomRectangle.js
@@ -7,7 +7,7 @@
 var Random = require('../geom/rectangle/Random');
 
 /**
- * [description]
+ * Takes an array of Game Objects and positions them at random locations within the Ellipse.
  *
  * @function Phaser.Actions.RandomRectangle
  * @since 3.0.0
@@ -15,7 +15,7 @@ var Random = require('../geom/rectangle/Random');
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {Phaser.Geom.Rectangle} rect - [description]
+ * @param {Phaser.Geom.Rectangle} rect - The Rectangle to position the Game Objects within.
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/RandomTriangle.js b/src/actions/RandomTriangle.js
index 38728ca77..e8e0492d3 100644
--- a/src/actions/RandomTriangle.js
+++ b/src/actions/RandomTriangle.js
@@ -7,7 +7,9 @@
 var Random = require('../geom/triangle/Random');
 
 /**
- * [description]
+ * Takes an array of Game Objects and positions them at random locations within the Triangle.
+ * 
+ * If you wish to pass a `Phaser.GameObjects.Triangle` Shape to this function, you should pass its `geom` property.
  *
  * @function Phaser.Actions.RandomTriangle
  * @since 3.0.0
@@ -15,7 +17,7 @@ var Random = require('../geom/triangle/Random');
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {Phaser.Geom.Triangle} triangle - [description]
+ * @param {Phaser.Geom.Triangle} triangle - The Triangle to position the Game Objects within.
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/RotateAroundDistance.js b/src/actions/RotateAroundDistance.js
index 1b010d5a4..c503ffbd2 100644
--- a/src/actions/RotateAroundDistance.js
+++ b/src/actions/RotateAroundDistance.js
@@ -7,7 +7,7 @@
 var MathRotateAroundDistance = require('../math/RotateAroundDistance');
 
 /**
- * [description]
+ * Rotates an array of Game Objects around a point by the given angle and distance.
  *
  * @function Phaser.Actions.RotateAroundDistance
  * @since 3.0.0
diff --git a/src/actions/ShiftPosition.js b/src/actions/ShiftPosition.js
index dbd8ba33c..9ea29f67b 100644
--- a/src/actions/ShiftPosition.js
+++ b/src/actions/ShiftPosition.js
@@ -7,9 +7,11 @@
 var Vector2 = require('../math/Vector2');
 
 /**
- * Iterate through items changing the position of each element to
- * be that of the element that came before it in the array (or after it if direction = 1)
+ * Iterate through the items array changing the position of each element to be that of the element that came before
+ * it in the array (or after it if direction = 1)
+ * 
  * The first items position is set to x/y.
+ * 
  * The final x/y coords are returned
  *
  * @function Phaser.Actions.ShiftPosition
@@ -19,10 +21,10 @@ var Vector2 = require('../math/Vector2');
  * @generic {Phaser.Math.Vector2} O - [output,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {number} x - [description]
- * @param {number} y - [description]
- * @param {integer} [direction=0] - [description]
- * @param {(Phaser.Math.Vector2|object)} [output] - [description]
+ * @param {number} x - The x coordinate to place the first item in the array at.
+ * @param {number} y - The y coordinate to place the first item in the array at.
+ * @param {integer} [direction=0] - The iteration direction. 0 = first to last and 1 = last to first.
+ * @param {(Phaser.Math.Vector2|object)} [output] - An optional objec to store the final objects position in.
  *
  * @return {Phaser.Math.Vector2} The output vector.
  */
diff --git a/src/actions/SmoothStep.js b/src/actions/SmoothStep.js
index 6c920e35a..ba341f2b4 100644
--- a/src/actions/SmoothStep.js
+++ b/src/actions/SmoothStep.js
@@ -7,7 +7,9 @@
 var MathSmoothStep = require('../math/SmoothStep');
 
 /**
- * [description]
+ * Smoothstep is a sigmoid-like interpolation and clamping function.
+ * 
+ * The function depends on three parameters, the input x, the "left edge" and the "right edge", with the left edge being assumed smaller than the right edge. The function receives a real number x as an argument and returns 0 if x is less than or equal to the left edge, 1 if x is greater than or equal to the right edge, and smoothly interpolates, using a Hermite polynomial, between 0 and 1 otherwise. The slope of the smoothstep function is zero at both edges. This is convenient for creating a sequence of transitions using smoothstep to interpolate each segment as an alternative to using more sophisticated or expensive interpolation techniques.
  *
  * @function Phaser.Actions.SmoothStep
  * @since 3.0.0
@@ -15,10 +17,10 @@ var MathSmoothStep = require('../math/SmoothStep');
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {string} property - [description]
- * @param {number} min - [description]
- * @param {number} max - [description]
- * @param {number} inc - [description]
+ * @param {string} property - The property of the Game Object to interpolate.
+ * @param {number} min - The minimum interpolation value.
+ * @param {number} max - The maximum interpolation value.
+ * @param {boolean} [inc=false] - Should the values be incremented? `true` or set (`false`)
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/SmootherStep.js b/src/actions/SmootherStep.js
index dea70d376..d70b56c46 100644
--- a/src/actions/SmootherStep.js
+++ b/src/actions/SmootherStep.js
@@ -7,7 +7,9 @@
 var MathSmootherStep = require('../math/SmootherStep');
 
 /**
- * [description]
+ * Smootherstep is a sigmoid-like interpolation and clamping function.
+ * 
+ * The function depends on three parameters, the input x, the "left edge" and the "right edge", with the left edge being assumed smaller than the right edge. The function receives a real number x as an argument and returns 0 if x is less than or equal to the left edge, 1 if x is greater than or equal to the right edge, and smoothly interpolates, using a Hermite polynomial, between 0 and 1 otherwise. The slope of the smoothstep function is zero at both edges. This is convenient for creating a sequence of transitions using smoothstep to interpolate each segment as an alternative to using more sophisticated or expensive interpolation techniques.
  *
  * @function Phaser.Actions.SmootherStep
  * @since 3.0.0
@@ -15,10 +17,10 @@ var MathSmootherStep = require('../math/SmootherStep');
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {string} property - [description]
- * @param {number} min - [description]
- * @param {number} max - [description]
- * @param {number} inc - [description]
+ * @param {string} property - The property of the Game Object to interpolate.
+ * @param {number} min - The minimum interpolation value.
+ * @param {number} max - The maximum interpolation value.
+ * @param {boolean} [inc=false] - Should the values be incremented? `true` or set (`false`)
  *
  * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
  */
diff --git a/src/actions/Spread.js b/src/actions/Spread.js
index e20a72cec..040e7ea49 100644
--- a/src/actions/Spread.js
+++ b/src/actions/Spread.js
@@ -5,7 +5,16 @@
  */
 
 /**
- * [description]
+ * Takes an array of Game Objects and then modifies their `property` so the value equals, or is incremented, the
+ * calculated spread value.
+ * 
+ * The spread value is derived from the given `min` and `max` values and the total number of items in the array.//#endregion
+ * 
+ * For example, to cause an array of Sprites to change in alpha from 0 to 1 you could call:
+ * 
+ * ```javascript
+ * Phaser.Actions.Spread(itemsArray, 'alpha', 0, 1);
+ * ```
  *
  * @function Phaser.Actions.Spread
  * @since 3.0.0
@@ -13,12 +22,12 @@
  * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
  *
  * @param {(array|Phaser.GameObjects.GameObject[])} items - An array of Game Objects. The contents of this array are updated by this Action.
- * @param {string} property - [description]
- * @param {number} min - [description]
- * @param {number} max - [description]
- * @param {number} [inc=false] - [description]
+ * @param {string} property - The property of the Game Object to spread.
+ * @param {number} min - The minimum value.
+ * @param {number} max - The maximum value.
+ * @param {boolean} [inc=false] - Should the values be incremented? `true` or set (`false`)
  *
- * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that was passed to this Action.
+ * @return {(array|Phaser.GameObjects.GameObject[])} The array of Game Objects that were passed to this Action.
  */
 var Spread = function (items, property, min, max, inc)
 {
diff --git a/src/actions/ToggleVisible.js b/src/actions/ToggleVisible.js
index f02eb98b9..e6cd15be9 100644
--- a/src/actions/ToggleVisible.js
+++ b/src/actions/ToggleVisible.js
@@ -5,7 +5,8 @@
  */
 
 /**
- * [description]
+ * Takes an array of Game Objects and toggles the visibility of each one.
+ * Those previously `visible = false` will become `visible = true`, and vice versa.
  *
  * @function Phaser.Actions.ToggleVisible
  * @since 3.0.0