Added jsdocs

Author: photonstorm

src/gameobjects/components/Alpha.js

@@ -72,7 +72,9 @@ var Alpha = {
     },
 
     /**
-     * [description]
+     * The alpha value of the Game Object.
+     *
+     * This is a global value, impacting the entire Game Object, not just a region of it.
      * 
      * @name Phaser.GameObjects.Components.Alpha#alpha
      * @type {float}
@@ -108,7 +110,8 @@ var Alpha = {
     },
 
     /**
-     * [description]
+     * The alpha value starting from the top-left of the Game Object.
+     * This value is interpolated from the corner to the center of the Game Object.
      * 
      * @name Phaser.GameObjects.Components.Alpha#alphaTopLeft
      * @type {float}
@@ -137,7 +140,8 @@ var Alpha = {
     },
 
     /**
-     * [description]
+     * The alpha value starting from the top-right of the Game Object.
+     * This value is interpolated from the corner to the center of the Game Object.
      * 
      * @name Phaser.GameObjects.Components.Alpha#alphaTopRight
      * @type {float}
@@ -166,7 +170,8 @@ var Alpha = {
     },
 
     /**
-     * [description]
+     * The alpha value starting from the bottom-left of the Game Object.
+     * This value is interpolated from the corner to the center of the Game Object.
      * 
      * @name Phaser.GameObjects.Components.Alpha#alphaBottomLeft
      * @type {float}
@@ -195,7 +200,8 @@ var Alpha = {
     },
 
     /**
-     * [description]
+     * The alpha value starting from the bottom-right of the Game Object.
+     * This value is interpolated from the corner to the center of the Game Object.
      * 
      * @name Phaser.GameObjects.Components.Alpha#alphaBottomRight
      * @type {float}

src/gameobjects/components/BlendMode.js

@@ -13,7 +13,24 @@ var BlendMode = {
     _blendMode: BlendModes.NORMAL,
 
     /**
-     * [description]
+     * Sets the Blend Mode being used by this Game Object.
+     * 
+     * This can be a const, such as `Phaser.BlendModes.SCREEN`, or an integer, such as 4 (for Overlay)
+     * 
+     * Under WebGL only the following Blend Modes are available:
+     * 
+     * * ADD
+     * * MULTIPLY
+     * * SCREEN
+     *
+     * Canvas has more available depending on browser support.
+     *
+     * You can also create your own custom Blend Modes in WebGL.
+     *
+     * Blend modes have different effects under Canvas and WebGL, and from browser to browser, depending
+     * on support. Blend Modes also cause a WebGL batch flush should it encounter a new blend mode. For these
+     * reasons try to be careful about the construction of your Scene and the frequency of which blend modes
+     * are used.
      * 
      * @name Phaser.GameObjects.Components.BlendMode#blendMode
      * @type {integer|string}
@@ -58,6 +75,11 @@ var BlendMode = {
      *
      * You can also create your own custom Blend Modes in WebGL.
      *
+     * Blend modes have different effects under Canvas and WebGL, and from browser to browser, depending
+     * on support. Blend Modes also cause a WebGL batch flush should it encounter a new blend mode. For these
+     * reasons try to be careful about the construction of your Scene and the frequency of which blend modes
+     * are used.
+     * 
      * @method Phaser.GameObjects.Components.BlendMode#setBlendMode
      * @since 3.0.0
      *

src/gameobjects/zone/Zone.js

@@ -1,4 +1,3 @@
-
 var BlendModes = require('../../renderer/BlendModes');
 var Circle = require('../../geom/circle/Circle');
 var CircleContains = require('../../geom/circle/Contains');
@@ -8,14 +7,38 @@ var GameObject = require('../GameObject');
 var Rectangle = require('../../geom/rectangle/Rectangle');
 var RectangleContains = require('../../geom/rectangle/Contains');
 
-//  A Zone is a non-rendering rectangular Game Object that has a position and size.
-//  It has no texture and never renders, but does live on the display list and
-//  can be moved, scaled and rotated like any other Game Object.
-
-//  The default origin is 0.5, the center of the Zone, the same as with Game Objects.
-//  It's useful for linking to drop zones and input hit areas and has a couple of helper methods specifically for this.
-//  Also useful for object overlap checks, or as a base for your own non-displaying objects.
-
+/**
+ * A Zone Game Object.
+ *
+ * A Zone is a non-rendering rectangular Game Object that has a position and size.
+ * It has no texture and never displays, but does live on the display list and
+ * can be moved, scaled and rotated like any other Game Object.
+ *
+ * Its primary use is for creating Drop Zones and Input Hit Areas and it has a couple of helper methods
+ * specifically for this. It is also useful for object overlap checks, or as a base for your own
+ * non-displaying Game Objects.
+
+ * The default origin is 0.5, the center of the Zone, the same as with Game Objects.
+ *
+ * @class Zone
+ * @extends Phaser.GameObjects.GameObject
+ * @memberOf Phaser.GameObjects
+ * @constructor
+ * @since 3.0.0
+ *
+ * @extends Phaser.GameObjects.Components.GetBounds
+ * @extends Phaser.GameObjects.Components.Origin
+ * @extends Phaser.GameObjects.Components.ScaleMode
+ * @extends Phaser.GameObjects.Components.Transform
+ * @extends Phaser.GameObjects.Components.ScrollFactor
+ * @extends Phaser.GameObjects.Components.Visible
+ *
+ * @param {Phaser.Scene} scene - [description]
+ * @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.
+ * @param {number} [width=1] - The width of the Game Object.
+ * @param {number} [height=1] - The height of the Game Object.
+ */
 var Zone = new Class({
 
     Extends: GameObject,
@@ -40,12 +63,44 @@ var Zone = new Class({
 
         this.setPosition(x, y);
 
+        /**
+         * The native (un-scaled) width of this Game Object.
+         *
+         * @name Phaser.GameObjects.Zone#width
+         * @type {number}
+         * @since 3.0.0
+         */
         this.width = width;
+
+        /**
+         * The native (un-scaled) height of this Game Object.
+         *
+         * @name Phaser.GameObjects.Zone#height
+         * @type {number}
+         * @since 3.0.0
+         */
         this.height = height;
 
+        /**
+         * The Blend Mode of the Game Object.
+         * Although a Zone never renders, it still has a blend mode to allow it to fit seamlessly into
+         * display lists without causing a batch flush.
+         *
+         * @name Phaser.GameObjects.Zone#blendMode
+         * @type {integer}
+         * @since 3.0.0
+         */
         this.blendMode = BlendModes.NORMAL;
     },
 
+    /**
+     * The displayed width of this Game Object.
+     * This value takes into account the scale factor.
+     * 
+     * @name Phaser.GameObjects.Zone#displayWidth
+     * @type {number}
+     * @since 3.0.0
+     */
     displayWidth: {
 
         get: function ()
@@ -60,6 +115,14 @@ var Zone = new Class({
 
     },
 
+    /**
+     * The displayed height of this Game Object.
+     * This value takes into account the scale factor.
+     * 
+     * @name Phaser.GameObjects.Zone#displayHeight
+     * @type {number}
+     * @since 3.0.0
+     */
     displayHeight: {
 
         get: function ()
@@ -74,6 +137,18 @@ var Zone = new Class({
 
     },
 
+    /**
+     * Sets the size of this Game Object.
+     *
+     * @method Phaser.GameObjects.Zone#setSize
+     * @since 3.0.0
+     *
+     * @param {number} width - The width of this Game Object.
+     * @param {number} height - The height of this Game Object.
+     * @param {boolean} [resizeInput=true] - If this Zone has a Rectangle for a hit area this argument will resize the hit area as well.
+     *
+     * @return {Phaser.GameObjects.Zone} This Game Object.
+     */
     setSize: function (width, height, resizeInput)
     {
         if (resizeInput === undefined) { resizeInput = true; }
@@ -90,6 +165,18 @@ var Zone = new Class({
         return this;
     },
 
+    /**
+     * Sets the display size of this Game Object.
+     * Calling this will adjust the scale.
+     *
+     * @method Phaser.GameObjects.Zone#setDisplaySize
+     * @since 3.0.0
+     *
+     * @param {number} width - The width of this Game Object.
+     * @param {number} height - The height of this Game Object.
+     *
+     * @return {Phaser.GameObjects.Zone} This Game Object.
+     */
     setDisplaySize: function (width, height)
     {
         this.displayWidth = width;
@@ -98,13 +185,34 @@ var Zone = new Class({
         return this;
     },
 
-    //  Centered on the Zones x/y
+    /**
+     * Sets this Zone to be a Circular Drop Zone.
+     * The circle is centered on this Zones `x` and `y` coordinates.
+     *
+     * @method Phaser.GameObjects.Zone#setCircleDropZone
+     * @since 3.0.0
+     *
+     * @param {number} radius - The radius of the Circle that will form the Drop Zone.
+     *
+     * @return {Phaser.GameObjects.Zone} This Game Object.
+     */
     setCircleDropZone: function (radius)
     {
         return this.setDropZone(new Circle(0, 0, radius), CircleContains);
     },
 
-    //  Centered on the Zones x/y position
+    /**
+     * Sets this Zone to be a Rectangle Drop Zone.
+     * The rectangle is centered on this Zones `x` and `y` coordinates.
+     *
+     * @method Phaser.GameObjects.Zone#setRectangleDropZone
+     * @since 3.0.0
+     *
+     * @param {number} width - The width of the rectangle drop zone.
+     * @param {number} height - The height of the rectangle drop zone.
+     *
+     * @return {Phaser.GameObjects.Zone} This Game Object.
+     */
     setRectangleDropZone: function (width, height)
     {
         var x = -(width / 2);
@@ -113,7 +221,17 @@ var Zone = new Class({
         return this.setDropZone(new Rectangle(x, y, width, height), RectangleContains);
     },
 
-    //  Define your own shape as the drop zone
+    /**
+     * Allows you to define your own Geometry shape to be used as a Drop Zone.
+     *
+     * @method Phaser.GameObjects.Zone#setDropZone
+     * @since 3.0.0
+     *
+     * @param {object} shape - A Geometry shape instance, such as Phaser.Geom.Ellipse, or your own custom shape.
+     * @param {function} callback - A function that will return `true` if the given x/y coords it is sent are within the shape.
+     *
+     * @return {Phaser.GameObjects.Zone} This Game Object.
+     */
     setDropZone: function (shape, callback)
     {
         if (shape === undefined)
@@ -133,14 +251,26 @@ var Zone = new Class({
         return this;
     },
 
+    /**
+     * A Zone does not render.
+     *
+     * @method Phaser.GameObjects.Zone#renderCanvas
+     * @private
+     * @since 3.0.0
+     */
     renderCanvas: function ()
     {
-        return;
     },
 
+    /**
+     * A Zone does not render.
+     *
+     * @method Phaser.GameObjects.Zone#renderWebGL
+     * @private
+     * @since 3.0.0
+     */
     renderWebGL: function ()
     {
-        return;
     }
 
 });

src/gameobjects/zone/ZoneCreator.js

@@ -2,8 +2,18 @@ var GameObjectCreator = require('../GameObjectCreator');
 var GetAdvancedValue = require('../../utils/object/GetAdvancedValue');
 var Zone = require('./Zone');
 
-//  When registering a factory function 'this' refers to the GameObjectCreator context.
-
+/**
+ * Creates a new Zone Game Object and returns it.
+ *
+ * Note: This method will only be available if the Zone Game Object has been built into Phaser.
+ *
+ * @method Phaser.GameObjects.GameObjectCreator#zone
+ * @since 3.0.0
+ *
+ * @param {object} config - [description]
+ *
+ * @return {Phaser.GameObjects.Zone} The Game Object that was created.
+ */
 GameObjectCreator.register('zone', function (config)
 {
     var x = GetAdvancedValue(config, 'x', 0);
@@ -13,3 +23,5 @@ GameObjectCreator.register('zone', function (config)
 
     return new Zone(this.scene, x, y, width, height);
 });
+
+//  When registering a factory function 'this' refers to the GameObjectCreator context.

src/gameobjects/zone/ZoneFactory.js

@@ -1,15 +1,30 @@
 var Zone = require('./Zone');
 var GameObjectFactory = require('../GameObjectFactory');
 
+/**
+ * Creates a new Zone Game Object and adds it to the Scene.
+ *
+ * Note: This method will only be available if the Zone Game Object has been built into Phaser.
+ *
+ * @method Phaser.GameObjects.GameObjectFactory#zone
+ * @since 3.0.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.
+ * @param {number} width - The width of the Game Object.
+ * @param {number} height - The height of the Game Object.
+ * 
+ * @return {Phaser.GameObjects.Zone} The Game Object that was created.
+ */
+GameObjectFactory.register('zone', function (x, y, width, height)
+{
+    return this.displayList.add(new Zone(this.scene, x, y, width, height));
+});
+
 //  When registering a factory function 'this' refers to the GameObjectFactory context.
 //  
 //  There are several properties available to use:
 //  
 //  this.scene - a reference to the Scene that owns the GameObjectFactory
 //  this.displayList - a reference to the Display List the Scene owns
 //  this.updateList - a reference to the Update List the Scene owns
-
-GameObjectFactory.register('zone', function (x, y, width, height)
-{
-    return this.displayList.add(new Zone(this.scene, x, y, width, height));
-});