Added jsdocs. Now 100% complete!

Author: photonstorm

CHANGELOG.md

@@ -4,8 +4,11 @@
 
 ### Camera - New Features, Updates and Fixes
 
+* All of the 2D Camera classes are now 100% covered by JSDocs!
 * `Camera.alpha` (and its related method `Camera.setAlpha`) allows you to set an alpha level for the entire camera. This impacts everything it is rendering, even if those objects also have their own alpha values too. You can tween the property to make the camera contents fade in / out, or otherwise set it as needed in your game.
 * `Camera.deadzone` (and its related method `Camera.setDeadzone`) allows you to specify the deadzone for a camera. The deadzone is a rectangular region used when a camera is following a target. If the target is within the deadzone then the camera will not scroll. As soon as the target leaves the deadzone, the camera will begin tracking it (applying lerp if needed.) It allows you to set a region of the camera in which a player can move freely before tracking begins. The deadzone is re-centered on the camera mid point every frame, meaning you can also use the rectangle for other in-game chcecks as needed.
+* `Camera.pan` is a new Camera Effect that allows you to control automatic camera pans between points in your game world. You can specify a duration and ease type for the pan, and it'll emit events just like all other camera effects, so you can hook into the start, update and completion of the pan. See the examples and docs for more details.
+* `Camera.zoom` is a new Camera Effect that allows you to control automatic camera zooming. You can specify a duration and ease type for the zoom, as well as the zoom factor of course, and it'll emit events just like all other camera effects, so you can hook into the start, update and completion of the zoom. Used in combination with the new Pan effect you can zoom and pan around with ease. See the examples and docs for more details.
 * `Camera.midPoint` is a new Vec2 property that is updated every frame. Use it to obtain exactly where in the world the center of the camera is currently looking.
 * `Camera.displayWidth` is a new property that returns the display width of the camera, factoring in the current zoom level.
 * `Camera.displayHeight` is a new property that returns the display height of the camera, factoring in the current zoom level.

src/cameras/2d/CameraManager.js

@@ -13,30 +13,54 @@ var RectangleContains = require('../../geom/rectangle/Contains');
 /**
  * @typedef {object} InputJSONCameraObject
  *
- * @property {string} [name=''] - [description]
- * @property {integer} [x=0] - [description]
- * @property {integer} [y=0] - [description]
- * @property {integer} [width] - [description]
- * @property {integer} [height] - [description]
- * @property {float} [zoom=1] - [description]
- * @property {float} [rotation=0] - [description]
- * @property {boolean} [roundPixels=false] - [description]
- * @property {float} [scrollX=0] - [description]
- * @property {float} [scrollY=0] - [description]
- * @property {(false|string)} [backgroundColor=false] - [description]
- * @property {?object} [bounds] - [description]
- * @property {number} [bounds.x=0] - [description]
- * @property {number} [bounds.y=0] - [description]
- * @property {number} [bounds.width] - [description]
- * @property {number} [bounds.height] - [description]
+ * @property {string} [name=''] - The name of the Camera.
+ * @property {integer} [x=0] - The horizontal position of the Camera viewport.
+ * @property {integer} [y=0] - The vertical position of the Camera viewport.
+ * @property {integer} [width] - The width of the Camera viewport.
+ * @property {integer} [height] - The height of the Camera viewport.
+ * @property {float} [zoom=1] - The default zoom level of the Camera.
+ * @property {float} [rotation=0] - The rotation of the Camera, in radians.
+ * @property {boolean} [roundPixels=false] - Should the Camera round pixels before rendering?
+ * @property {float} [scrollX=0] - The horizontal scroll position of the Camera.
+ * @property {float} [scrollY=0] - The vertical scroll position of the Camera.
+ * @property {(false|string)} [backgroundColor=false] - A CSS color string controlling the Camera background color.
+ * @property {?object} [bounds] - Defines the Camera bounds.
+ * @property {number} [bounds.x=0] - The top-left extent of the Camera bounds.
+ * @property {number} [bounds.y=0] - The top-left extent of the Camera bounds.
+ * @property {number} [bounds.width] - The width of the Camera bounds.
+ * @property {number} [bounds.height] - The height of the Camera bounds.
  */
 
-//  TODO stop it assigning more than 32 cameras (or whatever the limit is)
-//  The remove method leaves gaps in the ID list
-
 /**
  * @classdesc
- * [description]
+ * The Camera Manager is a plugin that belongs to a Scene and is responsible for managing all of the Scene Cameras.
+ * 
+ * By default you can access the Camera Manager from within a Scene using `this.cameras`, although this can be changed
+ * in your game config.
+ * 
+ * The Camera Manager can manage up to 31 unique Cameras. You can use the properties `camera1` through to `camera10`
+ * for quick and easy access to the first 10 cameras you define.
+ * 
+ * Create new Cameras using the `add` method. Or extend the Camera class with your own addition code and then add
+ * the new Camera in using the `addExisting` method.
+ * 
+ * Cameras provide a view into your game world, and can be positioned, rotated, zoomed and scrolled accordingly.
+ *
+ * A Camera consists of two elements: The viewport and the scroll values.
+ *
+ * The viewport is the physical position and size of the Camera within your game. Cameras, by default, are
+ * created the same size as your game, but their position and size can be set to anything. This means if you
+ * wanted to create a camera that was 320x200 in size, positioned in the bottom-right corner of your game,
+ * you'd adjust the viewport to do that (using methods like `setViewport` and `setSize`).
+ *
+ * If you wish to change where the Camera is looking in your game, then you scroll it. You can do this
+ * via the properties `scrollX` and `scrollY` or the method `setScroll`. Scrolling has no impact on the
+ * viewport, and changing the viewport has no impact on the scrolling.
+ *
+ * By default a Camera will render all Game Objects it can see. You can change this using the `ignore` method,
+ * allowing you to filter Game Objects out on a per-Camera basis.
+ *
+ * A Camera also has built-in special effects including Fade, Flash and Camera Shake.
  *
  * @class CameraManager
  * @memberOf Phaser.Cameras.Scene2D
@@ -174,19 +198,30 @@ var CameraManager = new Class({
     },
 
     /**
-     * [description]
+     * Adds a new Camera into the Camera Manager. The Camera Manager can support up to 31 different Cameras.
+     * 
+     * Each Camera has its own viewport, which controls the size of the Camera and its position within the canvas.
+     * 
+     * Use the `Camera.scrollX` and `Camera.scrollY` properties to change where the Camera is looking, or the
+     * Camera methods such as `centerOn`. Cameras also have built in special effects, such as fade, flash, shake,
+     * pan and zoom.
+     * 
+     * By default Cameras are transparent and will render anything that they can see based on their `scrollX`
+     * and `scrollY` values. Game Objects can be set to be ignored by a Camera by using the `Camera.ignore` method.
+     * 
+     * See the Camera class documentation for more details.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#add
      * @since 3.0.0
      *
-     * @param {number} [x=0] - [description]
-     * @param {number} [y=0] - [description]
-     * @param {number} [width] - [description]
-     * @param {number} [height] - [description]
-     * @param {boolean} [makeMain=false] - [description]
-     * @param {string} [name=''] - [description]
+     * @param {integer} [x=0] - The horizontal position of the Camera viewport.
+     * @param {integer} [y=0] - The vertical position of the Camera viewport.
+     * @param {integer} [width] - The width of the Camera viewport. If not given it'll be the game config size.
+     * @param {integer} [height] - The height of the Camera viewport. If not given it'll be the game config size.
+     * @param {boolean} [makeMain=false] - Set this Camera as being the 'main' camera. This just makes the property `main` a reference to it.
+     * @param {string} [name=''] - The name of the Camera.
      *
-     * @return {Phaser.Cameras.Scene2D.Camera} [description]
+     * @return {Phaser.Cameras.Scene2D.Camera} The newly created Camera.
      */
     add: function (x, y, width, height, makeMain, name)
     {
@@ -217,15 +252,22 @@ var CameraManager = new Class({
     },
 
     /**
-     * [description]
+     * Adds an existing Camera into the Camera Manager.
+     * 
+     * The Camera should either be a `Phaser.Cameras.Scene2D.Camera` instance, or a class that extends from it.
+     * 
+     * The Camera will be assigned an ID, which is used for Game Object exclusion and then added to the
+     * manager. As long as it doesn't already exist in the manager it will be added then returned.
+     * 
+     * If this method returns `null` then the Camera already exists in this Camera Manager.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#addExisting
      * @since 3.0.0
      *
-     * @param {Phaser.Cameras.Scene2D.Camera} camera - [description]
-     * @param {boolean} [makeMain=false] - [description]
+     * @param {Phaser.Cameras.Scene2D.Camera} camera - The Camera to be added to the Camera Manager.
+     * @param {boolean} [makeMain=false] - Set this Camera as being the 'main' camera. This just makes the property `main` a reference to it.
      *
-     * @return {Phaser.Cameras.Scene2D.Camera} [description]
+     * @return {?Phaser.Cameras.Scene2D.Camera} The Camera that was added to the Camera Manager, or `null` if it couldn't be added.
      */
     addExisting: function (camera, makeMain)
     {
@@ -253,14 +295,16 @@ var CameraManager = new Class({
     },
 
     /**
-     * [description]
+     * Populates this Camera Manager based on the given configuration object, or an array of config objects.
+     * 
+     * See the `InputJSONCameraObject` documentation for details of the object structure.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#fromJSON
      * @since 3.0.0
      *
-     * @param {(InputJSONCameraObject|InputJSONCameraObject[])} config - [description]
+     * @param {(InputJSONCameraObject|InputJSONCameraObject[])} config - A Camera configuration object, or an array of them, to be added to this Camera Manager.
      *
-     * @return {Phaser.Cameras.Scene2D.CameraManager} [description]
+     * @return {Phaser.Cameras.Scene2D.CameraManager} This Camera Manager instance.
      */
     fromJSON: function (config)
     {
@@ -320,14 +364,17 @@ var CameraManager = new Class({
     },
 
     /**
-     * [description]
+     * Gets a Camera based on its name.
+     * 
+     * Camera names are optional and don't have to be set, so this method is only of any use if you
+     * have given your Cameras unique names.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#getCamera
      * @since 3.0.0
      *
-     * @param {string} name - [description]
+     * @param {string} name - The name of the Camera.
      *
-     * @return {?Phaser.Cameras.Scene2D.Camera} [description]
+     * @return {?Phaser.Cameras.Scene2D.Camera} The first Camera with a name matching the given string, otherwise `null`.
      */
     getCamera: function (name)
     {
@@ -380,12 +427,18 @@ var CameraManager = new Class({
     },
 
     /**
-     * [description]
+     * Removes the given Camera from this Camera Manager.
+     * 
+     * If found in the Camera Manager it will be immediately removed from the local cameras array.
+     * If also currently the 'main' camera, 'main' will be reset to be camera 0.
+     * 
+     * The removed Camera is not destroyed. If you also wish to destroy the Camera, you should call
+     * `Camera.destroy` on it, so that it clears all references to the Camera Manager.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#remove
      * @since 3.0.0
      *
-     * @param {Phaser.Cameras.Scene2D.Camera} camera - [description]
+     * @param {Phaser.Cameras.Scene2D.Camera} camera - The Camera to be removed from this Camera Manager.
      */
     remove: function (camera)
     {
@@ -403,9 +456,13 @@ var CameraManager = new Class({
     },
 
     /**
-     * [description]
+     * The internal render method. This is called automatically by the Scene and should not be invoked directly.
+     * 
+     * It will iterate through all local cameras and render them in turn, as long as they're visible and have
+     * an alpha level > 0.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#render
+     * @protected
      * @since 3.0.0
      *
      * @param {(Phaser.Renderer.Canvas.CanvasRenderer|Phaser.Renderer.WebGL.WebGLRenderer)} renderer - The Renderer that will render the children to this camera.
@@ -433,12 +490,15 @@ var CameraManager = new Class({
     },
 
     /**
-     * [description]
+     * Resets this Camera Manager.
+     * 
+     * This will iterate through all current Cameras, destroying them all, then it will reset the
+     * cameras array, reset the ID counter and create 1 new single camera using the default values.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#resetAll
      * @since 3.0.0
      *
-     * @return {Phaser.Cameras.Scene2D.Camera} [description]
+     * @return {Phaser.Cameras.Scene2D.Camera} The freshly created main Camera.
      */
     resetAll: function ()
     {
@@ -457,13 +517,14 @@ var CameraManager = new Class({
     },
 
     /**
-     * [description]
+     * The main update loop. Called automatically when the Scene steps.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#update
+     * @protected
      * @since 3.0.0
      *
-     * @param {number} timestep - [description]
-     * @param {number} delta - [description]
+     * @param {number} timestep - The timestep value.
+     * @param {number} delta - The delta value since the last frame.
      */
     update: function (timestep, delta)
     {