Lots more jsdoc fixes and new documentation

src/animations/Animation.js

@@ -30,7 +30,7 @@ var GetValue = require('../utils/object/GetValue');
  *
  * @param {Phaser.Animations.AnimationManager} manager - A reference to the global Animation Manager
  * @param {string} key - The unique identifying string for this animation.
- * @param {Phaser.Animations.Animation.Config} config - The Animation configuration.
+ * @param {Phaser.Animations.Types.Animation} config - The Animation configuration.
  */
 var Animation = new Class({
 
@@ -224,7 +224,7 @@ var Animation = new Class({
      * @method Phaser.Animations.Animation#addFrame
      * @since 3.0.0
      *
-     * @param {(string|Phaser.Animations.AnimationFrame.Config[])} config - [description]
+     * @param {(string|Phaser.Animations.Types.AnimationFrame[])} config - [description]
      *
      * @return {Phaser.Animations.Animation} This Animation object.
      */
@@ -240,7 +240,7 @@ var Animation = new Class({
      * @since 3.0.0
      *
      * @param {integer} index - The index to insert the frame at within the animation.
-     * @param {(string|Phaser.Animations.AnimationFrame.Config[])} config - [description]
+     * @param {(string|Phaser.Animations.Types.AnimationFrame[])} config - [description]
      *
      * @return {Phaser.Animations.Animation} This Animation object.
      */
@@ -353,7 +353,7 @@ var Animation = new Class({
      * @since 3.0.0
      *
      * @param {Phaser.Textures.TextureManager} textureManager - [description]
-     * @param {(string|Phaser.Animations.AnimationFrame.Config[])} frames - [description]
+     * @param {(string|Phaser.Animations.Types.AnimationFrame[])} frames - [description]
      * @param {string} [defaultTextureKey] - [description]
      *
      * @return {Phaser.Animations.AnimationFrame[]} [description]

src/animations/typedefs/Animation.js

@@ -1,8 +1,8 @@
 /**
- * @typedef {object} Phaser.Animations.Animation.Config
+ * @typedef {object} Phaser.Animations.Types.Animation
  *
  * @property {string} [key] - The key that the animation will be associated with. i.e. sprite.animations.play(key)
- * @property {Phaser.Animations.AnimationFrame.Config[]} [frames] - An object containing data used to generate the frames for the animation
+ * @property {Phaser.Animations.Types.AnimationFrame[]} [frames] - An object containing data used to generate the frames for the animation
  * @property {string} [defaultTextureKey=null] - The key of the texture all frames of the animation will use. Can be overridden on a per frame basis.
  * @property {integer} [frameRate] - The frame rate of playback in frames per second (default 24 if duration is null)
  * @property {integer} [duration] - How long the animation should play for in milliseconds. If not given its derived from frameRate.

src/animations/typedefs/AnimationFrame.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {object} Phaser.Animations.AnimationFrame.Config
+ * @typedef {object} Phaser.Animations.Types.AnimationFrame
  *
  * @property {string} key - The key that the animation will be associated with. i.e. sprite.animations.play(key)
  * @property {(string|number)} frame - [description]

src/animations/typedefs/JSONAnimation.js

@@ -1,9 +1,9 @@
 /**
- * @typedef {object} JSONAnimation
+ * @typedef {object} Phaser.Animations.Types.JSONAnimation
  *
  * @property {string} key - The key that the animation will be associated with. i.e. sprite.animations.play(key)
  * @property {string} type - A frame based animation (as opposed to a bone based animation)
- * @property {JSONAnimationFrame[]} frames - [description]
+ * @property {Phaser.Animations.Types.JSONAnimationFrame[]} frames - [description]
  * @property {integer} frameRate - The frame rate of playback in frames per second (default 24 if duration is null)
  * @property {integer} duration - How long the animation should play for in milliseconds. If not given its derived from frameRate.
  * @property {boolean} skipMissedFrames - Skip frames if the time lags, or always advanced anyway?

src/animations/typedefs/JSONAnimationFrame.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {object} Phaser.Animations.AnimationFrame.JSONConfig
+ * @typedef {object} Phaser.Animations.Types.JSONAnimationFrame
  *
  * @property {string} key - The key of the Texture this AnimationFrame uses.
  * @property {(string|integer)} frame - The key of the Frame within the Texture that this AnimationFrame uses.

src/animations/typedefs/index.js

@@ -0,0 +1,9 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * @namespace Phaser.Animations.Types
+ */

src/display/color/Interpolate.js

@@ -7,16 +7,29 @@
 var Linear = require('../../math/Linear');
 
 /**
- * Interpolates color values
- *
- * @namespace Phaser.Display.Color.Interpolate
+ * @namespace Phaser.Display.Color.InterpolateFunctions
+ */
+
+/**
+ * @name Phaser.Display.Color.Interpolate
+ * @memberof Phaser.Display.Color
+ * @type {Phaser.Display.Color.InterpolateObject}
+ * @static
  * @since 3.0.0
  */
 
+/**
+ * @typedef {object} Phaser.Display.Color.InterpolateObject
+ * 
+ * @property {Phaser.Display.Color.InterpolateFunctions.RGBWithRGB} RGBWithRGB - Interpolates between the two given color ranges over the length supplied.
+ * @property {Phaser.Display.Color.InterpolateFunctions.ColorWithColor} ColorWithColor - Interpolates between the two given color objects over the length supplied.
+ * @property {Phaser.Display.Color.InterpolateFunctions.ColorWithRGB} ColorWithRGB - Interpolates between the Color object and color values over the length supplied.
+ */
+
 /**
  * Interpolates between the two given color ranges over the length supplied.
  *
- * @function Phaser.Display.Color.Interpolate.RGBWithRGB
+ * @function Phaser.Display.Color.InterpolateFunctions.RGBWithRGB
  * @since 3.0.0
  *
  * @param {number} r1 - Red value.
@@ -47,7 +60,7 @@ var RGBWithRGB = function (r1, g1, b1, r2, g2, b2, length, index)
 /**
  * Interpolates between the two given color objects over the length supplied.
  *
- * @function Phaser.Display.Color.Interpolate.ColorWithColor
+ * @function Phaser.Display.Color.InterpolateFunctions.ColorWithColor
  * @since 3.0.0
  *
  * @param {Phaser.Display.Color} color1 - The first Color object.
@@ -68,7 +81,7 @@ var ColorWithColor = function (color1, color2, length, index)
 /**
  * Interpolates between the Color object and color values over the length supplied.
  *
- * @function Phaser.Display.Color.Interpolate.ColorWithRGB
+ * @function Phaser.Display.Color.InterpolateFunctions.ColorWithRGB
  * @since 3.0.0
  *
  * @param {Phaser.Display.Color} color1 - The first Color object.

src/display/color/index.js

@@ -14,7 +14,8 @@
  */
 
 /**
- * @typedef {Object} ColorObject
+ * @typedef {object} ColorObject
+ * 
  * @property {number} r - The red color value in the range 0 to 255.
  * @property {number} g - The green color value in the range 0 to 255.
  * @property {number} b - The blue color value in the range 0 to 255.

src/gameobjects/blitter/Blitter.js

@@ -13,12 +13,16 @@ var GameObject = require('../GameObject');
 var List = require('../../structs/List');
 
 /**
- * @callback Phaser.GameObjects.Blitter.CreateCallback
+ * @callback CreateCallback
  *
  * @param {Phaser.GameObjects.Blitter.Bob} bob - The Bob that was created by the Blitter.
  * @param {integer} index - The position of the Bob within the Blitter display list.
  */
 
+/**
+ * @namespace [Phaser.GameObjects.Blitter] Phaser.GameObjects.Blitter
+ */
+
 /**
  * @classdesc
  * A Blitter Game Object.
@@ -167,7 +171,7 @@ var Blitter = new Class({
      * @method Phaser.GameObjects.Blitter#createFromCallback
      * @since 3.0.0
      *
-     * @param {Phaser.GameObjects.Blitter.CreateCallback} callback - The callback to invoke after creating a bob. It will be sent two arguments: The Bob and the index of the Bob.
+     * @param {CreateCallback} callback - The callback to invoke after creating a bob. It will be sent two arguments: The Bob and the index of the Bob.
      * @param {integer} quantity - The quantity of Bob objects to create.
      * @param {(string|integer|Phaser.Textures.Frame|string[]|integer[]|Phaser.Textures.Frame[])} [frame] - The Frame the Bobs will use. It must be part of the Blitter Texture.
      * @param {boolean} [visible=true] - Should the created Bob render or not?

src/gameobjects/graphics/Commands.js

@@ -4,10 +4,6 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
-/**
- * @namespace Phaser.GameObjects.Graphics.Commands
- */
-
 module.exports = {
 
     ARC: 0,

src/gameobjects/text/static/Text.js

@@ -16,6 +16,10 @@ var RemoveFromDOM = require('../../../dom/RemoveFromDOM');
 var TextRender = require('./TextRender');
 var TextStyle = require('../TextStyle');
 
+/**
+ * @namespace [Phaser.GameObjects.Text] Phaser.GameObjects.Text
+ */
+
 /**
  * @classdesc
  * A Text Game Object.
@@ -153,7 +157,7 @@ var Text = new Class({
          * Manages the style of this Text object.
          *
          * @name Phaser.GameObjects.Text#style
-         * @type {Phaser.GameObjects.Text.TextStyle}
+         * @type {Phaser.GameObjects.TextStyle}
          * @since 3.0.0
          */
         this.style = new TextStyle(this, style);

src/input/InputPluginCache.js

@@ -18,6 +18,10 @@ var inputPlugins = {};
  * @property {string} [mapping] - If this plugin is to be injected into the Input Plugin, this is the property key map used.
  */
 
+/**
+ * @namespace Phaser.Input.InputPluginCache
+ */
+
 var InputPluginCache = {};
 
 /**
@@ -26,7 +30,9 @@ var InputPluginCache = {};
  * Plugin is the object to instantiate to create the plugin
  * Mapping is what the plugin is injected into the Scene.Systems as (i.e. input)
  *
- * @method Phaser.Input.InputPluginCache.register
+ * @name Phaser.Input.InputPluginCache.register
+ * @type {function}
+ * @static
  * @since 3.10.0
  * 
  * @param {string} key - A reference used to get this plugin from the plugin cache.
@@ -43,7 +49,9 @@ InputPluginCache.register = function (key, plugin, mapping, settingsKey, configK
 /**
  * Returns the input plugin object from the cache based on the given key.
  *
- * @method Phaser.Input.InputPluginCache.getCore
+ * @name Phaser.Input.InputPluginCache.getCore
+ * @type {function}
+ * @static
  * @since 3.10.0
  * 
  * @param {string} key - The key of the input plugin to get.
@@ -58,7 +66,9 @@ InputPluginCache.getPlugin = function (key)
 /**
  * Installs all of the registered Input Plugins into the given target.
  *
- * @method Phaser.Input.InputPluginCache.install
+ * @name Phaser.Input.InputPluginCache.install
+ * @type {function}
+ * @static
  * @since 3.10.0
  * 
  * @param {Phaser.Input.InputPlugin} target - The target InputPlugin to install the plugins into.
@@ -86,7 +96,9 @@ InputPluginCache.install = function (target)
 /**
  * Removes an input plugin based on the given key.
  *
- * @method Phaser.Input.InputPluginCache.remove
+ * @name Phaser.Input.InputPluginCache.remove
+ * @type {function}
+ * @static
  * @since 3.10.0
  * 
  * @param {string} key - The key of the input plugin to remove.

src/scale/ScaleManager.js

@@ -22,7 +22,49 @@ var Vector2 = require('../math/Vector2');
  * @classdesc
  * The Scale Manager handles the scaling, resizing and alignment of the game canvas.
  * 
- * The game size is the logical size of the game; the display size is the scaled size of the canvas.
+ * The way scaling is handled is by setting the game canvas to a fixed size, which is defined in the
+ * game configuration. This dimension can be obtained in the `gameSize` property. The Scale Manager
+ * will then look at the available space within the _parent_ and scale the canvas accordingly. This
+ * is handled by setting the canvas CSS width and height properties, leaving the pixel dimensions
+ * untouched. Scaling is therefore achieved by keeping the core canvas the same size and 'stretching'
+ * it via its CSS properties. The actual displayed size of the game can be found in the `displaySize` component.
+ * 
+ * The calculations of the scale is heavily influenced by the bounding Parent size, which is the computed
+ * dimensions of the canvas's parent container / element. The CSS rules of the parent element play an
+ * important role in the operation of the Scale Manager.
+ * 
+ * #### Parent and Display canvas containment guidelines:
+ *
+ * - Style the Parent element (of the game canvas) to control the Parent size and
+ *   thus the games size and layout.
+ *
+ * - The Parent element's CSS styles should _effectively_ apply maximum (and minimum) bounding behavior.
+ *
+ * - The Parent element should _not_ apply a padding as this is not accounted for.
+ *   If a padding is required apply it to the Parent's parent or apply a margin to the Parent.
+ *   If you need to add a border, margin or any other CSS around your game container, then use a parent element and
+ *   apply the CSS to this instead, otherwise you'll be constantly resizing the shape of the game container.
+ *
+ * - The Display canvas layout CSS styles (i.e. margins, size) should not be altered / specified as
+ *   they may be updated by the Scale Manager.
+ *
+ * #### Scale Modes
+ * 
+ * The way the scaling is handled is determined by the `scaleMode` property. The default is `NO_SCALE`,
+ * which prevents Phaser from scaling or touching the canvas, or its parent, at all. In this mode, you are
+ * responsible for all scaling. The other scaling modes afford you automatic scaling.
+ * 
+ * If you wish to scale your game so that it always fits into the available space within the parent, you
+ * should use the scale mode `FIT`. Look at the documentation for other scale modes to see what options are
+ * available.
+ * 
+ * If you wish for the canvas to be resized directly, so that the canvas itself fills the available space
+ * (i.e. it isn't scaled, it's resized) then use the `RESIZE` scale mode. This will give you a 1:1 mapping
+ * of canvas pixels to game size.
+ * 
+ * You can also have the game canvas automatically centered. Again, this relies heavily on the parent being
+ * properly configured and styled, as the centering offsets are based entirely on the available space
+ * within the parent element. Please see the centering options for details.
  *
  * @class ScaleManager
  * @memberof Phaser.Scale
@@ -349,8 +391,6 @@ var ScaleManager = new Class({
 
         if (this.scaleMode === CONST.SCALE_MODE.NONE)
         {
-            console.log('NONE');
-
             this.resize(this.width, this.height);
         }
         else
@@ -360,9 +400,6 @@ var ScaleManager = new Class({
             //  Only set the parent bounds if the parent has an actual size
             if (this.parentSize.width > 0 && this.parentSize.height > 0)
             {
-                console.log('display parent set >>');
-                console.log(this.parentSize.toString());
-
                 this.displaySize.setParent(this.parentSize);
             }
 
@@ -513,8 +550,6 @@ var ScaleManager = new Class({
 
             if (this.parentIsWindow || DOMRect.height === 0)
             {
-                console.log('expanded');
-
                 document.documentElement.style.height = '100%';
                 document.body.style.height = '100%';
 
@@ -524,7 +559,6 @@ var ScaleManager = new Class({
                 //  has been set on it even though we fixed the body :(
                 if (!this.parentIsWindow && DOMRect.height === 0)
                 {
-                    console.log('dead div parent');
                     this.parent.style.overflow = 'hidden';
                     this.parent.style.width = '100%';
                     this.parent.style.height = '100%';
@@ -571,8 +605,6 @@ var ScaleManager = new Class({
 
         if (parentSize.width !== newWidth || parentSize.height !== newHeight)
         {
-            console.log(parentSize.toString());
-
             parentSize.setSize(newWidth, newHeight);
 
             return true;
@@ -982,8 +1014,6 @@ var ScaleManager = new Class({
         var offsetX = Math.floor((this.parentSize.width - width) / 2);
         var offsetY = Math.floor((this.parentSize.height - height) / 2);
 
-        console.log('cen', offsetX, offsetY);
-
         if (autoCenter === CONST.CENTER.CENTER_HORIZONTALLY)
         {
             offsetY = 0;
@@ -1087,9 +1117,6 @@ var ScaleManager = new Class({
 
         if (!fullscreen.active)
         {
-            console.log('fullscreen init');
-            console.log(this.parentSize.toString());
-
             var fsTarget = this.getFullscreenTarget();
 
             if (fullscreen.keyboard)
@@ -1101,12 +1128,8 @@ var ScaleManager = new Class({
                 fsTarget[fullscreen.request](fullscreenOptions);
             }
 
-            console.log('fullscreen done');
-
             this.getParentBounds();
 
-            console.log(this.parentSize.toString());
-
             this.refresh();
 
             this.emit(Events.ENTER_FULLSCREEN);

src/tilemaps/dynamiclayer/DynamicTilemapLayer.js

@@ -497,14 +497,6 @@ var DynamicTilemapLayer = new Class({
         return this;
     },
 
-    /**
-     * @typedef {object} FilteringOptions
-     * 
-     * @property {boolean} [isNotEmpty=false] - If true, only return tiles that don't have -1 for an index.
-     * @property {boolean} [isColliding=false] - If true, only return tiles that collide on at least one side.
-     * @property {boolean} [hasInterestingFace=false] - If true, only return tiles that have at least one interesting face.
-     */
-
     /**
      * For each tile in the given rectangular area (in tile coordinates) of the layer, run the given
      * filter callback function. Any tiles that pass the filter test (i.e. where the callback returns
@@ -858,14 +850,6 @@ var DynamicTilemapLayer = new Class({
         return TilemapComponents.RemoveTileAtWorldXY(worldX, worldY, replaceWithNull, recalculateFaces, camera, this.layer);
     },
 
-    /**
-     * @typedef {object} StyleConfig
-     * 
-     * @property {?Color} [tileColor=blue] - Color to use for drawing a filled rectangle at non-colliding tile locations. If set to null, non-colliding tiles will not be drawn.
-     * @property {?Color} [collidingTileColor=orange] - Color to use for drawing a filled rectangle at colliding tile locations. If set to null, colliding tiles will not be drawn.
-     * @property {?Color} [faceColor=grey] - Color to use for drawing a line at interesting tile faces. If set to null, interesting tile faces will not be drawn.
-     */
-
     /**
      * Draws a debug representation of the layer to the given Graphics. This is helpful when you want to
      * get a quick idea of which of your tiles are colliding and which have interesting faces. The tiles

src/tilemaps/staticlayer/StaticTilemapLayer.js

@@ -928,14 +928,6 @@ var StaticTilemapLayer = new Class({
         return TilemapComponents.FindByIndex(findIndex, skip, reverse, this.layer);
     },
 
-    /**
-     * @typedef {object} FilteringOptions
-     * 
-     * @property {boolean} [isNotEmpty=false] - If true, only return tiles that don't have -1 for an index.
-     * @property {boolean} [isColliding=false] - If true, only return tiles that collide on at least one side.
-     * @property {boolean} [hasInterestingFace=false] - If true, only return tiles that have at least one interesting face.
-     */
-
     /**
      * Find the first tile in the given rectangular area (in tile coordinates) of the layer that
      * satisfies the provided testing function. I.e. finds the first tile for which `callback` returns
@@ -1140,14 +1132,6 @@ var StaticTilemapLayer = new Class({
         return TilemapComponents.HasTileAtWorldXY(worldX, worldY, camera, this.layer);
     },
 
-    /**
-     * @typedef {object} StyleConfig
-     * 
-     * @property {?Color} [tileColor=blue] - Color to use for drawing a filled rectangle at non-colliding tile locations. If set to null, non-colliding tiles will not be drawn.
-     * @property {?Color} [collidingTileColor=orange] - Color to use for drawing a filled rectangle at colliding tile locations. If set to null, colliding tiles will not be drawn.
-     * @property {?Color} [faceColor=grey] - Color to use for drawing a line at interesting tile faces. If set to null, interesting tile faces will not be drawn.
-     */
-
     /**
      * Draws a debug representation of the layer to the given Graphics. This is helpful when you want to
      * get a quick idea of which of your tiles are colliding and which have interesting faces. The tiles

src/utils/array/StableSort.js

@@ -7,6 +7,10 @@
 //! stable.js 0.1.6, https://github.com/Two-Screen/stable
 //! © 2017 Angry Bytes and contributors. MIT licensed.
 
+/**
+ * @namespace Phaser.Utils.Array.StableSortFunctions
+ */
+
 (function() {
 
  /**
@@ -28,7 +32,8 @@ var stable = function(arr, comp) {
  /**
  * Sort the input array and simply copy it back if the result isn't in the original array, which happens on an odd number of passes.
  *
- * @function Phaser.Utils.Array.StableSort.inplace
+ * @function Phaser.Utils.Array.StableSortFunctions.inplace
+ * @memberof Phaser.Utils.Array.StableSortFunctions
  * @since 3.0.0
  *
  * @param {array} arr - The input array.