Merge pull request phaserjs#4563 from samme/types/tween-configs

Add types for tween configs

Author: photonstorm

src/gameobjects/components/PathFollower.js

@@ -108,7 +108,7 @@ var PathFollower = {
      * @since 3.0.0
      *
      * @param {Phaser.Curves.Path} path - The Path this PathFollower is following. It can only follow one Path at a time.
-     * @param {Phaser.Types.GameObjects.PathFollower.PathConfig} [config] - Settings for the PathFollower.
+     * @param {(number|Phaser.Types.GameObjects.PathFollower.PathConfig|Phaser.Types.Tweens.NumberTweenBuilderConfig)} [config] - Settings for the PathFollower.
      *
      * @return {Phaser.GameObjects.PathFollower} This Game Object.
      */
@@ -178,7 +178,7 @@ var PathFollower = {
      * @method Phaser.GameObjects.Components.PathFollower#startFollow
      * @since 3.3.0
      *
-     * @param {(number|Phaser.Types.GameObjects.PathFollower.PathConfig)} [config={}] - The duration of the follow, or a PathFollower config object.
+     * @param {(number|Phaser.Types.GameObjects.PathFollower.PathConfig|Phaser.Types.Tweens.NumberTweenBuilderConfig)} [config={}] - The duration of the follow, or a PathFollower config object.
      * @param {number} [startAt=0] - Optional start position of the follow, between 0 and 1.
      *
      * @return {Phaser.GameObjects.PathFollower} This Game Object.

src/gameobjects/pathfollower/typedefs/PathConfig.js

@@ -4,7 +4,7 @@
  * @typedef {object} Phaser.Types.GameObjects.PathFollower.PathConfig
  * @since 3.0.0
  *
- * @property {number} duration - The duration of the path follow in ms. Must be `> 0`.
+ * @property {number} [duration=1000] - The duration of the path follow in ms. Must be `> 0`.
  * @property {number} [from=0] - The start position of the path follow, between 0 and 1. Must be less than `to`.
  * @property {number} [to=1] - The end position of the path follow, between 0 and 1. Must be more than `from`.
  * @property {boolean} [positionOnPath=false] - Whether to position the PathFollower on the Path using its path offset.

src/tweens/TweenManager.js

@@ -193,7 +193,7 @@ var TweenManager = new Class({
      * @method Phaser.Tweens.TweenManager#create
      * @since 3.0.0
      *
-     * @param {object} config - The configuration object for the Tween as per {@link Phaser.Tweens.Builders.TweenBuilder}.
+     * @param {Phaser.Types.Tweens.TweenBuilderConfig|object} config - The configuration object for the Tween.
      *
      * @return {Phaser.Tweens.Tween} The created Tween object.
      */
@@ -208,7 +208,7 @@ var TweenManager = new Class({
      * @method Phaser.Tweens.TweenManager#add
      * @since 3.0.0
      *
-     * @param {object} config - The configuration object for the Tween as per the {@link Phaser.Tweens.Builders.TweenBuilder}.
+     * @param {Phaser.Types.Tweens.TweenBuilderConfig|object} config - The configuration object for the Tween.
      *
      * @return {Phaser.Tweens.Tween} The created Tween.
      */
@@ -243,12 +243,12 @@ var TweenManager = new Class({
     },
 
     /**
-     * Create a Tween and add it to the active Tween list.
+     * Create a Number Tween and add it to the active Tween list.
      *
      * @method Phaser.Tweens.TweenManager#addCounter
      * @since 3.0.0
      *
-     * @param {object} config - The configuration object for the Number Tween as per the {@link Phaser.Tweens.Builders.NumberTweenBuilder}.
+     * @param {Phaser.Types.Tweens.NumberTweenBuilderConfig} config - The configuration object for the Number Tween.
      *
      * @return {Phaser.Tweens.Tween} The created Number Tween.
      */

src/tweens/builders/NumberTweenBuilder.js

@@ -15,16 +15,16 @@ var Tween = require('../tween/Tween');
 var TweenData = require('../tween/TweenData');
 
 /**
- * [description]
+ * Creates a new Number Tween.
  *
  * @function Phaser.Tweens.Builders.NumberTweenBuilder
  * @since 3.0.0
  *
- * @param {(Phaser.Tweens.TweenManager|Phaser.Tweens.Timeline)} parent - [description]
- * @param {object} config - [description]
- * @param {Phaser.Types.Tweens.TweenConfigDefaults} defaults - [description]
+ * @param {(Phaser.Tweens.TweenManager|Phaser.Tweens.Timeline)} parent - The owner of the new Tween.
+ * @param {Phaser.Types.Tweens.NumberTweenBuilderConfig} config - Configuration for the new Tween.
+ * @param {Phaser.Types.Tweens.TweenConfigDefaults} defaults - Tween configuration defaults.
  *
- * @return {Phaser.Tweens.Tween} [description]
+ * @return {Phaser.Tweens.Tween} The new tween.
  */
 var NumberTweenBuilder = function (parent, config, defaults)
 {

src/tweens/builders/TweenBuilder.js

@@ -17,42 +17,16 @@ var Tween = require('../tween/Tween');
 var TweenData = require('../tween/TweenData');
 
 /**
- * [description]
+ * Creates a new Tween.
  *
  * @function Phaser.Tweens.Builders.TweenBuilder
  * @since 3.0.0
  *
- * @param {(Phaser.Tweens.TweenManager|Phaser.Tweens.Timeline)} parent - [description]
- * @param {object} config - [description]
+ * @param {(Phaser.Tweens.TweenManager|Phaser.Tweens.Timeline)} parent - The owner of the new Tween.
+ * @param {Phaser.Types.Tweens.TweenBuilderConfig|object} config - Configuration for the new Tween.
  * @param {Phaser.Types.Tweens.TweenConfigDefaults} defaults - Tween configuration defaults.
-`
- * @property {(object|object[])} targets - The object, or an array of objects, to run the tween on.
- * @property {number} [delay=0] - The number of milliseconds to delay before the tween will start.
- * @property {number} [duration=1000] - The duration of the tween in milliseconds.
- * @property {string} [ease='Power0'] - The easing equation to use for the tween.
- * @property {array} [easeParams] - Optional easing parameters.
- * @property {number} [hold=0] - The number of milliseconds to hold the tween for before yoyo'ing.
- * @property {number} [repeat=0] - The number of times to repeat the tween.
- * @property {number} [repeatDelay=0] - The number of milliseconds to pause before a tween will repeat.
- * @property {boolean} [yoyo=false] - Should the tween complete, then reverse the values incrementally to get back to the starting tween values? The reverse tweening will also take `duration` milliseconds to complete.
- * @property {boolean} [flipX=false] - Horizontally flip the target of the Tween when it completes (before it yoyos, if set to do so). Only works for targets that support the `flipX` property.
- * @property {boolean} [flipY=false] - Vertically flip the target of the Tween when it completes (before it yoyos, if set to do so). Only works for targets that support the `flipY` property.
-`
-{
-    targets: null,
-    delay: 0,
-    duration: 1000,
-    ease: 'Power0',
-    easeParams: null,
-    hold: 0,
-    repeat: 0,
-    repeatDelay: 0,
-    yoyo: false,
-    flipX: false,
-    flipY: false
-};
  *
- * @return {Phaser.Tweens.Tween} [description]
+ * @return {Phaser.Tweens.Tween} The new tween.
  */
 var TweenBuilder = function (parent, config, defaults)
 {

src/tweens/tween/Tween.js

@@ -1423,7 +1423,7 @@ Tween.TYPES = [
  * @method Phaser.GameObjects.GameObjectFactory#tween
  * @since 3.0.0
  *
- * @param {object} config - The Tween configuration.
+ * @param {Phaser.Types.Tweens.TweenBuilderConfig|object} config - The Tween configuration.
  *
  * @return {Phaser.Tweens.Tween} The Tween that was created.
  */
@@ -1448,7 +1448,7 @@ GameObjectFactory.register('tween', function (config)
  * @method Phaser.GameObjects.GameObjectCreator#tween
  * @since 3.0.0
  *
- * @param {object} config - The Tween configuration.
+ * @param {Phaser.Types.Tweens.TweenBuilderConfig|object} config - The Tween configuration.
  *
  * @return {Phaser.Tweens.Tween} The Tween that was created.
  */

src/tweens/typedefs/NumberTweenBuilderConfig.js

@@ -0,0 +1,40 @@
+/**
+ * @typedef {object} Phaser.Types.Tweens.NumberTweenBuilderConfig
+ * @since 3.18.0
+ *
+ * @property {number} [from=0] - The start number.
+ * @property {number} [to=1] - The end number.
+ * @property {number} [delay=0] - The number of milliseconds to delay before the tween will start.
+ * @property {number} [duration=1000] - The duration of the tween in milliseconds.
+ * @property {string} [ease='Power0'] - The easing equation to use for the tween.
+ * @property {array} [easeParams] - Optional easing parameters.
+ * @property {number} [hold=0] - The number of milliseconds to hold the tween for before yoyo'ing.
+ * @property {number} [repeat=0] - The number of times to repeat the tween.
+ * @property {number} [repeatDelay=0] - The number of milliseconds to pause before a tween will repeat.
+ * @property {boolean} [yoyo=false] - Should the tween complete, then reverse the values incrementally to get back to the starting tween values? The reverse tweening will also take `duration` milliseconds to complete.
+ * @property {number|function|object|array} [offset=null] - Used when the Tween is part of a Timeline.
+ * @property {number|function|object|array} [completeDelay=0] - The time the tween will wait before the onComplete event is dispatched once it has completed, in ms.
+ * @property {number|function|object|array} [loop=0] - The number of times the tween will repeat. (A value of 1 means the tween will play twice, as it repeated once.) The first loop starts after every property tween has completed once.
+ * @property {number|function|object|array} [loopDelay=0] - The time the tween will pause before starting either a yoyo or returning to the start for a repeat.
+ * @property {boolean} [paused=false] - Does the tween start in a paused state (true) or playing (false)?
+ * @property {boolean} [useFrames=false] - Use frames or milliseconds?
+ * @property {any} [callbackScope] - Scope (this) for the callbacks. The default scope is the tween.
+ * @property {Phaser.Types.Tweens.TweenOnCompleteCallback} [onComplete] - A function to call when the tween completes.
+ * @property {array} [onCompleteParams] - Additional parameters to pass to `onComplete`.
+ * @property {any} [onCompleteScope] - Scope (this) for `onComplete`.
+ * @property {Phaser.Types.Tweens.TweenOnLoopCallback} [onLoop] - A function to call each time the tween loops.
+ * @property {array} [onLoopParams] - Additional parameters to pass to `onLoop`.
+ * @property {any} [onLoopScope] - Scope (this) for `onLoop`.
+ * @property {Phaser.Types.Tweens.TweenOnRepeatCallback} [onRepeat] - A function to call each time the tween repeats. Called once per property per target.
+ * @property {array} [onRepeatParams] - Additional parameters to pass to `onRepeat`.
+ * @property {any} [onRepeatScope] - Scope (this) for `onRepeat`.
+ * @property {Phaser.Types.Tweens.TweenOnStartCallback} [onStart] - A function to call when the tween starts.
+ * @property {array} [onStartParams] - Additional parameters to pass to `onStart`.
+ * @property {any} [onStartScope] - Scope (this) for `onStart`.
+ * @property {Phaser.Types.Tweens.TweenOnUpdateCallback} [onUpdate] - A function to call each time the tween steps. Called once per property per target.
+ * @property {array} [onUpdateParams] - Additional parameters to pass to `onUpdate`.
+ * @property {any} [onUpdateScope] - Scope (this) for `onUpdate`.
+ * @property {Phaser.Types.Tweens.TweenOnYoyoCallback} [onYoyo] - A function to call each time the tween yoyos. Called once per property per target.
+ * @property {array} [onYoyoParams] - Additional parameters to pass to `onYoyo`.
+ * @property {any} [onYoyoScope] - Scope (this) for `onYoyo`.
+ */

src/tweens/typedefs/TweenBuilderConfig.js

@@ -0,0 +1,57 @@
+/**
+ * @typedef {object} Phaser.Types.Tweens.TweenBuilderConfig
+ * @since 3.18.0
+ *
+ * @property {any} targets - The object, or an array of objects, to run the tween on.
+ * @property {number} [delay=0] - The number of milliseconds to delay before the tween will start.
+ * @property {number} [duration=1000] - The duration of the tween in milliseconds.
+ * @property {string} [ease='Power0'] - The easing equation to use for the tween.
+ * @property {array} [easeParams] - Optional easing parameters.
+ * @property {number} [hold=0] - The number of milliseconds to hold the tween for before yoyo'ing.
+ * @property {number} [repeat=0] - The number of times each property tween repeats.
+ * @property {number} [repeatDelay=0] - The number of milliseconds to pause before a repeat.
+ * @property {boolean} [yoyo=false] - Should the tween complete, then reverse the values incrementally to get back to the starting tween values? The reverse tweening will also take `duration` milliseconds to complete.
+ * @property {boolean} [flipX=false] - Horizontally flip the target of the Tween when it completes (before it yoyos, if set to do so). Only works for targets that support the `flipX` property.
+ * @property {boolean} [flipY=false] - Vertically flip the target of the Tween when it completes (before it yoyos, if set to do so). Only works for targets that support the `flipY` property.
+ * @property {number|function|object|array} [offset=null] - Used when the Tween is part of a Timeline.
+ * @property {number|function|object|array} [completeDelay=0] - The time the tween will wait before the onComplete event is dispatched once it has completed, in ms.
+ * @property {number|function|object|array} [loop=0] - The number of times the tween will repeat. (A value of 1 means the tween will play twice, as it repeated once.) The first loop starts after every property tween has completed once.
+ * @property {number|function|object|array} [loopDelay=0] - The time the tween will pause before starting either a yoyo or returning to the start for a repeat.
+ * @property {boolean} [paused=false] - Does the tween start in a paused state (true) or playing (false)?
+ * @property {object} [props] - The properties to tween.
+ * @property {boolean} [useFrames=false] - Use frames or milliseconds?
+ * @property {any} [callbackScope] - Scope (this) for the callbacks. The default scope is the tween.
+ * @property {Phaser.Types.Tweens.TweenOnCompleteCallback} [onComplete] - A function to call when the tween completes.
+ * @property {array} [onCompleteParams] - Additional parameters to pass to `onComplete`.
+ * @property {any} [onCompleteScope] - Scope (this) for `onComplete`.
+ * @property {Phaser.Types.Tweens.TweenOnLoopCallback} [onLoop] - A function to call each time the tween loops.
+ * @property {array} [onLoopParams] - Additional parameters to pass to `onLoop`.
+ * @property {any} [onLoopScope] - Scope (this) for `onLoop`.
+ * @property {Phaser.Types.Tweens.TweenOnRepeatCallback} [onRepeat] - A function to call each time the tween repeats. Called once per property per target.
+ * @property {array} [onRepeatParams] - Additional parameters to pass to `onRepeat`.
+ * @property {any} [onRepeatScope] - Scope (this) for `onRepeat`.
+ * @property {Phaser.Types.Tweens.TweenOnStartCallback} [onStart] - A function to call when the tween starts.
+ * @property {array} [onStartParams] - Additional parameters to pass to `onStart`.
+ * @property {any} [onStartScope] - Scope (this) for `onStart`.
+ * @property {Phaser.Types.Tweens.TweenOnUpdateCallback} [onUpdate] - A function to call each time the tween steps. Called once per property per target.
+ * @property {array} [onUpdateParams] - Additional parameters to pass to `onUpdate`.
+ * @property {any} [onUpdateScope] - Scope (this) for `onUpdate`.
+ * @property {Phaser.Types.Tweens.TweenOnYoyoCallback} [onYoyo] - A function to call each time the tween yoyos. Called once per property per target.
+ * @property {array} [onYoyoParams] - Additional parameters to pass to `onYoyo`.
+ * @property {any} [onYoyoScope] - Scope (this) for `onYoyo`.
+ *
+ * @example
+ * {
+ *   targets: null,
+ *   delay: 0,
+ *   duration: 1000,
+ *   ease: 'Power0',
+ *   easeParams: null,
+ *   hold: 0,
+ *   repeat: 0,
+ *   repeatDelay: 0,
+ *   yoyo: false,
+ *   flipX: false,
+ *   flipY: false
+ * };
+ */

src/tweens/typedefs/TweenOnCompleteCallback.js

@@ -0,0 +1,8 @@
+/**
+ * @callback Phaser.Types.Tweens.TweenOnCompleteCallback
+ * @since 3.18.0
+ *
+ * @param {Phaser.Tweens.Tween} tween - The tween.
+ * @param {array} targets - The tween targets.
+ * @param {...any} param - Any value passed in `onCompleteParams`.
+ */

src/tweens/typedefs/TweenOnLoopCallback.js

@@ -0,0 +1,8 @@
+/**
+ * @callback Phaser.Types.Tweens.TweenOnLoopCallback
+ * @since 3.18.0
+ *
+ * @param {Phaser.Tweens.Tween} tween - The tween.
+ * @param {array} targets - The tween targets.
+ * @param {...any} param - Any value passed in `onLoopParams`.
+ */