Final Doc Jam merge

Author: photonstorm

CHANGELOG.md

@@ -146,11 +146,9 @@ Thanks to the following for helping with the Phaser 3 Examples and TypeScript de
 
 ### Phaser Doc Jam
 
-The [Phaser Doc Jam](http://docjam.phaser.io) is an on-going effort to ensure that the Phaser 3 API has 100% documentation coverage. Thanks to the monumental effort of myself and the following people we're now really close to that goal! My thanks to:
-
-16patsle - @icbat - @gurungrahul2 - @samme - @telinc1 - anandu pavanan - blackhawx - candelibas - Diego Romero - Elliott Wallace - eric - Georges Gabereau - Haobo Zhang - henriacle - madclaws - marc136 - Mihail Ilinov - naum303 - NicolasRoehm - rejacobson - Robert Kowalski - rootasjey - scottwestover - stetso - therealsamf - Tigran - willblackmore - zenwaichi
+The Phaser Doc Jam was a community-backed effort to try and get the Phaser 3 API documentation to 100% coverage. The Doc Jam is now over and I offer my thanks to the following who helped with docs in this release:
 
-If you'd like to help finish off the last parts of documentation then take a look at the [Doc Jam site](http://docjam.phaser.io).
+16patsle - @gurungrahul2 - @icbat - @samme - @telinc1 - anandu pavanan - blackhawx - candelibas - Diego Romero - doronlinder - Elliott Wallace - eric - Georges Gabereau - Haobo Zhang - henriacle - jak6jak - Jake Jensen - James Van Roose - JamesSkemp - joelahoover - Joey - madclaws - marc136 - Mihail Ilinov - naum303 - NicolasRoehm - nuane - rejacobson - Robert Kowalski - rodri042 - rootasjey - sawamara - scottwestover - sir13tommy - stetso - therealsamf - Tigran - willblackmore - zenwaichi
 
 ## Version 3.15.1 - Batou - 16th October 2018
 

src/animations/AnimationManager.js

@@ -421,7 +421,7 @@ var AnimationManager = new Class({
      * @param {string} key - The key of the animation to load.
      * @param {(string|integer)} [startFrame] - The name of a start frame to set on the loaded animation.
      *
-     * @return {Phaser.GameObjects.GameObject} [description]
+     * @return {Phaser.GameObjects.GameObject} The Game Object with the animation loaded into it.
      */
     load: function (child, key, startFrame)
     {
@@ -576,7 +576,7 @@ var AnimationManager = new Class({
     },
 
     /**
-     * [description]
+     * Get the animation data as javascript object by giving key, or get the data of all animations as array of objects, if key wasn't provided.
      *
      * @method Phaser.Animations.AnimationManager#toJSON
      * @since 3.0.0
@@ -608,7 +608,8 @@ var AnimationManager = new Class({
     },
 
     /**
-     * [description]
+     * Destroy this Animation Manager and clean up animation definitions and references to other objects.
+     * This method should not be called directly. It will be called automatically as a response to a `destroy` event from the Phaser.Game instance.
      *
      * @method Phaser.Animations.AnimationManager#destroy
      * @since 3.0.0

src/curves/path/MoveTo.js

@@ -9,15 +9,15 @@ var Vector2 = require('../../math/Vector2');
 
 /**
  * @classdesc
- * [description]
+ * A MoveTo Curve is a very simple curve consisting of only a single point. Its intended use is to move the ending point in a Path.
  *
  * @class MoveTo
  * @memberof Phaser.Curves
  * @constructor
  * @since 3.0.0
  *
- * @param {number} [x] - [description]
- * @param {number} [y] - [description]
+ * @param {number} [x] - `x` pixel coordinate.
+ * @param {number} [y] - `y` pixel coordinate.
  */
 var MoveTo = new Class({
 
@@ -28,7 +28,7 @@ var MoveTo = new Class({
         //  Skip length calcs in paths
 
         /**
-         * [description]
+         * Denotes that this Curve does not influence the bounds, points, and drawing of its parent Path. Must be `false` or some methods in the parent Path will throw errors.
          *
          * @name Phaser.Curves.MoveTo#active
          * @type {boolean}
@@ -38,7 +38,7 @@ var MoveTo = new Class({
         this.active = false;
 
         /**
-         * [description]
+         * The lone point which this curve consists of.
          *
          * @name Phaser.Curves.MoveTo#p0
          * @type {Phaser.Math.Vector2}
@@ -68,17 +68,17 @@ var MoveTo = new Class({
     },
 
     /**
-     * [description]
+     * Retrieves the point at given position in the curve. This will always return this curve's only point.
      *
      * @method Phaser.Curves.MoveTo#getPointAt
      * @since 3.0.0
      *
      * @generic {Phaser.Math.Vector2} O - [out,$return]
      *
-     * @param {number} u - [description]
-     * @param {Phaser.Math.Vector2} [out] - [description]
+     * @param {number} u - The position in the path to retrieve, between 0 and 1. Not used.
+     * @param {Phaser.Math.Vector2} [out] - An optional vector in which to store the point.
      *
-     * @return {Phaser.Math.Vector2} [description]
+     * @return {Phaser.Math.Vector2} The modified `out` vector, or a new `Vector2` if none was provided.
      */
     getPointAt: function (u, out)
     {
@@ -112,12 +112,12 @@ var MoveTo = new Class({
     },
 
     /**
-     * [description]
+     * Converts this curve into a JSON-serializable object.
      *
      * @method Phaser.Curves.MoveTo#toJSON
      * @since 3.0.0
      *
-     * @return {JSONCurve} [description]
+     * @return {JSONCurve} A primitive object with the curve's type and only point.
      */
     toJSON: function ()
     {

src/geom/line/NormalY.js

@@ -8,14 +8,15 @@ var MATH_CONST = require('../../math/const');
 var Angle = require('./Angle');
 
 /**
- * [description]
+ * The Y value of the normal of the given line.
+ * The normal of a line is a vector that points perpendicular from it.
  *
  * @function Phaser.Geom.Line.NormalY
  * @since 3.0.0
  *
- * @param {Phaser.Geom.Line} line - [description]
+ * @param {Phaser.Geom.Line} line - The line to calculate the normal of.
  *
- * @return {number} [description]
+ * @return {number} The Y value of the normal of the Line.
  */
 var NormalY = function (line)
 {

src/geom/point/GetCentroid.js

@@ -7,7 +7,8 @@
 var Point = require('./Point');
 
 /**
- * [description]
+ * Get the centroid or geometric center of a plane figure (the arithmetic mean position of all the points in the figure).
+ * Informally, it is the point at which a cutout of the shape could be perfectly balanced on the tip of a pin.
  *
  * @function Phaser.Geom.Point.GetCentroid
  * @since 3.0.0

src/geom/point/SetMagnitude.js

@@ -7,17 +7,17 @@
 var GetMagnitude = require('./GetMagnitude');
 
 /**
- * [description]
+ * Changes the magnitude (length) of a two-dimensional vector without changing its direction.
  *
  * @function Phaser.Geom.Point.SetMagnitude
  * @since 3.0.0
  *
  * @generic {Phaser.Geom.Point} O - [point,$return]
  *
- * @param {Phaser.Geom.Point} point - [description]
- * @param {number} magnitude - [description]
+ * @param {Phaser.Geom.Point} point - The Point to treat as the end point of the vector.
+ * @param {number} magnitude - The new magnitude of the vector.
  *
- * @return {Phaser.Geom.Point} [description]
+ * @return {Phaser.Geom.Point} The modified Point.
  */
 var SetMagnitude = function (point, magnitude)
 {

src/geom/polygon/Clone.js

@@ -7,14 +7,14 @@
 var Polygon = require('./Polygon');
 
 /**
- * [description]
+ * Create a new polygon which is a copy of the specified polygon
  *
  * @function Phaser.Geom.Polygon.Clone
  * @since 3.0.0
  *
- * @param {Phaser.Geom.Polygon} polygon - [description]
+ * @param {Phaser.Geom.Polygon} polygon - The polygon to create a clone of
  *
- * @return {Phaser.Geom.Polygon} [description]
+ * @return {Phaser.Geom.Polygon} A new separate Polygon cloned from the specified polygon, based on the same points.
  */
 var Clone = function (polygon)
 {

src/geom/polygon/Polygon.js

@@ -10,14 +10,26 @@ var GetPoints = require('./GetPoints');
 
 /**
  * @classdesc
- * [description]
+ * A Polygon object
+ *
+
+ * The polygon is a closed shape consists of a series of connected straight lines defined by list of ordered points.
+ * Several formats are supported to define the list of points, check the setTo method for details. 
+ * This is a geometry object allowing you to define and inspect the shape.
+ * It is not a Game Object, in that you cannot add it to the display list, and it has no texture.
+ * To render a Polygon you should look at the capabilities of the Graphics class.
  *
  * @class Polygon
  * @memberof Phaser.Geom
  * @constructor
  * @since 3.0.0
  *
- * @param {Phaser.Geom.Point[]} [points] - [description]
+ * @param {Phaser.Geom.Point[]} [points] - List of points defining the perimeter of this Polygon. Several formats are supported: 
+ * - A string containing paired x y values separated by a single space: `'40 0 40 20 100 20 100 80 40 80 40 100 0 50'`
+ * - An array of Point objects: `[new Phaser.Point(x1, y1), ...]`
+ * - An array of objects with public x y properties: `[obj1, obj2, ...]`
+ * - An array of paired numbers that represent point coordinates: `[x1,y1, x2,y2, ...]`
+ * - An array of arrays with two elements representing x/y coordinates: `[[x1, y1], [x2, y2], ...]`
  */
 var Polygon = new Class({
 
@@ -82,7 +94,7 @@ var Polygon = new Class({
      * @method Phaser.Geom.Polygon#setTo
      * @since 3.0.0
      *
-     * @param {array} points - [description]
+     * @param {array} points - Points defining the perimeter of this polygon. Please check function description above for the different supported formats.
      *
      * @return {Phaser.Geom.Polygon} This Polygon object.
      */

src/geom/polygon/Reverse.js

@@ -5,16 +5,16 @@
  */
 
 /**
- * [description]
+ * Reverses the order of the points of a Polygon.
  *
  * @function Phaser.Geom.Polygon.Reverse
  * @since 3.0.0
  *
  * @generic {Phaser.Geom.Polygon} O - [polygon,$return]
  *
- * @param {Phaser.Geom.Polygon} polygon - [description]
+ * @param {Phaser.Geom.Polygon} polygon - The Polygon to modify.
  *
- * @return {Phaser.Geom.Polygon} [description]
+ * @return {Phaser.Geom.Polygon} The modified Polygon.
  */
 var Reverse = function (polygon)
 {

src/geom/rectangle/Area.js

@@ -5,14 +5,14 @@
  */
 
 /**
- * [description]
+ * Calculates the area of the given Rectangle object.
  *
  * @function Phaser.Geom.Rectangle.Area
  * @since 3.0.0
  *
- * @param {Phaser.Geom.Rectangle} rect - [description]
+ * @param {Phaser.Geom.Rectangle} rect - The rectangle to calculate the area of.
  *
- * @return {number} [description]
+ * @return {number} The area of the Rectangle object.
  */
 var Area = function (rect)
 {