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