Added jsdocs to Container and made add support arrays

src/gameobjects/container/Container.js

@@ -1,8 +1,33 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @author       Felipe Alfonso <@bitnenfer>
+ * @copyright    2018 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
 var Class = require('../../utils/Class');
 var Components = require('../components');
 var GameObject = require('../GameObject');
 var Render = require('./ContainerRender');
+var Vector2 = require('../../math/Vector2');
 
+/**
+ * @classdesc
+ * A Container Game Object.
+ *
+ * @class Container
+ * @extends Phaser.GameObjects.GameObject
+ * @memberOf Phaser.GameObjects
+ * @constructor
+ * @since 3.4.0
+ *
+ * @extends Phaser.GameObjects.Components.BlendMode
+ * @extends Phaser.GameObjects.Components.Transform
+ *
+ * @param {Phaser.Scene} scene - The Scene to which this Game Object belongs. A Game Object can only belong to one Scene at a time.
+ * @param {number} x - The horizontal position of this Game Object in the world.
+ * @param {number} y - The vertical position of this Game Object in the world.
+ */
 var Container = new Class({
 
     Extends: GameObject,
@@ -18,62 +43,139 @@ var Container = new Class({
     function Container (scene, x, y)
     {
         GameObject.call(this, scene, 'Container');
+
+        /**
+         * [description]
+         *
+         * @name Phaser.GameObjects.Container#parentContainer
+         * @type {Phaser.GameObjects.Container}
+         * @since 3.4.0
+         */
         this.parentContainer = null;
+
+        /**
+         * [description]
+         *
+         * @name Phaser.GameObjects.Container#children
+         * @type {Phaser.GameObjects.GameObject[]}
+         * @since 3.4.0
+         */
         this.children = [];
+
         this.setPosition(x, y);
+
+        /**
+         * [description]
+         *
+         * @name Phaser.GameObjects.Container#localTransform
+         * @type {Phaser.GameObjects.Components.TransformMatrix}
+         * @since 3.4.0
+         */
         this.localTransform = new Components.TransformMatrix();
+
+        /**
+         * [description]
+         *
+         * @name Phaser.GameObjects.Container#tempTransformMatrix
+         * @type {Phaser.GameObjects.Components.TransformMatrix}
+         * @since 3.4.0
+         */
         this.tempTransformMatrix = new Components.TransformMatrix();
     },
 
+    /**
+     * Adds the given Game Object, or array of Game Objects, to this Container.
+     *
+     * @method Phaser.GameObjects.Container#add
+     * @since 3.4.0
+     *
+     * @param {(Phaser.GameObjects.GameObject|Phaser.GameObjects.GameObject[])} gameObject - The Game Object, or array of Game Objects, to add to this Container.
+     *
+     * @return {Phaser.GameObjects.Container} This Container instance.
+     */
     add: function (gameObject)
     {
-        if (gameObject.type === 'Container')
+        if (!Array.isArray(gameObject))
         {
-            gameObject.parentContainer = this;
+            gameObject = [ gameObject ];
         }
-        if (this.children.indexOf(gameObject) < 0)
+
+        for (var i = 0; i < gameObject.length; i++)
         {
-            this.children.push(gameObject);
+            var entry = gameObject[i];
+
+            if (entry.type === 'Container')
+            {
+                entry.parentContainer = this;
+            }
+
+            if (this.children.indexOf(entry) === -1)
+            {
+                this.children.push(entry);
+            }
         }
+
         return this;
     },
 
+    /**
+     * Removes a Game Object from this Container.
+     *
+     * @method Phaser.GameObjects.Container#remove
+     * @since 3.4.0
+     *
+     * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object to remove from this Container.
+     *
+     * @return {Phaser.GameObjects.Container} This Container instance.
+     */
     remove: function (gameObject)
     {
         var index = this.children.indexOf(gameObject);
-        if (index >= 0)
+
+        if (index !== -1)
         {
             if (gameObject.type === 'Container')
             {
                 gameObject.parentContainer = null;
             }
+
             this.children.splice(index, 1);
         }
+
         return this;
     },
 
-    pointToContainer: function (pointSrc, pointDst)
+    /**
+     * Takes a Point-like object, such as a Vector2, Geom.Point or object with public x and y properties,
+     * and transforms it into the space of this Container, then returns it in the output object.
+     *
+     * @method Phaser.GameObjects.Container#pointToContainer
+     * @since 3.4.0
+     *
+     * @param {(object|Phaser.Geom.Point|Phaser.Math.Vector2)} source - The Source Point to be transformed.
+     * @param {(object|Phaser.Geom.Point|Phaser.Math.Vector2)} [output] - A destination object to store the transformed point in. If none given a Vector2 will be created and returned.
+     *
+     * @return {(object|Phaser.Geom.Point|Phaser.Math.Vector2)} The transformed point.
+     */
+    pointToContainer: function (source, output)
     {
-        var parent = this.parentContainer;
-        var tempMatrix = this.tempTransformMatrix;
-        
-        if (pointDst === undefined)
+        if (output === undefined) { output = new Vector2(); }
+
+        if (this.parentContainer)
         {
-            pointDst = { x: 0, y: 0 };
+            this.parentContainer.pointToContainer(source, output);
         }
 
-        if (parent !== null)
-        {
-            parent.pointToContainer(pointSrc, pointDst);
-        }
+        var tempMatrix = this.tempTransformMatrix;
 
         tempMatrix.loadIdentity();
         tempMatrix.applyITRS(this.x, this.y, this.rotation, this.scaleX, this.scaleY);
         tempMatrix.invert();
-        tempMatrix.transformPoint(pointSrc.x, pointSrc.y, pointDst);
+        tempMatrix.transformPoint(source.x, source.y, output);
 
-        return pointDst;
+        return output;
     }
+
 });
 
 module.exports = Container;

src/gameobjects/container/ContainerCanvasRenderer.js

@@ -1,5 +1,27 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @author       Felipe Alfonso <@bitnenfer>
+ * @copyright    2018 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
 var GameObject = require('../GameObject');
 
+/**
+ * Renders this Game Object with the Canvas Renderer to the given Camera.
+ * The object will not render if any of its renderFlags are set or it is being actively filtered out by the Camera.
+ * This method should not be called directly. It is a utility function of the Render module.
+ *
+ * @method Phaser.GameObjects.Container#renderCanvas
+ * @since 3.4.0
+ * @private
+ *
+ * @param {Phaser.Renderer.Canvas.CanvasRenderer} renderer - A reference to the current active Canvas renderer.
+ * @param {Phaser.GameObjects.Container} container - 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 ContainerCanvasRenderer = function (renderer, container, interpolationPercentage, camera, parentMatrix)
 {
     if (GameObject.RENDER_MASK !== container.renderFlags || (container.cameraFilter > 0 && (container.cameraFilter & camera._id)))

src/gameobjects/container/ContainerCreator.js

@@ -1,18 +1,36 @@
-var GetAdvancedValue = require('../../utils/object/GetAdvancedValue');
-var GameObjectCreator = require('../GameObjectCreator');
-var Container = require('./Container');
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @author       Felipe Alfonso <@bitnenfer>
+ * @copyright    2018 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
 
+var Container = require('./Container');
+var GameObjectCreator = require('../GameObjectCreator');
+var GetAdvancedValue = require('../../utils/object/GetAdvancedValue');
+var GetFastValue = require('../../utils/object/GetFastValue');
+
+/**
+ * Creates a new Container Game Object and returns it.
+ *
+ * Note: This method will only be available if the Container Game Object has been built into Phaser.
+ *
+ * @method Phaser.GameObjects.GameObjectCreator#container
+ * @since 3.4.0
+ *
+ * @param {object} config - [description]
+ *
+ * @return {Phaser.GameObjects.Container} The Game Object that was created.
+ */
 GameObjectCreator.register('container', function (config)
 {
-    var x = GetAdvancedValue(config, 'x', 0.0);
-    var y = GetAdvancedValue(config, 'y', 0.0);
-    var add = GetAdvancedValue(config, 'add', true);
+    var x = GetAdvancedValue(config, 'x', 0);
+    var y = GetAdvancedValue(config, 'y', 0);
+    var add = GetFastValue(config, 'add', true);
+
     var container = new Container(this.scene, x, y);
 
-    if (add)
-    {
-        this.scene.sys.displayList.add(container);
-    }
+    BuildGameObject(this.scene, container, config);
     
     return container;
 });

src/gameobjects/container/ContainerFactory.js

@@ -1,11 +1,27 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @author       Felipe Alfonso <@bitnenfer>
+ * @copyright    2018 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
 var Container = require('./Container');
 var GameObjectFactory = require('../GameObjectFactory');
 
+/**
+ * Creates a new Container Game Object and adds it to the Scene.
+ *
+ * Note: This method will only be available if the Container Game Object has been built into Phaser.
+ *
+ * @method Phaser.GameObjects.GameObjectFactory#container
+ * @since 3.4.0
+ *
+ * @param {number} x - The horizontal position of this Game Object in the world.
+ * @param {number} y - The vertical position of this Game Object in the world.
+ *
+ * @return {Phaser.GameObjects.Container} The Game Object that was created.
+ */
 GameObjectFactory.register('container', function (x, y)
 {
-    var container = new Container(this.scene, x, y);
-
-    this.displayList.add(container);
-
-    return container;
+    return this.displayList.add(new Container(this.scene, x, y));
 });

src/gameobjects/container/ContainerRender.js

@@ -1,3 +1,10 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @author       Felipe Alfonso <@bitnenfer>
+ * @copyright    2018 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
 var renderWebGL = require('../../utils/NOOP');
 var renderCanvas = require('../../utils/NOOP');
 

src/gameobjects/container/ContainerWebGLRenderer.js

@@ -1,5 +1,27 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @author       Felipe Alfonso <@bitnenfer>
+ * @copyright    2018 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
 var GameObject = require('../GameObject');
 
+/**
+ * Renders this Game Object with the WebGL Renderer to the given Camera.
+ * The object will not render if any of its renderFlags are set or it is being actively filtered out by the Camera.
+ * This method should not be called directly. It is a utility function of the Render module.
+ *
+ * @method Phaser.GameObjects.Container#renderWebGL
+ * @since 3.4.0
+ * @private
+ *
+ * @param {Phaser.Renderer.WebGL.WebGLRenderer} renderer - A reference to the current active WebGL renderer.
+ * @param {Phaser.GameObjects.Container} container - 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 ContainerWebGLRenderer = function (renderer, container, interpolationPercentage, camera, parentMatrix)
 {
     if (GameObject.RENDER_MASK !== container.renderFlags || (container.cameraFilter > 0 && (container.cameraFilter & camera._id)))