Finished JSDocs

Author: photonstorm

src/gameobjects/domelement/DOMElement.js

@@ -14,7 +14,57 @@ var Vector4 = require('../../math/Vector4');
 
 /**
  * @classdesc
- * [description]
+ * DOM Element Game Objects are a way to control and manipulate HTML Elements over the top of your game.
+ * 
+ * In order for DOM Elements to display you have to enable them by adding the following to your game
+ * configuration object:
+ * 
+ * ```javascript
+ * dom {
+ *   createContainer: true
+ * }
+ * ```
+ * 
+ * When this is added, Phaser will automatically create a DOM Container div that is positioned over the top
+ * of the game canvas. This div is sized to match the canvas, and if the canvas size changes, as a result of
+ * settings within the Scale Manager, the dom container is resized accordingly.
+ * 
+ * You can create a DOM Element by either passing in DOMStrings, or by passing in a reference to an existing
+ * Element that you wish to be placed under the control of Phaser. For example:
+ * 
+ * ```javascript
+ * this.add.dom(x, y, 'div', 'background-color: lime; width: 220px; height: 100px; font: 48px Arial', 'Phaser');
+ * ```
+ * 
+ * The above code will insert a div element into the DOM Container at the given x/y coordinate. The DOMString in
+ * the 4th argument sets the initial CSS style of the div and the final argument is the inner text. In this case,
+ * it will create a lime colored div that is 220px by 100px in size with the text Phaser in it, in an Arial font.
+ * 
+ * You should nearly always, without exception, use explicitly sized HTML Elements, in order to fully control
+ * alignment and positioning of the elements next to regular game content.
+ * 
+ * Rather than specify the CSS and HTML directly you can use the `load.html` File Loader to load it into the
+ * cache and then use the `createFromCache` method instead. You can also use `createFromHTML` and various other
+ * methods available in this class to help construct your elements.
+ * 
+ * Once the element has been created you can then control it like you would any other Game Object. You can set its
+ * position, scale, rotation, alpha and other properties. It will move as the main Scene Camera moves and be clipped
+ * at the edge of the canvas. It's important to remember some limitations of DOM Elements: The obvious one is that
+ * they appear above or below your game canvas. You cannot blend them into the display list, meaning you cannot have
+ * a DOM Element, then a Sprite, then another DOM Element behind it.
+ * 
+ * They also cannot be enabled for input. To do that, you have to use the `addListener` method to add native event
+ * listeners directly. The final limitation is to do with cameras. The DOM Container is sized to match the game canvas
+ * entirely and clipped accordingly. DOM Elements respect camera scrolling and scrollFactor settings, but if you
+ * change the size of the camera so it no longer matches the size of the canvas, they won't be clipped accordingly.
+ * 
+ * Also, all DOM Elements are inserted into the same DOM Container, regardless of which Scene they are created in.
+ * 
+ * DOM Elements are a powerful way to align native HTML with your Phaser Game Objects. For example, you can insert
+ * a login form for a multiplayer game directly into your title screen. Or a text input box for a highscore table.
+ * Or a banner ad from a 3rd party service. Or perhaps you'd like to use them for high resolution text display and
+ * UI. The choice is up to you, just remember that you're dealing with standard HTML and CSS floating over the top
+ * of your game, and should treat it accordingly.
  *
  * @class DOMElement
  * @extends Phaser.GameObjects.GameObject

src/gameobjects/domelement/DOMElementCSSRenderer.js

@@ -20,8 +20,9 @@ var GameObject = require('../GameObject');
  * @param {Phaser.GameObjects.DOMElement} src - The Game Object being rendered in this call.
  * @param {number} interpolationPercentage - Reserved for future use and custom pipelines.
  * @param {Phaser.Cameras.Scene2D.Camera} camera - The Camera that is rendering the Game Object.
+ * @param {Phaser.GameObjects.Components.TransformMatrix} parentMatrix - This transform matrix is defined if the game object is nested
  */
-var DOMElementCSSRenderer = function (renderer, src, interpolationPercentage, camera, parentTransformMatrix)
+var DOMElementCSSRenderer = function (renderer, src, interpolationPercentage, camera, parentMatrix)
 {
     var node = src.node;
     var style = node.style;
@@ -54,7 +55,7 @@ var DOMElementCSSRenderer = function (renderer, src, interpolationPercentage, ca
     var tx = '0%';
     var ty = '0%';
 
-    if (parentTransformMatrix)
+    if (parentMatrix)
     {
         dx = (src.width * src.scaleX) * src.originX;
         dy = (src.height * src.scaleY) * src.originY;
@@ -64,7 +65,7 @@ var DOMElementCSSRenderer = function (renderer, src, interpolationPercentage, ca
         camMatrix.copyFrom(camera.matrix);
 
         //  Multiply the camera by the parent matrix
-        camMatrix.multiplyWithOffset(parentTransformMatrix, -camera.scrollX * src.scrollFactorX, -camera.scrollY * src.scrollFactorY);
+        camMatrix.multiplyWithOffset(parentMatrix, -camera.scrollX * src.scrollFactorX, -camera.scrollY * src.scrollFactorY);
 
         //  Undo the camera scroll
         srcMatrix.e = src.x - dx;

src/gameobjects/domelement/DOMElementFactory.js

@@ -8,9 +8,57 @@ var DOMElement = require('./DOMElement');
 var GameObjectFactory = require('../GameObjectFactory');
 
 /**
- * Creates a new DOM Element Game Object and adds it to the parent DOM Container.
+ * DOM Element Game Objects are a way to control and manipulate HTML Elements over the top of your game.
  * 
- * The game must have been configured with the `dom.createContainer` property set to `true` for this to work.
+ * In order for DOM Elements to display you have to enable them by adding the following to your game
+ * configuration object:
+ * 
+ * ```javascript
+ * dom {
+ *   createContainer: true
+ * }
+ * ```
+ * 
+ * When this is added, Phaser will automatically create a DOM Container div that is positioned over the top
+ * of the game canvas. This div is sized to match the canvas, and if the canvas size changes, as a result of
+ * settings within the Scale Manager, the dom container is resized accordingly.
+ * 
+ * You can create a DOM Element by either passing in DOMStrings, or by passing in a reference to an existing
+ * Element that you wish to be placed under the control of Phaser. For example:
+ * 
+ * ```javascript
+ * this.add.dom(x, y, 'div', 'background-color: lime; width: 220px; height: 100px; font: 48px Arial', 'Phaser');
+ * ```
+ * 
+ * The above code will insert a div element into the DOM Container at the given x/y coordinate. The DOMString in
+ * the 4th argument sets the initial CSS style of the div and the final argument is the inner text. In this case,
+ * it will create a lime colored div that is 220px by 100px in size with the text Phaser in it, in an Arial font.
+ * 
+ * You should nearly always, without exception, use explicitly sized HTML Elements, in order to fully control
+ * alignment and positioning of the elements next to regular game content.
+ * 
+ * Rather than specify the CSS and HTML directly you can use the `load.html` File Loader to load it into the
+ * cache and then use the `createFromCache` method instead. You can also use `createFromHTML` and various other
+ * methods available in this class to help construct your elements.
+ * 
+ * Once the element has been created you can then control it like you would any other Game Object. You can set its
+ * position, scale, rotation, alpha and other properties. It will move as the main Scene Camera moves and be clipped
+ * at the edge of the canvas. It's important to remember some limitations of DOM Elements: The obvious one is that
+ * they appear above or below your game canvas. You cannot blend them into the display list, meaning you cannot have
+ * a DOM Element, then a Sprite, then another DOM Element behind it.
+ * 
+ * They also cannot be enabled for input. To do that, you have to use the `addListener` method to add native event
+ * listeners directly. The final limitation is to do with cameras. The DOM Container is sized to match the game canvas
+ * entirely and clipped accordingly. DOM Elements respect camera scrolling and scrollFactor settings, but if you
+ * change the size of the camera so it no longer matches the size of the canvas, they won't be clipped accordingly.
+ * 
+ * Also, all DOM Elements are inserted into the same DOM Container, regardless of which Scene they are created in.
+ * 
+ * DOM Elements are a powerful way to align native HTML with your Phaser Game Objects. For example, you can insert
+ * a login form for a multiplayer game directly into your title screen. Or a text input box for a highscore table.
+ * Or a banner ad from a 3rd party service. Or perhaps you'd like to use them for high resolution text display and
+ * UI. The choice is up to you, just remember that you're dealing with standard HTML and CSS floating over the top
+ * of your game, and should treat it accordingly.
  *
  * Note: This method will only be available if the DOM Element Game Object has been built into Phaser.
  *