More docs.

src/core/LinkedList.js

@@ -2,11 +2,10 @@
 * @author       Richard Davey <rich@photonstorm.com>
 * @copyright    2013 Photon Storm Ltd.
 * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
-* @module       Phaser.LinkedList
 */
 
 /**
-* A linked list data structure.
+* A basic linked list data structure.
 *
 * @class Phaser.LinkedList
 * @constructor
@@ -48,12 +47,11 @@ Phaser.LinkedList = function () {
 Phaser.LinkedList.prototype = {
 
 	/**
-    * Add element to a linked list.
+    * Adds a new element to this linked list.
 	* 
-	* @method add
-    * @memberof Phaser.LinkedList
-	* @param {object} child - Description.
-	* @return {object} Description.	   
+	* @method Phaser.LinkedList#add
+	* @param {object} child - The element to add to this list. Can be a Phaser.Sprite or any other object you need to quickly iterate through.
+	* @return {object} The child that was added.
     */
     add: function (child) {
 
@@ -65,7 +63,7 @@ Phaser.LinkedList.prototype = {
 	    	this.next = child;
 	    	child.prev = this;
 	    	this.total++;
-    		return;
+    		return child;
     	}
 
     	//	Get gets appended to the end of the list, regardless of anything, and it won't have any children of its own (non-nested list)
@@ -82,31 +80,53 @@ Phaser.LinkedList.prototype = {
     },
 
 	/**
-    * Remove element from a linked list.
+    * Removes the given element from this linked list if it exists.
  	* 
- 	* @method remove
-    * @memberof Phaser.LinkedList
- 	* @param {object} child - Description.   
+ 	* @method Phaser.LinkedList#remove
+ 	* @param {object} child - The child to be removed from the list.
     */
     remove: function (child) {
-    	if( child == this.first )  this.first = this.first.next;      // It was 'first', make 'first' point to first.next
-		else if ( child == this.last ) this.last = this.last.prev; // It was 'last', make 'last' point to last.prev
 
-		if( child.prev ) child.prev.next = child.next; // make child.prev.next point to childs.next instead of child
-		if( child.next ) child.next.prev = child.prev; // make child.next.prev point to child.prev instead of child
+    	if (child == this.first)
+    	{
+			// It was 'first', make 'first' point to first.next
+    		this.first = this.first.next;
+    	}      
+		else if (child == this.last)
+		{
+			// It was 'last', make 'last' point to last.prev
+			this.last = this.last.prev;
+		} 
+
+		if (child.prev)
+		{
+			// make child.prev.next point to childs.next instead of child
+			child.prev.next = child.next; 
+		} 
+
+		if (child.next)
+		{
+			// make child.next.prev point to child.prev instead of child
+			child.next.prev = child.prev;
+		}
+
 		child.next = child.prev = null;
 
-		if( this.first == null ) this.last = null;
+		if (this.first == null )
+		{
+			this.last = null;
+		}
 
 		this.total--;
+
     },
 
 	/**
-    * Description.
+    * Calls a function on all members of this list, using the member as the context for the callback.
+    * The function must exist on the member.
   	* 
-  	* @method callAll
-    * @memberof Phaser.LinkedList
-  	* @param {object} callback - Description.   
+  	* @method Phaser.LinkedList#callAll
+  	* @param {function} callback - The function to call.
     */
     callAll: function (callback) {
 
@@ -129,85 +149,6 @@ Phaser.LinkedList.prototype = {
 		}
 		while(entity != this.last.next)			
 
-    },
-
-	/**
-    * Description.
-   	* 
-   	* @method dump 
-    * @memberof Phaser.LinkedList
-    */
-	dump: function () {
-
-		var spacing = 20;
-
-		var output = "\n" + Phaser.Utils.pad('Node', spacing) + "|" + Phaser.Utils.pad('Next', spacing) + "|" + Phaser.Utils.pad('Previous', spacing) + "|" + Phaser.Utils.pad('First', spacing) + "|" + Phaser.Utils.pad('Last', spacing);
-		console.log(output);
-
-		var output = Phaser.Utils.pad('----------', spacing) + "|" + Phaser.Utils.pad('----------', spacing) + "|" + Phaser.Utils.pad('----------', spacing) + "|" + Phaser.Utils.pad('----------', spacing) + "|" + Phaser.Utils.pad('----------', spacing);
-		console.log(output);
-
-		var entity = this;
-
-		var testObject = entity.last.next;
-		entity = entity.first;
-		
-		do	
-		{
-			var name = entity.sprite.name || '*';
-			var nameNext = '-';
-			var namePrev = '-';
-			var nameFirst = '-';
-			var nameLast = '-';
-
-			if (entity.next)
-			{
-				nameNext = entity.next.sprite.name;
-			}
-
-			if (entity.prev)
-			{
-				namePrev = entity.prev.sprite.name;
-			}
-
-			if (entity.first)
-			{
-				nameFirst = entity.first.sprite.name;
-			}
-
-			if (entity.last)
-			{
-				nameLast = entity.last.sprite.name;
-			}
-
-			if (typeof nameNext === 'undefined')
-			{
-				nameNext = '-';
-			}
-
-			if (typeof namePrev === 'undefined')
-			{
-				namePrev = '-';
-			}
-
-			if (typeof nameFirst === 'undefined')
-			{
-				nameFirst = '-';
-			}
-
-			if (typeof nameLast === 'undefined')
-			{
-				nameLast = '-';
-			}
-
-			var output = Phaser.Utils.pad(name, spacing) + "|" + Phaser.Utils.pad(nameNext, spacing) + "|" + Phaser.Utils.pad(namePrev, spacing) + "|" + Phaser.Utils.pad(nameFirst, spacing) + "|" + Phaser.Utils.pad(nameLast, spacing);
-			console.log(output);
-
-			entity = entity.next;
-
-		}
-		while(entity != testObject)
-
-	}
+    }
 
 };

src/core/Plugin.js

@@ -2,10 +2,8 @@
 * @author       Richard Davey <rich@photonstorm.com>
 * @copyright    2013 Photon Storm Ltd.
 * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
-* @module       Phaser.Plugin
 */
 
-
 /** 
 * This is a base Plugin template to use for any Phaser plugin development.
 * 
@@ -13,52 +11,54 @@
 * @classdesc Phaser - Plugin
 * @constructor
 * @param {Phaser.Game} game - A reference to the currently running game.
-* @param {Description} parent - Description.
+* @param {Any} parent - The object that owns this plugin, usually Phaser.PluginManager.
 */
 Phaser.Plugin = function (game, parent) {
 
+    if (typeof parent === 'undefined') { parent = null; }
+
 	/**
 	* @property {Phaser.Game} game - A reference to the currently running game.
 	*/
     this.game = game;
     
     /**
-	* @property {Description} parent - Description.
+	* @property {Any} parent - The parent of this plugin. If added to the PluginManager the parent will be set to that, otherwise it will be null.
 	*/
     this.parent = parent;
     
     /**
-	* @property {boolean} active - Description.
+	* @property {boolean} active - A Plugin with active=true has its preUpdate and update methods called by the parent, otherwise they are skipped.
 	* @default
 	*/
     this.active = false;
     
     /**
-	* @property {boolean} visible - Description.
+	* @property {boolean} visible - A Plugin with visible=true has its render and postRender methods called by the parent, otherwise they are skipped.
 	* @default
 	*/
     this.visible = false;
     
     /**
-	* @property {boolean} hasPreUpdate - Description.
+	* @property {boolean} hasPreUpdate - A flag to indicate if this plugin has a preUpdate method.
 	* @default
 	*/
     this.hasPreUpdate = false;
     
     /**
-	* @property {boolean} hasUpdate - Description.
+	* @property {boolean} hasUpdate - A flag to indicate if this plugin has an update method.
 	* @default
 	*/
     this.hasUpdate = false;
     
     /**
-	* @property {boolean} hasRender - Description.
+	* @property {boolean} hasRender - A flag to indicate if this plugin has a render method.
 	* @default
 	*/
     this.hasRender = false;
     
     /**
-	* @property {boolean} hasPostRender - Description.
+	* @property {boolean} hasPostRender - A flag to indicate if this plugin has a postRender method.
 	* @default
 	*/
     this.hasPostRender = false;
@@ -68,10 +68,9 @@ Phaser.Plugin = function (game, parent) {
 Phaser.Plugin.prototype = {
 
     /**
-    * Pre-update is called at the start of the update cycle, before any other updates have taken place (including Physics).
+    * Pre-update is called at the very start of the update cycle, before any other subsystems have been updated (including Physics).
     * It is only called if active is set to true.
-    * @method preUpdate
-    * @memberof Phaser.Plugin
+    * @method Phaser.Plugin#preUpdate
     */
     preUpdate: function () {
     },
@@ -79,8 +78,7 @@ Phaser.Plugin.prototype = {
     /**
     * Update is called after all the core subsystems (Input, Tweens, Sound, etc) and the State have updated, but before the render.
     * It is only called if active is set to true.
-    * @method update
-    * @memberof Phaser.Plugin
+    * @method Phaser.Plugin#update
     */
     update: function () {
     },
@@ -88,8 +86,7 @@ Phaser.Plugin.prototype = {
     /**
     * Render is called right after the Game Renderer completes, but before the State.render.
     * It is only called if visible is set to true.
-    * @method render
-    * @memberof Phaser.Plugin
+    * @method Phaser.Plugin#render
     */
     render: function () {
     },
@@ -97,16 +94,14 @@ Phaser.Plugin.prototype = {
     /**
     * Post-render is called after the Game Renderer and State.render have run.
     * It is only called if visible is set to true.
-    * @method postRender
-    * @memberof Phaser.Plugin
+    * @method Phaser.Plugin#postRender
     */
     postRender: function () {
     },
 
     /**
     * Clear down this Plugin and null out references
-    * @method destroy
-    * @memberof Phaser.Plugin
+    * @method Phaser.Plugin#destroy
     */
     destroy: function () {
 

src/core/PluginManager.js

@@ -46,8 +46,7 @@ Phaser.PluginManager.prototype = {
     /**
     * Add a new Plugin to the PluginManager.
     * The plugin's game and parent reference are set to this game and pluginmanager parent.
-    * @method add
-    * @memberof Phaser.PluginManager
+    * @method Phaser.PluginManager#add
     * @param {Phaser.Plugin} plugin - Description.
     * @return {Phaser.Plugin} Description.
     */
@@ -115,9 +114,8 @@ Phaser.PluginManager.prototype = {
 
     /**
      * Remove a Plugin from the PluginManager.
-     * @method remove
-     * @memberof Phaser.PluginManager
-     * @param {Phaser.Plugin} plugin - Description.
+     * @method Phaser.PluginManager#remove
+     * @param {Phaser.Plugin} plugin - The plugin to be removed.
      */
     remove: function (plugin) {
 
@@ -127,10 +125,10 @@ Phaser.PluginManager.prototype = {
     },
 
     /**
-    * Description.
+    * Pre-update is called at the very start of the update cycle, before any other subsystems have been updated (including Physics).
+    * It only calls plugins who have active=true.
     * 
-    * @method preUpdate
-    * @memberof Phaser.PluginManager
+    * @method Phaser.PluginManager#preUpdate
     */
     preUpdate: function () {
 
@@ -150,10 +148,10 @@ Phaser.PluginManager.prototype = {
     },
 
     /**
-    * Description.
+    * Update is called after all the core subsystems (Input, Tweens, Sound, etc) and the State have updated, but before the render.
+    * It only calls plugins who have active=true.
     * 
-    * @method update
-    * @memberof Phaser.PluginManager
+    * @method Phaser.PluginManager#update
     */
     update: function () {
         
@@ -173,10 +171,10 @@ Phaser.PluginManager.prototype = {
     },
 
     /**
-    * Description.
+    * Render is called right after the Game Renderer completes, but before the State.render.
+    * It only calls plugins who have visible=true.
     * 
-    * @method render
-    * @memberof Phaser.PluginManager
+    * @method Phaser.PluginManager#render
     */
     render: function () {
 
@@ -196,10 +194,10 @@ Phaser.PluginManager.prototype = {
     },
 
     /**
-    * Description.
+    * Post-render is called after the Game Renderer and State.render have run.
+    * It only calls plugins who have visible=true.
     * 
-    * @method postRender
-    * @memberof Phaser.PluginManager
+    * @method Phaser.PluginManager#postRender
     */
     postRender: function () {
 
@@ -219,10 +217,9 @@ Phaser.PluginManager.prototype = {
     },
 
     /**
-    * Description.
+    * Clear down this PluginManager and null out references
     * 
-    * @method destroy
-    * @memberof Phaser.PluginManager
+    * @method Phaser.PluginManager#destroy
     */
     destroy: function () {
 

src/core/Signal.js

@@ -2,7 +2,6 @@
 * @author       Richard Davey <rich@photonstorm.com>
 * @copyright    2013 Photon Storm Ltd.
 * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
-* @module       Phaser.Signal
 */
 
 /**
@@ -48,7 +47,6 @@ Phaser.Signal.prototype = {
 	memorize: false,
 
 	/**
-	* Description.
 	* @property {boolean} _shouldPropagate 
 	* @private
 	*/
@@ -63,11 +61,10 @@ Phaser.Signal.prototype = {
 	active: true,
 
 	/**
-	* Description.
-	* 
-	* @method validateListener
+	* @method Phaser.Signal#validateListener
 	* @param {function} listener - Signal handler function.
 	* @param {Description} fnName - Description.
+	* @private
     */
 	validateListener: function (listener, fnName) {
 		if (typeof listener !== 'function') {
@@ -76,9 +73,7 @@ Phaser.Signal.prototype = {
 	},
 
 	/**
-	 * Description.
-	 * 
-	 * @method _registerListener
+	 * @method Phaser.Signal#_registerListener
 	 * @param {function} listener - Signal handler function.
 	 * @param {boolean} isOnce - Description.
 	 * @param {object} [listenerContext] - Description.
@@ -109,9 +104,7 @@ Phaser.Signal.prototype = {
 	},
 
 	/**
-	 * Description.
-	 * 
-	 * @method _addBinding 
+	 * @method Phaser.Signal#_addBinding 
 	 * @param {Phaser.SignalBinding} binding - An Object representing the binding between the Signal and listener.
 	 * @private
 	 */
@@ -123,9 +116,7 @@ Phaser.Signal.prototype = {
 	},
 
 	/**
-	 * Description.
-	 * 
-	 * @method _indexOfListener
+	 * @method Phaser.Signal#_indexOfListener
 	 * @param {function} listener - Signal handler function.
 	 * @return {number} Description.
 	 * @private
@@ -145,7 +136,7 @@ Phaser.Signal.prototype = {
 	/**
 	 * Check if listener was attached to Signal.
 	 * 
-	 * @method has
+	 * @method Phaser.Signal#has
 	 * @param {Function} listener - Signal handler function.
 	 * @param {Object} [context] - Context on which listener will be executed (object that should represent the `this` variable inside listener function).
 	 * @return {boolean} If Signal has the specified listener.
@@ -157,7 +148,7 @@ Phaser.Signal.prototype = {
 	/**
 	 * Add a listener to the signal.
 	 * 
-	 * @method add
+	 * @method Phaser.Signal#add
 	 * @param {function} listener - Signal handler function.
 	 * @param {object} [listenerContext] Context on which listener will be executed (object that should represent the `this` variable inside listener function).
 	 * @param {number} [priority] The priority level of the event listener. Listeners with higher priority will be executed before listeners with lower priority. Listeners with same priority level will be executed at the same order as they were added. (default = 0).
@@ -170,6 +161,8 @@ Phaser.Signal.prototype = {
 
 	/**
 	* Add listener to the signal that should be removed after first execution (will be executed only once).
+	*
+	* @method Phaser.Signal#addOnce
 	* @param {function} listener Signal handler function.
 	* @param {object} [listenerContext] Context on which listener will be executed (object that should represent the `this` variable inside listener function).
 	* @param {number} [priority] The priority level of the event listener. Listeners with higher priority will be executed before listeners with lower priority. Listeners with same priority level will be executed at the same order as they were added. (default = 0)
@@ -182,23 +175,32 @@ Phaser.Signal.prototype = {
 
 	/**
 	* Remove a single listener from the dispatch queue.
+	*
+	* @method Phaser.Signal#remove
 	* @param {function} listener Handler function that should be removed.
 	* @param {object} [context] Execution context (since you can add the same handler multiple times if executing in a different context).
 	* @return {function} Listener handler function.
 	*/
 	remove: function (listener, context) {
+
 		this.validateListener(listener, 'remove');
 
 		var i = this._indexOfListener(listener, context);
-		if (i !== -1) {
+
+		if (i !== -1)
+		{
 			this._bindings[i]._destroy(); //no reason to a Phaser.SignalBinding exist if it isn't attached to a signal
 			this._bindings.splice(i, 1);
 		}
+
 		return listener;
+
 	},
 
 	/**
 	* Remove all listeners from the Signal.
+	*
+	* @method Phaser.Signal#removeAll
 	*/
 	removeAll: function () {
 		var n = this._bindings.length;
@@ -209,6 +211,9 @@ Phaser.Signal.prototype = {
 	},
 
 	/**
+	* Gets the total number of listeneres attached to ths Signal.
+	*
+	* @method Phaser.Signal#getNumListeners
 	* @return {number} Number of listeners attached to the Signal.
 	*/
 	getNumListeners: function () {
@@ -219,6 +224,8 @@ Phaser.Signal.prototype = {
 	* Stop propagation of the event, blocking the dispatch to next listeners on the queue.
 	* <p><strong>IMPORTANT:</strong> should be called only during signal dispatch, calling it before/after dispatch won't affect signal broadcast.</p>
 	* @see Signal.prototype.disable
+	*
+	* @method Phaser.Signal#halt
 	*/
 	halt: function () {
 		this._shouldPropagate = false;
@@ -226,7 +233,9 @@ Phaser.Signal.prototype = {
 
 	/**
 	* Dispatch/Broadcast Signal to all listeners added to the queue.
-	* @param {Description} [params] - Parameters that should be passed to each handler.
+	*
+	* @method Phaser.Signal#dispatch
+	* @param {any} [params] - Parameters that should be passed to each handler.
 	*/
 	dispatch: function (params) {
 		if (! this.active) {
@@ -255,17 +264,21 @@ Phaser.Signal.prototype = {
 	},
 
 	/**
-	 * Forget memorized arguments.
-	 * @see Signal.memorize
-	 */
+	* Forget memorized arguments.
+	* @see Signal.memorize
+	*
+	* @method Phaser.Signal#forget
+ 	*/
 	forget: function(){
 		this._prevParams = null;
 	},
 
 	/**
-	 * Remove all bindings from signal and destroy any reference to external objects (destroy Signal object).
-	 * <p><strong>IMPORTANT:</strong> calling any method on the signal instance after calling dispose will throw errors.</p>
-	 */
+	* Remove all bindings from signal and destroy any reference to external objects (destroy Signal object).
+	* <p><strong>IMPORTANT:</strong> calling any method on the signal instance after calling dispose will throw errors.</p>
+	*
+	* @method Phaser.Signal#dispose
+	*/
 	dispose: function () {
 		this.removeAll();
 		delete this._bindings;
@@ -273,8 +286,10 @@ Phaser.Signal.prototype = {
 	},
 
 	/**
-	 * @return {string} String representation of the object.
-	 */
+	*
+	* @method Phaser.Signal#toString
+	* @return {string} String representation of the object.
+	*/
 	toString: function () {
 		return '[Phaser.Signal active:'+ this.active +' numListeners:'+ this.getNumListeners() +']';
 	}

src/core/SignalBinding.js

@@ -2,10 +2,8 @@
 * @author       Richard Davey <rich@photonstorm.com>
 * @copyright    2013 Photon Storm Ltd.
 * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
-* @module       Phaser.SignalBinding
 */
 
-
 /**
 * Phaser.SignalBinding
 *
@@ -77,7 +75,7 @@ Phaser.SignalBinding.prototype = {
     /**
     * Call listener passing arbitrary parameters.
     * <p>If binding was added using `Signal.addOnce()` it will be automatically removed from signal dispatch queue, this method is used internally for the signal dispatch.</p>
-    * @method execute
+    * @method Phaser.SignalBinding#execute
     * @param {array} [paramsArr] - Array of parameters that should be passed to the listener.
     * @return {Description} Value returned by the listener.
     */
@@ -103,7 +101,7 @@ Phaser.SignalBinding.prototype = {
     /**
     * Detach binding from signal.
     * <p>alias to: @see mySignal.remove(myBinding.getListener());
-    * @method detach
+    * @method Phaser.SignalBinding#detach
     * @return {function|null} Handler function bound to the signal or `null` if binding was previously detached.
     */
     detach: function () {
@@ -111,7 +109,7 @@ Phaser.SignalBinding.prototype = {
     },
 
     /**
-    * @method isBound
+    * @method Phaser.SignalBinding#isBound
     * @return {boolean} True if binding is still bound to the signal and has a listener.
     */
     isBound: function () {
@@ -119,7 +117,7 @@ Phaser.SignalBinding.prototype = {
     },
 
     /**
-    * @method isOnce
+    * @method Phaser.SignalBinding#isOnce
     * @return {boolean} If SignalBinding will only be executed once.
     */
     isOnce: function () {
@@ -127,7 +125,7 @@ Phaser.SignalBinding.prototype = {
     },
 
     /**
-    * @method getListener
+    * @method Phaser.SignalBinding#getListener
     * @return {Function} Handler function bound to the signal.
     */
     getListener: function () {
@@ -135,7 +133,7 @@ Phaser.SignalBinding.prototype = {
     },
 
     /**
-    * @method getSignal
+    * @method Phaser.SignalBinding#getSignal
     * @return {Signal} Signal that listener is currently bound to.
     */
     getSignal: function () {
@@ -143,7 +141,7 @@ Phaser.SignalBinding.prototype = {
     },
 
     /**
-    * @method _destroy
+    * @method Phaser.SignalBinding#_destroy
     * Delete instance properties
     * @private
     */
@@ -154,7 +152,7 @@ Phaser.SignalBinding.prototype = {
     },
 
     /**
-    * @method toString
+    * @method Phaser.SignalBinding#toString
     * @return {string} String representation of the object.
     */
     toString: function () {