Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Various documentation improvements. #839

Merged
merged 2 commits into from
Jun 15, 2018
Merged

Various documentation improvements. #839

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1c6eb9
Various documentation improvements.
manthey Jun 6, 2018
a655b08
Merge branch 'master' into improve-docs
manthey Jun 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 32 additions & 20 deletions src/fetchQueue.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,13 @@ module.exports = (function () {
* tile images, thie number of concurrent requests should be 6 * (number of
* subdomains serving tiles).
*
* @class geo.fetchQueue
* @class
* @alias geo.fetchQueue
*
* @param {Object?} [options] A configuration object for the queue
* @param {Number} [options.size=6] The maximum number of concurrent deferred
* @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
* @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
Expand Down Expand Up @@ -55,20 +56,24 @@ module.exports = (function () {

/**
* Get the current queue size.
* @returns {number} The queue size.
*/
Object.defineProperty(this, 'length', {
get: function () { return this._queue.length; }
});

/**
* Get the current number of processing items.
* @returns {number} The number of processing items.
*/
Object.defineProperty(this, 'processing', {
get: function () { return this._processing; }
});

/**
* Remove all items from the queue.
*
* @returns {this}
*/
this.clear = function () {
this._queue = [];
Expand All @@ -78,12 +83,15 @@ module.exports = (function () {

/**
* Add a Deferred object to the queue.
* @param {Deferred} defer Deferred object to add to the queue.
* @param {function} callback a function to call when the item's turn is
*
* @param {jQuery.Deferred} defer Deferred object to add to the queue.
* @param {function} callback A function to call when the item's turn is
* granted.
* @param {boolean} atEnd if false, add the item to the front of the queue
* @param {boolean} atEnd If falsy, add the item to the front of the queue
* if batching is turned off or at the end of the current batch if it is
* turned on. If true, always add the item to the end of the queue.
* turned on. If truthy, always add the item to the end of the queue.
* @returns {jQuery.Deferred} The deferred object that was passed to the
* function.
*/
this.add = function (defer, callback, atEnd) {
if (defer.__fetchQueue) {
Expand Down Expand Up @@ -114,10 +122,11 @@ module.exports = (function () {
/**
* Add an item to the queue. If batches are being used, add it at after
* other items in the same batch.
* @param {Deferred} defer Deferred object to add to the queue.
* @param {boolean} atEnd if false, add the item to the front of the queue
*
* @param {jQuery.Deferred} defer Deferred object to add to the queue.
* @param {boolean} atEnd If falsy, add the item to the front of the queue
* if batching is turned off or at the end of the current batch if it is
* turned on. If true, always add the item to the end of the queue.
* turned on. If truthy, always add the item to the end of the queue.
*/
this._addToQueue = function (defer, atEnd) {
defer.__fetchQueue._batch = this._batch;
Expand All @@ -137,7 +146,8 @@ module.exports = (function () {

/**
* Get the position of a deferred object in the queue.
* @param {Deferred} defer Deferred object to get the position of.
*
* @param {jQuery.Deferred} defer Deferred object to get the position of.
* @returns {number} -1 if not in the queue, or the position in the queue.
*/
this.get = function (defer) {
Expand All @@ -146,8 +156,9 @@ module.exports = (function () {

/**
* Remove a Deferred object from the queue.
* @param {Deferred} defer Deferred object to add to the queue.
* @returns {bool} true if the object was removed
*
* @param {jQuery.Deferred} defer Deferred object to add to the queue.
* @returns {boolean} `true` if the object was removed.
*/
this.remove = function (defer) {
var pos = $.inArray(defer, this._queue);
Expand All @@ -160,10 +171,11 @@ module.exports = (function () {

/**
* Start a new batch or clear using batches.
* @param {boolean} start true to start a new batch, false to turn off
* using batches. Undefined to return the current
* state of batches.
* @return {Number|boolean|Object} the current batch state or this object.
*
* @param {boolean} start Truthy too start a new batch, falsy to turn off
* using batches. `undefined` to return the current state of batches.
* @returns {number|boolean|this} `false` if batches are turned off, the
* batch number if turned on, or `this` if setting the batch.
*/
this.batch = function (start) {
if (start === undefined) {
Expand All @@ -179,8 +191,8 @@ module.exports = (function () {
};

/**
* Check if any items are queued and if there if there are not too many
* deferred objects being processed. If so, process more items.
* Check if any items are queued and if the processing allotment is not
* full. If so, process more items.
*/
this.next_item = function () {
if (m_this._innextitem) {
Expand Down
43 changes: 24 additions & 19 deletions src/imageTile.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,22 +14,24 @@ module.exports = (function () {
* subclasses may define additional rendering steps to produce the images
* before passing them off to the handlers.
*
* @class geo.imageTile
* @param {object} spec The tile specification object
* @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.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 {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 {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 {object} spec.overlap The size of overlap with neighboring tiles.
* @param {number} [spec.overlap.x=0]
* @param {number} [spec.overlap.y=0]
*/
Expand All @@ -53,6 +55,7 @@ module.exports = (function () {
* tile. Note, this method does not gaurantee that the
* image data is available. Use the promise interface
* to add asyncronous handlers.
*
* @returns {Image}
*/
Object.defineProperty(this, 'image', {
Expand All @@ -62,7 +65,7 @@ module.exports = (function () {
/**
* Initiate the image request.
*
* @returns {this} The current tile class instance.
* @returns {this}
*/
this.fetch = function () {
var defer;
Expand All @@ -87,14 +90,16 @@ module.exports = (function () {
};

/**
* Set the opacity of the tile to 0 and gradually fade in
* over the given number of milliseconds. This will also
* resolve the embedded promise interface.
* @param {number} duration the duration of the animation in ms
* @returns {this} chainable
* Set the opacity of the tile to 0 and gradually fade in over the given
* number of milliseconds. This will also resolve the embedded promise
* interface.
*
* @param {number} duration The duration of the animation in ms.
* @returns {this}
*/
this.fadeIn = function (duration) {
var promise = this.fetch(), defer = $.Deferred();
var promise = this.fetch(),
defer = $.Deferred();
$(this._image).css('display', 'none');
promise.done(function () {
$(this._image).fadeIn(duration, function () {
Expand Down
34 changes: 30 additions & 4 deletions src/layer.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,35 @@ var rendererForAnnotations = require('./registry').rendererForAnnotations;
* @alias geo.layer
* @extends geo.sceneObject
* @param {object} [arg] Options for the new layer.
* @param {string} arg.attribution An attribution string to display
* @param {number} arg.zIndex The z-index to assign to the layer (defaults
* to the index of the layer inside the map)
* @param {number} [arg.id] The id of the layer. Defaults to a increasing
* sequence.
* @param {geo.map} [arg.map=null] Parent map of the layer.
* @param {string|geo.renderer} [arg.renderer] Renderer to associate with the
* layer. If not specified, either `arg.annotations` or `arg.features` can
* be used to determine the renderer.
* @param {string[]|object} [arg.annotations] A list of annotations that will
* be used on this layer, used to select a renderer. Instead of a list, if
* this is an object, the keys are the annotation names, and the values are
* each a list of modes that will be used with that annotation. See
* `featuresForAnnotations` more details. This is ignored if `arg.renderer`
* is specified.
* @param {string[]} [arg.features] A list of features that will be used on
* this layer, used to select a renderer. Features are the basic feature
* names (e.g., `'quad'`), or the feature name followed by a required
* capability (e.g., `'quad.image'`). This is ignored if `arg.renderer` or
* `arg.annotations` is specified.
* @param {boolean} [arg.active=true] Truthy if the layer has the `active` css
* class and may receive native mouse events.
* @param {string} [arg.attribution] An attribution string to display.
* @param {number} [arg.opacity=1] The layer opacity on a scale of [0-1].
* @param {string} [arg.name=''] A name for the layer for user convenience.
* @param {boolean} [arg.selectionAPI=true] Truthy if the layer can generate
* selection and other interaction events.
* @param {boolean} [arg.sticky=true] Truthy if the layer should navigate with
* the map.
* @param {boolean} [arg.visible=true] Truthy if the layer is visible.
* @param {number} [arg.zIndex] The z-index to assign to the layer (defaults
* to the index of the layer inside the map).
* @returns {geo.layer}
*/
var layer = function (arg) {
Expand All @@ -39,7 +65,7 @@ var layer = function (arg) {
var m_this = this,
s_exit = this._exit,
m_id = arg.id === undefined ? layer.newLayerId() : arg.id,
m_name = '',
m_name = arg.name === undefined ? '' : arg.name,
m_map = arg.map === undefined ? null : arg.map,
m_node = null,
m_canvas = null,
Expand Down
31 changes: 14 additions & 17 deletions src/osmLayer.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,17 @@ module.exports = (function () {
var quadFeature = require('./quadFeature');

/**
* Create a new instance of osmLayer.
* Create a new instance of osmLayer. This is a `geo.tileLayer` with an
* OSM url and attribution defaults and with the tiles centered on the
* origin.
*
* @class geo.osmLayer
* @extends geo.featureLayer
* @class
* @alias geo.osmLayer
* @extends geo.tileLayer
*
* @param {object} arg - arg can contain following keys: baseUrl,
* imageFormat (such as png or jpeg), and displayLast
* (to decide whether or not render tiles from last zoom level).
* @param {object} arg
* @param {number} [arg.mapOpacity] If specified, and `arg.opacity` is not
* specified, use this as the layer opacity.
*/
var osmLayer = function (arg) {

Expand All @@ -34,13 +37,14 @@ module.exports = (function () {

/**
* Returns an instantiated imageTile object with the given indices. This
* method always returns a new tile object. Use `_getTileCached`
* to use the caching layer.
* @param {object} index The tile index
* method always returns a new tile object. Use `_getTileCached` to use
* the caching layer.
*
* @param {object} index The tile index.
* @param {number} index.x
* @param {number} index.y
* @param {number} index.level
* @param {object} source The tile index used for constructing the url
* @param {object} source The tile index used for constructing the url.
* @param {number} source.x
* @param {number} source.y
* @param {number} source.level
Expand All @@ -66,17 +70,10 @@ module.exports = (function () {
* This object contains the default options used to initialize the osmLayer.
*/
osmLayer.defaults = $.extend({}, tileLayer.defaults, {
minLevel: 0,
maxLevel: 18,
tileOverlap: 0,
tileWidth: 256,
tileHeight: 256,
tileOffset : function (level) {
var s = Math.pow(2, level - 1) * 256;
return {x: s, y: s};
},
wrapX: true,
wrapY: false,
url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
attribution: 'Tile data &copy; <a href="http://osm.org/copyright">' +
'OpenStreetMap</a> contributors'
Expand Down
12 changes: 6 additions & 6 deletions src/registry.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ util.checkRenderer = function (name, noFallback) {
* features. If not, display a warning. This picks the first renderer that
* supports all of the listed features.
*
* @param {array|undefined} featureList A list of features that will be used
* @param {string[]|undefined} featureList A list of features that will be used
* with this renderer. Features are the basic feature names (e.g.,
* `'quad'`), or the feature name followed by a required capability (e.g.,
* `'quad.image'`). If more than one feature or more than one capability
Expand Down Expand Up @@ -273,7 +273,7 @@ util.adjustLayerForRenderer = function (name, layer) {
* @param {string} name Name of the layer to register. If the name already
* exists, the class creation function is replaced.
* @param {function} func Class creation function.
* @param {array} [defaultFeatures] An optional list of feature capabailities
* @param {string[]} [defaultFeatures] An optional list of feature capabilities
* that are required to use this layer.
*/
util.registerLayer = function (name, func, defaultFeatures) {
Expand Down Expand Up @@ -399,7 +399,7 @@ util.createAnnotation = function (name, options) {
/**
* Get a list of registered annotation types.
*
* @returns {array} A list of registered annotations.
* @returns {string[]} A list of registered annotations.
*/
util.listAnnotations = function () {
return Object.keys(annotations);
Expand All @@ -408,14 +408,14 @@ util.listAnnotations = function () {
/**
* Get a list of required features for a set of annotations.
*
* @param {array|object|undefined} annotationList A list of annotations that
* @param {string[]|object|undefined} annotationList A list of annotations that
* will be used. Instead of a list, if this is an object, the keys are the
* annotation names, and the values are each a list of modes that will be
* used with that annotation. For example, ['polygon', 'rectangle'] lists
* features required to show those annotations in any mode, whereas
* {polygon: [annotationState.done], rectangle: [annotationState.done]} only
* lists features that are needed to show the completed annotations.
* @returns {array} a list of features needed for the specified annotations.
* @returns {string[]} a list of features needed for the specified annotations.
* There may be duplicates in the list.
*/
util.featuresForAnnotations = function (annotationList) {
Expand Down Expand Up @@ -447,7 +447,7 @@ util.featuresForAnnotations = function (annotationList) {
* annotations. If not, display a warning. This generates a list of required
* features, then picks the first renderer that supports all of these features.
*
* @param {array|object|undefined} annotationList A list of annotations that
* @param {string[]|object|undefined} annotationList A list of annotations that
* will be used with this renderer. Instead of a list, if this is an object,
* the keys are the annotation names, and the values are each a list of modes
* that will be used with that annotation. See featuresForAnnotations for
Expand Down
Loading