Merge pull request #950 from OpenGeoscience/more-typdefs

Move more specifications to typedefs.

src/fetchQueue.js

@@ -1,30 +1,35 @@
 var $ = require('jquery');
 
+/**
+ * @typedef {object} geo.fetchQueue.spec
+ * @property {number} [size=6] The maximum number of concurrent deferred
+ *   objects.
+ * @property {number} [track=600] The number of objects that are tracked that
+ *   trigger checking if any of them have been abandoned.  The fetch queue can
+ *   grow to the greater of this size and the number of items that are still
+ *   needed.  Setting this to a low number will increase processing time, to a
+ *   high number can increase memory.  Ideally, it should reflect the number of
+ *   items that are kept in memory elsewhere.  If `needed` is `null`, this is
+ *   ignored.
+ * @property {function} [needed=null] If set, this function is passed a
+ *   Deferred object and must return a truthy value if the object is still
+ *   needed.
+ */
+
 /**
  * This class implements a queue for Deferred objects.  Whenever one of the
  * objects in the queue completes (resolved or rejected), another item in the
  * queue is processed.  The number of concurrently processing items can be
- * adjusted.  At this time (2015-12-29) most major browsers support 6
- * concurrent requests from any given server, so, when using the queue for
- * tile images, thie number of concurrent requests should be 6 * (number of
- * subdomains serving tiles).
+ * adjusted.
+ *
+ * At this time (2018-11-02) most major browsers support 6 concurrent requests
+ * from any given server, so, when using the queue for tile images, the number
+ * of concurrent requests should be 6 * (number of subdomains serving tiles).
  *
  * @class
  * @alias geo.fetchQueue
- *
- * @param {object} [options] A configuration object for the queue.
- * @param {number} [options.size=6] The maximum number of concurrent deferred
- *    objects.
- * @param {number} [options.track=600] The number of objects that are tracked
- *    that trigger checking if any of them have been abandoned.  The fetch
- *    queue can grow to the greater of this size and the number of items that
- *    are still needed.  Setting this to a low number will increase
- *    processing time, to a high number can increase memory.  Ideally, it
- *    should reflect the number of items that are kept in memory elsewhere.
- *    If needed is null, this is ignored.
- * @param {function} [options.needed=null] If set, this function is passed a
- *    Deferred object and must return a truthy value if the object is still
- *    needed.
+ * @param {geo.fetchQueue.spec} [options] A configuration object for the queue.
+ * @returns {geo.fetchQueue}
  */
 var fetchQueue = function (options) {
   if (!(this instanceof fetchQueue)) {

src/imageTile.js

@@ -1,6 +1,19 @@
 var inherit = require('./inherit');
 var tile = require('./tile');
 
+/**
+ * @typedef {geo.tile.spec} geo.imageTile.spec
+ * @extends {geo.tile.spec}
+ * @property {object} index The global position of the tile.
+ * @property {number} index.x The x-coordinate (the column number).
+ * @property {number} index.y The y-coordinate (the row number).
+ * @property {number} index.level The zoom level.
+ * @property {object} [size] The size of each tile.
+ * @property {number} [size.x=256] Width in pixels.
+ * @property {number} [size.y=256] Height in pixels.
+ * @property {string} [crossDomain='anonymous'] Image CORS attribute.
+ */
+
 /**
  * This class defines a tile that is part of a standard "image pyramid", such
  * as an open street map tile set.  Every tile is uniquely indexed by a row,
@@ -14,23 +27,7 @@ var tile = require('./tile');
  * @class
  * @alias geo.imageTile
  * @extends geo.tile
- * @param {object} spec The tile specification.
- *
- * @param {object} spec.index The global position of the tile.
- * @param {number} spec.index.x The x-coordinate (usually the column number).
- * @param {number} spec.index.y The y-coordinate (usually the row number).
- * @param {number} spec.index.level The zoom level.
- *
- * @param {object?} spec.size The size of each tile.
- * @param {number} [spec.size.x=256] Width in pixels.
- * @param {number} [spec.size.y=256] Height in pixels.
- *
- * @param {string} spec.url A url to the image.
- * @param {string} [spec.crossDomain='anonymous'] Image CORS attribute.
- *
- * @param {object} spec.overlap The size of overlap with neighboring tiles.
- * @param {number} [spec.overlap.x=0]
- * @param {number} [spec.overlap.y=0]
+ * @param {geo.imageTile.spec} spec The tile specification.
  */
 var imageTile = function (spec) {
   if (!(this instanceof imageTile)) {

src/tile.js

@@ -1,5 +1,20 @@
 var $ = require('jquery');
 
+/**
+ * @typedef {object} geo.tile.spec
+ *
+ * @property {object} index The global position of the tile.
+ * @property {number} index.x The x-coordinate (usually the column number).
+ * @property {number} index.y The y-coordinate (usually the row number).
+ * @property {object} size The size of each tile.
+ * @property {number} size.x Width (usually in pixels).
+ * @property {number} size.y Height (usually in pixels).
+ * @property {object|string} url A url or jQuery ajax config object.
+ * @property {object} [overlap] The size of overlap with neighboring tiles.
+ * @property {number} overlap.x=0
+ * @property {number} overlap.y=0
+ */
+
 /**
  * This class defines the raw interface for a "tile" on a map.  A tile is
  * defined as a rectangular section of a map.  The base implementation
@@ -11,21 +26,7 @@ var $ = require('jquery');
  *
  * @class
  * @alias geo.tile
- * @param {object} spec The tile specification.
- *
- * @param {object} spec.index The global position of the tile.
- * @param {number} spec.index.x The x-coordinate (usually the column number).
- * @param {number} spec.index.y The y-coordinate (usually the row number).
- *
- * @param {object} spec.size The size of each tile.
- * @param {number} spec.size.x Width (usually in pixels).
- * @param {number} spec.size.y Height (usually in pixels).
- *
- * @param {object|string} spec.url A url or jQuery ajax config object.
- *
- * @param {object?} spec.overlap The size of overlap with neighboring tiles.
- * @param {number} [spec.overlap.x=0]
- * @param {number} [spec.overlap.y=0]
+ * @param {geo.tile.spec} spec The tile specification.
  * @returns {geo.tile}
  */
 var tile = function (spec) {