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/)
diff --git a/src/geo/lng_lat_bounds.js b/src/geo/lng_lat_bounds.js
index 7fbf4db9c4a..f2360e96db6 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);
+    *
+    * console.log(llb.contains(ll)); // = true
     */
     contains(lnglat: LngLatLike) {
         const {lng, lat} = LngLat.convert(lnglat);
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);
diff --git a/src/source/geojson_source.js b/src/source/geojson_source.js
index 2b043f1ef91..67cfab6f8a8 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, 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>>) {
         this.actor.send('geojson.getClusterLeaves', {
diff --git a/src/ui/camera.js b/src/ui/camera.js
index b5d09d89bc7..40bfad0dc9e 100644
--- a/src/ui/camera.js
+++ b/src/ui/camera.js
@@ -33,11 +33,28 @@ 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 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 eachs side of the viewport for shifting the vanishing point.
+ * @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/)
+ * @see [Display buildings in 3D](https://docs.mapbox.com/mapbox-gl-js/example/3d-buildings/)
  */
 export type CameraOptions = {
     center?: LngLatLike,
@@ -71,7 +88,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. 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
@@ -79,6 +96,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://docs.mapbox.com/mapbox-gl-js/example/fitbounds/)
  */
 
 class Camera extends Evented {
@@ -119,6 +150,12 @@ class Camera extends Evented {
      *
      * @memberof Map#
      * @returns The map's geographical centerpoint.
+     * @example
+     * // 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();
+     * @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); }
 
@@ -156,15 +193,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
+     * // 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/)
      */
     panTo(lnglat: LngLatLike, options?: AnimationOptions, eventData?: Object) {
         return this.easeTo(extend({
@@ -177,6 +220,8 @@ class Camera extends Evented {
      *
      * @memberof Map#
      * @returns The map's current zoom level.
+     * @example
+     * map.getZoom();
      */
     getZoom(): number { return this.transform.zoom; }
 
@@ -194,7 +239,7 @@ class Camera extends Evented {
      * @fires zoomend
      * @returns {Map} `this`
      * @example
-     * // zoom the map to 5
+     * // Zoom to the zoom level 5 without an animated transition
      * map.setZoom(5);
      */
     setZoom(zoom: number, eventData?: Object) {
@@ -216,6 +261,14 @@ class Camera extends Evented {
      * @fires moveend
      * @fires zoomend
      * @returns {Map} `this`
+     * @example
+     * // 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, {
+     *   duration: 2000,
+     *   offset: [100, 50]
+     * });
      */
     zoomTo(zoom: number, options: ? AnimationOptions, eventData?: Object) {
         return this.easeTo(extend({
@@ -236,6 +289,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);
@@ -255,6 +311,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);
@@ -631,6 +690,18 @@ class Camera extends Evented {
      * @fires zoomend
      * @fires pitchend
      * @returns {Map} `this`
+     * @example
+     * // jump to coordinates at current zoom
+     * map.jumpTo({center: [0, 0]});
+     * // jump with zoom, pitch, and bearing options
+     * 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();
diff --git a/src/ui/control/geolocate_control.js b/src/ui/control/geolocate_control.js
index 0e5f5e80736..87a39f3848f 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`.
-     */
+    * 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
+    * // 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');
@@ -552,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.')
+ * });
  *
  */
 
@@ -562,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.')
+ * });
  *
  */
 
@@ -572,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.')
+ * });
  *
  */
 
@@ -581,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.')
+ * });
  *
  */
 
@@ -590,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.')
+ * });
  *
  */
diff --git a/src/ui/events.js b/src/ui/events.js
index cf261c396fb..66abb6d81fd 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'
@@ -218,17 +235,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 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
  */
 export type MapBoxZoomEvent = {
     type: 'boxzoomstart'
         | 'boxzoomend'
         | 'boxzoomcancel',
-    map: Map,
+    target: Map,
     originalEvent: MouseEvent
 };
 
@@ -251,6 +269,14 @@ 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 the source has finished loading
+ *    }
+ * });
  */
 export type MapDataEvent = {
     type: string,
@@ -266,34 +292,90 @@ export type MapEvent =
     /**
      * Fired when a pointing device (usually a mouse) is pressed 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
+     * the cursor is pressed while inside a visible portion of the specifed layer.
+     *
      * @event mousedown
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
-     * @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
+     * map.on('mousedown', function() {
+     *   console.log('A mousedown event has occurred.');
+     * });
+     * @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 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.
+     *
      * @event mouseup
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
-     * @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
+     * map.on('mouseup', function() {
+     *   console.log('A mouseup event has occurred.');
+     * });
+     * @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 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
+     * the cursor is moved inside a visible portion of the specifed layer.
      *
      * @event mouseover
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // 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/)
@@ -301,12 +383,31 @@ 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 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.
+     * If `layerId` is included as the second argument in {@link Map#on}, the event listener will fire only when the
+     * the cursor is inside a visible portion of the specified layer.
      *
      * @event mousemove
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // 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/)
@@ -316,47 +417,107 @@ 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 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.
+     *
      * @event click
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // 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 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.
      *
      * @event dblclick
      * @memberof Map
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // 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
      * @instance
      * @property {MapMouseEvent} data
+     * @example
+     * // Initialize the map
+     * var map = new mapboxgl.Map({ // map options });
+     * // Set an event listener
+     * 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://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'
 
     /**
      * 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
      * @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 +528,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 +547,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 +566,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 +584,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 +602,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 +621,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 +640,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 +659,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 +679,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://docs.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/)
      */
     | 'move'
 
@@ -460,8 +700,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 +721,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 +739,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 +757,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 +777,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 +796,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 +815,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 +833,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 +851,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 +869,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 +888,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 +927,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 +945,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 +964,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 +983,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 +1000,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 +1017,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 +1034,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 +1053,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 +1078,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 +1100,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 +1117,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 +1138,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 +1157,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 +1177,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 +1196,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 +1216,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 +1237,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 +1258,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 +1279,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/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;
     }
diff --git a/src/ui/map.js b/src/ui/map.js
index c1e5eee4dad..613bd549f47 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 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.
      * @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 a feature on the countries layer of 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) {
@@ -1326,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();
@@ -1393,7 +1463,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.
@@ -1460,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);
@@ -1680,15 +1759,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: {
@@ -1705,9 +1820,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();
@@ -1719,13 +1869,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);
@@ -1795,19 +1944,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
-     * map.setFilter('my-layer', ['==', 'name', 'USA']);
+     * // 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
+     * // 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);
@@ -1867,6 +2032,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);
@@ -1891,6 +2057,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
+     * 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 = {}) {
         this._lazyInitEmptyStyle();
@@ -1909,23 +2078,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', function(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);
@@ -1934,19 +2122,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', function(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', function(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);
@@ -1954,18 +2173,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', function(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);
@@ -2344,6 +2578,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) {
@@ -2377,6 +2615,8 @@ class Map extends Camera {
      * @type {boolean}
      * @instance
      * @memberof Map
+     * @example
+     * map.showTileBoundaries = true;
      */
     get showTileBoundaries(): boolean { return !!this._showTileBoundaries; }
     set showTileBoundaries(value: boolean) {
@@ -2582,10 +2822,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
  */
diff --git a/src/ui/marker.js b/src/ui/marker.js
index 55484adb013..0bb526743f4 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();
@@ -270,16 +274,30 @@ 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;
     }
 
     /**
-     * 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;
@@ -297,10 +315,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 {@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
+     * 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) {
@@ -364,16 +388,30 @@ 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()
+     *  .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 {@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()
+     *  .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;
diff --git a/src/ui/popup.js b/src/ui/popup.js
index 8acb87e2192..2732eb82857 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();
@@ -139,6 +148,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 +208,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'));
 
@@ -235,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() {
@@ -259,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() {
@@ -293,6 +335,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();
diff --git a/src/util/ajax.js b/src/util/ajax.js
index be730d0ed93..7c2d4445251 100644
--- a/src/util/ajax.js
+++ b/src/util/ajax.js
@@ -39,7 +39,23 @@ 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
+ * // use transformRequest to modify requests that begin with `http://myHost`
+ * transformRequest: function(url, resourceType) {
+ *  if (resourceType === 'Source' && url.indexOf('http://myHost') > -1) {
+ *    return {
+ *      url: url.replace('http', 'https'),
+ *      headers: { 'my-custom-header': true },
+ *      credentials: 'include'  // Include cookies for cross-origin requests
+ *    }
+ *   }
+ *  }
+ *
  */
 export type RequestParameters = {
     url: string,
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 {