From 5cc254430b864d596a4b7372f3c78ccc249f29fe Mon Sep 17 00:00:00 2001 From: David Manthey Date: Fri, 2 Nov 2018 12:03:08 -0400 Subject: [PATCH 1/2] Move more specifications to typedefs. --- src/fetchQueue.js | 41 +++++++++++++++++++++++------------------ src/imageTile.js | 31 ++++++++++++++----------------- src/tile.js | 31 ++++++++++++++++--------------- 3 files changed, 53 insertions(+), 50 deletions(-) diff --git a/src/fetchQueue.js b/src/fetchQueue.js index 6eba9d85ae..e8f1dc7f9a 100644 --- a/src/fetchQueue.js +++ b/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, thie 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)) { diff --git a/src/imageTile.js b/src/imageTile.js index c6e6107bdb..37e87b2303 100644 --- a/src/imageTile.js +++ b/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)) { diff --git a/src/tile.js b/src/tile.js index 4798fc706d..1f5fc909fc 100644 --- a/src/tile.js +++ b/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) { From 53bf5c297e578096ae984999827eb671bef4e2a7 Mon Sep 17 00:00:00 2001 From: Roni Choudhury <2903332+waxlamp@users.noreply.github.com> Date: Fri, 2 Nov 2018 14:34:17 -0400 Subject: [PATCH 2/2] Update src/fetchQueue.js Co-Authored-By: manthey --- src/fetchQueue.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/fetchQueue.js b/src/fetchQueue.js index e8f1dc7f9a..3e39397eb9 100644 --- a/src/fetchQueue.js +++ b/src/fetchQueue.js @@ -23,7 +23,7 @@ var $ = require('jquery'); * 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, thie number + * 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