Merge pull request phaserjs#4573 from samme/types/timeline-config

Add types for Timeline config

Author: photonstorm

src/tweens/Timeline.js

@@ -264,7 +264,7 @@ var Timeline = new Class({
     },
 
     /**
-     * Gets the value of the time scale applied to this Timeline. A value of 1 runs in real-time. A value of 0.5 runs 50% slower, and so on. 
+     * Gets the value of the time scale applied to this Timeline. A value of 1 runs in real-time. A value of 0.5 runs 50% slower, and so on.
      *
      * @method Phaser.Tweens.Timeline#getTimeScale
      * @since 3.0.0
@@ -290,12 +290,12 @@ var Timeline = new Class({
     },
 
     /**
-     * [description]
+     * Creates a new Tween and adds it to this Timeline.
      *
      * @method Phaser.Tweens.Timeline#add
      * @since 3.0.0
      *
-     * @param {object} config - [description]
+     * @param {(Phaser.Types.Tweens.TweenBuilderConfig|object)} config - The configuration object for the Tween.
      *
      * @return {Phaser.Tweens.Timeline} This Timeline object.
      */
@@ -305,12 +305,12 @@ var Timeline = new Class({
     },
 
     /**
-     * [description]
+     * Adds a Tween to this Timeline.
      *
      * @method Phaser.Tweens.Timeline#queue
      * @since 3.0.0
      *
-     * @param {Phaser.Tweens.Tween} tween - [description]
+     * @param {Phaser.Tweens.Tween} tween - The tween
      *
      * @return {Phaser.Tweens.Timeline} This Timeline object.
      */
@@ -330,14 +330,14 @@ var Timeline = new Class({
     },
 
     /**
-     * [description]
+     * Checks whether a tween has an offset value.
      *
      * @method Phaser.Tweens.Timeline#hasOffset
      * @since 3.0.0
      *
-     * @param {Phaser.Tweens.Tween} tween - [description]
+     * @param {Phaser.Tweens.Tween} tween - The tween
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if the tween has a non-null offset.
      */
     hasOffset: function (tween)
     {
@@ -604,12 +604,14 @@ var Timeline = new Class({
     },
 
     /**
-     * [description]
+     * Updates the Timeline's `state` and fires callbacks and events.
      *
      * @method Phaser.Tweens.Timeline#nextState
      * @fires Phaser.Tweens.Events#TIMELINE_COMPLETE
      * @fires Phaser.Tweens.Events#TIMELINE_LOOP
      * @since 3.0.0
+     *
+     * @see Phaser.Tweens.Timeline#update
      */
     nextState: function ()
     {
@@ -674,7 +676,7 @@ var Timeline = new Class({
      * @fires Phaser.Tweens.Events#TIMELINE_UPDATE
      * @since 3.0.0
      *
-     * @param {number} timestamp - [description]
+     * @param {number} timestamp - The current time. Either a High Resolution Timer value if it comes from Request Animation Frame, or Date.now if using SetTimeout.
      * @param {number} delta - The delta time in ms since the last frame. This is a smoothed and capped value based on the FPS rate.
      *
      * @return {boolean} Returns `true` if this Timeline has finished and should be removed from the Tween Manager.

src/tweens/TweenManager.js

@@ -154,7 +154,7 @@ var TweenManager = new Class({
      * @method Phaser.Tweens.TweenManager#createTimeline
      * @since 3.0.0
      *
-     * @param {object} config - The configuration object for the Timeline and its Tweens.
+     * @param {Phaser.Types.Tweens.TimelineBuilderConfig} config - The configuration object for the Timeline and its Tweens.
      *
      * @return {Phaser.Tweens.Timeline} The created Timeline object.
      */
@@ -169,7 +169,7 @@ var TweenManager = new Class({
      * @method Phaser.Tweens.TweenManager#timeline
      * @since 3.0.0
      *
-     * @param {object} config - The configuration object for the Timeline and its Tweens.
+     * @param {Phaser.Types.Tweens.TimelineBuilderConfig} config - The configuration object for the Timeline and its Tweens.
      *
      * @return {Phaser.Tweens.Timeline} The created Timeline object.
      */

src/tweens/builders/TimelineBuilder.js

@@ -19,40 +19,11 @@ var TweenBuilder = require('./TweenBuilder');
 /**
  * Builds a Timeline of Tweens based on a configuration object.
  *
- * The configuration object (`config`) can have the following properties:
- *
- * `tweens` - an array of tween configuration objects to create and add into the new Timeline, as described by `TweenBuilder`. If this doesn't exist or is empty, the Timeline will start off paused and none of the other configuration settings will be read. If it's a function, it will be called and its return value will be used as the array.
- * `targets` - an array (or function which returns one) of default targets to which to apply the Timeline. Each individual Tween configuration can override this value.
- * `totalDuration` - if specified, each Tween in the Timeline will get an equal portion of this duration, usually in milliseconds, by default. Each individual Tween configuration can override the Tween's duration.
- * `duration` - if `totalDuration` is not specified, the default duration, usually in milliseconds, of each Tween which will be created. Each individual Tween configuration can override the Tween's duration.
- * `delay`, `easeParams`, `ease`, `hold`, `repeat`, `repeatDelay`, `yoyo`, `flipX`, `flipY` - the default settings for each Tween which will be created, as specified by `TweenBuilder`. Each individual Tween configuration can override any of these values.
- * `completeDelay` - if specified, the time to wait, usually in milliseconds, before the Timeline completes.
- * `loop` - how many times the Timeline should loop, or -1 to loop indefinitely.
- * `loopDelay` - the time, usually in milliseconds, between each loop
- * `paused` - if `true`, the Timeline will start paused
- * `useFrames` - if `true`, all duration in the Timeline will be in frames instead of milliseconds
- * `callbackScope` - the default scope (`this` value) to use for each callback registered by the Timeline Builder. If not specified, the Timeline itself will be used.
- * `onStart` - if specified, the `onStart` callback for the Timeline, called every time it starts playing
- * `onStartScope` - the scope (`this` value) to use for the `onStart` callback. If not specified, the `callbackScope` will be used.
- * `onStartParams` - additional arguments to pass to the `onStart` callback. The Timeline will always be the first argument.
- * `onUpdate` - if specified, the `onUpdate` callback for the Timeline, called every frame it's active, regardless of its Tweens
- * `onUpdateScope` - the scope (`this` value) to use for the `onUpdate` callback. If not specified, the `callbackScope` will be used.
- * `onUpdateParams` - additional arguments to pass to the `onUpdate` callback. The Timeline will always be the first argument.
- * `onLoop` - if specified, the `onLoop` callback for the Timeline, called every time it loops
- * `onLoopScope` - the scope (`this` value) to use for the `onLoop` callback. If not specified, the `callbackScope` will be used.
- * `onLoopParams` - additional arguments to pass to the `onLoop` callback. The Timeline will always be the first argument.
- * `onYoyo` - if specified, the `onYoyo` callback for the Timeline, called every time it yoyos
- * `onYoyoScope` - the scope (`this` value) to use for the `onYoyo` callback. If not specified, the `callbackScope` will be used.
- * `onYoyoParams` - additional arguments to pass to the `onYoyo` callback. The first argument will always be `null`, while the Timeline will always be the second argument.
- * `onComplete` - if specified, the `onComplete` callback for the Timeline, called after it completes
- * `onCompleteScope` - the scope (`this` value) to use for the `onComplete` callback. If not specified, the `callbackScope` will be used.
- * `onCompleteParams` - additional arguments to pass to the `onComplete` callback. The Timeline will always be the first argument.
- *
  * @function Phaser.Tweens.Builders.TimelineBuilder
  * @since 3.0.0
  *
  * @param {Phaser.Tweens.TweenManager} manager - The Tween Manager to which the Timeline will belong.
- * @param {object} config - The configuration object for the Timeline, as described above.
+ * @param {Phaser.Types.Tweens.TimelineBuilderConfig} config - The configuration object for the Timeline.
  *
  * @return {Phaser.Tweens.Timeline} The created Timeline.
  */

src/tweens/tween/Tween.js

@@ -1261,7 +1261,7 @@ var Tween = new Class({
      * @param {Phaser.Types.Tweens.TweenDataConfig} tweenData - The TweenData property to update.
      * @param {number} delta - Either a value in ms, or 1 if Tween.useFrames is true
      *
-     * @return {boolean} [description]
+     * @return {boolean} True if the tween is not complete (e.g., playing), or false if the tween is complete.
      */
     updateTweenData: function (tween, tweenData, delta)
     {

src/tweens/typedefs/TimelineBuilderConfig.js

@@ -0,0 +1,7 @@
+/**
+ * @callback Phaser.Types.Tweens.TimelineOnCompleteCallback
+ * @since 3.18.0
+ *
+ * @param {Phaser.Tweens.Timeline} timeline - The timeline.
+ * @param {...any} param - Any value passed in `onCompleteParams`.
+ */

src/tweens/typedefs/TimelineOnCompleteCallback.js

@@ -0,0 +1,7 @@
+/**
+ * @callback Phaser.Types.Tweens.TimelineOnLoopCallback
+ * @since 3.18.0
+ *
+ * @param {Phaser.Tweens.Timeline} timeline - The timeline.
+ * @param {...any} param - Any value passed in `onLoopParams`.
+ */

src/tweens/typedefs/TimelineOnLoopCallback.js

@@ -0,0 +1,7 @@
+/**
+ * @callback Phaser.Types.Tweens.TimelineOnStartCallback
+ * @since 3.18.0
+ *
+ * @param {Phaser.Tweens.Timeline} timeline - The timeline.
+ * @param {...any} param - Any value passed in `onStartParams`.
+ */

src/tweens/typedefs/TimelineOnStartCallback.js

@@ -0,0 +1,7 @@
+/**
+ * @callback Phaser.Types.Tweens.TimelineOnUpdateCallback
+ * @since 3.18.0
+ *
+ * @param {Phaser.Tweens.Timeline} timeline - The timeline.
+ * @param {...any} param - Any value passed in `onUpdateParams`.
+ */

src/tweens/typedefs/TimelineOnUpdateCallback.js

@@ -0,0 +1,7 @@
+/**
+ * @callback Phaser.Types.Tweens.TimelineOnYoyoCallback
+ * @since 3.18.0
+ *
+ * @param {Phaser.Tweens.Timeline} timeline - The timeline.
+ * @param {...any} param - Any value passed in `onYoyoParams`.
+ */