Added jsdocs

Author: photonstorm

CHANGELOG.md

@@ -87,6 +87,7 @@ The Loader has been given an overhaul to improve its performance and extensibili
 * The Graphics Creator would automatically add the Graphics to the display list by mistake. The default should be to remain hidden. Fix #3637 (thanks @mikuso)
 * BitmapText, both static and dynamic, can now take any data-type, including numbers, for the `text` argument in the constructor. Before they only worked via `setText` (thanks @Jelaw21)
 * The Forward Diffuse Light Pipeline was hard coded to assume the normal map would be stored in the source index zero. It now correctly obtains the normal map from the frame source index, which means all Game Objects that used frames from multi-atlas textures will now work with lights properly.
+* The Tiled Base64Decode function worked off the wrong array length, causing extra undefined values at the end (thanks @tamagokun)
 
 ### Examples, Documentation and TypeScript
 

src/loader/File.js

@@ -12,12 +12,6 @@ var MergeXHRSettings = require('./MergeXHRSettings');
 var XHRLoader = require('./XHRLoader');
 var XHRSettings = require('./XHRSettings');
 
-/**
- * @callback FileProcessCallback
- *
- * @param {Phaser.Loader.File} file - [description]
- */
-
 /**
  * @typedef {object} FileConfig
  *
@@ -33,15 +27,16 @@ var XHRSettings = require('./XHRSettings');
 
 /**
  * @classdesc
- * [description]
+ * The base File class used by all File Types that the Loader can support.
+ * You shouldn't create an instance of a File directly, but should extend it with your own class, setting a custom type and processing methods.
  *
  * @class File
  * @memberOf Phaser.Loader
  * @constructor
  * @since 3.0.0
  *
  * @param {Phaser.Loader.LoaderPlugin} loader - The Loader that is going to load this File.
- * @param {FileConfig} fileConfig - [description]
+ * @param {FileConfig} fileConfig - The file configuration object, as created by the file type.
  */
 var File = new Class({
 
@@ -99,6 +94,7 @@ var File = new Class({
 
         /**
          * The URL of the file, not including baseURL.
+         * Automatically has Loader.path prepended to it.
          *
          * @name Phaser.Loader.File#url
          * @type {string}
@@ -116,7 +112,8 @@ var File = new Class({
         }
 
         /**
-         * Set when the Loader calls 'load' on this file.
+         * The final URL this file will load from, including baseURL and path.
+         * Set automatically when the Loader calls 'load' on this file.
          *
          * @name Phaser.Loader.File#src
          * @type {string}
@@ -200,7 +197,7 @@ var File = new Class({
         this.crossOrigin = undefined;
 
         /**
-         * The processed file data, stored in here after the file has loaded.
+         * The processed file data, stored here after the file has loaded.
          *
          * @name Phaser.Loader.File#data
          * @type {*}
@@ -212,14 +209,14 @@ var File = new Class({
          * A config object that can be used by file types to store transitional data.
          *
          * @name Phaser.Loader.File#config
-         * @type {object}
+         * @type {*}
          * @since 3.0.0
          */
         this.config = GetFastValue(fileConfig, 'config', {});
 
         /**
          * If this is a multipart file, i.e. an atlas and its json together, then this is a reference
-         * to the linked file. Set and used internally by the Loader.
+         * to the parent MultiFile. Set and used internally by the Loader or specific file types.
          *
          * @name Phaser.Loader.File#multiFile
          * @type {?Phaser.Loader.MultiFile}
@@ -239,6 +236,14 @@ var File = new Class({
         this.linkFile;
     },
 
+    /**
+     * Links this File with another, so they depend upon each other for loading and processing.
+     *
+     * @method Phaser.Loader.File#setLink
+     * @since 3.7.0
+     *
+     * @param {Phaser.Loader.File} fileB - The file to link to this one.
+     */
     setLink: function (fileB)
     {
         this.linkFile = fileB;
@@ -247,7 +252,7 @@ var File = new Class({
     },
 
     /**
-     * Resets the XHRLoader instance.
+     * Resets the XHRLoader instance this file is using.
      *
      * @method Phaser.Loader.File#resetXHR
      * @since 3.0.0
@@ -264,7 +269,8 @@ var File = new Class({
 
     /**
      * Called by the Loader, starts the actual file downloading.
-     * During the load the methods onLoad, onProgress, etc are called based on the XHR events.
+     * During the load the methods onLoad, onError and onProgress are called, based on the XHR events.
+     * You shouldn't normally call this method directly, it's meant to be invoked by the Loader.
      *
      * @method Phaser.Loader.File#load
      * @since 3.0.0
@@ -289,9 +295,9 @@ var File = new Class({
                 //  The creation of this XHRLoader starts the load process going.
                 //  It will automatically call the following, based on the load outcome:
                 //  
-                // xhr.onload = file.onLoad.bind(file);
-                // xhr.onerror = file.onError.bind(file);
-                // xhr.onprogress = file.onProgress.bind(file);
+                // xhr.onload = this.onLoad
+                // xhr.onerror = this.onError
+                // xhr.onprogress = this.onProgress
 
                 this.xhrLoader = XHRLoader(this, this.loader.xhr);
             }
@@ -352,7 +358,8 @@ var File = new Class({
     },
 
     /**
-     * Usually overridden by the FileTypes and is called by Loader.finishedLoading.
+     * Usually overridden by the FileTypes and is called by Loader.nextFile.
+     * This method controls what extra work this File does with its loaded data, for example a JSON file will parse itself during this stage.
      *
      * @method Phaser.Loader.File#onProcess
      * @since 3.0.0
@@ -365,7 +372,7 @@ var File = new Class({
     },
 
     /**
-     * Called when the File has completed loading.
+     * Called when the File has completed processing.
      * Checks on the state of its multifile, if set.
      *
      * @method Phaser.Loader.File#onProcessComplete
@@ -384,7 +391,7 @@ var File = new Class({
     },
 
     /**
-     * Called when the File has completed loading.
+     * Called when the File has completed processing but it generated an error.
      * Checks on the state of its multifile, if set.
      *
      * @method Phaser.Loader.File#onProcessError
@@ -419,7 +426,6 @@ var File = new Class({
 
     /**
      * Adds this file to its target cache upon successful loading and processing.
-     * It will emit a `filecomplete` event from the LoaderPlugin.
      * This method is often overridden by specific file types.
      *
      * @method Phaser.Loader.File#addToCache
@@ -435,12 +441,20 @@ var File = new Class({
         this.pendingDestroy();
     },
 
+    /**
+     * @event Phaser.Loader.File#fileCompleteEvent
+     * @param {string} key - The key of the file that just loaded and finished processing.
+     * @param {string} type - The type of the file that just loaded and finished processing.
+     * @param {any} data - The data of the file.
+     */
+
     /**
      * Adds this file to its target cache upon successful loading and processing.
      * It will emit a `filecomplete` event from the LoaderPlugin.
      * This method is often overridden by specific file types.
      *
      * @method Phaser.Loader.File#pendingDestroy
+     * @fires Phaser.Loader.File#fileCompleteEvent
      * @since 3.7.0
      */
     pendingDestroy: function (data)

src/loader/FileTypesManager.js

@@ -8,6 +8,17 @@ var types = {};
 
 var FileTypesManager = {
 
+    /**
+     * Static method called when a LoaderPlugin is created.
+     * 
+     * Loops through the local types object and injects all of them as
+     * properties into the LoaderPlugin instance.
+     *
+     * @method Phaser.Loader.FileTypesManager.register
+     * @since 3.0.0
+     * 
+     * @param {Phaser.Loader.LoaderPlugin} loader - The LoaderPlugin to install the types into.
+     */
     install: function (loader)
     {
         for (var key in types)
@@ -16,13 +27,28 @@ var FileTypesManager = {
         }
     },
 
+    /**
+     * Static method called directly by the File Types.
+     * 
+     * The key is a reference to the function used to load the files via the Loader, i.e. `image`.
+     *
+     * @method Phaser.Loader.FileTypesManager.register
+     * @since 3.0.0
+     * 
+     * @param {string} key - The key that will be used as the method name in the LoaderPlugin.
+     * @param {function} factoryFunction - The function that will be called when LoaderPlugin.key is invoked.
+     */
     register: function (key, factoryFunction)
     {
         types[key] = factoryFunction;
-
-        // console.log('FileTypesManager.register', key);
     },
 
+    /**
+     * Removed all associated file types.
+     *
+     * @method Phaser.Loader.FileTypesManager.destroy
+     * @since 3.0.0
+     */
     destroy: function ()
     {
         types = {};

src/loader/MultiFile.js

@@ -8,7 +8,10 @@ var Class = require('../utils/Class');
 
 /**
  * @classdesc
- * [description]
+ * A MultiFile is a special kind of parent that contains two, or more, Files as children and looks after
+ * the loading and processing of them all. It is commonly extended and used as a base class for file types such as AtlasJSON or BitmapFont.
+ * 
+ * You shouldn't create an instance of a MultiFile directly, but should extend it with your own class, setting a custom type and processing methods.
  *
  * @class MultiFile
  * @memberOf Phaser.Loader
@@ -67,6 +70,7 @@ var MultiFile = new Class({
          *
          * @name Phaser.Loader.MultiFile#complete
          * @type {boolean}
+         * @default false
          * @since 3.7.0
          */
         this.complete = false;
@@ -91,6 +95,13 @@ var MultiFile = new Class({
          */
         this.failed = 0;
 
+        /**
+         * A storage container for transient data that the loading files need.
+         *
+         * @name Phaser.Loader.MultiFile#config
+         * @type {any}
+         * @since 3.7.0
+         */
         this.config = {};
 
         //  Link the files
@@ -100,11 +111,29 @@ var MultiFile = new Class({
         }
     },
 
+    /**
+     * Checks if this MultiFile is ready to process its children or not.
+     *
+     * @method Phaser.Loader.MultiFile#isReadyToProcess
+     * @since 3.7.0
+     *
+     * @return {boolean} `true` if all children of this MultiFile have loaded, otherwise `false`.
+     */
     isReadyToProcess: function ()
     {
         return (this.pending === 0 && this.failed === 0 && !this.complete);
     },
 
+    /**
+     * Adds another child to this MultiFile, increases the pending count and resets the completion status.
+     *
+     * @method Phaser.Loader.MultiFile#addToMultiFile
+     * @since 3.7.0
+     *
+     * @param {Phaser.Loader.File} files - The File to add to this MultiFile.
+     *
+     * @return {Phaser.Loader.MultiFile} This MultiFile instance.
+     */
     addToMultiFile: function (file)
     {
         this.files.push(file);