Updated docs and destroy properties

Author: photonstorm

CHANGELOG.md

@@ -55,6 +55,7 @@ Please see the complete JSDocs for the ScenePlugin for more details, as well as
 * When shutting down a Scene all Game Objects that belong to the scene will now automatically destroy themselves. They would previously be removed from the display and update lists, but the objects themselves didn't self-destruct. You can control this on a per-object basis with the `ignoreDestroy` property.
 * A Matter Mouse Spring will disable debug draw of its constraint by default (you can override it by passing in your own config)
 * The RandomDataGenerator class is now exposed under Phaser.Math should you wish to instantiate it yourself. Fix #3576 (thanks @wtravO)
+* Refined the Game.destroy sequence, so it will now only destroy the game at the start of the next frame, not during processing.
 
 ### Examples, Documentation and TypeScript
 

src/boot/Game.js

@@ -243,7 +243,7 @@ var Game = new Class({
         this.onStepCallback = NOOP;
 
         /**
-         * Is this Game pending destroy at the end of the next frame?
+         * Is this Game pending destruction at the start of the next frame?
          *
          * @name Phaser.Game#pendingDestroy
          * @type {boolean}
@@ -552,17 +552,19 @@ var Game = new Class({
     },
 
     /**
-     * Destroys this Phaser.Game instance, all global systems, all sub-systems and all Scenes.
+     * Flags this Game instance as needing to be destroyed on the next frame.
+     * It will wait until the current frame has completed and then call `runDestroy` internally.
      *
      * @method Phaser.Game#destroy
      * @since 3.0.0
+     *
+     * @param {boolean} removeCanvas - Set to `true` if you would like the parent canvas element removed from the DOM, or `false` to leave it in place.
      */
     destroy: function (removeCanvas)
     {
         this.pendingDestroy = true;
-        this.removeCanvas = removeCanvas;
 
-        this.loop.stop();
+        this.removeCanvas = removeCanvas;
     },
 
     /**