Merge pull request phaserjs#3422 from orblazer/fix-types

Fix types and begin object TypeDef

Author: photonstorm

src/animations/Animation.js

@@ -8,6 +8,58 @@ var Class = require('../utils/Class');
 var Frame = require('./AnimationFrame');
 var GetValue = require('../utils/object/GetValue');
 
+/**
+ * @typedef {object} JSONAnimation
+ *
+ * @property {string} key - [description]
+ * @property {string} type - A frame based animation (as opposed to a bone based animation)
+ * @property {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.
+ * @property {boolean} skipMissedFrames - Skip frames if the time lags, or always advanced anyway?
+ * @property {integer} delay - Delay before starting playback (in seconds)
+ * @property {integer} repeat - Number of times to repeat the animation (-1 for infinity)
+ * @property {integer} repeatDelay - Delay before the repeat starts (in seconds)
+ * @property {boolean} yoyo - Should the animation yoyo? (reverse back down to the start) before repeating?
+ * @property {boolean} showOnStart - Should sprite.visible = true when the animation starts to play?
+ * @property {boolean} hideOnComplete - Should sprite.visible = false when the animation finishes?
+ */
+
+/**
+ * @typedef {object} AnimationFrameConfig
+ *
+ * @property {string} key - [description]
+ * @property {string|number} frame - [description]
+ * @property {float} [duration=0] - [description]
+ * @property {boolean} [visible] - [description]
+ * @property {function} [onUpdate] - [description]
+ */
+
+/**
+ * @typedef {object} AnimationConfig // TODO 19/03/2018 fix type
+ *
+ * @property {AnimationFrameConfig[]} [frames] - [description]
+ * @property {string} [defaultTextureKey=null] - [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.
+ * @property {boolean} [skipMissedFrames=true] - Skip frames if the time lags, or always advanced anyway?
+ * @property {integer} [delay=0] - Delay before starting playback (in seconds)
+ * @property {integer} [repeat=0] - Number of times to repeat the animation (-1 for infinity)
+ * @property {integer} [repeatDelay=0] - Delay before the repeat starts (in seconds)
+ * @property {boolean} [yoyo=false] - Should the animation yoyo? (reverse back down to the start) before repeating?
+ * @property {boolean} [showOnStart=false] - Should sprite.visible = true when the animation starts to play?
+ * @property {boolean} [hideOnComplete=false] - Should sprite.visible = false when the animation finishes?
+ * @property {object} [callbackScope] - [description]
+ * @property {boolean} [onStart=false] - [description]
+ * @property {array} [onStartParams] - [description]
+ * @property {boolean} [onRepeat=false] - [description]
+ * @property {array} [onRepeatParams] - [description]
+ * @property {boolean} [onUpdate=false] - [description]
+ * @property {array} [onUpdateParams] - [description]
+ * @property {boolean} [onComplete=false] - [description]
+ * @property {array} [onCompleteParams] - [description]
+ */
+
 /**
  * @classdesc
  * A Frame based Animation.
@@ -25,7 +77,7 @@ var GetValue = require('../utils/object/GetValue');
  *
  * @param {Phaser.Animations.AnimationManager} manager - [description]
  * @param {string} key - [description]
- * @param {object} config - [description]
+ * @param {AnimationConfig} config - [description]
  */
 var Animation = new Class({
 
@@ -65,7 +117,7 @@ var Animation = new Class({
          * Extract all the frame data into the frames array
          *
          * @name Phaser.Animations.Animation#frames
-         * @type {array}
+         * @type {Phaser.Animations.AnimationFrame[]}
          * @since 3.0.0
          */
         this.frames = this.getFrames(
@@ -290,11 +342,6 @@ var Animation = new Class({
         this.manager.on('resumeall', this.resume.bind(this));
     },
 
-    //  config = Array of Animation config objects, like:
-    //  [
-    //      { key: 'gems', frame: 'diamond0001', [duration], [visible], [onUpdate] }
-    //  ]
-
     //  Add frames to the end of the animation
 
     /**
@@ -303,7 +350,7 @@ var Animation = new Class({
      * @method Phaser.Animations.Animation#addFrame
      * @since 3.0.0
      *
-     * @param {string|object[]} config - [description]
+     * @param {string|AnimationFrameConfig[]} config - [description]
      *
      * @return {Phaser.Animations.Animation} This Animation object.
      */
@@ -312,11 +359,6 @@ var Animation = new Class({
         return this.addFrameAt(this.frames.length, config);
     },
 
-    //  config = Array of Animation config objects, like:
-    //  [
-    //      { key: 'gems', frame: 'diamond0001', [duration], [visible], [onUpdate] }
-    //  ]
-
     //  Add frame/s into the animation
 
     /**
@@ -326,7 +368,7 @@ var Animation = new Class({
      * @since 3.0.0
      *
      * @param {integer} index - [description]
-     * @param {string|object[]} config - [description]
+     * @param {string|AnimationFrameConfig[]} config - [description]
      *
      * @return {Phaser.Animations.Animation} This Animation object.
      */
@@ -436,20 +478,13 @@ var Animation = new Class({
      * @since 3.0.0
      *
      * @param {Phaser.Textures.TextureManager} textureManager - [description]
-     * @param {string|object[]} frames - [description]
+     * @param {string|AnimationFrameConfig[]} frames - [description]
      * @param {string} [defaultTextureKey] - [description]
      *
      * @return {Phaser.Animations.AnimationFrame[]} [description]
      */
     getFrames: function (textureManager, frames, defaultTextureKey)
     {
-        //      frames: [
-        //          { key: textureKey, frame: textureFrame },
-        //          { key: textureKey, frame: textureFrame, duration: float },
-        //          { key: textureKey, frame: textureFrame, onUpdate: function }
-        //          { key: textureKey, frame: textureFrame, visible: boolean }
-        //      ],
-
         var out = [];
         var prev;
         var animationFrame;
@@ -779,7 +814,7 @@ var Animation = new Class({
      * @method Phaser.Animations.Animation#toJSON
      * @since 3.0.0
      *
-     * @return {object} [description]
+     * @return {JSONAnimation} [description]
      */
     toJSON: function ()
     {

src/animations/AnimationFrame.js

@@ -6,6 +6,14 @@
 
 var Class = require('../utils/Class');
 
+/**
+ * @typedef {object} 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.
+ * @property {number} duration - Additional time (in ms) that this frame should appear for during playback.
+ */
+
 /**
  * @classdesc
  * A single frame in an Animation sequence.
@@ -151,8 +159,8 @@ var AnimationFrame = new Class({
      *
      * @method Phaser.Animations.AnimationFrame#toJSON
      * @since 3.0.0
-     * 
-     * @return {object} The AnimationFrame data.
+     *
+     * @return {JSONAnimationFrame} The AnimationFrame data.
      */
     toJSON: function ()
     {

src/animations/AnimationManager.js

@@ -11,22 +11,29 @@ var EventEmitter = require('eventemitter3');
 var GetValue = require('../utils/object/GetValue');
 var Pad = require('../utils/string/Pad');
 
+/**
+ * @typedef {object} JSONAnimationManager
+ *
+ * @property {JSONAnimation[]} anims - [description]
+ * @property {number} globalTimeScale - [description]
+ */
+
 /**
  * @classdesc
  * The Animation Manager.
- * 
+ *
  * Animations are managed by the global Animation Manager. This is a singleton class that is
  * responsible for creating and delivering animations and their corresponding data to all Game Objects.
  * Unlike plugins it is owned by the Game instance, not the Scene.
- * 
+ *
  * Sprites and other Game Objects get the data they need from the AnimationManager.
  *
  * @class AnimationManager
  * @extends EventEmitter
  * @memberOf Phaser.Animations
  * @constructor
  * @since 3.0.0
- * 
+ *
  * @param {Phaser.Game} game - [description]
  */
 var AnimationManager = new Class({
@@ -120,10 +127,10 @@ var AnimationManager = new Class({
      * @method Phaser.Animations.AnimationManager#add
      * @fires AddAnimationEvent
      * @since 3.0.0
-     * 
+     *
      * @param {string} key - [description]
      * @param {Phaser.Animations.Animation} animation - [description]
-     * 
+     *
      * @return {Phaser.Animations.AnimationManager} This Animation Manager.
      */
     add: function (key, animation)
@@ -149,9 +156,9 @@ var AnimationManager = new Class({
      * @method Phaser.Animations.AnimationManager#create
      * @fires AddAnimationEvent
      * @since 3.0.0
-     * 
-     * @param {object} config - [description]
-     * 
+     *
+     * @param {AnimationConfig} config - [description]
+     *
      * @return {Phaser.Animations.Animation} The Animation that was created.
      */
     create: function (config)
@@ -178,10 +185,10 @@ var AnimationManager = new Class({
      *
      * @method Phaser.Animations.AnimationManager#fromJSON
      * @since 3.0.0
-     * 
+     *
      * @param {string|object} data - [description]
      * @param {boolean} [clearCurrentAnimations=false] - [description]
-     * 
+     *
      * @return {Phaser.Animations.Animation[]} An array containing all of the Animation objects that were created as a result of this call.
      */
     fromJSON: function (data, clearCurrentAnimations)
@@ -227,7 +234,7 @@ var AnimationManager = new Class({
      *
      * @method Phaser.Animations.AnimationManager#generateFrameNames
      * @since 3.0.0
-     * 
+     *
      * @param {string} key - [description]
      * @param {object} config - [description]
      * @param {string} [config.prefix=''] - [description]
@@ -237,8 +244,8 @@ var AnimationManager = new Class({
      * @param {integer} [config.zeroPad=0] - [description]
      * @param {array} [config.outputArray=[]] - [description]
      * @param {boolean} [config.frames=false] - [description]
-     * 
-     * @return {object[]} [description]
+     *
+     * @return {AnimationFrameConfig[]} [description]
      */
     generateFrameNames: function (key, config)
     {
@@ -299,16 +306,16 @@ var AnimationManager = new Class({
      *
      * @method Phaser.Animations.AnimationManager#generateFrameNumbers
      * @since 3.0.0
-     * 
+     *
      * @param {string} key - [description]
      * @param {object} config - [description]
      * @param {integer} [config.start=0] - [description]
      * @param {integer} [config.end=-1] - [description]
      * @param {boolean} [config.first=false] - [description]
      * @param {array} [config.outputArray=[]] - [description]
      * @param {boolean} [config.frames=false] - [description]
-     * 
-     * @return {object[]} [description]
+     *
+     * @return {AnimationFrameConfig[]} [description]
      */
     generateFrameNumbers: function (key, config)
     {
@@ -369,9 +376,9 @@ var AnimationManager = new Class({
      *
      * @method Phaser.Animations.AnimationManager#get
      * @since 3.0.0
-     * 
+     *
      * @param {string} key - [description]
-     * 
+     *
      * @return {Phaser.Animations.Animation} [description]
      */
     get: function (key)
@@ -384,11 +391,11 @@ var AnimationManager = new Class({
      *
      * @method Phaser.Animations.AnimationManager#load
      * @since 3.0.0
-     * 
+     *
      * @param {Phaser.GameObjects.GameObject} child - [description]
      * @param {string} key - [description]
      * @param {string|integer} [startFrame] - [description]
-     * 
+     *
      * @return {Phaser.GameObjects.GameObject} [description]
      */
     load: function (child, key, startFrame)
@@ -409,7 +416,7 @@ var AnimationManager = new Class({
      * @method Phaser.Animations.AnimationManager#pauseAll
      * @fires PauseAllAnimationEvent
      * @since 3.0.0
-     * 
+     *
      * @return {Phaser.Animations.AnimationManager} This Animation Manager.
      */
     pauseAll: function ()
@@ -429,10 +436,10 @@ var AnimationManager = new Class({
      *
      * @method Phaser.Animations.AnimationManager#play
      * @since 3.0.0
-     * 
+     *
      * @param {string} key - [description]
      * @param {Phaser.GameObjects.GameObject} child - [description]
-     * 
+     *
      * @return {Phaser.Animations.AnimationManager} This Animation Manager.
      */
     play: function (key, child)
@@ -463,9 +470,9 @@ var AnimationManager = new Class({
      * @method Phaser.Animations.AnimationManager#remove
      * @fires RemoveAnimationEvent
      * @since 3.0.0
-     * 
+     *
      * @param {string} key - [description]
-     * 
+     *
      * @return {Phaser.Animations.Animation} [description]
      */
     remove: function (key)
@@ -488,7 +495,7 @@ var AnimationManager = new Class({
      * @method Phaser.Animations.AnimationManager#resumeAll
      * @fires ResumeAllAnimationEvent
      * @since 3.0.0
-     * 
+     *
      * @return {Phaser.Animations.AnimationManager} This Animation Manager.
      */
     resumeAll: function ()
@@ -508,11 +515,11 @@ var AnimationManager = new Class({
      *
      * @method Phaser.Animations.AnimationManager#staggerPlay
      * @since 3.0.0
-     * 
+     *
      * @param {string} key - [description]
      * @param {Phaser.GameObjects.GameObject} child - [description]
      * @param {number} [stagger=0] - [description]
-     * 
+     *
      * @return {Phaser.Animations.AnimationManager} This Animation Manager.
      */
     staggerPlay: function (key, child, stagger)
@@ -544,10 +551,10 @@ var AnimationManager = new Class({
      *
      * @method Phaser.Animations.AnimationManager#toJSON
      * @since 3.0.0
-     * 
+     *
      * @param {string} key - [description]
-     * 
-     * @return {object} [description]
+     *
+     * @return {JSONAnimationManager} [description]
      */
     toJSON: function (key)
     {