From 690a4b4e803e41df0ebd08cd685bea03ee94c11a Mon Sep 17 00:00:00 2001 From: David Clark Date: Mon, 11 Jul 2016 11:09:08 -0700 Subject: [PATCH] Minor corrections to documentation (#2850) * Minor corrections to documentation * More tweaks based on feedback --- js/geo/lng_lat_bounds.js | 4 ++-- js/source/geojson_source.js | 2 +- js/ui/camera.js | 42 +++++++++++++++++++------------------ js/ui/control/geolocate.js | 4 ++-- js/ui/map.js | 21 ++++++++++++------- js/util/browser/browser.js | 8 ------- js/util/evented.js | 2 +- 7 files changed, 41 insertions(+), 42 deletions(-) diff --git a/js/geo/lng_lat_bounds.js b/js/geo/lng_lat_bounds.js index 6d8993019d..f253857b0f 100644 --- a/js/geo/lng_lat_bounds.js +++ b/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>} 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]); diff --git a/js/source/geojson_source.js b/js/source/geojson_source.js index 8864c95e15..e9a969279f 100644 --- a/js/source/geojson_source.js +++ b/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. diff --git a/js/ui/camera.js b/js/ui/camera.js index 2b95837bae..bf913b3337 100644 --- a/js/ui/camera.js +++ b/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} 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} 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=[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 diff --git a/js/ui/control/geolocate.js b/js/ui/control/geolocate.js index 0b9b1f9256..dd211a7036 100644 --- a/js/ui/control/geolocate.js +++ b/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). * */ diff --git a/js/ui/map.js b/js/ui/map.js index 73b235724d..0e88d17f3b 100755 --- a/js/ui/map.js +++ b/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} 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 */ diff --git a/js/util/browser/browser.js b/js/util/browser/browser.js index 9e5d8ee611..c10c8027e3 100755 --- a/js/util/browser/browser.js +++ b/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; diff --git a/js/util/evented.js b/js/util/evented.js index 1a26d227a5..53601daf9f 100644 --- a/js/util/evented.js +++ b/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) {