Lots more jsdoc fixes and new documentation

photonstorm · photonstorm · commit 348306cafb1e · 2019-01-31T14:47:50.000Z
diff --git a/src/animations/Animation.js b/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]
diff --git a/src/animations/typedefs/Animation.js b/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.
diff --git a/src/animations/typedefs/AnimationFrame.js b/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]
diff --git a/src/animations/typedefs/JSONAnimation.js b/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?
diff --git a/src/animations/typedefs/JSONAnimationFrame.js b/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.
diff --git a/src/animations/typedefs/index.js b/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
+ */
diff --git a/src/display/color/Interpolate.js b/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.
diff --git a/src/display/color/index.js b/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.
diff --git a/src/display/index.js b/src/display/index.js
@@ -15,5 +15,5 @@ module.exports = {
     Canvas: require('./canvas'),
     Color: require('./color'),
     Masks: require('./mask')
-  
+
 };
diff --git a/src/gameobjects/blitter/Blitter.js b/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?
diff --git a/src/gameobjects/graphics/Commands.js b/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,
diff --git a/src/gameobjects/text/static/Text.js b/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);
diff --git a/src/input/InputPluginCache.js b/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.
diff --git a/src/scale/ScaleManager.js b/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);
diff --git a/src/tilemaps/dynamiclayer/DynamicTilemapLayer.js b/src/tilemaps/dynamiclayer/DynamicTilemapLayer.js
diff --git a/src/tilemaps/staticlayer/StaticTilemapLayer.js b/src/tilemaps/staticlayer/StaticTilemapLayer.js
diff --git a/src/utils/array/StableSort.js b/src/utils/array/StableSort.js

Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@ var GetValue = require('../utils/object/GetValue');`
`30`	`30`	`*`
`31`	`31`	`* @param {Phaser.Animations.AnimationManager} manager - A reference to the global Animation Manager`
`32`	`32`	`* @param {string} key - The unique identifying string for this animation.`
`33`		`- * @param {Phaser.Animations.Animation.Config} config - The Animation configuration.`
	`33`	`+ * @param {Phaser.Animations.Types.Animation} config - The Animation configuration.`
`34`	`34`	`*/`
`35`	`35`	`var Animation = new Class({`
`36`	`36`
`@@ -224,7 +224,7 @@ var Animation = new Class({`
`224`	`224`	`* @method Phaser.Animations.Animation#addFrame`
`225`	`225`	`* @since 3.0.0`
`226`	`226`	`*`
`227`		`- * @param {(string\|Phaser.Animations.AnimationFrame.Config[])} config - [description]`
	`227`	`+ * @param {(string\|Phaser.Animations.Types.AnimationFrame[])} config - [description]`
`228`	`228`	`*`
`229`	`229`	`* @return {Phaser.Animations.Animation} This Animation object.`
`230`	`230`	`*/`
`@@ -240,7 +240,7 @@ var Animation = new Class({`
`240`	`240`	`* @since 3.0.0`
`241`	`241`	`*`
`242`	`242`	`* @param {integer} index - The index to insert the frame at within the animation.`
`243`		`- * @param {(string\|Phaser.Animations.AnimationFrame.Config[])} config - [description]`
	`243`	`+ * @param {(string\|Phaser.Animations.Types.AnimationFrame[])} config - [description]`
`244`	`244`	`*`
`245`	`245`	`* @return {Phaser.Animations.Animation} This Animation object.`
`246`	`246`	`*/`
`@@ -353,7 +353,7 @@ var Animation = new Class({`
`353`	`353`	`* @since 3.0.0`
`354`	`354`	`*`
`355`	`355`	`* @param {Phaser.Textures.TextureManager} textureManager - [description]`
`356`		`- * @param {(string\|Phaser.Animations.AnimationFrame.Config[])} frames - [description]`
	`356`	`+ * @param {(string\|Phaser.Animations.Types.AnimationFrame[])} frames - [description]`
`357`	`357`	`* @param {string} [defaultTextureKey] - [description]`
`358`	`358`	`*`
`359`	`359`	`* @return {Phaser.Animations.AnimationFrame[]} [description]`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/**`
`2`		`- * @typedef {object} Phaser.Animations.AnimationFrame.Config`
	`2`	`+ * @typedef {object} Phaser.Animations.Types.AnimationFrame`
`3`	`3`	`*`
`4`	`4`	`* @property {string} key - The key that the animation will be associated with. i.e. sprite.animations.play(key)`
`5`	`5`	`* @property {(string\|number)} frame - [description]`