Jsdocs: Tilemap Creator & Factor

Author: mikewesthad

v3/src/gameobjects/tilemap/TilemapCreator.js

@@ -3,18 +3,30 @@ var ParseToTilemap = require('./ParseToTilemap');
 
 //  When registering a factory function 'this' refers to the GameObjectCreator context.
 
+/**
+ * Creates a Tilemap from the given key or data, or creates a blank Tilemap if no key/data provided.
+ *
+ * @param {object} [config] - The config options for the Tilemap.
+ * @param {string} [config.key] - The key in the Phaser cache that corresponds to the loaded tilemap
+ * data.
+ * @param {array} [config.data] - Instead of loading from the cache, you can also load directly from
+ * a 2D array of tile indexes.
+ * @param {number} [config.tileWidth=32] - The width of a tile in pixels.
+ * @param {number} [config.tileHeight=32] - The height of a tile in pixels.
+ * @param {number} [config.width=10] - The width of the map in tiles.
+ * @param {number} [config.height=10] - The height of the map in tiles.
+ * @param {boolean} [config.insertNull=false] - Controls how empty tiles, tiles with an index of -1,
+ * in the map data are handled. If `true`, empty locations will get a value of `null`. If `false`,
+ * empty location will get a Tile object with an index of -1. If you've a large sparsely populated
+ * map and the tile data doesn't need to change then setting this value to `true` will help with
+ * memory consumption. However if your map is small or you need to update the tiles dynamically,
+ * then leave the default value set.
+ * @returns {Tilemap}
+ */
 GameObjectCreator.register('tilemap', function (config)
 {
-    // config {
-    //     key: undefined, (string|number),
-    //     tileWidth: 32,
-    //     tileHeight: 32,
-    //     width: 10,
-    //     height: 10,
-    //     data: null (2D array of tile indexes),
-    //     insertNull: false
-    // }
-
+    // Defaults are applied in ParseToTilemap
     var c = config !== undefined ? config : {};
-    return ParseToTilemap(this.scene, c.key, c.tileWidth, c.tileHeight, c.width, c.height, c.data, c.insertNull);
+    return ParseToTilemap(this.scene, c.key, c.tileWidth, c.tileHeight, c.width, c.height, c.data,
+        c.insertNull);
 });

v3/src/gameobjects/tilemap/TilemapFactory.js

@@ -1,7 +1,6 @@
 var GameObjectFactory = require('../../scene/plugins/GameObjectFactory');
 var ParseToTilemap = require('./ParseToTilemap');
 
-
 //  When registering a factory function 'this' refers to the GameObjectFactory context.
 //
 //  There are several properties available to use:
@@ -10,17 +9,38 @@ var ParseToTilemap = require('./ParseToTilemap');
 //  this.displayList - a reference to the Display List the Scene owns
 //  this.updateList - a reference to the Update List the Scene owns
 
+/**
+ * Creates a Tilemap from the given key or data, or creates a blank Tilemap if no key/data provided.
+ *
+ * @param {string} [key] - The key in the Phaser cache that corresponds to the loaded tilemap data.
+ * @param {number} [tileWidth=32] - The width of a tile in pixels. Pass in `null` to leave as the
+ * default.
+ * @param {number} [tileHeight=32] - The height of a tile in pixels. Pass in `null` to leave as the
+ * default.
+ * @param {number} [width=10] - The width of the map in tiles. Pass in `null` to leave as the
+ * default.
+ * @param {number} [height=10] - The height of the map in tiles. Pass in `null` to leave as the
+ * default.
+ * @param {array} [data] - Instead of loading from the cache, you can also load directly from a 2D
+ * array of tile indexes. Pass in `null` for no data.
+ * @param {boolean} [insertNull=false] - Controls how empty tiles, tiles with an index of -1, in the
+ * map data are handled. If `true`, empty locations will get a value of `null`. If `false`, empty
+ * location will get a Tile object with an index of -1. If you've a large sparsely populated map and
+ * the tile data doesn't need to change then setting this value to `true` will help with memory
+ * consumption. However if your map is small or you need to update the tiles dynamically, then leave
+ * the default value set.
+ * @returns {Tilemap}
+ */
 GameObjectFactory.register('tilemap', function (key, tileWidth, tileHeight, width, height, data, insertNull)
 {
-    // Allow users to specify null as default parameter, but convert it to undefined to match what
-    // the creator function passed to the parser.
+    // Allow users to specify null to indicate that they want the default value, since null is
+    // shorter & more legible than undefined. Convert null to undefined to allow ParseToTilemap
+    // defaults to take effect.
     if (key === null) { key = undefined; }
     if (tileWidth === null) { tileWidth = undefined; }
     if (tileHeight === null) { tileHeight = undefined; }
     if (width === null) { width = undefined; }
     if (height === null) { height = undefined; }
-    if (data === null) { data = undefined; }
-    if (insertNull === null) { insertNull = undefined; }
 
     return ParseToTilemap(this.scene, key, tileWidth, tileHeight, width, height, data, insertNull);
 });