From 410fa94b88248664fb17205520b640b2e9a01b3e Mon Sep 17 00:00:00 2001
From: Adriana Babakanian <adriana.babakanian@mapbox.com>
Date: Mon, 20 Apr 2020 11:47:07 -0700
Subject: [PATCH 01/74] [docsprint] Clarify meaning of Map#isSourceLoaded
 (#9589)

---
 src/ui/map.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index c1e5eee4dad..8adcef4735c 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1393,7 +1393,8 @@ class Map extends Camera {
     }
 
     /**
-     * Returns a Boolean indicating whether the source is loaded.
+     * Returns a Boolean indicating whether the source is loaded. Returns `true` if the source with
+     * the given ID in the map's style has no outstanding network requests, otherwise `false`.
      *
      * @param {string} id The ID of the source to be checked.
      * @returns {boolean} A Boolean indicating whether the source is loaded.

From 9f1891832458570ece222c2256a45b351bee6175 Mon Sep 17 00:00:00 2001
From: Sam Fader <samfader@users.noreply.github.com>
Date: Mon, 20 Apr 2020 11:48:25 -0700
Subject: [PATCH 02/74] [docsprint] Add geolocate trigger example (#9552)

Co-authored-by: Adriana Babakanian <adriana.babakanian@mapbox.com>
---
 src/ui/control/geolocate_control.js | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/ui/control/geolocate_control.js b/src/ui/control/geolocate_control.js
index 0e5f5e80736..34ff7731d3c 100644
--- a/src/ui/control/geolocate_control.js
+++ b/src/ui/control/geolocate_control.js
@@ -406,10 +406,23 @@ class GeolocateControl extends Evented {
     }
 
     /**
-     * Trigger a geolocation
-     *
-     * @returns {boolean} Returns `false` if called before control was added to a map, otherwise returns `true`.
-     */
+    * Trigger a geolocation
+    *
+    * @returns {boolean} Returns `false` if called before control was added to a map, otherwise returns `true`.
+    * @example
+    * // Initialize the geolocate control.
+    * var geolocate = new mapboxgl.GeolocateControl({
+    *  positionOptions: {
+    *    enableHighAccuracy: true
+    *  },
+    *  trackUserLocation: true
+    * });
+    * // Add the control to the map.
+    * map.addControl(geolocate);
+    * map.on('load', function() {
+    *   geolocate.trigger();
+    * }
+    */
     trigger() {
         if (!this._setup) {
             warnOnce('Geolocate control triggered before added to a map');

From d54cef2508f4d115e2823bf1135139a33812d24f Mon Sep 17 00:00:00 2001
From: Heather Stenson <heather.stenson@mapbox.com>
Date: Mon, 20 Apr 2020 11:49:13 -0700
Subject: [PATCH 03/74] [docsprint] Add inline snippet to marker#addTo (#9592)

---
 src/ui/marker.js | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/ui/marker.js b/src/ui/marker.js
index 55484adb013..4904799baee 100644
--- a/src/ui/marker.js
+++ b/src/ui/marker.js
@@ -216,9 +216,13 @@ export default class Marker extends Evented {
     }
 
     /**
-     * Attaches the marker to a map
+     * Attaches the `Marker` to a `Map` object.
      * @param {Map} map The Mapbox GL JS map to add the marker to.
      * @returns {Marker} `this`
+     * @example
+     * var marker = new mapboxgl.Marker()
+     *   .setLngLat([30.5, 50.5])
+     *   .addTo(map); // add the marker to the map
      */
     addTo(map: Map) {
         this.remove();

From 0f7c8b984ec31e9eaa238e90bf7c407ea82458fb Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Mon, 20 Apr 2020 14:44:49 -0700
Subject: [PATCH 04/74] [docsprint] Add inline snippet and related examples to
 popup.setHTML (#9538)

* add inline snippet and related examples to popup.setHTML

* update see URLs to docs subdomain
---
 src/ui/popup.js | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/ui/popup.js b/src/ui/popup.js
index 8acb87e2192..b2803888863 100644
--- a/src/ui/popup.js
+++ b/src/ui/popup.js
@@ -293,6 +293,15 @@ export default class Popup extends Evented {
      *
      * @param html A string representing HTML content for the popup.
      * @returns {Popup} `this`
+     * @example
+     * var popup = new mapboxgl.Popup()
+     *   .setLngLat(e.lngLat)
+     *   .setHTML("<h1>Hello World!</h1>")
+     *   .addTo(map);
+     * @see [Display a popup](https://docs.mapbox.com/mapbox-gl-js/example/popup/)
+     * @see [Display a popup on hover](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-hover/)
+     * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
+     * @see [Attach a popup to a marker instance](https://docs.mapbox.com/mapbox-gl-js/example/set-popup/)
      */
     setHTML(html: string) {
         const frag = window.document.createDocumentFragment();

From c625efa546903f1018b1e57517d3313d9b622b48 Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Mon, 20 Apr 2020 17:45:24 -0400
Subject: [PATCH 05/74] Add inline and related example for panTo (#9547)

---
 src/ui/camera.js | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index e78443f14d9..a02c8bace9f 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -156,15 +156,21 @@ class Camera extends Evented {
     }
 
     /**
-     * Pans the map to the specified location, with an animated transition.
+     * Pans the map to the specified location with an animated transition.
      *
      * @memberof Map#
      * @param lnglat The location to pan the map to.
-     * @param options Options object
+     * @param options Options describing the destination and animation of the transition.
      * @param eventData Additional properties to be added to event objects of events triggered by this method.
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
+     * @example
+     * map.panTo([-74, 38]);
+     * @example
+     * // Change the duration of panTo to 5000 milliseconds.
+     * map.panTo([-74, 38], {duration: 5000});
+     * @see [Update a feature in realtime](https://docs.mapbox.com/mapbox-gl-js/example/live-update-feature/)
      */
     panTo(lnglat: LngLatLike, options?: AnimationOptions, eventData?: Object) {
         return this.easeTo(extend({

From 4ed7ca898b71f2384fe0c79ac1aa7267cea6cdb3 Mon Sep 17 00:00:00 2001
From: jbranigan <john.branigan@mapbox.com>
Date: Mon, 20 Apr 2020 16:46:29 -0500
Subject: [PATCH 06/74] Add inline snippet to LngLatBounds.contains (#9548)

---
 src/geo/lng_lat_bounds.js | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/geo/lng_lat_bounds.js b/src/geo/lng_lat_bounds.js
index 7fbf4db9c4a..6bc992340ef 100644
--- a/src/geo/lng_lat_bounds.js
+++ b/src/geo/lng_lat_bounds.js
@@ -216,6 +216,15 @@ class LngLatBounds {
     *
     * @param {LngLatLike} lnglat geographic point to check against.
     * @returns {boolean} True if the point is within the bounding box.
+    * @example
+    * var llb = new mapboxgl.LngLatBounds(
+    *   new mapboxgl.LngLat(-73.9876, 40.7661),
+    *   new mapboxgl.LngLat(-73.9397, 40.8002)
+    * );
+    *
+    * var ll = new mapboxgl.LngLat(-73.9567, 40.7789);
+    *
+    * llb.contains(ll); // = true
     */
     contains(lnglat: LngLatLike) {
         const {lng, lat} = LngLat.convert(lnglat);

From 254f29f4410508b00c5efd866c450af47b2603e0 Mon Sep 17 00:00:00 2001
From: Jeremy Stratman <jstratman@users.noreply.github.com>
Date: Mon, 20 Apr 2020 14:47:12 -0700
Subject: [PATCH 07/74] [docsprint] Add inline snippet and examples to
 map.jumpTo (#9549)

* add inline snippet and examples to map.jumpTo

* minor reorder to match options and text
---
 src/ui/camera.js | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index a02c8bace9f..caf116baee6 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -637,6 +637,19 @@ class Camera extends Evented {
      * @fires zoomend
      * @fires pitchend
      * @returns {Map} `this`
+     * @example
+     * // jump to null island at current zoom
+     * map.jumpTo({center: [0, 0]});
+     * // jump with zoom, pitch, and bearing set
+     * map.jumpTo({
+     *   center: [0, 0],
+     *   zoom: 8,
+     *   pitch: 45,
+     *   bearing: 90
+     *   }
+     * });
+     * @see [Jump to a series of locations](https://docs.mapbox.com/mapbox-gl-js/example/jump-to/)
+     * @see [Update a feature in realtime](https://docs.mapbox.com/mapbox-gl-js/example/live-update-feature/)
      */
     jumpTo(options: CameraOptions, eventData?: Object) {
         this.stop();

From c201f06bfeb627d7d2a5af5d6426683adc0d5ab3 Mon Sep 17 00:00:00 2001
From: Jeremy Stratman <jstratman@users.noreply.github.com>
Date: Mon, 20 Apr 2020 14:49:49 -0700
Subject: [PATCH 08/74] added inline and tutorial examples for map.getCenter
 (#9551)

---
 src/ui/camera.js | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index caf116baee6..538e17f05d8 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -119,6 +119,13 @@ class Camera extends Evented {
      *
      * @memberof Map#
      * @returns The map's geographical centerpoint.
+     * @example
+     * // return a LngLat object such as {lng: 0, lat: 0} at null island
+     * var center = map.getCenter();
+     * // return longitude and latitude values directly
+     * var longitude = map.getCenter().lng;
+     * var latitude = map.getCenter().lat;
+     * @see [Use Mapbox GL JS in a React app](https://docs.mapbox.com/help/tutorials/use-mapbox-gl-js-with-react/#store-the-new-coordinates)
      */
     getCenter(): LngLat { return new LngLat(this.transform.center.lng, this.transform.center.lat); }
 

From 74fc5ef6a20d4bec9840ded8d7cff318a9535e32 Mon Sep 17 00:00:00 2001
From: Mal Wood-Santoro <mal.wood@mapbox.com>
Date: Mon, 20 Apr 2020 14:50:51 -0700
Subject: [PATCH 09/74] add example for Marker class setLngLat (#9553)

---
 src/ui/marker.js | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/ui/marker.js b/src/ui/marker.js
index 4904799baee..b1b5f130f4e 100644
--- a/src/ui/marker.js
+++ b/src/ui/marker.js
@@ -280,10 +280,18 @@ export default class Marker extends Evented {
     }
 
     /**
-     * Set the marker's geographical position and move it.
-     * @param {LngLat} lnglat A {@link LngLat} describing where the marker should be located.
-     * @returns {Marker} `this`
-     */
+    * Set the marker's geographical position and move it.
+    * @param {LngLat} lnglat A {@link LngLat} describing where the marker should be located.
+    * @returns {Marker} `this`
+    * @example
+    * // Create a new marker, set the longitude and latitude, and add it to the map
+    * new mapboxgl.Marker()
+    *   .setLngLat([-65.017, -16.457])
+    *   .addTo(map);
+    * @see [Add custom icons with Markers](https://docs.mapbox.com/mapbox-gl-js/example/custom-marker-icons/)
+    * @see [Create a draggable Marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-marker/)
+    * @see [Add a marker using a place name](https://docs.mapbox.com/mapbox-gl-js/example/marker-from-geocode/)
+    */
     setLngLat(lnglat: LngLatLike) {
         this._lngLat = LngLat.convert(lnglat);
         this._pos = null;

From 08c55fb3874e091ac457fac8179d0615ed2eec0a Mon Sep 17 00:00:00 2001
From: Jeremy Stratman <jstratman@users.noreply.github.com>
Date: Mon, 20 Apr 2020 14:59:24 -0700
Subject: [PATCH 10/74] added examples to get- and setLayoutProperty (#9554)

---
 src/ui/map.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/ui/map.js b/src/ui/map.js
index 8adcef4735c..ca1571ad7d2 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1868,6 +1868,7 @@ class Map extends Camera {
      * @returns {Map} `this`
      * @example
      * map.setLayoutProperty('my-layer', 'visibility', 'none');
+     * @see [Show and hide layers](https://docs.mapbox.com/mapbox-gl-js/example/toggle-layers/)
      */
     setLayoutProperty(layerId: string, name: string, value: any, options: StyleSetterOptions = {}) {
         this.style.setLayoutProperty(layerId, name, value, options);
@@ -1892,6 +1893,9 @@ class Map extends Camera {
      * @param {Object} [options] Options object.
      * @param {boolean} [options.validate=true] Whether to check if the filter conforms to the Mapbox GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function.
      * @returns {Map} `this`
+     * @example
+     * map.getLayoutProperty('my-layer', 'visibility');
+     * @see [Show and hide layers](https://docs.mapbox.com/mapbox-gl-js/example/toggle-layers/)
      */
     setLight(light: LightSpecification, options: StyleSetterOptions = {}) {
         this._lazyInitEmptyStyle();

From 10ed623511ba9788caa72617bccd96b9348b3f42 Mon Sep 17 00:00:00 2001
From: Jeremy Stratman <jstratman@users.noreply.github.com>
Date: Mon, 20 Apr 2020 15:05:03 -0700
Subject: [PATCH 11/74] add inline snippet and examples to map.triggerRepaint
 (#9555)

---
 src/ui/map.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/ui/map.js b/src/ui/map.js
index ca1571ad7d2..9b2f5503fe6 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -2349,6 +2349,10 @@ class Map extends Camera {
      * Trigger the rendering of a single frame. Use this method with custom layers to
      * repaint the map when the layer changes. Calling this multiple times before the
      * next frame is rendered will still result in only a single frame being rendered.
+     * @example
+     * map.triggerRepaint();
+     * @see [Add a 3D model](https://docs.mapbox.com/mapbox-gl-js/example/add-3d-model/)
+     * @see [Add an animated icon to the map](https://docs.mapbox.com/mapbox-gl-js/example/add-image-animated/)
      */
     triggerRepaint() {
         if (this.style && !this._frame) {

From 6874d42b3e1e94f5bc78ee9dd2fa52244c578935 Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Mon, 20 Apr 2020 18:07:50 -0400
Subject: [PATCH 12/74] CameraOptions - update pitch and bearing definitions,
 add inline code example, add example links (#9556)

---
 src/ui/camera.js | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index 538e17f05d8..d6aec3205b3 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -33,11 +33,26 @@ import type {PaddingOptions} from '../geo/edge_insets';
  * @typedef {Object} CameraOptions
  * @property {LngLatLike} center The desired center.
  * @property {number} zoom The desired zoom level.
- * @property {number} bearing The desired bearing, in degrees. The bearing is the compass direction that
- * is "up"; for example, a bearing of 90° orients the map so that east is up.
- * @property {number} pitch The desired pitch, in degrees.
+ * @property {number} bearing The desired bearing in degrees. The bearing is the compass direction that
+ * is "up". For example, `bearing: 90` orients the map so that east is up.
+ * @property {number} pitch The desired pitch in degrees. The pitch is the angle towards the horizon
+ * measured in degrees with a range between 0 and 60 degrees. For example, `pitch: 0` results in a two-dimensional map,
+ * as if your line of sight forms a perpendicular angle with the earth's surface.
  * @property {LngLatLike} around If `zoom` is specified, `around` determines the point around which the zoom is centered.
  * @property {PaddingOptions} padding Dimensions in pixels applied on each side of the viewport for shifting the vanishing point.
+ * @example
+ * // set the map's initial perspective with CameraOptions
+ * var map = new mapboxgl.Map({
+ *   container: 'map',
+ *   style: 'mapbox://styles/mapbox/streets-v11',
+ *   center: [-73.5804, 45.53483],
+ *   pitch: 60,
+ *   bearing: -60,
+ *   zoom: 10
+ * });
+ * @see [Set pitch and bearing](https://docs.mapbox.com/mapbox-gl-js/example/set-perspective/)
+ * @see [Jump to a series of locations](https://docs.mapbox.com/mapbox-gl-js/example/jump-to/)
+ * @see [Fly to a location](https://docs.mapbox.com/mapbox-gl-js/example/flyto/)
  */
 export type CameraOptions = {
     center?: LngLatLike,

From a5eed0e41e9911fe323e6f49b92adecfaccd1f7b Mon Sep 17 00:00:00 2001
From: Jeremy Stratman <jstratman@users.noreply.github.com>
Date: Mon, 20 Apr 2020 15:12:13 -0700
Subject: [PATCH 13/74] add inline code snippet to map.showTileBoundaries
 (#9557)

---
 src/ui/map.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/ui/map.js b/src/ui/map.js
index 9b2f5503fe6..05563cf7aec 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -2386,6 +2386,8 @@ class Map extends Camera {
      * @type {boolean}
      * @instance
      * @memberof Map
+     * @example
+     * map.showTileBoundaries = true;
      */
     get showTileBoundaries(): boolean { return !!this._showTileBoundaries; }
     set showTileBoundaries(value: boolean) {

From d82116102839fb7b7c459a38d8f716d1d7f86a4e Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Mon, 20 Apr 2020 15:12:39 -0700
Subject: [PATCH 14/74] Mark Debug namespace as private to hide it from the
 docs (#9558)

---
 src/util/debug.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/util/debug.js b/src/util/debug.js
index 0255172726f..e26672e7472 100644
--- a/src/util/debug.js
+++ b/src/util/debug.js
@@ -5,6 +5,8 @@ import window from './window';
 /**
  * This is a private namespace for utility functions that will get automatically stripped
  * out in production builds.
+ *
+ * @private
  */
 export const Debug = {
     extend(dest: Object, ...sources: Array<?Object>): Object {

From f7e35a92ce43cc91f76184207666a594932908b1 Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Date: Mon, 20 Apr 2020 15:13:43 -0700
Subject: [PATCH 15/74] [docsprint] Add detail to docs on setFeatureState,
 removeFeatureState, getFeatureState (#9559)

* add detail to docs on setFeatureState, removeFeatureState, getFeatureState

* address asheemmamoowala's feedback

* remove trailing spaces
---
 src/ui/map.js | 119 ++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 92 insertions(+), 27 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 05563cf7aec..bde352876ad 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1914,23 +1914,42 @@ class Map extends Camera {
 
     // eslint-disable-next-line jsdoc/require-returns
     /**
-     * Sets the state of a feature. The `state` object is merged in with the existing state of the feature.
-     * Features are identified by their `id` attribute, which must be an integer or a string that can be
-     * cast to an integer.
+     * Sets the `state` of a feature.
+     * A feature's `state` is a set of user-defined key-value pairs that are assigned to a feature at runtime.
+     * When using this method, the `state` object is merged with any existing key-value pairs in the feature's state.
+     * Features are identified by their `feature.id` attribute, which can be any number or string.
+     *
+     * This method can only be used with sources that have a `feature.id` attribute. The `feature.id` attribute can be defined in three ways:
+     * - For vector or GeoJSON sources, including an `id` attribute in the original data file.
+     * - For vector or GeoJSON sources, using the [`promoteId`](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#vector-promoteId) option at the time the source is defined.
+     * - For GeoJSON sources, using the [`generateId`](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#geojson-generateId) option to auto-assign an `id` based on the feature's index in the source data. If you change feature data using `map.getSource('some id').setData(..)`, you may need to re-apply state taking into account updated `id` values.
+     *
+     * _Note: You can use the [`feature-state` expression](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/#feature-state) to access the values in a feature's state object for the purposes of styling._
      *
      * @param {Object} feature Feature identifier. Feature objects returned from
      * {@link Map#queryRenderedFeatures} or event handlers can be used as feature identifiers.
      * @param {string | number} feature.id Unique id of the feature.
-     * @param {string} feature.source The Id of the vector source or GeoJSON source for the feature.
-     * @param {string} [feature.sourceLayer] (optional)  *For vector tile sources, the sourceLayer is
-     *  required.*
+     * @param {string} feature.source The id of the vector or GeoJSON source for the feature.
+     * @param {string} [feature.sourceLayer] (optional) *For vector tile sources, `sourceLayer` is required.*
      * @param {Object} state A set of key-value pairs. The values should be valid JSON types.
      *
-     * This method requires the `feature.id` attribute on data sets. For GeoJSON sources without
-     * feature ids, set the `generateId` option in the `GeoJSONSourceSpecification` to auto-assign them. This
-     * option assigns ids based on a feature's index in the source data. If you change feature data using
-     * `map.getSource('some id').setData(..)`, you may need to re-apply state taking into account updated `id` values.
+     * @example
+     * // When the mouse moves over the `my-layer` layer, update
+     * // the feature state for the feature under the mouse
+     * map.on('mousemove', 'my-layer', (e) => {
+     *   if (e.features.length > 0) {
+     *     map.setFeatureState({
+     *       source: 'my-source',
+     *       sourceLayer: 'my-source-layer',
+     *       id: e.features[0].id,
+     *     }, {
+     *       hover: true
+     *     });
+     *   }
+     * });
+     *
      * @see [Create a hover effect](https://docs.mapbox.com/mapbox-gl-js/example/hover-styles/)
+     * @see Tutorial: [Create interactive hover effects with Mapbox GL JS](https://docs.mapbox.com/help/tutorials/create-interactive-hover-effects-with-mapbox-gl-js/)
      */
     setFeatureState(feature: { source: string; sourceLayer?: string; id: string | number; }, state: Object) {
         this.style.setFeatureState(feature, state);
@@ -1939,19 +1958,50 @@ class Map extends Camera {
 
     // eslint-disable-next-line jsdoc/require-returns
     /**
-     * Removes feature state, setting it back to the default behavior. If only
-     * source is specified, removes all states of that source. If
-     * target.id is also specified, removes all keys for that feature's state.
-     * If key is also specified, removes that key from that feature's state.
-     * Features are identified by their `id` attribute, which must be an integer or a string that can be
-     * cast to an integer.
-     * @param {Object} target Identifier of where to set state: can be a source, a feature, or a specific key of feature.
+     * Removes the `state` of a feature, setting it back to the default behavior.
+     * If only a `target.source` is specified, it will remove the state for all features from that source.
+     * If `target.id` is also specified, it will remove all keys for that feature's state.
+     * If `key` is also specified, it removes only that key from that feature's state.
+     * Features are identified by their `feature.id` attribute, which can be any number or string.
+     *
+     * @param {Object} target Identifier of where to remove state. It can be a source, a feature, or a specific key of feature.
      * Feature objects returned from {@link Map#queryRenderedFeatures} or event handlers can be used as feature identifiers.
      * @param {string | number} target.id (optional) Unique id of the feature. Optional if key is not specified.
-     * @param {string} target.source The Id of the vector source or GeoJSON source for the feature.
-     * @param {string} [target.sourceLayer] (optional)  *For vector tile sources, the sourceLayer is
-     *  required.*
+     * @param {string} target.source The id of the vector or GeoJSON source for the feature.
+     * @param {string} [target.sourceLayer] (optional) *For vector tile sources, `sourceLayer` is required.*
      * @param {string} key (optional) The key in the feature state to reset.
+     *
+     * @example
+     * // Reset the entire state object for all features
+     * // in the `my-source` source
+     * map.removeFeatureState({
+     *   source: 'my-source'
+     * });
+     *
+     * @example
+     * // When the mouse leaves the `my-layer` layer,
+     * // reset the entire state object for the
+     * // feature under the mouse
+     * map.on('mouseleave', 'my-layer', (e) => {
+     *   map.removeFeatureState({
+     *     source: 'my-source',
+     *     sourceLayer: 'my-source-layer',
+     *     id: e.features[0].id
+     *   });
+     * });
+     *
+     * @example
+     * // When the mouse leaves the `my-layer` layer,
+     * // reset only the `hover` key-value pair in the
+     * // state for the feature under the mouse
+     * map.on('mouseleave', 'my-layer', (e) => {
+     *   map.removeFeatureState({
+     *     source: 'my-source',
+     *     sourceLayer: 'my-source-layer',
+     *     id: e.features[0].id
+     *   }, 'hover');
+     * });
+     *
     */
     removeFeatureState(target: { source: string; sourceLayer?: string; id?: string | number; }, key?: string) {
         this.style.removeFeatureState(target, key);
@@ -1959,18 +2009,33 @@ class Map extends Camera {
     }
 
     /**
-     * Gets the state of a feature.
-     * Features are identified by their `id` attribute, which must be an integer or a string that can be
-     * cast to an integer.
+     * Gets the `state` of a feature.
+     * A feature's `state` is a set of user-defined key-value pairs that are assigned to a feature at runtime.
+     * Features are identified by their `feature.id` attribute, which can be any number or string.
+     *
+     * _Note: To access the values in a feature's state object for the purposes of styling the feature, use the [`feature-state` expression](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/#feature-state)._
      *
      * @param {Object} feature Feature identifier. Feature objects returned from
      * {@link Map#queryRenderedFeatures} or event handlers can be used as feature identifiers.
      * @param {string | number} feature.id Unique id of the feature.
-     * @param {string} feature.source The Id of the vector source or GeoJSON source for the feature.
-     * @param {string} [feature.sourceLayer] (optional)  *For vector tile sources, the sourceLayer is
-     *  required.*
+     * @param {string} feature.source The id of the vector or GeoJSON source for the feature.
+     * @param {string} [feature.sourceLayer] (optional) *For vector tile sources, `sourceLayer` is required.*
+     *
+     * @returns {Object} The state of the feature: a set of key-value pairs that was assigned to the feature at runtime.
+     *
+     * @example
+     * // When the mouse moves over the `my-layer` layer,
+     * // get the feature state for the feature under the mouse
+     * map.on('mousemove', 'my-layer', (e) => {
+     *   if (e.features.length > 0) {
+     *     map.getFeatureState({
+     *       source: 'my-source',
+     *       sourceLayer: 'my-source-layer'
+     *       id: e.features[0].id
+     *     });
+     *   }
+     * });
      *
-     * @returns {Object} The state of the feature.
      */
     getFeatureState(feature: { source: string; sourceLayer?: string; id: string | number; }): any {
         return this.style.getFeatureState(feature);

From 319c5eb0508df086c349d3ecde5963781d25b395 Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Mon, 20 Apr 2020 15:15:18 -0700
Subject: [PATCH 16/74] [docsprint] map.on: remove extra on section, link to
 event types, add code snippet, add related (#9560)

---
 src/ui/events.js | 413 ++++++++++++++++++++++++++++++++++++++++++++++-
 src/ui/map.js    | 120 +++++++++++---
 2 files changed, 505 insertions(+), 28 deletions(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index cf261c396fb..c3740f0133d 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -270,6 +270,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the pointing device is pressed
+     * // within the map.
+     * map.on('mousedown', function() {
+     *   console.log('A mousedown event has occurred.');
+     * });
      * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)
      * @see [Create a draggable point](https://www.mapbox.com/mapbox-gl-js/example/drag-a-point/)
      */
@@ -282,6 +291,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the pointing device is released
+     * // within the map.
+     * map.on('mouseup', function() {
+     *   console.log('A mouseup event has occurred.');
+     * });
      * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)
      * @see [Create a draggable point](https://www.mapbox.com/mapbox-gl-js/example/drag-a-point/)
      */
@@ -294,6 +312,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the pointing is moved
+     * // within the map.
+     * map.on('mouseover', function() {
+     *   console.log('A mouseover event has occurred.');
+     * });
      * @see [Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/)
      * @see [Highlight features under the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/hover-styles/)
      * @see [Display a popup on hover](https://www.mapbox.com/mapbox-gl-js/example/popup-on-hover/)
@@ -307,6 +334,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the pointing device is moved
+     * // within the map.
+     * map.on('mousemove', function() {
+     *   console.log('A mousemove event has occurred.');
+     * });
      * @see [Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/)
      * @see [Highlight features under the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/hover-styles/)
      * @see [Display a popup on over](https://www.mapbox.com/mapbox-gl-js/example/popup-on-hover/)
@@ -320,6 +356,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the pointing device is pressed and
+     * // released at the same point within the map.
+     * map.on('click', function(e) {
+     *   console.log('A click event has occurred at ' + e.lngLat);
+     * });
      * @see [Measure distances](https://www.mapbox.com/mapbox-gl-js/example/measure/)
      * @see [Center the map on a clicked symbol](https://www.mapbox.com/mapbox-gl-js/example/center-on-symbol/)
      */
@@ -332,6 +377,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the pointing device is pressed and
+     * // released twice at the same point within the map.
+     * map.on('dblclick', function() {
+     *   console.log('A dblclick event has occurred.');
+     * });
      */
     | 'dblclick'
 
@@ -344,6 +398,17 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the pointing device enters
+     * // a visible portion of the specified layer.
+     * map.on('mouseenter', 'water', function() {
+     *   console.log('A mouseenter event occurred.');
+     * });
+     * @see [Center the map on a clicked symbol](https://www.mapbox.com/mapbox-gl-js/example/center-on-symbol/)
+     * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
      */
     | 'mouseenter'
 
@@ -356,7 +421,17 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the pointing device leaves
+     * // a visible portion of the specified layer.
+     * map.on('mouseleave', 'water', function() {
+     *   console.log('A mouseleave event occurred.');
+     * });
      * @see [Highlight features under the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/hover-styles/)
+     * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
      */
     | 'mouseleave'
 
@@ -367,6 +442,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the pointing device leave's
+     * // the map's canvas.
+     * map.on('mouseout', function() {
+     *   console.log('A mouseout event occurred.');
+     * });
      */
     | 'mouseout'
 
@@ -377,6 +461,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the right mouse button is
+     * // pressed within the map.
+     * map.on('contextmenu', function() {
+     *   console.log('A contextmenu event occurred.');
+     * });
      */
     | 'contextmenu'
 
@@ -387,6 +480,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapWheelEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when a wheel event occurs within the map.
+     * map.on('wheel', function() {
+     *   console.log('A wheel event occurred.');
+     * });
      */
     | 'wheel'
 
@@ -397,6 +498,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapTouchEvent} data
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when a touchstart event occurs within the map.
+     * map.on('touchstart', function() {
+     *   console.log('A touchstart event occurred.');
+     * });
+     * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/)
      */
     | 'touchstart'
 
@@ -407,6 +516,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when a touchstart event occurs within the map.
+     * map.on('touchstart', function() {
+     *   console.log('A touchstart event occurred.');
+     * });
+     * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/)
      */
     | 'touchend'
 
@@ -417,6 +535,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when a touchmove event occurs within the map.
+     * map.on('touchmove', function() {
+     *   console.log('A touchmove event occurred.');
+     * });
+     * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/)
      */
     | 'touchmove'
 
@@ -427,6 +554,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when a touchcancel event occurs within the map.
+     * map.on('touchcancel', function() {
+     *   console.log('A touchcancel event occurred.');
+     * });
      */
     | 'touchcancel'
 
@@ -438,6 +573,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {{originalEvent: DragEvent}} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just before the map begins a transition
+     * // from one view to another.
+     * map.on('movestart', function() {
+     *   console.log('A movestart` event occurred.');
+     * });
      */
     | 'movestart'
 
@@ -449,6 +593,16 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent | MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // repeatedly during an animated transition.
+     * map.on('move', function() {
+     *   console.log('A move event occurred.');
+     * });
+     * @see [Display HTML clusters with custom properties](https://docs.mapbox.com/mapbox-gl-js/example/cluster-html/)
+     * @see [Filter features within map view](https://www.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/)
      */
     | 'move'
 
@@ -460,8 +614,17 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {{originalEvent: DragEvent}} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just after the map completes a transition.
+     * map.on('moveend', function() {
+     *   console.log('A moveend event occurred.');
+     * });
      * @see [Play map locations as a slideshow](https://www.mapbox.com/mapbox-gl-js/example/playback-locations/)
      * @see [Filter features within map view](https://www.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/)
+     * @see [Display HTML clusters with custom properties](https://docs.mapbox.com/mapbox-gl-js/example/cluster-html/)
      */
     | 'moveend'
 
@@ -472,6 +635,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {{originalEvent: DragEvent}} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when a "drag to pan" interaction starts.
+     * map.on('dragstart', function() {
+     *   console.log('A dragstart event occurred.');
+     * });
      */
     | 'dragstart'
 
@@ -482,6 +653,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent | MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // repeatedly  during a "drag to pan" interaction.
+     * map.on('drag', function() {
+     *   console.log('A drag event occurred.');
+     * });
      */
     | 'drag'
 
@@ -492,6 +671,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {{originalEvent: DragEvent}} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when a "drag to pan" interaction ends.
+     * map.on('dragend', function() {
+     *   console.log('A dragend event occurred.');
+     * });
+     * @see [Create a draggable marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-marker/)
      */
     | 'dragend'
 
@@ -503,6 +691,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent | MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just before a zoom transition starts.
+     * map.on('zoomstart', function() {
+     *   console.log('A zoomstart event occurred.');
+     * });
      */
     | 'zoomstart'
 
@@ -514,6 +710,13 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent | MapTouchEvent} data
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // repeatedly during a zoom transition.
+     * map.on('zoom', function() {
+     *   console.log('A zoom event occurred.');
+     * });
      * @see [Update a choropleth layer by zoom level](https://www.mapbox.com/mapbox-gl-js/example/updating-choropleth/)
      */
     | 'zoom'
@@ -526,6 +729,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent | MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just after a zoom transition finishes.
+     * map.on('zoomend', function() {
+     *   console.log('A zoomend event occurred.');
+     * });
      */
     | 'zoomend'
 
@@ -536,6 +747,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent | MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just before a "drag to rotate" interaction starts.
+     * map.on('rotatestart', function() {
+     *   console.log('A rotatestart event occurred.');
+     * });
      */
     | 'rotatestart'
 
@@ -546,6 +765,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent | MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // repeatedly during "drag to rotate" interaction.
+     * map.on('rotate', function() {
+     *   console.log('A rotate event occurred.');
+     * });
      */
     | 'rotate'
 
@@ -556,6 +783,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapMouseEvent | MapTouchEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just after a "drag to rotate" interaction ends.
+     * map.on('rotateend', function() {
+     *   console.log('A rotateend event occurred.');
+     * });
      */
     | 'rotateend'
 
@@ -567,17 +802,34 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapEventData} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just before a pitch (tilt) transition starts.
+     * map.on('pitchstart', function() {
+     *   console.log('A pitchstart event occurred.');
+     * });
      */
     | 'pitchstart'
 
     /**
-     * Fired whenever the map's pitch (tilt) changes as
-     * the result of either user interaction or methods such as {@link Map#flyTo}.
+     * Fired repeatedly during the map's pitch (tilt) animation between
+     * one state and another as the result of either user interaction
+     * or methods such as {@link Map#flyTo}.
      *
      * @event pitch
      * @memberof Map
      * @instance
      * @property {MapEventData} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // repeatedly during a pitch (tilt) transition.
+     * map.on('pitch', function() {
+     *   console.log('A pitch event occurred.');
+     * });
      */
     | 'pitch'
 
@@ -589,6 +841,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapEventData} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just after a pitch (tilt) transition ends.
+     * map.on('pitchend', function() {
+     *   console.log('A pitchend event occurred.');
+     * });
      */
     | 'pitchend'
 
@@ -599,6 +859,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapBoxZoomEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just before a "box zoom" interaction starts.
+     * map.on('boxzoomstart', function() {
+     *   console.log('A boxzoomstart event occurred.');
+     * });
      */
     | 'boxzoomstart'
 
@@ -610,6 +878,14 @@ export type MapEvent =
      * @instance
      * @type {Object}
      * @property {MapBoxZoomEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just after a "box zoom" interaction ends.
+     * map.on('boxzoomend', function() {
+     *   console.log('A boxzoomend event occurred.');
+     * });
      */
     | 'boxzoomend'
 
@@ -621,6 +897,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapBoxZoomEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // the user cancels a "box zoom" interaction.
+     * map.on('boxzoomcancel', function() {
+     *   console.log('A boxzoomcancel event occurred.');
+     * });
      */
     | 'boxzoomcancel'
 
@@ -630,6 +914,14 @@ export type MapEvent =
      * @event resize
      * @memberof Map
      * @instance
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // immediately after the map has been resized.
+     * map.on('resize', function() {
+     *   console.log('A resize event occurred.');
+     * });
      */
     | 'resize'
 
@@ -639,6 +931,14 @@ export type MapEvent =
      * @event webglcontextlost
      * @memberof Map
      * @instance
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the WebGL context is lost.
+     * map.on('webglcontextlost', function() {
+     *   console.log('A webglcontextlost event occurred.');
+     * });
      */
     | 'webglcontextlost'
 
@@ -648,6 +948,14 @@ export type MapEvent =
      * @event webglcontextrestored
      * @memberof Map
      * @instance
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the WebGL context is restored.
+     * map.on('webglcontextrestored', function() {
+     *   console.log('A webglcontextrestored event occurred.');
+     * });
      */
     | 'webglcontextrestored'
 
@@ -659,6 +967,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @type {Object}
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the map has finished loading.
+     * map.on('load', function() {
+     *   console.log('A load event occurred.');
+     * });
      * @see [Draw GeoJSON points](https://www.mapbox.com/mapbox-gl-js/example/geojson-markers/)
      * @see [Add live realtime data](https://www.mapbox.com/mapbox-gl-js/example/live-geojson/)
      * @see [Animate a point](https://www.mapbox.com/mapbox-gl-js/example/animate-point-along-line/)
@@ -676,6 +992,14 @@ export type MapEvent =
      * @event render
      * @memberof Map
      * @instance
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // whenever the map is drawn to the screen.
+     * map.on('render', function() {
+     *   console.log('A render event occurred.');
+     * });
      */
     | 'render'
 
@@ -690,6 +1014,14 @@ export type MapEvent =
      * @event idle
      * @memberof Map
      * @instance
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just before the map enters an "idle" state.
+     * map.on('idle', function() {
+     *   console.log('A idle event occurred.');
+     * });
      */
     | 'idle'
 
@@ -699,6 +1031,14 @@ export type MapEvent =
      * @event remove
      * @memberof Map
      * @instance
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // just after the map is removed.
+     * map.on('remove', function() {
+     *   console.log('A remove event occurred.');
+     * });
      */
     | 'remove'
 
@@ -712,6 +1052,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {{error: {message: string}}} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when an error occurs.
+     * map.on('error', function() {
+     *   console.log('A error event occurred.');
+     * });
      */
     | 'error'
 
@@ -723,6 +1071,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapDataEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when map data loads or changes.
+     * map.on('data', function() {
+     *   console.log('A data event occurred.');
+     * });
+     * @see [Display HTML clusters with custom properties](https://docs.mapbox.com/mapbox-gl-js/example/cluster-html/)
      */
     | 'data'
 
@@ -734,6 +1091,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapDataEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when the map's style loads or changes.
+     * map.on('styledata', function() {
+     *   console.log('A styledata event occurred.');
+     * });
      */
     | 'styledata'
 
@@ -745,6 +1110,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapDataEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when one of the map's sources loads or changes.
+     * map.on('sourcedata', function() {
+     *   console.log('A sourcedata event occurred.');
+     * });
      */
     | 'sourcedata'
 
@@ -757,6 +1130,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapDataEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // when any map data begins loading
+     * // or changing asynchronously.
+     * map.on('dataloading', function() {
+     *   console.log('A dataloading event occurred.');
+     * });
      */
     | 'dataloading'
 
@@ -769,6 +1151,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapDataEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // map's style begins loading or
+     * // changing asyncronously.
+     * map.on('styledataloading', function() {
+     *   console.log('A styledataloading event occurred.');
+     * });
      */
     | 'styledataloading'
 
@@ -781,6 +1172,15 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {MapDataEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // map's sources begin loading or
+     * // changing asyncronously.
+     * map.on('sourcedataloading', function() {
+     *   console.log('A sourcedataloading event occurred.');
+     * });
      */
     | 'sourcedataloading'
 
@@ -793,7 +1193,14 @@ export type MapEvent =
      * @memberof Map
      * @instance
      * @property {string} id The id of the missing image.
-     *
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener that fires
+     * // an icon or pattern is missing.
+     * map.on('styleimagemissing', function() {
+     *   console.log('A styleimagemissing event occurred.');
+     * });
      * @see [Generate and add a missing icon to the map](https://mapbox.com/mapbox-gl-js/example/add-image-missing-generated/)
      */
     | 'styleimagemissing'
diff --git a/src/ui/map.js b/src/ui/map.js
index bde352876ad..4e12e769153 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -925,33 +925,103 @@ class Map extends Camera {
     }
 
     /**
-     * Adds a listener for events of a specified type.
-     *
-     * @method
-     * @name on
-     * @memberof Map
-     * @instance
-     * @param {string} type The event type to add a listen for.
-     * @param {Function} listener The function to be called when the event is fired.
-     *   The listener function is called with the data object passed to `fire`,
-     *   extended with `target` and `type` properties.
-     * @returns {Map} `this`
-     */
-
-    /**
-     * Adds a listener for events of a specified type occurring on features in a specified style layer.
-     *
-     * @param {string} type The event type to listen for; one of `'mousedown'`, `'mouseup'`, `'click'`, `'dblclick'`,
-     * `'mousemove'`, `'mouseenter'`, `'mouseleave'`, `'mouseover'`, `'mouseout'`, `'contextmenu'`, `'touchstart'`,
-     * `'touchend'`, or `'touchcancel'`. `mouseenter` and `mouseover` events are triggered when the cursor enters
-     * a visible portion of the specified layer from outside that layer or outside the map canvas. `mouseleave`
-     * and `mouseout` events are triggered when the cursor leaves a visible portion of the specified layer, or leaves
-     * the map canvas.
-     * @param {string} layerId The ID of a style layer. Only events whose location is within a visible
-     * feature in this layer will trigger the listener. The event will have a `features` property containing
-     * an array of the matching features.
+     * Adds a listener for events of a specified type, optionally limited to features in a specified style layer.
+     *
+     * @param {string} type The event type to listen for. Events compatible with the optional `layerId` parameter are triggered
+     * when the cursor enters a visible portion of the specified layer from outside that layer or outside the map canvas.
+     *
+     * | Event                                                     | Compatible with `layerId` |
+     * |-----------------------------------------------------------|---------------------------|
+     * | [`mousedown`](#map.event:mousedown)                       | yes                       |
+     * | [`mouseup`](#map.event:mouseup)                           | yes                       |
+     * | [`mouseover`](#map.event:mouseover)                       | yes                       |
+     * | [`mouseout`](#map.event:mouseout)                         | yes                       |
+     * | [`mousemove`](#map.event:mousemove)                       | yes                       |
+     * | [`mouseenter`](#map.event:mouseenter)                     | yes (required)            |
+     * | [`mouseleave`](#map.event:mouseleave)                     | yes (required)            |
+     * | [`click`](#map.event:click)                               | yes                       |
+     * | [`dblclick`](#map.event:dblclick)                         | yes                       |
+     * | [`contextmenu`](#map.event:contextmenu)                   | yes                       |
+     * | [`touchstart`](#map.event:touchstart)                     | yes                       |
+     * | [`touchend`](#map.event:touchend)                         | yes                       |
+     * | [`touchcancel`](#map.event:touchcancel)                   | yes                       |
+     * | [`wheel`](#map.event:wheel)                               |                           |
+     * | [`resize`](#map.event:resize)                             |                           |
+     * | [`remove`](#map.event:remove)                             |                           |
+     * | [`touchmove`](#map.event:touchmove)                       |                           |
+     * | [`movestart`](#map.event:movestart)                       |                           |
+     * | [`move`](#map.event:move)                                 |                           |
+     * | [`moveend`](#map.event:moveend)                           |                           |
+     * | [`dragstart`](#map.event:dragstart)                       |                           |
+     * | [`drag`](#map.event:drag)                                 |                           |
+     * | [`dragend`](#map.event:dragend)                           |                           |
+     * | [`zoomstart`](#map.event:zoomstart)                       |                           |
+     * | [`zoom`](#map.event:zoom)                                 |                           |
+     * | [`zoomend`](#map.event:zoomend)                           |                           |
+     * | [`rotatestart`](#map.event:rotatestart)                   |                           |
+     * | [`rotate`](#map.event:rotate)                             |                           |
+     * | [`rotateend`](#map.event:rotateend)                       |                           |
+     * | [`pitchstart`](#map.event:pitchstart)                     |                           |
+     * | [`pitch`](#map.event:pitch)                               |                           |
+     * | [`pitchend`](#map.event:pitchend)                         |                           |
+     * | [`boxzoomstart`](#map.event:boxzoomstart)                 |                           |
+     * | [`boxzoomend`](#map.event:boxzoomend)                     |                           |
+     * | [`boxzoomcancel`](#map.event:boxzoomcancel)               |                           |
+     * | [`webglcontextlost`](#map.event:webglcontextlost)         |                           |
+     * | [`webglcontextrestored`](#map.event:webglcontextrestored) |                           |
+     * | [`load`](#map.event:load)                                 |                           |
+     * | [`render`](#map.event:render)                             |                           |
+     * | [`idle`](#map.event:idle)                                 |                           |
+     * | [`error`](#map.event:error)                               |                           |
+     * | [`data`](#map.event:data)                                 |                           |
+     * | [`styledata`](#map.event:styledata)                       |                           |
+     * | [`sourcedata`](#map.event:sourcedata)                     |                           |
+     * | [`dataloading`](#map.event:dataloading)                   |                           |
+     * | [`styledataloading`](#map.event:styledataloading)         |                           |
+     * | [`sourcedataloading`](#map.event:sourcedataloading)       |                           |
+     * | [`styleimagemissing`](#map.event:styleimagemissing)       |                           |
+     *
+     * @param {string} layerId (optional) The ID of a style layer. Event will only be triggered if their location
+     * is within a visible feature in this layer. The event will have a `features` property containing
+     * an array of the matching features. If `layerId` is not supplied, the event will not have a `features` property.
+     * Please note that many event types are not compatible with the optional `layerId` parameter.
      * @param {Function} listener The function to be called when the event is fired.
      * @returns {Map} `this`
+     * @example
+     * // Set an event listener that will fire
+     * // when the map has finished loading
+     * map.on('load', function() {
+     *   // Once the map has finished loading,
+     *   // add a new layer
+     *   map.addLayer({
+     *     id: 'points-of-interest',
+     *     source: {
+     *       type: 'vector',
+     *       url: 'mapbox://mapbox.mapbox-streets-v8'
+     *     },
+     *     'source-layer': 'poi_label',
+     *     type: 'circle',
+     *     paint: {
+     *       // Mapbox Style Specification paint properties
+     *     },
+     *     layout: {
+     *       // Mapbox Style Specification layout properties
+     *     }
+     *   });
+     * });
+     * @example
+     * // Set an event listener that will fire
+     * // when the map is clicked
+     * map.on('click', 'countries', function(e) {
+     *   new mapboxgl.Popup()
+     *     .setLngLat(e.lngLat)
+     *     .setHTML(`Country name: ${e.features[0].properties.name}`)
+     *     .addTo(map);
+     * });
+     * @see [Display popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
+     * @see [Center the map on a clicked symbol](https://docs.mapbox.com/mapbox-gl-js/example/center-on-symbol/)
+     * @see [Create a hover effect](https://docs.mapbox.com/mapbox-gl-js/example/hover-styles/)
+     * @see [Create a draggable marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/)
      */
     on(type: MapEvent, layerId: any, listener: any) {
         if (listener === undefined) {

From 0f4a3f07db298b394121e842ac520f1122428523 Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Date: Mon, 20 Apr 2020 15:28:25 -0700
Subject: [PATCH 17/74] add examples to open and close popup events (#9565)

---
 src/ui/popup.js | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/ui/popup.js b/src/ui/popup.js
index b2803888863..3ca5a36efcf 100644
--- a/src/ui/popup.js
+++ b/src/ui/popup.js
@@ -139,6 +139,16 @@ export default class Popup extends Evented {
          * @instance
          * @type {Object}
          * @property {Popup} popup object that was opened
+         *
+         * @example
+         * // Create a popup
+         * var popup = new mapboxgl.Popup();
+         * // Set an event listener that will fire
+         * // any time the popup is opened
+         * popup.on('open', function(){
+         *   console.log('popup was opened');
+         * });
+         *
          */
         this.fire(new Event('open'));
 
@@ -189,6 +199,16 @@ export default class Popup extends Evented {
          * @instance
          * @type {Object}
          * @property {Popup} popup object that was closed
+         *
+         * @example
+         * // Create a popup
+         * var popup = new mapboxgl.Popup();
+         * // Set an event listener that will fire
+         * // any time the popup is closed
+         * popup.on('close', function(){
+         *   console.log('popup was closed');
+         * });
+         *
          */
         this.fire(new Event('close'));
 

From ce1e98de78e860cd39c0c7faa3c12f2ecdf1fa1f Mon Sep 17 00:00:00 2001
From: Mal Wood-Santoro <mal.wood@mapbox.com>
Date: Mon, 20 Apr 2020 15:29:08 -0700
Subject: [PATCH 18/74] [docsprint] Clarify how map.moveLayer works (#9566)

* clarify how map.moveLayer works

* fix wording

* small wording fix

* fix id capitalization
---
 src/ui/map.js | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 4e12e769153..68108061a37 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1790,13 +1790,12 @@ class Map extends Camera {
      * Moves a layer to a different z-position.
      *
      * @param {string} id The ID of the layer to move.
-     * @param {string} [beforeId] The ID of an existing layer to insert the new layer before.
-     *   If this argument is omitted, the layer will be appended to the end of the layers array.
+     * @param {string} [beforeId] The ID of an existing layer to insert the new layer before. When viewing the map, the `id` layer will appear beneath the `beforeId` layer. If `beforeId` is omitted, the layer will be appended to the end of the layers array and appear above all other layers on the map.
      * @returns {Map} `this`
      *
      * @example
-     * // Move a layer with ID 'label' before the layer with ID 'waterways'.
-     * map.moveLayer('label', 'waterways');
+     * // Move a layer with ID 'polygon' before the layer with ID 'country-label'. The `polygon` layer will appear beneath the `country-label` layer on the map.
+     * map.moveLayer('polygon', 'country-label');
      */
     moveLayer(id: string, beforeId?: string) {
         this.style.moveLayer(id, beforeId);

From 07110037d40045f8a3562b614eb828d47c7d1728 Mon Sep 17 00:00:00 2001
From: geografa <geografa@users.noreply.github.com>
Date: Mon, 20 Apr 2020 15:29:52 -0700
Subject: [PATCH 19/74] [doscprint] add links to EPSG and minor example changes
 for LngLat (#9570)

* add links to EPSG and minor example changes for LngLat

* removes trailing spaces
---
 src/geo/lng_lat.js | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/geo/lng_lat.js b/src/geo/lng_lat.js
index 971214994a3..e978f348cee 100644
--- a/src/geo/lng_lat.js
+++ b/src/geo/lng_lat.js
@@ -12,8 +12,10 @@ export const earthRadius = 6371008.8;
 
 /**
  * A `LngLat` object represents a given longitude and latitude coordinate, measured in degrees.
+ * These coordinates are based on the [WGS84 (EPSG:4326) standard](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84).
  *
- * Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
+ * Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match the
+ * [GeoJSON specification](https://tools.ietf.org/html/rfc7946).
  *
  * Note that any Mapbox GL method that accepts a `LngLat` object as an argument or option
  * can also accept an `Array` of two numbers and will perform an implicit conversion.
@@ -22,7 +24,8 @@ export const earthRadius = 6371008.8;
  * @param {number} lng Longitude, measured in degrees.
  * @param {number} lat Latitude, measured in degrees.
  * @example
- * var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
+ * var ll = new mapboxgl.LngLat(-123.9749, 40.7736);
+ * ll.lng; // = -123.9749
  * @see [Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/)
  * @see [Display a popup](https://www.mapbox.com/mapbox-gl-js/example/popup/)
  * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)

From d536278c5f613a4bf81c7b59bf336d4c6df54d97 Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Date: Mon, 20 Apr 2020 15:31:07 -0700
Subject: [PATCH 20/74] document the layer object's properties in addLayer
 (#9571)

---
 src/ui/map.js | 85 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 78 insertions(+), 7 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 68108061a37..fd5160a072d 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1751,15 +1751,51 @@ class Map extends Camera {
      * A layer defines how data from a specified source will be styled. Read more about layer types
      * and available paint and layout properties in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers).
      *
-     * @param {Object | CustomLayerInterface} layer The style layer to add, conforming to the Mapbox Style Specification's
-     *   [layer definition](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers).
+     * @param {Object | CustomLayerInterface} layer The layer to add, conforming to either the Mapbox Style Specification's [layer definition](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers) or, less commonly, the [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/#customlayerinterface) specification.
+     * The Mapbox Style Specification's layer definition is appropriate for most layers.
+     *
+     * @param {string} layer.id A unique idenfier that you define.
+     * @param {string} layer.type The type of layer (for example `fill` or `symbol`).
+     * A list of layer types is available in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#type).
+     *
+     * (This can also be `custom`. For more information, see [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/#customlayerinterface).)
+     * @param {string | Object} [layer.source] The data source for the layer.
+     * Reference a source that has _already been defined_ using the source's unique id.
+     * Reference a _new source_ using a source object (as defined in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/)) directly.
+     * This is **required** for all `layer.type` options _except_ for `custom`.
+     * @param {string} [layer.sourceLayer] (optional) The name of the [source layer](https://docs.mapbox.com/help/glossary/source-layer/) within the specified `layer.source` to use for this style layer.
+     * This is only applicable for vector tile sources and is **required** when `layer.source` is of the type `vector`.
+     * @param {array} [layer.filter] (optional) An expression specifying conditions on source features.
+     * Only features that match the filter are displayed.
+     * The Mapbox Style Specification includes more information on the limitations of the [`filter`](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#filter) parameter
+     * and a complete list of available [expressions](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/).
+     * If no filter is provided, all features in the source (or source layer for vector tilesets) will be displayed.
+     * @param {Object} [layer.paint] (optional) Paint properties for the layer.
+     * Available paint properties vary by `layer.type`.
+     * A full list of paint properties for each layer type is available in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/).
+     * If no paint properties are specified, default values will be used.
+     * @param {Object} [layer.layout] (optional) Layout properties for the layer.
+     * Available layout properties vary by `layer.type`.
+     * A full list of layout properties for each layer type is available in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/).
+     * If no layout properties are specified, default values will be used.
+     * @param {number} [layer.maxzoom] (optional) The maximum zoom level for the layer.
+     * At zoom levels equal to or greater than the maxzoom, the layer will be hidden.
+     * The value can be any number between `0` and `24` (inclusive).
+     * If no maxzoom is provided, the layer will be visible at all zoom levels for which there are tiles available.
+     * @param {number} [layer.minzoom] (optional) The minimum zoom level for the layer.
+     * At zoom levels less than the minzoom, the layer will be hidden.
+     * The value can be any number between `0` and `24` (inclusive).
+     * If no minzoom is provided, the layer will be visible at all zoom levels for which there are tiles available.
+     * @param {Object} [layer.metadata] (optional) Arbitrary properties useful to track with the layer, but do not influence rendering.
+     * @param {string} [layer.renderingMode] This is only applicable for layers with the type `custom`.
+     * See [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/#customlayerinterface) for more information.
      * @param {string} [beforeId] The ID of an existing layer to insert the new layer before.
-     *   If this argument is omitted, the layer will be appended to the end of the layers array.
+     * If this argument is not specified, the layer will be appended to the end of the layers array.
      *
      * @returns {Map} `this`
      *
      * @example
-     * // Add a circle layer with a vector source.
+     * // Add a circle layer with a vector source
      * map.addLayer({
      *   id: 'points-of-interest',
      *   source: {
@@ -1776,9 +1812,44 @@ class Map extends Camera {
      *   }
      * });
      *
-     * @see [Create and style clusters](https://www.mapbox.com/mapbox-gl-js/example/cluster/)
-     * @see [Add a vector tile source](https://www.mapbox.com/mapbox-gl-js/example/vector-source/)
-     * @see [Add a WMS source](https://www.mapbox.com/mapbox-gl-js/example/wms/)
+     * @example
+     * // Define a source before using it to create a new layer
+     * map.addSource('state-data', {
+     *   type: 'geojson',
+     *   data: 'path/to/data.geojson'
+     * });
+     *
+     * map.addLayer({
+     *   id: 'states',
+     *   // References the GeoJSON source defined above
+     *   // and does not require a `source-layer`
+     *   source: 'state-data',
+     *   type: 'symbol',
+     *   layout: {
+     *     // Set the label content to the
+     *     // feature's `name` property
+     *     text-field: ['get', 'name']
+     *   }
+     * });
+     *
+     * @example
+     * // Add a new symbol layer before an existing layer
+     * map.addLayer({
+     *   id: 'states',
+     *   // References a source that's already been defined
+     *   source: 'state-data',
+     *   type: 'symbol',
+     *   layout: {
+     *     // Set the label content to the
+     *     // feature's `name` property
+     *     text-field: ['get', 'name']
+     *   }
+     * // Add the layer before the existing `cities` layer
+     * }, 'cities');
+     *
+     * @see [Create and style clusters](https://docs.mapbox.com/mapbox-gl-js/example/cluster/)
+     * @see [Add a vector tile source](https://docs.mapbox.com/mapbox-gl-js/example/vector-source/)
+     * @see [Add a WMS source](https://docs.mapbox.com/mapbox-gl-js/example/wms/)
      */
     addLayer(layer: LayerSpecification | CustomLayerInterface, beforeId?: string) {
         this._lazyInitEmptyStyle();

From 8279ca5308e18792c53eea6b31bf8ac8cf41cc05 Mon Sep 17 00:00:00 2001
From: Jeremy Stratman <jstratman@users.noreply.github.com>
Date: Mon, 20 Apr 2020 15:31:52 -0700
Subject: [PATCH 21/74] [docsprint] Add inline snippet and examples to
 popup.addTo (#9572)

* added inline example to popup-addto

* added relevant examples to popup.addto

* swapped examples
---
 src/ui/popup.js | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/ui/popup.js b/src/ui/popup.js
index 3ca5a36efcf..1b419f7e5c0 100644
--- a/src/ui/popup.js
+++ b/src/ui/popup.js
@@ -104,6 +104,15 @@ export default class Popup extends Evented {
      *
      * @param {Map} map The Mapbox GL JS map to add the popup to.
      * @returns {Popup} `this`
+     * @example
+     * new mapboxgl.Popup()
+     *   .setLngLat([0, 0])
+     *   .setHTML("<h1>Null Island</h1>")
+     *   .addTo(map);
+     * @see [Display a popup](https://docs.mapbox.com/mapbox-gl-js/example/popup/)
+     * @see [Display a popup on hover](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-hover/)
+     * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
+     * @see [Show polygon information on click](https://docs.mapbox.com/mapbox-gl-js/example/polygon-popup-on-click/)
      */
     addTo(map: Map) {
         if (this._map) this.remove();

From 3f39525e65e175275443b362aabf7a775160eafe Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Mon, 20 Apr 2020 18:33:57 -0400
Subject: [PATCH 22/74] Add inline example for trackPointer (#9575)

---
 src/ui/popup.js | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/ui/popup.js b/src/ui/popup.js
index 1b419f7e5c0..f3bffddd493 100644
--- a/src/ui/popup.js
+++ b/src/ui/popup.js
@@ -264,8 +264,13 @@ export default class Popup extends Evented {
     }
 
     /**
-     * Tracks the popup anchor to the cursor position, on screens with a pointer device (will be hidden on touchscreens). Replaces the setLngLat behavior.
-     * For most use cases, `closeOnClick` and `closeButton` should also be set to `false` here.
+     * Tracks the popup anchor to the cursor position on screens with a pointer device (it will be hidden on touchscreens). Replaces the `setLngLat` behavior.
+     * For most use cases, set `closeOnClick` and `closeButton` to `false`.
+     * @example
+     * var popup = new mapboxgl.Popup({ closeOnClick: false, closeButton: false })
+     *   .setHTML("<h1>Hello World!</h1>")
+     *   .trackPointer()
+     *   .addTo(map);
      * @returns {Popup} `this`
      */
     trackPointer() {

From 41f52a083a9f8faf6d6386791f49e4139767659c Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Mon, 20 Apr 2020 18:35:24 -0400
Subject: [PATCH 23/74] Add inline example for Popup#getElement (#9576)

---
 src/ui/popup.js | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/ui/popup.js b/src/ui/popup.js
index f3bffddd493..2732eb82857 100644
--- a/src/ui/popup.js
+++ b/src/ui/popup.js
@@ -293,6 +293,14 @@ export default class Popup extends Evented {
 
     /**
      * Returns the `Popup`'s HTML element.
+     * @example
+     * // Change the `Popup` element's font size
+     * var popup = new mapboxgl.Popup()
+     *   .setLngLat([-96, 37.8])
+     *   .setHTML("<p>Hello World!</p>")
+     *   .addTo(map);
+     * var popupElem = popup.getElement();
+     * popupElem.style.fontSize = "25px";
      * @returns {HTMLElement} element
      */
     getElement() {

From e5954f260d5c65281089f84c1cbb75bec8beca58 Mon Sep 17 00:00:00 2001
From: Adriana Babakanian <adriana.babakanian@mapbox.com>
Date: Mon, 20 Apr 2020 15:36:48 -0700
Subject: [PATCH 24/74] [docsprint] Add inline examples for Point & PointLike
 types (#9577)

* Add inline examples for Point & PointLike types

* Correct syntax
---
 src/ui/map.js | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/ui/map.js b/src/ui/map.js
index fd5160a072d..f1ec4579948 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -2798,10 +2798,15 @@ function removeNode(node) {
  * `x` and `y` properties representing screen coordinates in pixels.
  *
  * @typedef {Object} Point
+ * @example
+ * var point = new mapboxgl.Point(-77, 38);
  */
 
 /**
  * A {@link Point} or an array of two numbers representing `x` and `y` screen coordinates in pixels.
  *
  * @typedef {(Point | Array<number>)} PointLike
+ * @example
+ * var p1 = new mapboxgl.Point(-77, 38); // a PointLike which is a Point
+ * var p2 = [-77, 38]; // a PointLike which is an array of two numbers
  */

From 6b419c2517daf19939f750d9c7afda11e21f797c Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Mon, 20 Apr 2020 15:37:21 -0700
Subject: [PATCH 25/74] [docsprint] Cleanup doc for MapBoxZoomEvent (#9564)

---
 src/ui/events.js | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index c3740f0133d..c987b1b3e55 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -218,17 +218,18 @@ export class MapWheelEvent extends Event {
 }
 
 /**
- * A `MapBoxZoomEvent` is the event type for boxzoom-related map events.
- * `originalEvent` can be a {@link Map.event:click} when the zoom is triggered by a UI event.
+ * A `MapBoxZoomEvent` is the event type for the boxzoom-related map events emitted by the {@link BoxZoomHandler}.
  *
  * @typedef {Object} MapBoxZoomEvent
- * @property {MouseEvent} originalEvent
+ * @property {MouseEvent?} originalEvent The DOM event that triggered the box zoom event. Can be a `MouseEvent` or `KeyboardEvent`
+ * @property {string} type The type of box zoom event. One of `boxzoomstart`, `boxzoomend` or `boxzoomcancel`
+ * @property {Map} target The `map` instance that triggerred the event
  */
 export type MapBoxZoomEvent = {
     type: 'boxzoomstart'
         | 'boxzoomend'
         | 'boxzoomcancel',
-    map: Map,
+    target: Map,
     originalEvent: MouseEvent
 };
 

From 73bc12013d663f10030965f98587239e80440a4b Mon Sep 17 00:00:00 2001
From: Adriana Babakanian <adriana.babakanian@mapbox.com>
Date: Mon, 20 Apr 2020 15:37:59 -0700
Subject: [PATCH 26/74] Describe map style object returned by Map#getStyle
 (#9579)

---
 src/ui/map.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index f1ec4579948..f77e8acf5ec 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1396,9 +1396,9 @@ class Map extends Camera {
     }
 
     /**
-     * Returns the map's Mapbox style object, which can be used to recreate the map's style.
+     * Returns the map's Mapbox [style](https://docs.mapbox.com/help/glossary/style/) object, a JSON object which can be used to recreate the map's style.
      *
-     * @returns {Object} The map's style object.
+     * @returns {Object} The map's style JSON object.
      *
      * @example
      * var styleJson = map.getStyle();

From 21a7fe998c339104a7ce0eab9b4f40e0c7152f75 Mon Sep 17 00:00:00 2001
From: Mal Wood-Santoro <mal.wood@mapbox.com>
Date: Mon, 20 Apr 2020 15:38:42 -0700
Subject: [PATCH 27/74] [docsprint] Add inline example for getClusterLeaves
 (#9580)

---
 src/source/geojson_source.js | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/source/geojson_source.js b/src/source/geojson_source.js
index 2b043f1ef91..864c505873e 100644
--- a/src/source/geojson_source.js
+++ b/src/source/geojson_source.js
@@ -230,6 +230,22 @@ class GeoJSONSource extends Evented implements Source {
      * @param offset The number of features to skip (e.g. for pagination).
      * @param callback A callback to be called when the features are retrieved (`(error, features) => { ... }`).
      * @returns {GeoJSONSource} this
+     * @example
+     * // Retrieve cluster leaves on click
+     *  map.on('click', 'clusters', function(e) {
+     *    var features = map.queryRenderedFeatures(e.point, {
+     *      layers: ['clusters']
+     *    });
+     *
+     *    var clusterId = features[0].properties.cluster_id;
+	 *    var pointCount = features[0].properties.point_count;
+	 *    var clusterSource = map.getSource('clusters');
+     *
+     *  clusterSource.getClusterLeaves(clusterId, pointCount, 0, (error, features) => {
+     *    // Print cluster leaves in the console
+     *    console.log('Cluster leaves:', error, features);
+  	 *	})
+     * });
      */
     getClusterLeaves(clusterId: number, limit: number, offset: number, callback: Callback<Array<GeoJSONFeature>>) {
         this.actor.send('geojson.getClusterLeaves', {

From 1d273381e9052a976b71f37be8a41967ad713b2d Mon Sep 17 00:00:00 2001
From: Patrick Leonard <pjleonard37@users.noreply.github.com>
Date: Mon, 20 Apr 2020 15:40:45 -0700
Subject: [PATCH 28/74] [docsprint] PaddingOptions - update definition,
 example, and related (#9581)

* PaddingOptions - update definition, example, and related

* Fixes formatting issues
---
 src/ui/camera.js | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index d6aec3205b3..b70649ffae6 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -86,7 +86,7 @@ export type AnimationOptions = {
 };
 
 /**
- * Options for setting padding on a call to {@link Map#fitBounds}. All properties of this object must be
+ * Options for setting padding on calls to methods such as {@link Map#fitBounds}, {@link Map#fitScreenCoordinates}, and {@link Map#setPadding}. Adjust these options to set the amount of padding in pixels added to the edges of the canvas. This can be set for either all edges or individually. All properties of this object must be
  * non-negative integers.
  *
  * @typedef {Object} PaddingOptions
@@ -94,6 +94,20 @@ export type AnimationOptions = {
  * @property {number} bottom Padding in pixels from the bottom of the map canvas.
  * @property {number} left Padding in pixels from the left of the map canvas.
  * @property {number} right Padding in pixels from the right of the map canvas.
+ *
+ * @example
+ * var bbox = [[-79, 43], [-73, 45]];
+ * map.fitBounds(bbox, {
+ *   padding: {top: 10, bottom:25, left: 15, right: 5}
+ * });
+ *
+ * @example
+ * var bbox = [[-79, 43], [-73, 45]];
+ * map.fitBounds(bbox, {
+ *   padding: 20
+ * });
+ * @see [Fit to the bounds of a LineString](https://docs.mapbox.com/mapbox-gl-js/example/zoomto-linestring/)
+ * @see [Fit a map to a bounding box](https://www.mapbox.com/mapbox-gl-js/example/fitbounds/)
  */
 
 class Camera extends Evented {

From cde46bec33b4ac6d5e977618929b1393ff0ffe1d Mon Sep 17 00:00:00 2001
From: Heather Stenson <heather.stenson@mapbox.com>
Date: Mon, 20 Apr 2020 15:41:49 -0700
Subject: [PATCH 29/74] [docsprint] Add inline snippet to marker#setPopup,
 marker#getPopup, and marker#togglePopup (#9582)

* update setPopup

* update getPopup

* update togglePopup

* update formatting
---
 src/ui/marker.js | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/src/ui/marker.js b/src/ui/marker.js
index b1b5f130f4e..7fe090c1394 100644
--- a/src/ui/marker.js
+++ b/src/ui/marker.js
@@ -309,10 +309,16 @@ export default class Marker extends Evented {
     }
 
     /**
-     * Binds a Popup to the Marker
-     * @param popup an instance of the `Popup` class. If undefined or null, any popup
-     * set on this `Marker` instance is unset
+     * Binds a `Popup` to the `Marker`.
+     * @param popup An instance of the `Popup` class. If undefined or null, any popup
+     * set on this `Marker` instance is unset.
      * @returns {Marker} `this`
+     * @example
+     * var marker = new mapboxgl.Marker()
+     *  .setLngLat([0, 0])
+     *  .setPopup(new mapboxgl.Popup().setHTML("<h1>Hello World!</h1>")) // add popup
+     *  .addTo(map);
+     * @see [Attach a popup to a marker instance](https://docs.mapbox.com/mapbox-gl-js/example/set-popup/)
      */
     setPopup(popup: ?Popup) {
         if (this._popup) {
@@ -376,16 +382,30 @@ export default class Marker extends Evented {
     }
 
     /**
-     * Returns the Popup instance that is bound to the Marker
+     * Returns the `Popup` instance that is bound to the `Marker`.
      * @returns {Popup} popup
+     * @example
+     * var marker = new mapboxgl.Marker()
+     *  .setLngLat([0, 0])
+     *  .setPopup(new mapboxgl.Popup().setHTML("<h1>Hello World!</h1>"))
+     *  .addTo(map);
+     *
+     * console.log(marker.getPopup()); // return the popup instance
      */
     getPopup() {
         return this._popup;
     }
 
     /**
-     * Opens or closes the bound popup, depending on the current state
+     * Opens or closes the `Popup` instance that is bound to the `Marker`, depending on the current state of the `Popup`.
      * @returns {Marker} `this`
+     * @example
+     * var marker = new mapboxgl.Marker()
+     *  .setLngLat([0, 0])
+     *  .setPopup(new mapboxgl.Popup().setHTML("<h1>Hello World!</h1>"))
+     *  .addTo(map);
+     *
+     * marker.togglePopup(); // toggle popup open or closed
      */
     togglePopup() {
         const popup = this._popup;

From 6228c725ebf235e8983271f22d0ba14d3b164347 Mon Sep 17 00:00:00 2001
From: David Wicks <david.wicks@mapbox.com>
Date: Mon, 20 Apr 2020 18:43:07 -0400
Subject: [PATCH 30/74] update setFilter jsdoc (#9586)

---
 src/ui/map.js | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index f77e8acf5ec..3959b2beb0a 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1936,19 +1936,35 @@ class Map extends Camera {
     /**
      * Sets the filter for the specified style layer.
      *
+     * Filters control which features a style layer renders from its source.
+     * Any feature for which the filter expression evaluates to true will be
+     * rendered on the map. Those that are false will be hidden.
+     *
+     * Use setFilter to show a subset of your source data.
+     *
+     * To clear the filter, pass `null` or `undefined` as the second parameter.
+     *
      * @param {string} layerId The ID of the layer to which the filter will be applied.
      * @param {Array | null | undefined} filter The filter, conforming to the Mapbox Style Specification's
      *   [filter definition](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#filter).  If `null` or `undefined` is provided, the function removes any existing filter from the layer.
      * @param {Object} [options] Options object.
      * @param {boolean} [options.validate=true] Whether to check if the filter conforms to the Mapbox GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function.
-     *
      * @returns {Map} `this`
+     *
+     * @example
+     * // display only features with the 'name' property 'USA'
+     * map.setFilter('my-layer', ['==', ['get', 'name'], 'USA']);
+     * @example
+     * // display only features with five or more 'available-spots'
+     * map.setFilter('bike-docks', ['>=', ['get', 'available-spots'], 5]);
      * @example
-     * map.setFilter('my-layer', ['==', 'name', 'USA']);
+     * // remove the filter for the 'bike-docks' style layer
+     * map.setFilter('bike-docks', null);
      *
      * @see [Filter features within map view](https://www.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/)
      * @see [Highlight features containing similar data](https://www.mapbox.com/mapbox-gl-js/example/query-similar-features/)
      * @see [Create a timeline animation](https://www.mapbox.com/mapbox-gl-js/example/timeline-animation/)
+     * @see [Tutorial: Show changes over time](https://docs.mapbox.com/help/tutorials/show-changes-over-time/)
      */
     setFilter(layerId: string, filter: ?FilterSpecification,  options: StyleSetterOptions = {}) {
         this.style.setFilter(layerId, filter, options);

From ea0f47ecdad513fcdef8b0947959a5b486bdc466 Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Date: Mon, 20 Apr 2020 15:43:37 -0700
Subject: [PATCH 31/74] add more details to getSource (#9587)

---
 src/ui/map.js | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 3959b2beb0a..35bb908cc6b 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1531,14 +1531,22 @@ class Map extends Camera {
     /**
      * Returns the source with the specified ID in the map's style.
      *
+     * This method is often used to update a source using the instance members for the relevant
+     * source type as defined in [Sources](#sources).
+     * For example, setting the `data` for a GeoJSON source or updating the `url` and `coordinates`
+     * of an image source.
+     *
      * @param {string} id The ID of the source to get.
-     * @returns {?Object} The style source with the specified ID, or `undefined`
-     *   if the ID corresponds to no existing sources.
+     * @returns {?Object} The style source with the specified ID or `undefined` if the ID
+     * corresponds to no existing sources.
+     * The shape of the object varies by source type.
+     * A list of options for each source type is available on the Mapbox Style Specification's
+     * [Sources](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/) page.
      * @example
      * var sourceObject = map.getSource('points');
-     * @see [Create a draggable point](https://www.mapbox.com/mapbox-gl-js/example/drag-a-point/)
-     * @see [Animate a point](https://www.mapbox.com/mapbox-gl-js/example/animate-point-along-line/)
-     * @see [Add live realtime data](https://www.mapbox.com/mapbox-gl-js/example/live-geojson/)
+     * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/)
+     * @see [Animate a point](https://docs.mapbox.com/mapbox-gl-js/example/animate-point-along-line/)
+     * @see [Add live realtime data](https://docs.mapbox.com/mapbox-gl-js/example/live-geojson/)
      */
     getSource(id: string) {
         return this.style.getSource(id);

From 48a3546cfe1d8b2306845b5bffba9f30aad148fc Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Date: Mon, 20 Apr 2020 15:44:06 -0700
Subject: [PATCH 32/74] add clearStorage example (#9588)

---
 src/index.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/index.js b/src/index.js
index c85f5def198..bdc8b97f348 100644
--- a/src/index.js
+++ b/src/index.js
@@ -163,6 +163,8 @@ const exported = {
      *
      * @function clearStorage
      * @param {Function} callback Called with an error argument if there is an error.
+     * @example
+     * mapboxgl.clearStorage();
      */
     clearStorage(callback?: (err: ?Error) => void) {
         clearTileCache(callback);

From 93774c6dbfc4b27fdaa7f9c82f50c15f92a3c333 Mon Sep 17 00:00:00 2001
From: Mal Wood-Santoro <mal.wood@mapbox.com>
Date: Mon, 20 Apr 2020 15:46:20 -0700
Subject: [PATCH 33/74] [docsprint] Add documentation for RequestParameters
 (#9573)

---
 src/util/ajax.js | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/util/ajax.js b/src/util/ajax.js
index be730d0ed93..03c2699f775 100644
--- a/src/util/ajax.js
+++ b/src/util/ajax.js
@@ -39,7 +39,29 @@ if (typeof Object.freeze == 'function') {
  * @typedef {Object} RequestParameters
  * @property {string} url The URL to be requested.
  * @property {Object} headers The headers to be sent with the request.
+ * @property {string} method Request method `'GET' | 'POST' | 'PUT'`.
+ * @property {string} body Request body.
+ * @property {string} type Response body type to be returned `'string' | 'json' | 'arrayBuffer'`.
  * @property {string} credentials `'same-origin'|'include'` Use 'include' to send cookies with cross-origin requests.
+ * @property {boolean} collectResourceTiming If true, Resource Timing API information will be collected for these transformed requests and returned in a resourceTiming property of relevant data events.
+ * @example
+ * // transformRequest used to modify requests that begin with `http://myHost`
+ * transformRequest: (url, resourceType)=> {
+ *  if(resourceType === 'Source' && url.startsWith('http://myHost')) {
+ *    return {
+ *      url: url.replace('http', 'https'),
+ *      headers: { 'my-custom-header': true},
+ *      credentials: 'include'  // Include cookies for cross-origin requests
+ *    }
+ *   }
+ *  }
+ * // Example of `RequestParameters` object returned from the above transformRequest function.
+ * {
+ *  url: 'https://myHost//assets/sample.geojson'
+ *  headers: {'my-custom-header': true}
+ *  credentials: 'include'
+ * }
+ *
  */
 export type RequestParameters = {
     url: string,

From 523a4454a958adaf86a36aca38fd87089812c8f6 Mon Sep 17 00:00:00 2001
From: Mal Wood-Santoro <mal.wood@mapbox.com>
Date: Mon, 20 Apr 2020 15:55:48 -0700
Subject: [PATCH 34/74] [docsprint] Add inline example for setZoomRate and
 setWheelZoomRate of scrollZoomHandler (#9593)

* Add inline example for setZoomRate of scrollZoomHandler

* add setWheelZoomRate inline example
---
 src/ui/handler/scroll_zoom.js | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/ui/handler/scroll_zoom.js b/src/ui/handler/scroll_zoom.js
index a123a1e711e..a8fc61d109f 100644
--- a/src/ui/handler/scroll_zoom.js
+++ b/src/ui/handler/scroll_zoom.js
@@ -81,15 +81,21 @@ class ScrollZoomHandler {
     /**
      * Set the zoom rate of a trackpad
      * @param {number} [zoomRate=1/100] The rate used to scale trackpad movement to a zoom value.
+     * @example
+     * // Speed up trackpad zoom
+     * map.scrollZoom.setZoomRate(1/25);
      */
     setZoomRate(zoomRate: number) {
         this._defaultZoomRate = zoomRate;
     }
 
     /**
-     * Set the zoom rate of a mouse wheel
-     * @param {number} [wheelZoomRate=1/450] The rate used to scale mouse wheel movement to a zoom value.
-     */
+    * Set the zoom rate of a mouse wheel
+    * @param {number} [wheelZoomRate=1/450] The rate used to scale mouse wheel movement to a zoom value.
+    * @example
+    * // Slow down zoom of mouse wheel
+    * map.scrollZoom.setWheelZoomRate(1/600);
+    */
     setWheelZoomRate(wheelZoomRate: number) {
         this._wheelZoomRate = wheelZoomRate;
     }

From 176e092f1f49a67de61bc6b515365e5661326901 Mon Sep 17 00:00:00 2001
From: Adriana Babakanian <adriana.babakanian@mapbox.com>
Date: Mon, 20 Apr 2020 15:57:09 -0700
Subject: [PATCH 35/74] Add inline examples for map zoom-related methods
 (#9594)

---
 src/ui/camera.js | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index b70649ffae6..56f2c74931c 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -219,6 +219,8 @@ class Camera extends Evented {
      *
      * @memberof Map#
      * @returns The map's current zoom level.
+     * @example
+     * map.getZoom();
      */
     getZoom(): number { return this.transform.zoom; }
 
@@ -236,7 +238,7 @@ class Camera extends Evented {
      * @fires zoomend
      * @returns {Map} `this`
      * @example
-     * // zoom the map to 5
+     * // zoom the map to 5 without an animated transition
      * map.setZoom(5);
      */
     setZoom(zoom: number, eventData?: Object) {
@@ -258,6 +260,14 @@ class Camera extends Evented {
      * @fires moveend
      * @fires zoomend
      * @returns {Map} `this`
+     * @example
+     * // zoom the map to 5 with an animated transition
+     * map.zoomTo(5);
+     * // zoom the map to 8 with custom animation options
+     * map.zoomTo(8, {
+     *   duration: 2000,
+     *   offset: [100, 50]
+     * });
      */
     zoomTo(zoom: number, options: ? AnimationOptions, eventData?: Object) {
         return this.easeTo(extend({
@@ -278,6 +288,9 @@ class Camera extends Evented {
      * @fires moveend
      * @fires zoomend
      * @returns {Map} `this`
+     * @example
+     * // zoom the map in one level with a custom animation duration
+     * map.zoomIn({duration: 1000});
      */
     zoomIn(options?: AnimationOptions, eventData?: Object) {
         this.zoomTo(this.getZoom() + 1, options, eventData);
@@ -297,6 +310,9 @@ class Camera extends Evented {
      * @fires moveend
      * @fires zoomend
      * @returns {Map} `this`
+     * @example
+     * // zoom the map out one level with a custom animation offset
+     * map.zoomOut({offset: [80, 60]});
      */
     zoomOut(options?: AnimationOptions, eventData?: Object) {
         this.zoomTo(this.getZoom() - 1, options, eventData);

From e8aab02827af81a63f69924839e550909f444323 Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Date: Mon, 20 Apr 2020 15:57:45 -0700
Subject: [PATCH 36/74] [docsprint] Add example to MapMouseEvent (#9595)

* add example to MapMouseEvent

* fix linting error

* fix copy paste error
---
 src/ui/events.js | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index c987b1b3e55..4a793f603b4 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -12,10 +12,27 @@ import type LngLat from '../geo/lng_lat';
 /**
  * `MapMouseEvent` is the event type for mouse-related map events.
  * @extends {Object}
+ * @example
+ * // The `click` event is an example of a `MapMouseEvent`.
+ * // Set up an event listener on the map.
+ * map.on('click', function(e) {
+ *   // The event object (`e`) contains information like the
+ *   // coordinates of the point on the map that was clicked.
+ *   console.log('A click event has occurred at ' + e.lngLat);
+ * });
  */
 export class MapMouseEvent extends Event {
     /**
-     * The event type.
+     * The event type (one of [`mousedown`](#map.event:mousedown),
+     * [`mouseup`](#map.event:mouseup),
+     * [`click`](#map.event:click),
+     * [`dblclick`](#map.event:dblclick),
+     * [`mousemove`](#map.event:mousemove),
+     * [`mouseover`](#map.event:mouseover),
+     * [`mouseenter`](#map.event:mouseenter),
+     * [`mouseleave`](#map.event:mouseleave),
+     * [`mouseout`](#map.event:mouseout),
+     * [`contextmenu`](#map.event:contextmenu)).
      */
     type: 'mousedown'
         | 'mouseup'

From 4bbd7f00315c68263db90a09129ae4a6e123d8d6 Mon Sep 17 00:00:00 2001
From: Adriana Babakanian <adriana.babakanian@mapbox.com>
Date: Mon, 20 Apr 2020 15:59:22 -0700
Subject: [PATCH 37/74] Add examples for GeolocateControl events (#9596)

---
 src/ui/control/geolocate_control.js | 75 +++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/src/ui/control/geolocate_control.js b/src/ui/control/geolocate_control.js
index 34ff7731d3c..37377e613db 100644
--- a/src/ui/control/geolocate_control.js
+++ b/src/ui/control/geolocate_control.js
@@ -565,6 +565,21 @@ export default GeolocateControl;
  * @memberof GeolocateControl
  * @instance
  * @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) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition).
+ * @example
+ * // Initialize the geolocate control.
+ * var geolocate = new mapboxgl.GeolocateControl({
+ *   positionOptions: {
+ *       enableHighAccuracy: true
+ *   },
+ *   trackUserLocation: true
+ * });
+ * // Add the control to the map.
+ * map.addControl(geolocate);
+ * // Set an event listener that fires
+ * // when a geolocate event occurs.
+ * geolocate.on('geolocate', function() {
+ *   console.log('A geolocate event has occurred.')
+ * });
  *
  */
 
@@ -575,6 +590,21 @@ export default GeolocateControl;
  * @memberof GeolocateControl
  * @instance
  * @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) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition).
+ * @example
+ * // Initialize the geolocate control.
+ * var geolocate = new mapboxgl.GeolocateControl({
+ *   positionOptions: {
+ *       enableHighAccuracy: true
+ *   },
+ *   trackUserLocation: true
+ * });
+ * // Add the control to the map.
+ * map.addControl(geolocate);
+ * // Set an event listener that fires
+ * // when an error event occurs.
+ * geolocate.on('error', function() {
+ *   console.log('An error event has occurred.')
+ * });
  *
  */
 
@@ -585,6 +615,21 @@ export default GeolocateControl;
  * @memberof GeolocateControl
  * @instance
  * @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) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition).
+ * @example
+ * // Initialize the geolocate control.
+ * var geolocate = new mapboxgl.GeolocateControl({
+ *   positionOptions: {
+ *       enableHighAccuracy: true
+ *   },
+ *   trackUserLocation: true
+ * });
+ * // Add the control to the map.
+ * map.addControl(geolocate);
+ * // Set an event listener that fires
+ * // when an outofmaxbounds event occurs.
+ * geolocate.on('outofmaxbounds', function() {
+ *   console.log('An outofmaxbounds event has occurred.')
+ * });
  *
  */
 
@@ -594,6 +639,21 @@ export default GeolocateControl;
  * @event trackuserlocationstart
  * @memberof GeolocateControl
  * @instance
+ * @example
+ * // Initialize the geolocate control.
+ * var geolocate = new mapboxgl.GeolocateControl({
+ *   positionOptions: {
+ *       enableHighAccuracy: true
+ *   },
+ *   trackUserLocation: true
+ * });
+ * // Add the control to the map.
+ * map.addControl(geolocate);
+ * // Set an event listener that fires
+ * // when a trackuserlocationstart event occurs.
+ * geolocate.on('trackuserlocationstart', function() {
+ *   console.log('A trackuserlocationstart event has occurred.')
+ * });
  *
  */
 
@@ -603,5 +663,20 @@ export default GeolocateControl;
  * @event trackuserlocationend
  * @memberof GeolocateControl
  * @instance
+ * @example
+ * // Initialize the geolocate control.
+ * var geolocate = new mapboxgl.GeolocateControl({
+ *   positionOptions: {
+ *       enableHighAccuracy: true
+ *   },
+ *   trackUserLocation: true
+ * });
+ * // Add the control to the map.
+ * map.addControl(geolocate);
+ * // Set an event listener that fires
+ * // when a trackuserlocationend event occurs.
+ * geolocate.on('trackuserlocationend', function() {
+ *   console.log('A trackuserlocationend event has occurred.')
+ * });
  *
  */

From b0623b8a0128ef00cbb1ef13b6f7685c238c880f Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Date: Mon, 20 Apr 2020 16:00:32 -0700
Subject: [PATCH 38/74] [docsprint] Add example to MapDataEvent (#9597)

* add example to MapDataEvent

* fix copy paste mistake
---
 src/ui/events.js | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/ui/events.js b/src/ui/events.js
index 4a793f603b4..f4a36fbca63 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -269,6 +269,15 @@ export type MapBoxZoomEvent = {
  * the event is related to loading of a tile.
  * @property {Coordinate} [coord] The coordinate of the tile if the event has a `dataType` of `source` and
  * the event is related to loading of a tile.
+ * @example
+ * // The `sourcedata` event is an example of `MapDataEvent`.
+ * // Set up an event listener on the map.
+ * map.on('sourcedata', function(e) {
+ *    if (e.isSourceLoaded) {
+ *        // Do something when there are no more
+ *        // outstanding network requests
+ *    }
+ * });
  */
 export type MapDataEvent = {
     type: string,

From a55e8e8fb8b148f927fd1b0957e4b4b2e47ac9a4 Mon Sep 17 00:00:00 2001
From: Deven Diliberto <deven.diliberto@mapbox.com>
Date: Mon, 20 Apr 2020 16:04:01 -0700
Subject: [PATCH 39/74] add example for getLngLat (#9591)

---
 src/ui/marker.js | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/ui/marker.js b/src/ui/marker.js
index 7fe090c1394..991d1f1b39a 100644
--- a/src/ui/marker.js
+++ b/src/ui/marker.js
@@ -274,7 +274,13 @@ export default class Marker extends Evented {
      * the marker on screen.
      *
      * @returns {LngLat} A {@link LngLat} describing the marker's location.
-     */
+    * @example
+    * // Store the marker's longitude and latitude coordinates in a variable
+    * var lngLat = marker.getLngLat();
+    * // Print the marker's longitude and latitude values in the console
+    * console.log('Longitude: ' + lngLat.lng + ', Latitude: ' + lngLat.lat )
+    * @see [Create a draggable Marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-marker/)
+    */
     getLngLat() {
         return this._lngLat;
     }

From 48660260b010773e132c6e85b2ca40240a35e0a1 Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Thu, 16 Apr 2020 14:59:52 -0700
Subject: [PATCH 40/74] suggested edits for clarifying mouse events

---
 src/ui/events.js | 126 ++++++++++++++++++++++++++++++++++-------------
 1 file changed, 93 insertions(+), 33 deletions(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index f4a36fbca63..70f50b61858 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -293,6 +293,10 @@ export type MapEvent =
     /**
      * Fired when a pointing device (usually a mouse) is pressed within the map.
      *
+     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
+     * the cursor is pressed while inside a visible portion of the specifed layer.
+     *
      * @event mousedown
      * @memberof Map
      * @instance
@@ -300,20 +304,29 @@ export type MapEvent =
      * @example
      * // Initialize the map
      * var map = new mapboxgl.Map({ // map options });
-     * // Set an event listener that fires
-     * // when the pointing device is pressed
-     * // within the map.
+     * // Set an event listener
      * map.on('mousedown', function() {
      *   console.log('A mousedown event has occurred.');
      * });
-     * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)
-     * @see [Create a draggable point](https://www.mapbox.com/mapbox-gl-js/example/drag-a-point/)
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener for a specific layer
+     * map.on('mousedown', 'poi-label', function() {
+     *   console.log('A mousedown event has occurred on a visible portion of the poi-label layer.');
+     * });
+     * @see [Highlight features within a bounding box](https://docs.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)
+     * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/)
      */
     | 'mousedown'
 
     /**
      * Fired when a pointing device (usually a mouse) is released within the map.
      *
+     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
+     * the cursor is released while inside a visible portion of the specifed layer.
+     *
      * @event mouseup
      * @memberof Map
      * @instance
@@ -321,19 +334,30 @@ export type MapEvent =
      * @example
      * // Initialize the map
      * var map = new mapboxgl.Map({ // map options });
-     * // Set an event listener that fires
-     * // when the pointing device is released
-     * // within the map.
+     * // Set an event listener
      * map.on('mouseup', function() {
      *   console.log('A mouseup event has occurred.');
      * });
-     * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)
-     * @see [Create a draggable point](https://www.mapbox.com/mapbox-gl-js/example/drag-a-point/)
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener for a specific layer
+     * map.on('mouseup', 'poi-label', function() {
+     *   console.log('A mouseup event has occurred on a visible portion of the poi-label layer.');
+     * });
+     * @see [Highlight features within a bounding box](https://docs.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)
+     * @see [Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/)
      */
     | 'mouseup'
 
     /**
      * Fired when a pointing device (usually a mouse) is moved within the map.
+     * As you move the cursor across a web page containing a map,
+     * the event will fire each time it enters the map and any child elements.
+     *
+     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
+     * the cursor is moved inside a visible portion of the specifed layer.
      *
      * @event mouseover
      * @memberof Map
@@ -342,12 +366,17 @@ export type MapEvent =
      * @example
      * // Initialize the map
      * var map = new mapboxgl.Map({ // map options });
-     * // Set an event listener that fires
-     * // when the pointing is moved
-     * // within the map.
+     * // Set an event listener
      * map.on('mouseover', function() {
      *   console.log('A mouseover event has occurred.');
      * });
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener for a specific layer
+     * map.on('mouseover', 'poi-label', function() {
+     *   console.log('A mouseover event has occurred on a visible portion of the poi-label layer.');
+     * });
      * @see [Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/)
      * @see [Highlight features under the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/hover-styles/)
      * @see [Display a popup on hover](https://www.mapbox.com/mapbox-gl-js/example/popup-on-hover/)
@@ -355,7 +384,12 @@ export type MapEvent =
     | 'mouseover'
 
     /**
-     * Fired when a pointing device (usually a mouse) is moved within the map.
+     * Fired when a pointing device (usually a mouse) is moved while the cursor's hotspot is inside the map.
+     * As you move the cursor across the map, the event will fire everytime the cursor changes position within the map.
+     *
+     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
+     * the cursor's hotspot is inside a visible portion of the specifed layer.
      *
      * @event mousemove
      * @memberof Map
@@ -364,12 +398,17 @@ export type MapEvent =
      * @example
      * // Initialize the map
      * var map = new mapboxgl.Map({ // map options });
-     * // Set an event listener that fires
-     * // when the pointing device is moved
-     * // within the map.
+     * // Set an event listener
      * map.on('mousemove', function() {
      *   console.log('A mousemove event has occurred.');
      * });
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener for a specific layer
+     * map.on('mousemove', 'poi-label', function() {
+     *   console.log('A mousemove event has occurred on a visible portion of the poi-label layer.');
+     * });
      * @see [Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/)
      * @see [Highlight features under the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/hover-styles/)
      * @see [Display a popup on over](https://www.mapbox.com/mapbox-gl-js/example/popup-on-hover/)
@@ -379,6 +418,10 @@ export type MapEvent =
     /**
      * Fired when a pointing device (usually a mouse) is pressed and released at the same point on the map.
      *
+     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
+     * point that is pressed and released contains a visible portion of the specifed layer.
+     *
      * @event click
      * @memberof Map
      * @instance
@@ -386,19 +429,29 @@ export type MapEvent =
      * @example
      * // Initialize the map
      * var map = new mapboxgl.Map({ // map options });
-     * // Set an event listener that fires
-     * // when the pointing device is pressed and
-     * // released at the same point within the map.
+     * // Set an event listener
      * map.on('click', function(e) {
      *   console.log('A click event has occurred at ' + e.lngLat);
      * });
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener for a specific layer
+     * map.on('click', 'poi-label', function(e) {
+     *   console.log('A click event has occurred on a visible portion of the poi-label layer at ' + e.lngLat);
+     * });
      * @see [Measure distances](https://www.mapbox.com/mapbox-gl-js/example/measure/)
      * @see [Center the map on a clicked symbol](https://www.mapbox.com/mapbox-gl-js/example/center-on-symbol/)
      */
     | 'click'
 
     /**
-     * Fired when a pointing device (usually a mouse) is clicked twice at the same point on the map.
+     * Fired when a pointing device (usually a mouse) is pressed and released twice at the same point on
+     * the map in rapid succession.
+     *
+     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only
+     * when the point that is clicked twice contains a visible portion of the specifed layer.
      *
      * @event dblclick
      * @memberof Map
@@ -407,19 +460,26 @@ export type MapEvent =
      * @example
      * // Initialize the map
      * var map = new mapboxgl.Map({ // map options });
-     * // Set an event listener that fires
-     * // when the pointing device is pressed and
-     * // released twice at the same point within the map.
-     * map.on('dblclick', function() {
-     *   console.log('A dblclick event has occurred.');
+     * // Set an event listener
+     * map.on('dblclick', function(e) {
+     *   console.log('A dblclick event has occurred at ' + e.lngLat);
+     * });
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener for a specific layer
+     * map.on('dblclick', 'poi-label', function(e) {
+     *   console.log('A dblclick event has occurred on a visible portion of the poi-label layer at ' + e.lngLat);
      * });
      */
     | 'dblclick'
 
     /**
      * Fired when a pointing device (usually a mouse) enters a visible portion of a specified layer from
-     * outside that layer or outside the map canvas. This event can only be listened for via the three-argument
-     * version of {@link Map#on}, where the second argument specifies the desired layer.
+     * outside that layer or outside the map canvas.
+     *
+     * **Important:** This event can only be listened for when {@link Map#on} includes three arguements,
+     * where the second argument specifies the desired layer.
      *
      * @event mouseenter
      * @memberof Map
@@ -428,11 +488,9 @@ export type MapEvent =
      * @example
      * // Initialize the map
      * var map = new mapboxgl.Map({ // map options });
-     * // Set an event listener that fires
-     * // when the pointing device enters
-     * // a visible portion of the specified layer.
+     * // Set an event listener
      * map.on('mouseenter', 'water', function() {
-     *   console.log('A mouseenter event occurred.');
+     *   console.log('A mouseenter event occurred on a visible portion of the water layer.');
      * });
      * @see [Center the map on a clicked symbol](https://www.mapbox.com/mapbox-gl-js/example/center-on-symbol/)
      * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
@@ -441,7 +499,9 @@ export type MapEvent =
 
     /**
      * Fired when a pointing device (usually a mouse) leaves a visible portion of a specified layer, or leaves
-     * the map canvas. This event can only be listened for via the three-argument version of {@link Map#on},
+     * the map canvas.
+     *
+     * **Important:** This event can only be listened for when {@link Map#on} includes three arguements,
      * where the second argument specifies the desired layer.
      *
      * @event mouseleave

From 3379e241ffb7be94ef7a4ebfabf049eba9f2503a Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Wed, 22 Apr 2020 09:19:40 -0400
Subject: [PATCH 41/74] Small grammar fix: "optional the `layerId`" -> "the
 optional `layerId"

---
 src/ui/events.js | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index 70f50b61858..74fa1e520a3 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -293,7 +293,7 @@ export type MapEvent =
     /**
      * Fired when a pointing device (usually a mouse) is pressed within the map.
      *
-     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * **Note:** This event is compatible with the optional `layerId` parameter.
      * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
      * the cursor is pressed while inside a visible portion of the specifed layer.
      *
@@ -323,7 +323,7 @@ export type MapEvent =
     /**
      * Fired when a pointing device (usually a mouse) is released within the map.
      *
-     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * **Note:** This event is compatible with the optional `layerId` parameter.
      * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
      * the cursor is released while inside a visible portion of the specifed layer.
      *
@@ -355,7 +355,7 @@ export type MapEvent =
      * As you move the cursor across a web page containing a map,
      * the event will fire each time it enters the map and any child elements.
      *
-     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * **Note:** This event is compatible with the optional `layerId` parameter.
      * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
      * the cursor is moved inside a visible portion of the specifed layer.
      *
@@ -387,7 +387,7 @@ export type MapEvent =
      * Fired when a pointing device (usually a mouse) is moved while the cursor's hotspot is inside the map.
      * As you move the cursor across the map, the event will fire everytime the cursor changes position within the map.
      *
-     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * **Note:** This event is compatible with the optional `layerId` parameter.
      * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
      * the cursor's hotspot is inside a visible portion of the specifed layer.
      *
@@ -418,7 +418,7 @@ export type MapEvent =
     /**
      * Fired when a pointing device (usually a mouse) is pressed and released at the same point on the map.
      *
-     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * **Note:** This event is compatible with the optional `layerId` parameter.
      * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
      * point that is pressed and released contains a visible portion of the specifed layer.
      *
@@ -449,7 +449,7 @@ export type MapEvent =
      * Fired when a pointing device (usually a mouse) is pressed and released twice at the same point on
      * the map in rapid succession.
      *
-     * **Note:** This event is compatible with optional the `layerId` parameter.
+     * **Note:** This event is compatible with the optional `layerId` parameter.
      * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only
      * when the point that is clicked twice contains a visible portion of the specifed layer.
      *

From 94217f904966b64e585cbcc42dff0dcbc660a044 Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Wed, 22 Apr 2020 09:23:07 -0400
Subject: [PATCH 42/74] Remove stray `}`; Add missing `);`

---
 src/ui/camera.js                    | 1 -
 src/ui/control/geolocate_control.js | 2 +-
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index 56f2c74931c..6d700e5991d 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -698,7 +698,6 @@ class Camera extends Evented {
      *   zoom: 8,
      *   pitch: 45,
      *   bearing: 90
-     *   }
      * });
      * @see [Jump to a series of locations](https://docs.mapbox.com/mapbox-gl-js/example/jump-to/)
      * @see [Update a feature in realtime](https://docs.mapbox.com/mapbox-gl-js/example/live-update-feature/)
diff --git a/src/ui/control/geolocate_control.js b/src/ui/control/geolocate_control.js
index 37377e613db..e9010990968 100644
--- a/src/ui/control/geolocate_control.js
+++ b/src/ui/control/geolocate_control.js
@@ -421,7 +421,7 @@ class GeolocateControl extends Evented {
     * map.addControl(geolocate);
     * map.on('load', function() {
     *   geolocate.trigger();
-    * }
+    * });
     */
     trigger() {
         if (!this._setup) {

From 72a6f6fc23a7a94f2b9ac2da95ee712819399ea1 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:36:32 -0700
Subject: [PATCH 43/74] Update src/geo/lng_lat_bounds.js

Co-Authored-By: Katy DeCorah <decorah@mapbox.com>
---
 src/geo/lng_lat_bounds.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/geo/lng_lat_bounds.js b/src/geo/lng_lat_bounds.js
index 6bc992340ef..f2360e96db6 100644
--- a/src/geo/lng_lat_bounds.js
+++ b/src/geo/lng_lat_bounds.js
@@ -224,7 +224,7 @@ class LngLatBounds {
     *
     * var ll = new mapboxgl.LngLat(-73.9567, 40.7789);
     *
-    * llb.contains(ll); // = true
+    * console.log(llb.contains(ll)); // = true
     */
     contains(lnglat: LngLatLike) {
         const {lng, lat} = LngLat.convert(lnglat);

From efff4faac36288718862bbe91a7d92d83564f621 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:36:52 -0700
Subject: [PATCH 44/74] Update src/source/geojson_source.js

Co-Authored-By: Katy DeCorah <decorah@mapbox.com>
---
 src/source/geojson_source.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/source/geojson_source.js b/src/source/geojson_source.js
index 864c505873e..c168b228c3e 100644
--- a/src/source/geojson_source.js
+++ b/src/source/geojson_source.js
@@ -241,7 +241,7 @@ class GeoJSONSource extends Evented implements Source {
 	 *    var pointCount = features[0].properties.point_count;
 	 *    var clusterSource = map.getSource('clusters');
      *
-     *  clusterSource.getClusterLeaves(clusterId, pointCount, 0, (error, features) => {
+     *  clusterSource.getClusterLeaves(clusterId, pointCount, 0, function(error, features) {
      *    // Print cluster leaves in the console
      *    console.log('Cluster leaves:', error, features);
   	 *	})

From 265943345facb62ff55726e940a1626c3725b26f Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:37:07 -0700
Subject: [PATCH 45/74] Update src/ui/camera.js

Co-Authored-By: Katy DeCorah <decorah@mapbox.com>
---
 src/ui/camera.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index 6d700e5991d..0be8add62f8 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -149,7 +149,7 @@ class Camera extends Evented {
      * @memberof Map#
      * @returns The map's geographical centerpoint.
      * @example
-     * // return a LngLat object such as {lng: 0, lat: 0} at null island
+     * // return a LngLat object such as {lng: 0, lat: 0} 
      * var center = map.getCenter();
      * // return longitude and latitude values directly
      * var longitude = map.getCenter().lng;

From 1cea6207a0e1009a9a540fd31222689c85af8ad9 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:37:22 -0700
Subject: [PATCH 46/74] Update src/ui/map.js

Co-Authored-By: Katy DeCorah <decorah@mapbox.com>
---
 src/ui/map.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 35bb908cc6b..9f4fa14db35 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -2158,7 +2158,7 @@ class Map extends Camera {
      * // When the mouse leaves the `my-layer` layer,
      * // reset only the `hover` key-value pair in the
      * // state for the feature under the mouse
-     * map.on('mouseleave', 'my-layer', (e) => {
+     * map.on('mouseleave', 'my-layer', function(e) {
      *   map.removeFeatureState({
      *     source: 'my-source',
      *     sourceLayer: 'my-source-layer',

From da7fbf432088d2f734df9e0033bf7a0c06026754 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:37:38 -0700
Subject: [PATCH 47/74] Update src/util/ajax.js

Co-Authored-By: Katy DeCorah <decorah@mapbox.com>
---
 src/util/ajax.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/util/ajax.js b/src/util/ajax.js
index 03c2699f775..8fc79a6da8b 100644
--- a/src/util/ajax.js
+++ b/src/util/ajax.js
@@ -46,7 +46,7 @@ if (typeof Object.freeze == 'function') {
  * @property {boolean} collectResourceTiming If true, Resource Timing API information will be collected for these transformed requests and returned in a resourceTiming property of relevant data events.
  * @example
  * // transformRequest used to modify requests that begin with `http://myHost`
- * transformRequest: (url, resourceType)=> {
+ * transformRequest: function(url, resourceType) {
  *  if(resourceType === 'Source' && url.startsWith('http://myHost')) {
  *    return {
  *      url: url.replace('http', 'https'),

From cf16abe2d971a194734a03dc2402db088149a857 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:37:59 -0700
Subject: [PATCH 48/74] Update src/ui/events.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/events.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index 74fa1e520a3..3871088f119 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -16,7 +16,7 @@ import type LngLat from '../geo/lng_lat';
  * // The `click` event is an example of a `MapMouseEvent`.
  * // Set up an event listener on the map.
  * map.on('click', function(e) {
- *   // The event object (`e`) contains information like the
+ *   // The event object (e) contains information like the
  *   // coordinates of the point on the map that was clicked.
  *   console.log('A click event has occurred at ' + e.lngLat);
  * });

From 95e277327ba50207b79448571af931330b782a84 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:38:13 -0700
Subject: [PATCH 49/74] Update src/ui/events.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/events.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index 3871088f119..010cfecf7dd 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -239,7 +239,7 @@ export class MapWheelEvent extends Event {
  *
  * @typedef {Object} MapBoxZoomEvent
  * @property {MouseEvent?} originalEvent The DOM event that triggered the box zoom event. Can be a `MouseEvent` or `KeyboardEvent`
- * @property {string} type The type of box zoom event. One of `boxzoomstart`, `boxzoomend` or `boxzoomcancel`
+ * @property {string} type The type of boxzoom event. One of `boxzoomstart`, `boxzoomend` or `boxzoomcancel`
  * @property {Map} target The `map` instance that triggerred the event
  */
 export type MapBoxZoomEvent = {

From 4cf5c75ee9eed250a42814cb335dad9ea2e853a5 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:38:27 -0700
Subject: [PATCH 50/74] Update src/ui/events.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/events.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index 010cfecf7dd..036244f192c 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -238,7 +238,7 @@ export class MapWheelEvent extends Event {
  * A `MapBoxZoomEvent` is the event type for the boxzoom-related map events emitted by the {@link BoxZoomHandler}.
  *
  * @typedef {Object} MapBoxZoomEvent
- * @property {MouseEvent?} originalEvent The DOM event that triggered the box zoom event. Can be a `MouseEvent` or `KeyboardEvent`
+ * @property {MouseEvent?} originalEvent The DOM event that triggered the boxzoom event. Can be a `MouseEvent` or `KeyboardEvent`
  * @property {string} type The type of boxzoom event. One of `boxzoomstart`, `boxzoomend` or `boxzoomcancel`
  * @property {Map} target The `map` instance that triggerred the event
  */

From 173196bc638935be351949ec6ef053ab077426d5 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:40:01 -0700
Subject: [PATCH 51/74] Update src/ui/events.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/events.js | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index 036244f192c..90f2052ce6b 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -274,8 +274,7 @@ export type MapBoxZoomEvent = {
  * // Set up an event listener on the map.
  * map.on('sourcedata', function(e) {
  *    if (e.isSourceLoaded) {
- *        // Do something when there are no more
- *        // outstanding network requests
+ *        // Do something when the source has finished loading
  *    }
  * });
  */

From 05a1650ec6d5221e90364e0a7d5b069c3744d4ce Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:40:15 -0700
Subject: [PATCH 52/74] Update src/ui/map.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/map.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 9f4fa14db35..a7fc9b0c3be 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -981,7 +981,7 @@ class Map extends Camera {
      * | [`sourcedataloading`](#map.event:sourcedataloading)       |                           |
      * | [`styleimagemissing`](#map.event:styleimagemissing)       |                           |
      *
-     * @param {string} layerId (optional) The ID of a style layer. Event will only be triggered if their location
+     * @param {string} layerId (optional) The ID of a style layer. Event will only be triggered if its location
      * is within a visible feature in this layer. The event will have a `features` property containing
      * an array of the matching features. If `layerId` is not supplied, the event will not have a `features` property.
      * Please note that many event types are not compatible with the optional `layerId` parameter.

From 165afe8ae6e5773716447d14e1e5aa0a1f280390 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:42:36 -0700
Subject: [PATCH 53/74] Update src/ui/camera.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/camera.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index 0be8add62f8..2b1c444a213 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -692,7 +692,7 @@ class Camera extends Evented {
      * @example
      * // jump to null island at current zoom
      * map.jumpTo({center: [0, 0]});
-     * // jump with zoom, pitch, and bearing set
+     * // jump with zoom, pitch, and bearing options
      * map.jumpTo({
      *   center: [0, 0],
      *   zoom: 8,

From 001da7b4f02f4769845e9953a781b73ebcb73771 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:42:53 -0700
Subject: [PATCH 54/74] Update src/ui/events.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/events.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index 90f2052ce6b..a3f78be261c 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -240,7 +240,7 @@ export class MapWheelEvent extends Event {
  * @typedef {Object} MapBoxZoomEvent
  * @property {MouseEvent?} originalEvent The DOM event that triggered the boxzoom event. Can be a `MouseEvent` or `KeyboardEvent`
  * @property {string} type The type of boxzoom event. One of `boxzoomstart`, `boxzoomend` or `boxzoomcancel`
- * @property {Map} target The `map` instance that triggerred the event
+ * @property {Map} target The `Map` instance that triggerred the event
  */
 export type MapBoxZoomEvent = {
     type: 'boxzoomstart'

From 1c2256274e3d635a9403ff1b6215abdf170ef599 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:43:04 -0700
Subject: [PATCH 55/74] Update src/ui/events.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/events.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index a3f78be261c..22f85942268 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -352,7 +352,7 @@ export type MapEvent =
     /**
      * Fired when a pointing device (usually a mouse) is moved within the map.
      * As you move the cursor across a web page containing a map,
-     * the event will fire each time it enters the map and any child elements.
+     * the event will fire each time it enters the map or any child elements.
      *
      * **Note:** This event is compatible with the optional `layerId` parameter.
      * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the

From 8a8d020fd7f706607ea011ae960283daaad45c84 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:53:18 -0700
Subject: [PATCH 56/74] Update src/ui/marker.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/marker.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/marker.js b/src/ui/marker.js
index 991d1f1b39a..37b19067cff 100644
--- a/src/ui/marker.js
+++ b/src/ui/marker.js
@@ -403,7 +403,7 @@ export default class Marker extends Evented {
     }
 
     /**
-     * Opens or closes the `Popup` instance that is bound to the `Marker`, depending on the current state of the `Popup`.
+     * Opens or closes the {@link Popup} instance that is bound to the {@link Marker}, depending on the current state of the {@link Popup}.
      * @returns {Marker} `this`
      * @example
      * var marker = new mapboxgl.Marker()

From d56984ac16a175843a68e840651d6bfce6d5e848 Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:53:30 -0700
Subject: [PATCH 57/74] Update src/ui/marker.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/marker.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/marker.js b/src/ui/marker.js
index 37b19067cff..c0a277b1bb3 100644
--- a/src/ui/marker.js
+++ b/src/ui/marker.js
@@ -388,7 +388,7 @@ export default class Marker extends Evented {
     }
 
     /**
-     * Returns the `Popup` instance that is bound to the `Marker`.
+     * Returns the {@link Popup} instance that is bound to the {@link Marker}.
      * @returns {Popup} popup
      * @example
      * var marker = new mapboxgl.Marker()

From 35e14e91249f8bd158fbee590a6fa0c0b960acbd Mon Sep 17 00:00:00 2001
From: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Date: Wed, 22 Apr 2020 22:53:41 -0700
Subject: [PATCH 58/74] Update src/ui/marker.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/marker.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/marker.js b/src/ui/marker.js
index c0a277b1bb3..c01dc7b4b95 100644
--- a/src/ui/marker.js
+++ b/src/ui/marker.js
@@ -317,7 +317,7 @@ export default class Marker extends Evented {
     /**
      * Binds a `Popup` to the `Marker`.
      * @param popup An instance of the `Popup` class. If undefined or null, any popup
-     * set on this `Marker` instance is unset.
+     * set on this {@link Marker} instance is unset.
      * @returns {Marker} `this`
      * @example
      * var marker = new mapboxgl.Marker()

From b0ad7efabc82995f32f675cdbb5fc1a0e93805ec Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Thu, 23 Apr 2020 14:42:06 -0400
Subject: [PATCH 59/74] Apply suggestions from code review

Co-Authored-By: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/source/geojson_source.js |  6 +++---
 src/ui/camera.js             | 13 ++++++-------
 src/ui/events.js             |  4 ++--
 src/ui/map.js                | 10 +++++-----
 src/ui/marker.js             |  4 ++--
 5 files changed, 18 insertions(+), 19 deletions(-)

diff --git a/src/source/geojson_source.js b/src/source/geojson_source.js
index c168b228c3e..c5a13b0ced9 100644
--- a/src/source/geojson_source.js
+++ b/src/source/geojson_source.js
@@ -238,13 +238,13 @@ class GeoJSONSource extends Evented implements Source {
      *    });
      *
      *    var clusterId = features[0].properties.cluster_id;
-	 *    var pointCount = features[0].properties.point_count;
-	 *    var clusterSource = map.getSource('clusters');
+    *    var pointCount = features[0].properties.point_count;
+    *    var clusterSource = map.getSource('clusters');
      *
      *  clusterSource.getClusterLeaves(clusterId, pointCount, 0, function(error, features) {
      *    // Print cluster leaves in the console
      *    console.log('Cluster leaves:', error, features);
-  	 *	})
+    * })
      * });
      */
     getClusterLeaves(clusterId: number, limit: number, offset: number, callback: Callback<Array<GeoJSONFeature>>) {
diff --git a/src/ui/camera.js b/src/ui/camera.js
index 2b1c444a213..9e56efc6345 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -86,7 +86,7 @@ export type AnimationOptions = {
 };
 
 /**
- * Options for setting padding on calls to methods such as {@link Map#fitBounds}, {@link Map#fitScreenCoordinates}, and {@link Map#setPadding}. Adjust these options to set the amount of padding in pixels added to the edges of the canvas. This can be set for either all edges or individually. All properties of this object must be
+ * Options for setting padding on calls to methods such as {@link Map#fitBounds}, {@link Map#fitScreenCoordinates}, and {@link Map#setPadding}. Adjust these options to set the amount of padding in pixels added to the edges of the canvas. Set a uniform padding on all edges or individual values for each edge. All properties of this object must be
  * non-negative integers.
  *
  * @typedef {Object} PaddingOptions
@@ -151,10 +151,9 @@ class Camera extends Evented {
      * @example
      * // return a LngLat object such as {lng: 0, lat: 0} 
      * var center = map.getCenter();
-     * // return longitude and latitude values directly
-     * var longitude = map.getCenter().lng;
-     * var latitude = map.getCenter().lat;
-     * @see [Use Mapbox GL JS in a React app](https://docs.mapbox.com/help/tutorials/use-mapbox-gl-js-with-react/#store-the-new-coordinates)
+     * // access longitude and latitude values directly
+     * var {longitude, latitude} = map.getCenter();
+     * @see Tutorial: [Use Mapbox GL JS in a React app](https://docs.mapbox.com/help/tutorials/use-mapbox-gl-js-with-react/#store-the-new-coordinates)
      */
     getCenter(): LngLat { return new LngLat(this.transform.center.lng, this.transform.center.lat); }
 
@@ -204,7 +203,7 @@ class Camera extends Evented {
      * @example
      * map.panTo([-74, 38]);
      * @example
-     * // Change the duration of panTo to 5000 milliseconds.
+     * // Specify that the panTo animation should last 5000 milliseconds.
      * map.panTo([-74, 38], {duration: 5000});
      * @see [Update a feature in realtime](https://docs.mapbox.com/mapbox-gl-js/example/live-update-feature/)
      */
@@ -690,7 +689,7 @@ class Camera extends Evented {
      * @fires pitchend
      * @returns {Map} `this`
      * @example
-     * // jump to null island at current zoom
+     * // jump to coordinates at current zoom
      * map.jumpTo({center: [0, 0]});
      * // jump with zoom, pitch, and bearing options
      * map.jumpTo({
diff --git a/src/ui/events.js b/src/ui/events.js
index 22f85942268..cd69091e580 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -270,7 +270,7 @@ export type MapBoxZoomEvent = {
  * @property {Coordinate} [coord] The coordinate of the tile if the event has a `dataType` of `source` and
  * the event is related to loading of a tile.
  * @example
- * // The `sourcedata` event is an example of `MapDataEvent`.
+ * // The sourcedata event is an example of MapDataEvent.
  * // Set up an event listener on the map.
  * map.on('sourcedata', function(e) {
  *    if (e.isSourceLoaded) {
@@ -384,7 +384,7 @@ export type MapEvent =
 
     /**
      * Fired when a pointing device (usually a mouse) is moved while the cursor's hotspot is inside the map.
-     * As you move the cursor across the map, the event will fire everytime the cursor changes position within the map.
+     * As you move the cursor across the map, the event will fire every time the cursor changes position within the map.
      *
      * **Note:** This event is compatible with the optional `layerId` parameter.
      * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
diff --git a/src/ui/map.js b/src/ui/map.js
index a7fc9b0c3be..2aadc2d0509 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1011,7 +1011,7 @@ class Map extends Camera {
      * });
      * @example
      * // Set an event listener that will fire
-     * // when the map is clicked
+     * // when a feature on the countries layer of the map is clicked
      * map.on('click', 'countries', function(e) {
      *   new mapboxgl.Popup()
      *     .setLngLat(e.lngLat)
@@ -1972,7 +1972,7 @@ class Map extends Camera {
      * @see [Filter features within map view](https://www.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/)
      * @see [Highlight features containing similar data](https://www.mapbox.com/mapbox-gl-js/example/query-similar-features/)
      * @see [Create a timeline animation](https://www.mapbox.com/mapbox-gl-js/example/timeline-animation/)
-     * @see [Tutorial: Show changes over time](https://docs.mapbox.com/help/tutorials/show-changes-over-time/)
+     * @see Tutorial: [Show changes over time](https://docs.mapbox.com/help/tutorials/show-changes-over-time/)
      */
     setFilter(layerId: string, filter: ?FilterSpecification,  options: StyleSetterOptions = {}) {
         this.style.setFilter(layerId, filter, options);
@@ -2058,7 +2058,7 @@ class Map extends Camera {
      * @param {boolean} [options.validate=true] Whether to check if the filter conforms to the Mapbox GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function.
      * @returns {Map} `this`
      * @example
-     * map.getLayoutProperty('my-layer', 'visibility');
+     * const layerVisibility = map.getLayoutProperty('my-layer', 'visibility');
      * @see [Show and hide layers](https://docs.mapbox.com/mapbox-gl-js/example/toggle-layers/)
      */
     setLight(light: LightSpecification, options: StyleSetterOptions = {}) {
@@ -2146,7 +2146,7 @@ class Map extends Camera {
      * // When the mouse leaves the `my-layer` layer,
      * // reset the entire state object for the
      * // feature under the mouse
-     * map.on('mouseleave', 'my-layer', (e) => {
+     * map.on('mouseleave', 'my-layer', function(e) {
      *   map.removeFeatureState({
      *     source: 'my-source',
      *     sourceLayer: 'my-source-layer',
@@ -2190,7 +2190,7 @@ class Map extends Camera {
      * @example
      * // When the mouse moves over the `my-layer` layer,
      * // get the feature state for the feature under the mouse
-     * map.on('mousemove', 'my-layer', (e) => {
+     * map.on('mousemove', 'my-layer', function(e) {
      *   if (e.features.length > 0) {
      *     map.getFeatureState({
      *       source: 'my-source',
diff --git a/src/ui/marker.js b/src/ui/marker.js
index c01dc7b4b95..0bb526743f4 100644
--- a/src/ui/marker.js
+++ b/src/ui/marker.js
@@ -315,8 +315,8 @@ export default class Marker extends Evented {
     }
 
     /**
-     * Binds a `Popup` to the `Marker`.
-     * @param popup An instance of the `Popup` class. If undefined or null, any popup
+     * Binds a {@link Popup} to the {@link Marker}.
+     * @param popup An instance of the {@link Popup} class. If undefined or null, any popup
      * set on this {@link Marker} instance is unset.
      * @returns {Marker} `this`
      * @example

From 2d2597fad23b05db3c83ed01f5ee715e35ca0f9b Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Thu, 23 Apr 2020 14:49:36 -0400
Subject: [PATCH 60/74] Update pitch param definition; add Display buildings in
 3D example

---
 src/ui/camera.js | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index 9e56efc6345..f6a398210cb 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -36,8 +36,9 @@ import type {PaddingOptions} from '../geo/edge_insets';
  * @property {number} bearing The desired bearing in degrees. The bearing is the compass direction that
  * is "up". For example, `bearing: 90` orients the map so that east is up.
  * @property {number} pitch The desired pitch in degrees. The pitch is the angle towards the horizon
- * measured in degrees with a range between 0 and 60 degrees. For example, `pitch: 0` results in a two-dimensional map,
- * as if your line of sight forms a perpendicular angle with the earth's surface.
+ * measured in degrees with a range between 0 and 60 degrees. For example, pitch: 0 provides the appearance
+ * of looking straight down at the map, while pitch: 60 tilts the user's perspective towards the horizon.
+ * Increasing the pitch value is often used to display 3D objects.
  * @property {LngLatLike} around If `zoom` is specified, `around` determines the point around which the zoom is centered.
  * @property {PaddingOptions} padding Dimensions in pixels applied on each side of the viewport for shifting the vanishing point.
  * @example
@@ -53,6 +54,7 @@ import type {PaddingOptions} from '../geo/edge_insets';
  * @see [Set pitch and bearing](https://docs.mapbox.com/mapbox-gl-js/example/set-perspective/)
  * @see [Jump to a series of locations](https://docs.mapbox.com/mapbox-gl-js/example/jump-to/)
  * @see [Fly to a location](https://docs.mapbox.com/mapbox-gl-js/example/flyto/)
+ * @see [Display buildings in 3D](https://docs.mapbox.com/mapbox-gl-js/example/3d-buildings/)
  */
 export type CameraOptions = {
     center?: LngLatLike,
@@ -149,7 +151,7 @@ class Camera extends Evented {
      * @memberof Map#
      * @returns The map's geographical centerpoint.
      * @example
-     * // return a LngLat object such as {lng: 0, lat: 0} 
+     * // return a LngLat object such as {lng: 0, lat: 0}
      * var center = map.getCenter();
      * // access longitude and latitude values directly
      * var {longitude, latitude} = map.getCenter();

From b8a3249d338f5de6ba43e220afca1923f8dacbcf Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Thu, 23 Apr 2020 14:51:24 -0400
Subject: [PATCH 61/74] whitespace adjustments

---
 src/source/geojson_source.js | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/src/source/geojson_source.js b/src/source/geojson_source.js
index c5a13b0ced9..67cfab6f8a8 100644
--- a/src/source/geojson_source.js
+++ b/src/source/geojson_source.js
@@ -232,19 +232,19 @@ class GeoJSONSource extends Evented implements Source {
      * @returns {GeoJSONSource} this
      * @example
      * // Retrieve cluster leaves on click
-     *  map.on('click', 'clusters', function(e) {
-     *    var features = map.queryRenderedFeatures(e.point, {
-     *      layers: ['clusters']
-     *    });
+     * map.on('click', 'clusters', function(e) {
+     *   var features = map.queryRenderedFeatures(e.point, {
+     *     layers: ['clusters']
+     *   });
      *
-     *    var clusterId = features[0].properties.cluster_id;
-    *    var pointCount = features[0].properties.point_count;
-    *    var clusterSource = map.getSource('clusters');
+     *   var clusterId = features[0].properties.cluster_id;
+     *   var pointCount = features[0].properties.point_count;
+     *   var clusterSource = map.getSource('clusters');
      *
-     *  clusterSource.getClusterLeaves(clusterId, pointCount, 0, function(error, features) {
-     *    // Print cluster leaves in the console
-     *    console.log('Cluster leaves:', error, features);
-    * })
+     *   clusterSource.getClusterLeaves(clusterId, pointCount, 0, function(error, features) {
+     *     // Print cluster leaves in the console
+     *     console.log('Cluster leaves:', error, features);
+     *   })
      * });
      */
     getClusterLeaves(clusterId: number, limit: number, offset: number, callback: Callback<Array<GeoJSONFeature>>) {

From fc3fd852f29043a275aba88237da836b8da30975 Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Thu, 23 Apr 2020 14:54:42 -0400
Subject: [PATCH 62/74] remove example object, light formatting and copyediting

---
 src/util/ajax.js | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/src/util/ajax.js b/src/util/ajax.js
index 8fc79a6da8b..a5474cd906f 100644
--- a/src/util/ajax.js
+++ b/src/util/ajax.js
@@ -45,22 +45,16 @@ if (typeof Object.freeze == 'function') {
  * @property {string} credentials `'same-origin'|'include'` Use 'include' to send cookies with cross-origin requests.
  * @property {boolean} collectResourceTiming If true, Resource Timing API information will be collected for these transformed requests and returned in a resourceTiming property of relevant data events.
  * @example
- * // transformRequest used to modify requests that begin with `http://myHost`
+ * // use transformRequest to modify requests that begin with `http://myHost`
  * transformRequest: function(url, resourceType) {
- *  if(resourceType === 'Source' && url.startsWith('http://myHost')) {
+ *  if (resourceType === 'Source' && url.startsWith('http://myHost')) {
  *    return {
  *      url: url.replace('http', 'https'),
- *      headers: { 'my-custom-header': true},
+ *      headers: { 'my-custom-header': true },
  *      credentials: 'include'  // Include cookies for cross-origin requests
  *    }
  *   }
  *  }
- * // Example of `RequestParameters` object returned from the above transformRequest function.
- * {
- *  url: 'https://myHost//assets/sample.geojson'
- *  headers: {'my-custom-header': true}
- *  credentials: 'include'
- * }
  *
  */
 export type RequestParameters = {

From 944a324da747d3aaaa5cd8a5c14980beda1eb43b Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Thu, 23 Apr 2020 15:01:18 -0400
Subject: [PATCH 63/74] Apply suggestions from code review

---
 src/ui/map.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 2aadc2d0509..7e5eed48f65 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -2058,7 +2058,7 @@ class Map extends Camera {
      * @param {boolean} [options.validate=true] Whether to check if the filter conforms to the Mapbox GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function.
      * @returns {Map} `this`
      * @example
-     * const layerVisibility = map.getLayoutProperty('my-layer', 'visibility');
+     * var layerVisibility = map.getLayoutProperty('my-layer', 'visibility');
      * @see [Show and hide layers](https://docs.mapbox.com/mapbox-gl-js/example/toggle-layers/)
      */
     setLight(light: LightSpecification, options: StyleSetterOptions = {}) {
@@ -2100,7 +2100,7 @@ class Map extends Camera {
      * @example
      * // When the mouse moves over the `my-layer` layer, update
      * // the feature state for the feature under the mouse
-     * map.on('mousemove', 'my-layer', (e) => {
+     * map.on('mousemove', 'my-layer', function(e) {
      *   if (e.features.length > 0) {
      *     map.setFeatureState({
      *       source: 'my-source',

From 14385ab2c7ad75f0abec50e2b322dcd32d357fac Mon Sep 17 00:00:00 2001
From: Katy DeCorah <decorah@mapbox.com>
Date: Thu, 23 Apr 2020 15:06:08 -0400
Subject: [PATCH 64/74] Apply suggestions from code review

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
---
 src/ui/camera.js                    | 2 +-
 src/ui/control/geolocate_control.js | 2 +-
 src/ui/events.js                    | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index f6a398210cb..6b9920b160f 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -109,7 +109,7 @@ export type AnimationOptions = {
  *   padding: 20
  * });
  * @see [Fit to the bounds of a LineString](https://docs.mapbox.com/mapbox-gl-js/example/zoomto-linestring/)
- * @see [Fit a map to a bounding box](https://www.mapbox.com/mapbox-gl-js/example/fitbounds/)
+ * @see [Fit a map to a bounding box](https://docs.mapbox.com/mapbox-gl-js/example/fitbounds/)
  */
 
 class Camera extends Evented {
diff --git a/src/ui/control/geolocate_control.js b/src/ui/control/geolocate_control.js
index e9010990968..4f8bf61a29f 100644
--- a/src/ui/control/geolocate_control.js
+++ b/src/ui/control/geolocate_control.js
@@ -406,7 +406,7 @@ class GeolocateControl extends Evented {
     }
 
     /**
-    * Trigger a geolocation
+    * Programmatically request and move the map to the user's location. 
     *
     * @returns {boolean} Returns `false` if called before control was added to a map, otherwise returns `true`.
     * @example
diff --git a/src/ui/events.js b/src/ui/events.js
index cd69091e580..d5e0c4ba2a5 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -491,7 +491,7 @@ export type MapEvent =
      * map.on('mouseenter', 'water', function() {
      *   console.log('A mouseenter event occurred on a visible portion of the water layer.');
      * });
-     * @see [Center the map on a clicked symbol](https://www.mapbox.com/mapbox-gl-js/example/center-on-symbol/)
+     * @see [Center the map on a clicked symbol](https://docs.mapbox.com/mapbox-gl-js/example/center-on-symbol/)
      * @see [Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
      */
     | 'mouseenter'
@@ -688,7 +688,7 @@ export type MapEvent =
      *   console.log('A move event occurred.');
      * });
      * @see [Display HTML clusters with custom properties](https://docs.mapbox.com/mapbox-gl-js/example/cluster-html/)
-     * @see [Filter features within map view](https://www.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/)
+     * @see [Filter features within map view](https://docs.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/)
      */
     | 'move'
 

From 9d4aee9be20088b5bd5cbc3d256545bff73da251 Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Thu, 23 Apr 2020 15:45:52 -0700
Subject: [PATCH 65/74] Update src/ui/camera.js

---
 src/ui/camera.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index 6b9920b160f..8c57e03c16c 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -239,7 +239,7 @@ class Camera extends Evented {
      * @fires zoomend
      * @returns {Map} `this`
      * @example
-     * // zoom the map to 5 without an animated transition
+     * // Zoom to the zoom level 5 without an animated transition
      * map.setZoom(5);
      */
     setZoom(zoom: number, eventData?: Object) {

From f6285e8ae6e05df8bde4559837b6225d39a6af8c Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Thu, 23 Apr 2020 15:46:35 -0700
Subject: [PATCH 66/74] Update src/ui/camera.js

---
 src/ui/camera.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index 8c57e03c16c..31e9fc0383f 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -264,7 +264,7 @@ class Camera extends Evented {
      * @example
      * // zoom the map to 5 with an animated transition
      * map.zoomTo(5);
-     * // zoom the map to 8 with custom animation options
+     * // Zoom to the zoom level 8 with an animated transition
      * map.zoomTo(8, {
      *   duration: 2000,
      *   offset: [100, 50]

From fe8ce62e1deb3a82a9705703cfd3e1bb94d59d74 Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Thu, 23 Apr 2020 15:46:46 -0700
Subject: [PATCH 67/74] Update src/ui/camera.js

---
 src/ui/camera.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/camera.js b/src/ui/camera.js
index 31e9fc0383f..40bfad0dc9e 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -262,7 +262,7 @@ class Camera extends Evented {
      * @fires zoomend
      * @returns {Map} `this`
      * @example
-     * // zoom the map to 5 with an animated transition
+     * // Zoom to the zoom level 5 without an animated transition
      * map.zoomTo(5);
      * // Zoom to the zoom level 8 with an animated transition
      * map.zoomTo(8, {

From ff6bfef7c3e4cb34a557fdec50a1abb16b4af89a Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Thu, 23 Apr 2020 15:49:49 -0700
Subject: [PATCH 68/74] Update src/ui/events.js

---
 src/ui/events.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index d5e0c4ba2a5..e29b9404c29 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -383,7 +383,7 @@ export type MapEvent =
     | 'mouseover'
 
     /**
-     * Fired when a pointing device (usually a mouse) is moved while the cursor's hotspot is inside the map.
+     * Fired when a pointing device (usually a mouse) is moved while the cursor is inside the map.
      * As you move the cursor across the map, the event will fire every time the cursor changes position within the map.
      *
      * **Note:** This event is compatible with the optional `layerId` parameter.

From b417ce0c726ca25c78dc5a85966ec082a2d9c377 Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Thu, 23 Apr 2020 15:50:29 -0700
Subject: [PATCH 69/74] Update src/ui/events.js

---
 src/ui/events.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index e29b9404c29..9b25316a05f 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -388,7 +388,7 @@ export type MapEvent =
      *
      * **Note:** This event is compatible with the optional `layerId` parameter.
      * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
-     * the cursor's hotspot is inside a visible portion of the specifed layer.
+     * the cursor is inside a visible portion of the specified layer.
      *
      * @event mousemove
      * @memberof Map

From c5923cd74ac1e08b01bbf134985f4dd6600982ce Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Thu, 23 Apr 2020 16:05:10 -0700
Subject: [PATCH 70/74] Update src/util/ajax.js

---
 src/util/ajax.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/util/ajax.js b/src/util/ajax.js
index a5474cd906f..7c2d4445251 100644
--- a/src/util/ajax.js
+++ b/src/util/ajax.js
@@ -47,7 +47,7 @@ if (typeof Object.freeze == 'function') {
  * @example
  * // use transformRequest to modify requests that begin with `http://myHost`
  * transformRequest: function(url, resourceType) {
- *  if (resourceType === 'Source' && url.startsWith('http://myHost')) {
+ *  if (resourceType === 'Source' && url.indexOf('http://myHost') > -1) {
  *    return {
  *      url: url.replace('http', 'https'),
  *      headers: { 'my-custom-header': true },

From 6c6722511dee2168f514c55cebcae58930d37402 Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Thu, 23 Apr 2020 16:20:07 -0700
Subject: [PATCH 71/74] Update src/ui/control/geolocate_control.js

---
 src/ui/control/geolocate_control.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/control/geolocate_control.js b/src/ui/control/geolocate_control.js
index 4f8bf61a29f..87a39f3848f 100644
--- a/src/ui/control/geolocate_control.js
+++ b/src/ui/control/geolocate_control.js
@@ -406,7 +406,7 @@ class GeolocateControl extends Evented {
     }
 
     /**
-    * Programmatically request and move the map to the user's location. 
+    * Programmatically request and move the map to the user's location.
     *
     * @returns {boolean} Returns `false` if called before control was added to a map, otherwise returns `true`.
     * @example

From b90fcd2863e878b380a34878d269aae09c16896a Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Fri, 24 Apr 2020 12:04:32 -0700
Subject: [PATCH 72/74] Update src/ui/map.js

---
 src/ui/map.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 7e5eed48f65..567e18524c8 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1948,7 +1948,7 @@ class Map extends Camera {
      * Any feature for which the filter expression evaluates to true will be
      * rendered on the map. Those that are false will be hidden.
      *
-     * Use setFilter to show a subset of your source data.
+     * Use `setFilter` to show a subset of your source data.
      *
      * To clear the filter, pass `null` or `undefined` as the second parameter.
      *

From ab887c42dc66ecf94f14cb7d42dcce4b9b81b212 Mon Sep 17 00:00:00 2001
From: Dan Swick <dan.swick@gmail.com>
Date: Fri, 24 Apr 2020 12:04:43 -0700
Subject: [PATCH 73/74] Update src/ui/map.js

---
 src/ui/map.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 567e18524c8..613bd549f47 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1945,7 +1945,7 @@ class Map extends Camera {
      * Sets the filter for the specified style layer.
      *
      * Filters control which features a style layer renders from its source.
-     * Any feature for which the filter expression evaluates to true will be
+     * Any feature for which the filter expression evaluates to `true` will be
      * rendered on the map. Those that are false will be hidden.
      *
      * Use `setFilter` to show a subset of your source data.

From b01e9620158b1c9c629a8e92dc49e3be3ed1ca9a Mon Sep 17 00:00:00 2001
From: Karim Naaji <karim.naaji@gmail.com>
Date: Fri, 24 Apr 2020 14:11:50 -0700
Subject: [PATCH 74/74] Fix typo in src/ui/events.js

---
 src/ui/events.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ui/events.js b/src/ui/events.js
index 9b25316a05f..66abb6d81fd 100644
--- a/src/ui/events.js
+++ b/src/ui/events.js
@@ -238,7 +238,7 @@ export class MapWheelEvent extends Event {
  * A `MapBoxZoomEvent` is the event type for the boxzoom-related map events emitted by the {@link BoxZoomHandler}.
  *
  * @typedef {Object} MapBoxZoomEvent
- * @property {MouseEvent?} originalEvent The DOM event that triggered the boxzoom event. Can be a `MouseEvent` or `KeyboardEvent`
+ * @property {MouseEvent} originalEvent The DOM event that triggered the boxzoom event. Can be a `MouseEvent` or `KeyboardEvent`
  * @property {string} type The type of boxzoom event. One of `boxzoomstart`, `boxzoomend` or `boxzoomcancel`
  * @property {Map} target The `Map` instance that triggerred the event
  */