Input, Loader and Math docs tidied up.

src/loader/Cache.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.Cache
 */
 
 /**
@@ -70,11 +69,12 @@ Phaser.Cache = function (game) {
 Phaser.Cache.prototype = {
 
     /**
-     * Add a new canvas.
-     * @param {string} key - Asset key for this canvas.
-     * @param {HTMLCanvasElement} canvas - Canvas DOM element.
-     * @param {CanvasRenderingContext2D} context - Render context of this canvas.
-     */
+    * Add a new canvas object in to the cache.
+    * @method Phaser.Cache#addCanvas
+    * @param {string} key - Asset key for this canvas.
+    * @param {HTMLCanvasElement} canvas - Canvas DOM element.
+    * @param {CanvasRenderingContext2D} context - Render context of this canvas.
+    */
     addCanvas: function (key, canvas, context) {
 
         this._canvases[key] = { canvas: canvas, context: context };
@@ -82,10 +82,12 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Add a new canvas.
-     * @param key {string} Asset key for this canvas.
-     * @param canvas {RenderTexture} A RenderTexture.
-     */
+    * Add a new Phaser.RenderTexture in to the cache.
+    *
+    * @method Phaser.Cache#addRenderTexture
+    * @param {string} key - The unique key by which you will reference this object.
+    * @param {Phaser.Texture} textue - The texture to use as the base of the RenderTexture.
+    */
     addRenderTexture: function (key, texture) {
 
         var frame = new Phaser.Animation.Frame(0, 0, 0, texture.width, texture.height, '', '');
@@ -95,14 +97,16 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Add a new sprite sheet.
-     * @param {string} key - Asset key for the sprite sheet.
-     * @param {string} url - URL of this sprite sheet file.
-     * @param {object} data - Extra sprite sheet data.
-     * @param {number} frameWidth - Width of the sprite sheet.
-     * @param {number} frameHeight - Height of the sprite sheet.
-     * @param {number} frameMax - How many frames stored in the sprite sheet.
-     */
+    * Add a new sprite sheet in to the cache.
+    *
+    * @method Phaser.Cache#addSpriteSheet
+    * @param {string} key - The unique key by which you will reference this object.
+    * @param {string} url - URL of this sprite sheet file.
+    * @param {object} data - Extra sprite sheet data.
+    * @param {number} frameWidth - Width of the sprite sheet.
+    * @param {number} frameHeight - Height of the sprite sheet.
+    * @param {number} frameMax - How many frames stored in the sprite sheet.
+    */
     addSpriteSheet: function (key, url, data, frameWidth, frameHeight, frameMax) {
 
         this._images[key] = { url: url, data: data, spriteSheet: true, frameWidth: frameWidth, frameHeight: frameHeight };
@@ -115,12 +119,15 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Add a new tilemap.
-     * @param {string} key - Asset key for the texture atlas.
-     * @param {string} url - URL of this texture atlas file.
-     * @param {object} data - Extra texture atlas data.
-     * @param {object} atlasData  - Texture atlas frames data.
-     */
+    * Add a new tilemap.
+    *
+    * @method Phaser.Cache#addTilemap
+    * @param {string} key - The unique key by which you will reference this object.
+    * @param {string} url - URL of the tilemap image.
+    * @param {object} data - Tilemap data.
+    * @param {object} mapData - The tilemap data object.
+    * @param {number} format - The format of the tilemap data.
+    */
     addTilemap: function (key, url, data, mapData, format) {
 
         this._tilemaps[key] = { url: url, data: data, spriteSheet: true, mapData: mapData, format: format };
@@ -131,13 +138,15 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Add a new texture atlas.
-     * @param {string} key - Asset key for the texture atlas.
-     * @param {string} url - URL of this texture atlas file.
-     * @param {object} data - Extra texture atlas data.
-     * @param {object} atlasData  - Texture atlas frames data.
-     * @param {Description} format  - Description.
-     */
+    * Add a new texture atlas.
+    *
+    * @method Phaser.Cache#addTextureAtlas
+    * @param {string} key - The unique key by which you will reference this object.
+    * @param {string} url - URL of this texture atlas file.
+    * @param {object} data - Extra texture atlas data.
+    * @param {object} atlasData  - Texture atlas frames data.
+    * @param {number} format - The format of the texture atlas.
+    */
     addTextureAtlas: function (key, url, data, atlasData, format) {
 
         this._images[key] = { url: url, data: data, spriteSheet: true };
@@ -161,12 +170,14 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Add a new Bitmap Font.
-     * @param {string} key - Asset key for the font texture.
-     * @param {string} url - URL of this font xml file.
-     * @param {object} data - Extra font data.
-     * @param xmlData {object} Texture atlas frames data.
-     */
+    * Add a new Bitmap Font.
+    *
+    * @method Phaser.Cache#addBitmapFont
+    * @param {string} key - The unique key by which you will reference this object.
+    * @param {string} url - URL of this font xml file.
+    * @param {object} data - Extra font data.
+    * @param xmlData {object} Texture atlas frames data.
+    */
     addBitmapFont: function (key, url, data, xmlData) {
 
         this._images[key] = { url: url, data: data, spriteSheet: true };
@@ -180,10 +191,10 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Adds a default image to be used when a key is wrong / missing.
-     * Is mapped to the key __default
-     * @method addDefaultImage
-     */
+    * Adds a default image to be used when a key is wrong / missing. Is mapped to the key __default.
+    *
+    * @method Phaser.Cache#addDefaultImage
+    */
     addDefaultImage: function () {
 
         this._images['__default'] = { url: null, data: null, spriteSheet: false };
@@ -200,12 +211,13 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Add a new image.
-     * @method addImage
-     * @param {string} key - Asset key for the image.
-     * @param {string} url - URL of this image file.
-     * @param {object} data - Extra image data.
-     */
+    * Add a new image.
+    *
+    * @method Phaser.Cache#addImage
+    * @param {string} key - The unique key by which you will reference this object.
+    * @param {string} url - URL of this image file.
+    * @param {object} data - Extra image data.
+    */
     addImage: function (key, url, data) {
 
         this._images[key] = { url: url, data: data, spriteSheet: false };
@@ -217,12 +229,15 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Add a new sound.
-     * @method addSound
-     * @param {string} key - Asset key for the sound.
-     * @param {string} url - URL of this sound file.
-     * @param {object} data - Extra sound data.
-     */
+    * Add a new sound.
+    *
+    * @method Phaser.Cache#addSound
+    * @param {string} key - Asset key for the sound.
+    * @param {string} url - URL of this sound file.
+    * @param {object} data - Extra sound data.
+    * @param {boolean} webAudio - True if the file is using web audio.
+    * @param {boolean} audioTag - True if the file is using legacy HTML audio.
+    */
     addSound: function (key, url, data, webAudio, audioTag) {
 
         webAudio = webAudio || true;
@@ -241,10 +256,10 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Reload a sound.
-     * @method reloadSound
-     * @param {string} key - Asset key for the sound.
-     */
+    * Reload a sound.
+    * @method Phaser.Cache#reloadSound
+    * @param {string} key - Asset key for the sound.
+    */
     reloadSound: function (key) {
 
         var _this = this;
@@ -262,10 +277,10 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Description.
-     * @method reloadSoundComplete
-     * @param {string} key - Asset key for the sound.
-     */
+    * Description.
+    * @method Phaser.Cache#reloadSoundComplete
+    * @param {string} key - Asset key for the sound.
+    */
     reloadSoundComplete: function (key) {
 
         if (this._sounds[key])
@@ -277,10 +292,10 @@ Phaser.Cache.prototype = {
     },
 
     /**
-     * Description.
-     * @method updateSound
-     * @param {string} key - Asset key for the sound.
-     */
+    * Description.
+    * @method Phaser.Cache#updateSound
+    * @param {string} key - Asset key for the sound.
+    */
     updateSound: function (key, property, value) {
         
         if (this._sounds[key])
@@ -292,6 +307,8 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Add a new decoded sound.
+    *
+    * @method Phaser.Cache#decodedSound
 	* @param {string} key - Asset key for the sound.
 	* @param {object} data - Extra sound data.
 	*/
@@ -305,6 +322,8 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Add a new text data.
+    *
+    * @method Phaser.Cache#addText
 	* @param {string} key - Asset key for the text data. 
 	* @param {string} url - URL of this text data file.
 	* @param {object} data - Extra text data.
@@ -319,7 +338,9 @@ Phaser.Cache.prototype = {
     },
 
 	/**
-	* Get canvas by key.
+	* Get acanvas object from the cache by its key.
+    *
+    * @method Phaser.Cache#getCanvas
 	* @param {string} key - Asset key of the canvas you want.
 	* @return {object} The canvas you want.
 	*/
@@ -335,6 +356,8 @@ Phaser.Cache.prototype = {
 
     /**
     * Checks if an image key exists.
+    *
+    * @method Phaser.Cache#checkImageKey
     * @param {string} key - Asset key of the image you want.
     * @return {boolean} True if the key exists, otherwise false.
     */    
@@ -351,6 +374,8 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Get image data by key.
+    *
+    * @method Phaser.Cache#getImage
 	* @param {string} key - Asset key of the image you want.
 	* @return {object} The image data you want.
 	*/    
@@ -366,8 +391,10 @@ Phaser.Cache.prototype = {
 
     /**
     * Get tilemap data by key.
+    *
+    * @method Phaser.Cache#getTilemap
     * @param {string} key - Asset key of the tilemap you want.
-    * @return {object} The tilemap data. The tileset image is in the data property, the map data in mapData.
+    * @return {Phaser.Tilemap} The tilemap data. The tileset image is in the data property, the map data in mapData.
     */
     getTilemap: function (key) {
 
@@ -381,8 +408,10 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Get frame data by key.
+    *
+    * @method Phaser.Cache#getFrameData
 	* @param {string} key - Asset key of the frame data you want.
-	* @return {object} The frame data you want.
+	* @return {Phaser.Animation.FrameData} The frame data you want.
 	*/
     getFrameData: function (key) {
 
@@ -396,8 +425,10 @@ Phaser.Cache.prototype = {
 
     /**
     * Get a single frame out of a frameData set by key.
+    *
+    * @method Phaser.Cache#getFrameByIndex
     * @param {string} key - Asset key of the frame data you want.
-    * @return {object} The frame data you want.
+    * @return {Phaser.Animation.Frame} The frame data you want.
     */
     getFrameByIndex: function (key, frame) {
 
@@ -411,8 +442,10 @@ Phaser.Cache.prototype = {
 
     /**
     * Get a single frame out of a frameData set by key.
+    *
+    * @method Phaser.Cache#getFrameByName
     * @param {string} key - Asset key of the frame data you want.
-    * @return {object} The frame data you want.
+    * @return {Phaser.Animation.Frame} The frame data you want.
     */
     getFrameByName: function (key, frame) {
 
@@ -426,8 +459,10 @@ Phaser.Cache.prototype = {
 
     /**
     * Get a single frame by key. You'd only do this to get the default Frame created for a non-atlas/spritesheet image.
+    *
+    * @method Phaser.Cache#getFrame
     * @param {string} key - Asset key of the frame data you want.
-    * @return {object} The frame data you want.
+    * @return {Phaser.Animation.Frame} The frame data you want.
     */
     getFrame: function (key) {
 
@@ -441,8 +476,10 @@ Phaser.Cache.prototype = {
 
     /**
     * Get a single frame by key. You'd only do this to get the default Frame created for a non-atlas/spritesheet image.
+    *
+    * @method Phaser.Cache#getTextureFrame
     * @param {string} key - Asset key of the frame data you want.
-    * @return {object} The frame data you want.
+    * @return {Phaser.Animation.Frame} The frame data you want.
     */
     getTextureFrame: function (key) {
 
@@ -456,8 +493,10 @@ Phaser.Cache.prototype = {
 
     /**
     * Get a RenderTexture by key.
+    *
+    * @method Phaser.Cache#getTexture
     * @param {string} key - Asset key of the RenderTexture you want.
-    * @return {object} The RenderTexture you want.
+    * @return {Phaser.RenderTexture} The RenderTexture you want.
     */
     getTexture: function (key) {
 
@@ -472,8 +511,10 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Get sound by key.
+    *
+    * @method Phaser.Cache#getSound
 	* @param {string} key - Asset key of the sound you want.
-	* @return {object} The sound you want.
+	* @return {Phaser.Sound} The sound you want.
 	*/
     getSound: function (key) {
 
@@ -488,6 +529,8 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Get sound data by key.
+    *
+    * @method Phaser.Cache#getSoundData
 	* @param {string} key - Asset key of the sound you want.
 	* @return {object} The sound data you want.
 	*/
@@ -503,9 +546,11 @@ Phaser.Cache.prototype = {
     },
 
 	/**
-	* Check whether an asset is decoded sound.
+	* Check if the given sound has finished decoding.
+    *
+    * @method Phaser.Cache#isSoundDecoded
 	* @param {string} key - Asset key of the sound you want.
-	* @return {object} The sound data you want.
+	* @return {boolean} The decoded state of the Sound object.
 	*/
     isSoundDecoded: function (key) {
 
@@ -517,9 +562,11 @@ Phaser.Cache.prototype = {
     },
 
 	/**
-	* Check whether an asset is decoded sound.
+	* Check if the given sound is ready for playback. A sound is considered ready when it has finished decoding and the device is no longer touch locked.
+    *
+    * @method Phaser.Cache#isSoundReady
 	* @param {string} key - Asset key of the sound you want.
-	* @return {object} The sound data you want.
+	* @return {boolean} True if the sound is decoded and the device is not touch locked.
 	*/
     isSoundReady: function (key) {
 
@@ -528,9 +575,11 @@ Phaser.Cache.prototype = {
     },
 
 	/**
-	* Check whether an asset is sprite sheet.
+	* Check whether an image asset is sprite sheet or not.
+    *
+    * @method Phaser.Cache#isSpriteSheet
 	* @param {string} key - Asset key of the sprite sheet you want.
-	* @return {object} The sprite sheet data you want.
+	* @return {boolean} True if the image is a sprite sheet.
 	*/
     isSpriteSheet: function (key) {
 
@@ -545,6 +594,8 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Get text data by key.
+    *
+    * @method Phaser.Cache#getText
 	* @param {string} key - Asset key of the text data you want.
 	* @return {object} The text data you want.
 	*/
@@ -559,6 +610,14 @@ Phaser.Cache.prototype = {
         
     },
 
+    /**
+    * Get the cache keys from a given array of objects.
+    * Normally you don't call this directly but instead use getImageKeys, getSoundKeys, etc.
+    *
+    * @method Phaser.Cache#getKeys
+    * @param {Array} array - An array of items to return the keys for.
+    * @return {Array} The array of item keys.
+    */
     getKeys: function (array) {
 
         var output = [];
@@ -577,6 +636,8 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Returns an array containing all of the keys of Images in the Cache.
+    *
+    * @method Phaser.Cache#getImageKeys
 	* @return {Array} The string based keys in the Cache.
 	*/
     getImageKeys: function () {
@@ -585,6 +646,8 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Returns an array containing all of the keys of Sounds in the Cache.
+    *
+    * @method Phaser.Cache#getSoundKeys
 	* @return {Array} The string based keys in the Cache.
 	*/
     getSoundKeys: function () {
@@ -593,6 +656,8 @@ Phaser.Cache.prototype = {
 
 	/**
 	* Returns an array containing all of the keys of Text Files in the Cache.
+    *
+    * @method Phaser.Cache#getTextKeys
 	* @return {Array} The string based keys in the Cache.
 	*/
     getTextKeys: function () {
@@ -600,40 +665,49 @@ Phaser.Cache.prototype = {
     },
 
 	/**
-	* Description.
-	* @method removeCanvas
+	* Removes a canvas from the cache.
+    *
+	* @method Phaser.Cache#removeCanvas
+    * @param {string} key - Key of the asset you want to remove.
 	*/
     removeCanvas: function (key) {
         delete this._canvases[key];
     },
 
-	/**
-	* Description.
-	* @method removeImage
-	*/
+    /**
+    * Removes an image from the cache.
+    *
+    * @method Phaser.Cache#removeImage
+    * @param {string} key - Key of the asset you want to remove.
+    */
     removeImage: function (key) {
         delete this._images[key];
     },
 
-	/**
-	* Description.
-	* @method removeSound
-	*/
+    /**
+    * Removes a sound from the cache.
+    *
+    * @method Phaser.Cache#removeSound
+    * @param {string} key - Key of the asset you want to remove.
+    */
     removeSound: function (key) {
         delete this._sounds[key];
     },
 
-	/**
-	* Description.
-	* @method removeText
-	*/
+    /**
+    * Removes a text from the cache.
+    *
+    * @method Phaser.Cache#removeText
+    * @param {string} key - Key of the asset you want to remove.
+    */
     removeText: function (key) {
         delete this._text[key];
     },
 
 	/**
-	* Clean up cache memory.
-	* @method destroy
+	* Clears the cache. Removes every local cache object reference.
+    *
+	* @method Phaser.Cache#destroy
 	*/
     destroy: function () {
 

src/loader/Loader.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.Loader
 */
 
 /**
@@ -116,19 +115,33 @@ Phaser.Loader = function (game) {
 };
 
 /**
- * TextureAtlas data format constants
- */
+* @constant
+* @type {number}
+*/
 Phaser.Loader.TEXTURE_ATLAS_JSON_ARRAY = 0;
+
+/**
+* @constant
+* @type {number}
+*/
 Phaser.Loader.TEXTURE_ATLAS_JSON_HASH = 1;
+
+/**
+* @constant
+* @type {number}
+*/
 Phaser.Loader.TEXTURE_ATLAS_XML_STARLING = 2;
 
 Phaser.Loader.prototype = {
+
 	/**
-	* Description.
+	* You can set a Sprite to be a "preload" sprite by passing it to this method.
+	* A "preload" sprite will have its width or height crop adjusted based on the percentage of the loader in real-time.
+	* This allows you to easily make loading bars for games.
 	*
-	* @method setPreloadSprite
-    * @param {Phaser.Sprite} sprite - Description.
-    * @param {number} direction - Description.
+	* @method Phaser.Loader#setPreloadSprite
+    * @param {Phaser.Sprite} sprite - The sprite that will be cropped during the load.
+    * @param {number} [direction=0] - A value of zero means the sprite width will be cropped, a value of 1 means its height will be cropped.
     */
 	setPreloadSprite: function (sprite, direction) {
 
@@ -153,7 +166,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Check whether asset exists with a specific key.
-	* @method checkKeyExists
+	*
+	* @method Phaser.Loader#checkKeyExists
 	* @param {string} key - Key of the asset you want to check.
 	* @return {boolean} Return true if exists, otherwise return false.
 	*/
@@ -172,7 +186,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Reset loader, this will remove all loaded assets.
-	* @method reset
+	*
+	* @method Phaser.Loader#reset
 	*/
 	reset: function () {
 
@@ -183,12 +198,14 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	* Internal function that adds a new entry to the file list.
-	* @method addToFileList
+	* Internal function that adds a new entry to the file list. Do not call directly.
+	*
+	* @method Phaser.Loader#addToFileList
 	* @param {Description} type - Description.
 	* @param {string} key - Description.
 	* @param {string} url - URL of Description.
 	* @param {Description} properties - Description.
+	* @protected
 	*/
 	addToFileList: function (type, key, url, properties) {
 
@@ -219,7 +236,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Add an image to the Loader.
-	* @method image
+	*
+	* @method Phaser.Loader#image
 	* @param {string} key - Unique asset key of this image file.
 	* @param {string} url - URL of image file.
 	* @param {boolean} overwrite - If an entry with a matching key already exists this will over-write it
@@ -237,7 +255,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Add a text file to the Loader.
-	* @method text
+	*
+	* @method Phaser.Loader#text
 	* @param {string} key - Unique asset key of the text file.
 	* @param {string} url - URL of the text file.
 	* @param {boolean} overwrite - True if Description.
@@ -254,8 +273,9 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	* Add a new sprite sheet loading request.
-	* @method spritesheet
+	* Add a new sprite sheet to the loader.
+	*
+	* @method Phaser.Loader#spritesheet
 	* @param {string} key - Unique asset key of the sheet file.
 	* @param {string} url - URL of the sheet file.
 	* @param {number} frameWidth - Width of each single frame.
@@ -274,8 +294,9 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	* Add a new audio file loading request.
-	* @method audio
+	* Add a new audio file to the loader.
+	*
+	* @method Phaser.Loader#audio
 	* @param {string} key - Unique asset key of the audio file.
 	* @param {Array} urls - An array containing the URLs of the audio files, i.e.: [ 'jump.mp3', 'jump.ogg', 'jump.m4a' ].
 	* @param {boolean} autoDecode - When using Web Audio the audio files can either be decoded at load time or run-time. They can't be played until they are decoded, but this let's you control when that happens. Decoding is a non-blocking async process.
@@ -293,7 +314,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Add a new tilemap loading request.
-	* @method tilemap
+	*
+	* @method Phaser.Loader#tilemap
 	* @param {string} key - Unique asset key of the tilemap data.
 	* @param {string} tilesetURL - The url of the tile set image file.
 	* @param {string} [mapDataURL] - The url of the map data file (csv/json)
@@ -340,7 +362,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Add a new bitmap font loading request.
-	* @method bitmapFont
+	*
+	* @method Phaser.Loader#bitmapFont
 	* @param {string} key - Unique asset key of the bitmap font.
 	* @param {string} textureURL - The url of the font image file.
 	* @param {string} [xmlURL] - The url of the font data file (xml/fnt)
@@ -398,8 +421,9 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	* Description.
-	* @method atlasJSONArray
+	* Add a new texture atlas to the loader. This atlas uses the JSON Array data format.
+	*
+	* @method Phaser.Loader#atlasJSONArray
 	* @param {string} key - Unique asset key of the bitmap font.
 	* @param {Description} atlasURL - The url of the Description.
 	* @param {Description} atlasData - Description.
@@ -411,8 +435,9 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	* Description.
-	* @method atlasJSONHash
+	* Add a new texture atlas to the loader. This atlas uses the JSON Hash data format.
+	*
+	* @method Phaser.Loader#atlasJSONHash
 	* @param {string} key - Unique asset key of the bitmap font.
 	* @param {Description} atlasURL - The url of the Description.
 	* @param {Description} atlasData - Description.
@@ -424,8 +449,9 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	* Description.
-	* @method atlasXML
+	* Add a new texture atlas to the loader. This atlas uses the Starling XML data format.
+	*
+	* @method Phaser.Loader#atlasXML
 	* @param {string} key - Unique asset key of the bitmap font.
 	* @param {Description} atlasURL - The url of the Description.
 	* @param {Description} atlasData - Description.
@@ -437,13 +463,14 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	* Add a new texture atlas loading request.
-	* @method atlas
+	* Add a new texture atlas to the loader.
+	*
+	* @method Phaser.Loader#atlas
 	* @param {string} key - Unique asset key of the texture atlas file.
 	* @param {string} textureURL - The url of the texture atlas image file.
-	* @param {string} [atlasURL] - The url of the texture atlas data file (json/xml)
-	* @param {object} [atlasData] - A JSON or XML data object.
-	* @param {number} [format] - A value describing the format of the data.
+	* @param {string} [atlasURL] - The url of the texture atlas data file (json/xml). You don't need this if you are passing an atlasData object instead.
+	* @param {object} [atlasData] - A JSON or XML data object. You don't need this if the data is being loaded from a URL.
+	* @param {number} [format] - A value describing the format of the data, the default is Phaser.Loader.TEXTURE_ATLAS_JSON_ARRAY.
 	*/
 	atlas: function (key, textureURL, atlasURL, atlasData, format) {
 
@@ -517,10 +544,11 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	 * Remove loading request of a file.
-	 * @method removeFile
-	 * @param key {string} Key of the file you want to remove.
-	 */
+	* Remove loading request of a file.
+	*
+	* @method Phaser.Loader#removeFile
+	* @param key {string} Key of the file you want to remove.
+	*/
 	removeFile: function (key) {
 
 		delete this._fileList[key];
@@ -528,9 +556,10 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	 * Remove all file loading requests.
-	 * @method removeAll
-	 */
+	* Remove all file loading requests.
+	*
+	* @method Phaser.Loader#removeAll
+	*/
 	removeAll: function () {
 
 		this._fileList = {};
@@ -538,9 +567,10 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	 * Load assets.
-	 * @method start
-	 */
+	* Start loading the assets. Normally you don't need to call this yourself as the StateManager will do so.
+	*
+	* @method Phaser.Loader#start
+	*/
 	start: function () {
 
 		if (this.isLoading)
@@ -570,7 +600,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Load files. Private method ONLY used by loader.
-	* @method loadFile
+	*
+	* @method Phaser.Loader#loadFile
 	* @private
 	*/
 	loadFile: function () {
@@ -664,9 +695,10 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	* Load files. Private method ONLY used by loader.
-	* @method getAudioURL
+	* Private method ONLY used by loader.
+	* @method Phaser.Loader#getAudioURL
 	* @param {Description} urls - Description.
+	* @private
 	*/
 	getAudioURL: function (urls) {
 
@@ -690,7 +722,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Error occured when load a file.
-	* @method fileError
+	*
+	* @method Phaser.Loader#fileError
 	* @param {string} key - Key of the error loading file.
 	*/
 	fileError: function (key) {
@@ -708,7 +741,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Called when a file is successfully loaded.
-	* @method fileComplete
+	*
+	* @method Phaser.Loader#fileComplete
 	* @param {string} key - Key of the successfully loaded file.
 	*/
 	fileComplete: function (key) {
@@ -872,7 +906,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Successfully loaded a JSON file.
-	* @method jsonLoadComplete
+	*
+	* @method Phaser.Loader#jsonLoadComplete
 	* @param {string} key - Key of the loaded JSON file.
 	*/
 	jsonLoadComplete: function (key) {
@@ -895,7 +930,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Successfully loaded a CSV file.
-	* @method csvLoadComplete
+	*
+	* @method Phaser.Loader#csvLoadComplete
 	* @param {string} key - Key of the loaded CSV file.
 	*/
 	csvLoadComplete: function (key) {
@@ -911,7 +947,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Error occured when load a JSON.
-	* @method dataLoadError
+	*
+	* @method Phaser.Loader#dataLoadError
 	* @param {string} key - Key of the error loading JSON file.
 	*/
 	dataLoadError: function (key) {
@@ -928,7 +965,8 @@ Phaser.Loader.prototype = {
 
 	/**
 	* Successfully loaded an XML file.
-	* @method xmlLoadComplete
+	*
+	* @method Phaser.Loader#xmlLoadComplete
 	* @param {string} key - Key of the loaded XML file.
 	*/
 	xmlLoadComplete: function (key) {
@@ -976,10 +1014,12 @@ Phaser.Loader.prototype = {
 	},
 
 	/**
-	 * Handle loading next file.
-	 * @param previousKey {string} Key of previous loaded asset.
-	 * @param success {boolean} Whether the previous asset loaded successfully or not.
-	 */
+	* Handle loading next file.
+	*
+	* @param previousKey {string} Key of previous loaded asset.
+	* @param success {boolean} Whether the previous asset loaded successfully or not.
+	* @private
+	*/
 	nextFile: function (previousKey, success) {
 
 		this.progress = Math.round(this.progress + this._progressChunk);

src/loader/Parser.js

@@ -2,19 +2,18 @@
 * @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.Parser
 */
 
-
 /**
-* Description of Phaser.Loader.Parser
+* Phaser.Loader.Parser parses data objects from Phaser.Loader that need more preparation before they can be inserted into the Cache.
 *
-* @class    Phaser.Loader.Parser
+* @class Phaser.Loader.Parser
 */
 Phaser.Loader.Parser = {
 	
     /**
     * Parse frame data from an XML file.
+    * @method Phaser.Loader.Parser.bitmapFont
     * @param {object} xml - XML data you want to parse.
     * @return {FrameData} Generated FrameData object.
     */