Merge pull request #839 from OpenGeoscience/improve-docs

Various documentation improvements.

src/fetchQueue.js

@@ -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
@@ -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 = [];
@@ -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) {
@@ -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;
@@ -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) {
@@ -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);
@@ -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) {
@@ -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) {

src/imageTile.js

@@ -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]
    */
@@ -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', {
@@ -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;
@@ -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 () {

src/layer.js

@@ -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) {
@@ -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,

src/osmLayer.js

@@ -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) {
 
@@ -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
@@ -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'

src/registry.js

@@ -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
@@ -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) {
@@ -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);
@@ -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) {
@@ -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