Merge branch 'master' of https://github.com/photonstorm/phaser

.eslintrc.json

@@ -9,7 +9,8 @@
         "WEBGL_RENDERER": true,
         "CANVAS_RENDERER": true,
         "Phaser": true,
-        "p2": true
+        "p2": true,
+        "ActiveXObject": true
     },
     "rules": {
 

src/dom/AddToDOM.js

@@ -1,14 +1,15 @@
 /**
- * [description]
+ * Adds the given element to the DOM. If a parent is provided the element is added as a child of the parent, providing it was able to access it.
+ * If no parent was given or falls back to using `document.body`.
  *
  * @function Phaser.Dom.AddToDOM
  * @since 3.0.0
  *
- * @param {any} element - [description]
- * @param {any} parent - [description]
+ * @param {object} element - The element to be added to the DOM. Usually a Canvas object.
+ * @param {string|object} [parent] - The parent in which to add the element. Can be a string which is passed to `getElementById` or an actual DOM object.
  * @param {boolean} [overflowHidden=true] - [description]
  *
- * @return {any} [description]
+ * @return {object} The element that was added to the DOM.
  */
 var AddToDOM = function (element, parent, overflowHidden)
 {

src/dom/DOMContentLoaded.js

@@ -3,7 +3,9 @@ var OS = require('../device/OS');
 var isBooted = false;
 
 /**
- * [description]
+ * Inspects the readyState of the document. If the document is already complete then it invokes the given callback.
+ * If not complete it sets up several event listeners such as `deviceready`, and once those fire, it invokes the callback.
+ * Called automatically by the Phaser.Game instance. Should not usually be access directly.
  *
  * @function Phaser.Dom.DOMContentLoaded
  * @since 3.0.0

src/dom/ParseXML.js

@@ -1,12 +1,14 @@
 /**
- * [description]
+ * Takes the given data string and parses it as XML.
+ * First tries to use the window.DOMParser and reverts to the Microsoft.XMLDOM if that fails.
+ * The parsed XML object is returned, or `null` if there was an error while parsing the data.
  *
  * @function Phaser.Dom.ParseXML
  * @since 3.0.0
  *
  * @param {string} data - The XML source stored in a string.
  *
- * @return {any} [description]
+ * @return {any} The parsed XML data, or `null` if the data could not be parsed.
  */
 var ParseXML = function (data)
 {

src/dom/RemoveFromDOM.js

@@ -1,10 +1,10 @@
 /**
- * [description]
+ * Attempts to remove the element from its parentNode in the DOM.
  *
  * @function Phaser.Dom.RemoveFromDOM
  * @since 3.0.0
  *
- * @param {any} element - [description]
+ * @param {any} element - The DOM element to remove from its parent node.
  */
 var RemoveFromDOM = function (element)
 {

src/dom/RequestAnimationFrame.js

@@ -1,67 +1,149 @@
+var Class = require('../utils/Class');
 var NOOP = require('../utils/NOOP');
 
-// Abstracts away the use of RAF or setTimeOut for the core game update loop.
-var RequestAnimationFrame = function ()
-{
-    // @property {boolean} isRunning - true if RequestAnimationFrame is running, otherwise false.
-    this.isRunning = false;
+var RequestAnimationFrame = new Class({
 
-    this.callback = NOOP;
+    initialize:
 
-    this.tick = 0;
-
-    // @property {boolean} isSetTimeOut  - True if the browser is using setTimeout instead of rAf.
-    this.isSetTimeOut = false;
-
-    // @property {number} timeOutID - The callback setTimeout or rAf callback ID used when calling cancel.
-    this.timeOutID = null;
-
-    var _this = this;
-
-    //  timestamp = DOMHighResTimeStamp
-    var step = function (timestamp)
+    /**
+     * Abstracts away the use of RAF or setTimeOut for the core game update loop.
+     * This is invoked automatically by the Phaser.Game instance.
+     *
+     * @class RequestAnimationFrame
+     * @memberOf Phaser.DOM
+     * @constructor
+     * @since 3.0.0
+     */
+    function RequestAnimationFrame ()
     {
-        _this.tick = timestamp;
+        /**
+         * True if RequestAnimationFrame is running, otherwise false.
+         *
+         * @property {boolean} isRunning
+         * @default false
+         * @since 3.0.0
+         */
+        this.isRunning = false;
 
-        _this.callback(timestamp);
+        /**
+         * The callback to be invoked each step.
+         *
+         * @property {function} callback
+         * @since 3.0.0
+         */
+        this.callback = NOOP;
 
-        _this.timeOutID = window.requestAnimationFrame(step);
-    };
+        /**
+         * The most recent timestamp. Either a DOMHighResTimeStamp under RAF or `Date.now` under SetTimeout.
+         *
+         * @property {DOMHighResTimeStamp|number} tick
+         * @default 0
+         * @since 3.0.0
+         */
+        this.tick = 0;
 
-    var stepTimeout = function ()
-    {
-        var d = Date.now();
+        /**
+         * True if the step is using setTimeout instead of RAF.
+         *
+         * @property {boolean} isSetTimeOut
+         * @default false
+         * @since 3.0.0
+         */
+        this.isSetTimeOut = false;
 
-        _this.tick = d;
+        /**
+         * The setTimeout or RAF callback ID used when canceling them.
+         *
+         * @property {?number} timeOutID
+         * @default null
+         * @since 3.0.0
+         */
+        this.timeOutID = null;
 
-        _this.callback(d);
+        /**
+         * The previous time the step was called.
+         *
+         * @property {number} lastTime
+         * @default 0
+         * @since 3.0.0
+         */
+        this.lastTime = 0;
 
-        _this.timeOutID = window.setTimeout(stepTimeout, _this.timeToCall);
-    };
+        var _this = this;
 
-    this.step = step;
-    this.stepTimeout = stepTimeout;
-};
+        /**
+         * The RAF step function.
+         * Updates the local tick value, invokes the callback and schedules another call to requestAnimationFrame.
+         *
+         * @property {function} step
+         * @since 3.0.0
+         */
+        this.step = function step (timestamp)
+        {
+            // DOMHighResTimeStamp
+            _this.lastTime = _this.tick;
 
-RequestAnimationFrame.prototype.constructor = RequestAnimationFrame;
+            _this.tick = timestamp;
 
-RequestAnimationFrame.prototype = {
+            _this.callback(timestamp);
 
-    // Starts the requestAnimationFrame running or setTimeout if unavailable in browser
+            _this.timeOutID = window.requestAnimationFrame(step);
+        };
+
+        /**
+         * The SetTimeout step function.
+         * Updates the local tick value, invokes the callback and schedules another call to setTimeout.
+         *
+         * @property {function} stepTimeout
+         * @since 3.0.0
+         */
+        this.stepTimeout = function stepTimeout ()
+        {
+            var d = Date.now();
+
+            var delay = Math.max(16 + _this.lastTime - d, 0);
+
+            _this.lastTime = _this.tick;
+
+            _this.tick = d;
+
+            _this.callback(d);
+
+            _this.timeOutID = window.setTimeout(stepTimeout, delay);
+        };
+    },
+
+    /**
+     * Starts the requestAnimationFrame or setTimeout process running.
+     *
+     * @method Phaser.DOM.RequestAnimationFrame#start
+     * @since 3.0.0
+     *
+     * @param {function} callback - The callback to invoke each step.
+     * @param {boolean} forceSetTimeOut - Should it use SetTimeout, even if RAF is available?
+     */
     start: function (callback, forceSetTimeOut)
     {
+        if (this.isRunning)
+        {
+            return;
+        }
+
         this.callback = callback;
 
         this.isSetTimeOut = forceSetTimeOut;
 
         this.isRunning = true;
 
-        var _this = this;
-
-        this.timeOutID = (forceSetTimeOut) ? window.setTimeout(_this.stepTimeout, 0) : window.requestAnimationFrame(_this.step);
+        this.timeOutID = (forceSetTimeOut) ? window.setTimeout(this.stepTimeout, 0) : window.requestAnimationFrame(this.step);
     },
 
-    // Stops the requestAnimationFrame from running.
+    /**
+     * Stops the requestAnimationFrame or setTimeout from running.
+     *
+     * @method Phaser.DOM.RequestAnimationFrame#stop
+     * @since 3.0.0
+     */
     stop: function ()
     {
         this.isRunning = false;
@@ -76,6 +158,12 @@ RequestAnimationFrame.prototype = {
         }
     },
 
+    /**
+     * Stops the step from running and clears the callback reference.
+     *
+     * @method Phaser.DOM.RequestAnimationFrame#destroy
+     * @since 3.0.0
+     */
     destroy: function ()
     {
         this.stop();
@@ -83,6 +171,6 @@ RequestAnimationFrame.prototype = {
         this.callback = NOOP;
     }
 
-};
+});
 
 module.exports = RequestAnimationFrame;

src/events/EventEmitter.js

@@ -2,24 +2,43 @@ var Class = require('../utils/Class');
 var EE = require('eventemitter3');
 var PluginManager = require('../plugins/PluginManager');
 
-//  Phaser.EventEmitter
-
 var EventEmitter = new Class({
 
     Extends: EE,
 
     initialize:
 
+    /**
+     * EventEmitter is a Scene Systems plugin compatible version of eventemitter3.
+     *
+     * @class EventEmitter
+     * @extends eventemitter3
+     * @memberOf Phaser.Events
+     * @constructor
+     * @since 3.0.0
+     */
     function EventEmitter ()
     {
         EE.call(this);
     },
 
+    /**
+     * Removes all listeners.
+     *
+     * @method Phaser.Events.EventEmitter#shutdown
+     * @since 3.0.0
+     */
     shutdown: function ()
     {
         this.removeAllListeners();
     },
 
+    /**
+     * Removes all listeners.
+     *
+     * @method Phaser.Events.EventEmitter#destroy
+     * @since 3.0.0
+     */
     destroy: function ()
     {
         this.removeAllListeners();