Minor corrections to documentation (#2850)

* Minor corrections to documentation

* More tweaks based on feedback

js/geo/lng_lat_bounds.js

@@ -39,7 +39,7 @@ LngLatBounds.prototype = {
     /**
      * Extends the bounding box to include an area represented by a `LngLat` or `LngLatBounds`.
      *
-     * @param {LngLat|LngLatBounds} obj The area that the bounding box will extend to include.
+     * @param {LngLatLike|LngLatBoundsLike} obj The area that the bounding box will extend to include.
      * @returns {LngLatBounds} `this`
      */
     extend: function(obj) {
@@ -146,7 +146,7 @@ LngLatBounds.prototype = {
     /**
      * Returns the bounding box represented as an array.
      *
-     * @returns {array} The bounding box represented as an array, consisting of the
+     * @returns {Array<Array<number>>} The bounding box represented as an array, consisting of the
      *   southwest and northeast coordinates of the bounding represented as arrays of numbers.
      * @example
      * var llb = new mapboxgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);

js/source/geojson_source.js

@@ -14,7 +14,7 @@ module.exports = GeoJSONSource;
  *
  * @class GeoJSONSource
  * @param {Object} [options]
- * @param {Object|string} options.data A GeoJSON data object or a URL to one. The latter is preferable in the case of large GeoJSON objects.
+ * @param {Object|string} [options.data] A GeoJSON data object or a URL to one. The latter is preferable in the case of large GeoJSON objects.
  * @param {number} [options.maxzoom=18] The maximum zoom level at which to preserve detail (1-20).
  * @param {number} [options.buffer=128] The tile buffer, measured in pixels. The buffer extends each
  *   tile's data just past its visible edges, helping to ensure seamless rendering across tile boundaries.

js/ui/camera.js

@@ -18,7 +18,7 @@ var Point = require('point-geometry');
  * @property {number} zoom The destination's zoom level.
  * @property {number} bearing The destination's bearing (rotation), measured in degrees counter-clockwise from north.
  * @property {number} pitch The destination's pitch (tilt), measured in degrees.
- * @property {LngLat} around If a `zoom` is specified, `around` determines the zoom center (defaults to the center of the map).
+ * @property {LngLatLike} around If a `zoom` is specified, `around` determines the zoom center (defaults to the center of the map).
  */
 
 /**
@@ -29,7 +29,7 @@ var Point = require('point-geometry');
  * @typedef {Object} AnimationOptions
  * @property {number} duration The animation's duration, measured in milliseconds.
  * @property {Function} easing The animation's easing function.
- * @property {Array<number>} offset `x` and `y` coordinates representing the animation's origin of movement relative to the map's center.
+ * @property {PointLike} offset `x` and `y` coordinates representing the animation's origin of movement relative to the map's center.
  * @property {boolean} animate If `false`, no animation will occur.
  */
 
@@ -47,7 +47,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * Sets the map's geographical centerpoint. Equivalent to `jumpTo({center: center})`.
      *
      * @param {LngLatLike} center The centerpoint to set.
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -64,7 +64,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      *
      * @param {Array<number>} offset `x` and `y` coordinates by which to pan the map.
      * @param {AnimationOptions} [options]
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -80,7 +80,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      *
      * @param {LngLatLike} lnglat The location to pan the map to.
      * @param {AnimationOptions} [options]
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -103,7 +103,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * Sets the map's zoom level. Equivalent to `jumpTo({zoom: zoom})`.
      *
      * @param {number} zoom The zoom level to set (0-20).
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires zoomstart
      * @fires move
@@ -125,7 +125,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      *
      * @param {number} zoom The zoom level to transition to.
      * @param {AnimationOptions} [options]
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires zoomstart
      * @fires move
@@ -144,7 +144,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * Increases the map's zoom level by 1.
      *
      * @param {AnimationOptions} [options]
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires zoomstart
      * @fires move
@@ -162,7 +162,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * Decreases the map's zoom level by 1.
      *
      * @param {AnimationOptions} [options]
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires zoomstart
      * @fires move
@@ -188,7 +188,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * Sets the maps' bearing (rotation). Equivalent to `jumpTo({bearing: bearing})`.
      *
      * @param {number} bearing The bearing to set, measured in degrees counter-clockwise from north.
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -206,7 +206,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      *
      * @param {number} bearing The bearing to rotate the map to, measured in degrees counter-clockwise from north.
      * @param {AnimationOptions} [options]
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -221,7 +221,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * Rotates the map to a bearing of 0 (due north), with an animated transition.
      *
      * @param {AnimationOptions} [options]
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -235,7 +235,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * Snaps the map's bearing to 0 (due north), if the current bearing is close enough to it (i.e. within the `bearingSnap` threshold).
      *
      * @param {AnimationOptions} [options]
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -258,7 +258,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * Sets the map's pitch (tilt). Equivalent to `jumpTo({pitch: pitch})`.
      *
      * @param {number} pitch The pitch to set, measured in degrees away from the plane of the screen (0-60).
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -279,9 +279,9 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      *     {@link Map#flyTo} for information about the options specific to that animated transition.
      * @param {Function} [options.easing] An easing function for the animated transition.
      * @param {number} [options.padding=0] The amount of padding, in pixels, to allow around the specified bounds.
-     * @param {Array<number>=[0, 0]} [options.offset] The center of the given bounds relative to the map's center, measured in pixels.
+     * @param {PointLike} [options.offset=[0, 0]] The center of the given bounds relative to the map's center, measured in pixels.
      * @param {number} [options.maxZoom] The maximum zoom level to allow when the map view transitions to the specified bounds.
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -319,7 +319,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * details not specified in `options`.
      *
      * @param {CameraOptions} options
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires zoomstart
      * @fires move
@@ -383,7 +383,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * details not specified in `options`.
      *
      * @param {CameraOptions|AnimationOptions} options Options describing the destination and animation of the transition.
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires zoomstart
      * @fires move
@@ -496,7 +496,9 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * evokes flight. The animation seamlessly incorporates zooming and panning to help
      * the user maintain her bearings even after traversing a great distance.
      *
-     * @param {CameraOptions|AnimationOptions} options Options describing the destination and animation of the transition.
+     * @param {Object} options Options describing the destination and animation of the transition.
+     *     Accepts [CameraOptions](#CameraOptions), [AnimationOptions](#AnimationOptions),
+     *     and the following additional options.
      * @param {number} [options.curve=1.42] The zooming "curve" that will occur along the
      *     flight path. A high value maximizes zooming for an exaggerated animation, while a low
      *     value minimizes zooming for an effect closer to {@link Map#easeTo}. 1.42 is the average
@@ -513,7 +515,7 @@ util.extend(Camera.prototype, /** @lends Map.prototype */{
      * @param {number} [options.screenSpeed] The average speed of the animation measured in screenfuls
      *     per second, assuming a linear timing curve. If `options.speed` is specified, this option is ignored.
      * @param {Function} [options.easing] An easing function for the animated transition.
-     * @param {EventData} [eventData] Data to propagate to any event listeners.
+     * @param {Object} [eventData] Data to propagate to any event listeners.
      * @fires movestart
      * @fires zoomstart
      * @fires move

js/ui/control/geolocate.js

@@ -84,7 +84,7 @@ Geolocate.prototype = util.inherit(Control, {
  * @event geolocate
  * @memberof Geolocate
  * @instance
- * @property {EventData} data The returned Position object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition)
+ * @property {Position} data The returned [Position](https://developer.mozilla.org/en-US/docs/Web/API/Position) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition).
  *
  */
 
@@ -94,6 +94,6 @@ Geolocate.prototype = util.inherit(Control, {
  * @event error
  * @memberof Geolocate
  * @instance
- * @property {EventData} data The returned PositionError object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition)
+ * @property {PositionError} data The returned [PositionError](https://developer.mozilla.org/en-US/docs/Web/API/PositionError) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition).
  *
  */

js/ui/map.js

@@ -69,7 +69,7 @@ var defaultOptions = {
  *
  * @class Map
  * @param {Object} options
- * @param {Element|string} options.container The HTML element in which Mapbox GL JS will render the map, or the element's string `id`.
+ * @param {HTMLElement|string} options.container The HTML element in which Mapbox GL JS will render the map, or the element's string `id`.
  * @param {number} [options.minZoom=0] The minimum zoom level of the map (1-20).
  * @param {number} [options.maxZoom=20] The maximum zoom level of the map (1-20).
  * @param {Object|string} [options.style] The map's Mapbox style. This must be an a JSON object conforming to
@@ -98,8 +98,8 @@ var defaultOptions = {
  *   in an HTML element's `class` attribute. To learn more about Mapbox style classes, read about
  *   [Layers](https://www.mapbox.com/mapbox-gl-style-spec/#layers) in the style specification.
  * @param {boolean} [options.attributionControl=true] If `true`, an [Attribution](#Attribution) control will be added to the map.
- * @param {boolean} [options.failIfMajorPerformanceCaveat=false] If `true`, map creation will fail if it is determined
- *   that the performance of the created WebGL context would be too low.
+ * @param {boolean} [options.failIfMajorPerformanceCaveat=false] If `true`, map creation will fail if the performance of Mapbox
+ *   GL JS would be dramatically worse than expected (i.e. a software renderer would be used).
  * @param {boolean} [options.preserveDrawingBuffer=false] If `true`, the map's canvas can be exported to a PNG using `map.getCanvas().toDataURL()`. This is `false` by default as a performance optimization.
  * @param {LngLatBoundsLike} [options.maxBounds] If set, the map will be constrained to the given bounds.
  * @param {boolean} [options.scrollZoom=true] If `true`, the "scroll to zoom" interaction is enabled (see [`ScrollZoomHandler`](#ScrollZoomHandler)).
@@ -393,8 +393,8 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
      * If the map's current zoom level is lower than the new minimum,
      * the map will zoom to the new minimum.
      *
-     * @param {number | null | undefined} minZoom The minimum zoom level to set (0-20).
-     *   If`null` or `undefined` is provided, the function removes the current minimum zoom (i.e. sets it to 0).
+     * @param {?number} minZoom The minimum zoom level to set (0-20).
+     *   If `null` or `undefined` is provided, the function removes the current minimum zoom (i.e. sets it to 0).
      * @returns {Map} `this`
      */
     setMinZoom: function(minZoom) {
@@ -417,8 +417,8 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
      * If the map's current zoom level is higher than the new maximum,
      * the map will zoom to the new maximum.
      *
-     * @param {number} maxZoom The maximum zoom level to set (0-20).
-     *   If`null` or `undefined` is provided, the function removes the current maximum zoom (sets it to 20).
+     * @param {?number} maxZoom The maximum zoom level to set (0-20).
+     *   If `null` or `undefined` is provided, the function removes the current maximum zoom (sets it to 20).
      * @returns {Map} `this`
      */
     setMaxZoom: function(maxZoom) {
@@ -761,7 +761,7 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
      * Sets the filter for the specified style layer.
      *
      * @param {string} layer The ID of the layer to which the filter will be applied.
-     * @param {Array<string>} filter The filter, conforming to the Mapbox Style Specification's
+     * @param {Array} filter The filter, conforming to the Mapbox Style Specification's
      *   [filter definition](https://www.mapbox.com/mapbox-gl-style-spec/#types-filter).
      * @returns {Map} `this`
      * @example
@@ -1236,6 +1236,11 @@ function removeNode(node) {
   * Returns a Boolean indicating whether the browser [supports Mapbox GL JS](https://www.mapbox.com/help/mapbox-browser-support/#mapbox-gl-js).
   *
   * @function supported
+  * @param {Object} options
+  * @param {boolean} [options.failIfMajorPerformanceCaveat=false] If `true`,
+  *   the function will return `false` if the performance of Mapbox GL JS would
+  *   be dramatically worse than expected (i.e. a software renderer would be used).
+  * @return {boolean}
   * @example
   * mapboxgl.supported() // = true
   */

js/util/browser/browser.js

@@ -66,14 +66,6 @@ exports.timed = function (fn, dur, ctx) {
     return function() { abort = true; };
 };
 
-/**
- * Test if the current browser supports Mapbox GL JS
- * @param {Object} options
- * @param {boolean} [options.failIfMajorPerformanceCaveat=false] Return `false`
- *   if the performance of Mapbox GL JS would be dramatically worse than
- *   expected (i.e. a software renderer would be used)
- * @return {boolean}
- */
 exports.supported = require('mapbox-gl-js-supported');
 
 exports.hardwareConcurrency = navigator.hardwareConcurrency || 4;

js/util/evented.js

@@ -81,7 +81,7 @@ var Evented = {
      * Fires an event of the specified type.
      *
      * @param {string} type The type of event to fire.
-     * @param {Object} [data] Data to be passed to any listeners (e.g. {@link EventData}).
+     * @param {Object} [data] Data to be passed to any listeners.
      * @returns {Object} `this`
      */
     fire: function(type, data) {