From 92f6fe27491486d2c7b114c0b1bc7368ecc96620 Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Mon, 9 Sep 2019 16:11:41 -0700
Subject: [PATCH 01/15] make it clear that ui handlers examples are below

---
 src/ui/map.js | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 5b9286cda4d..e00b4d151db 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -276,39 +276,45 @@ class Map extends Camera {
     _requestManager: RequestManager;
 
     /**
-     * The map's {@link ScrollZoomHandler}, which implements zooming in and out with a scroll wheel or trackpad.
+     * The map's `ScrollZoomHandler`, which implements zooming in and out with a scroll wheel or trackpad.
+     * Find more details and examples using `scrollZoom` in the {@link ScrollZoomHandler} section.
      */
     scrollZoom: ScrollZoomHandler;
 
     /**
-     * The map's {@link BoxZoomHandler}, which implements zooming using a drag gesture with the Shift key pressed.
+     * The map's `BoxZoomHandler`, which implements zooming using a drag gesture with the Shift key pressed.
+     * Find more details and examples using `boxZoom` in the {@link BoxZoomHandler} section.
      */
     boxZoom: BoxZoomHandler;
 
     /**
-     * The map's {@link DragRotateHandler}, which implements rotating the map while dragging with the right
-     * mouse button or with the Control key pressed.
+     * The map's `DragRotateHandler, which implements rotating the map while dragging with the right
+     * mouse button or with the Control key pressed. Find more details and examples using `dragRotate` 
+     * in the {@link DragRotateHandler} section.
      */
     dragRotate: DragRotateHandler;
 
     /**
-     * The map's {@link DragPanHandler}, which implements dragging the map with a mouse or touch gesture.
+     * The map's `DragPanHandler`, which implements dragging the map with a mouse or touch gesture.
+     * Find more details and examples using `dragPan` in the {@link DragPanHandler} section.
      */
     dragPan: DragPanHandler;
 
     /**
-     * The map's {@link KeyboardHandler}, which allows the user to zoom, rotate, and pan the map using keyboard
-     * shortcuts.
+     * The map's `KeyboardHandler`, which allows the user to zoom, rotate, and pan the map using keyboard
+     * shortcuts. Find more details and examples using `keyboard` in the {@link KeyboardHandler} section.
      */
     keyboard: KeyboardHandler;
 
     /**
-     * The map's {@link DoubleClickZoomHandler}, which allows the user to zoom by double clicking.
+     * The map's `DoubleClickZoomHandler`, which allows the user to zoom by double clicking.
+     * Find more details and examples using `doubleClickZoom` in the {@link DoubleClickZoomHandler} section.
      */
     doubleClickZoom: DoubleClickZoomHandler;
 
     /**
-     * The map's {@link TouchZoomRotateHandler}, which allows the user to zoom or rotate the map with touch gestures.
+     * The map's `TouchZoomRotateHandler`, which allows the user to zoom or rotate the map with touch gestures.
+     * Find more details and examples using `touchZoomRotate` in the {@link TouchZoomRotateHandler} section.
      */
     touchZoomRotate: TouchZoomRotateHandler;
 

From 4e36e0906ccb839832d1c1e5393ec601edc90db3 Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Mon, 9 Sep 2019 16:30:38 -0700
Subject: [PATCH 02/15] add examples related to controls

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

diff --git a/src/ui/map.js b/src/ui/map.js
index e00b4d151db..007e885e305 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -442,6 +442,9 @@ class Map extends Camera {
      * @param {string} [position] position on the map to which the control will be added.
      * Valid values are `'top-left'`, `'top-right'`, `'bottom-left'`, and `'bottom-right'`. Defaults to `'top-right'`.
      * @returns {Map} `this`
+     * @example
+     * // Add zoom and rotation controls to the map.
+     * map.addControl(new mapboxgl.NavigationControl());
      * @see [Display map navigation controls](https://www.mapbox.com/mapbox-gl-js/example/navigation/)
      */
     addControl(control: IControl, position?: ControlPosition) {
@@ -472,6 +475,13 @@ class Map extends Camera {
      *
      * @param {IControl} control The {@link IControl} to remove.
      * @returns {Map} `this`
+     * @example
+     * // Define a new navigation control.
+     * var navigation = new mapboxgl.NavigationControl();
+     * // Add zoom and rotation controls to the map.
+     * map.addControl(navigation);
+     * // Remove zoom and rotation controls from the map.
+     * map.removeControl(navigation);
      */
     removeControl(control: IControl) {
         if (!control || !control.onRemove) {

From 5ac06c579259ac9c31073705ad0a44c57a015801 Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Mon, 9 Sep 2019 17:36:50 -0700
Subject: [PATCH 03/15] add examples related to bounds

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

diff --git a/src/ui/map.js b/src/ui/map.js
index 007e885e305..0d5bd7f6f62 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -523,6 +523,8 @@ class Map extends Camera {
     /**
      * Returns the map's geographical bounds. When the bearing or pitch is non-zero, the visible region is not
      * an axis-aligned rectangle, and the result is the smallest bounds that encompasses the visible region.
+     * @example
+     * map.getBounds();
      */
     getBounds(): LngLatBounds {
         return this.transform.getBounds();
@@ -530,6 +532,8 @@ class Map extends Camera {
 
     /**
      * Returns the maximum geographical bounds the map is constrained to, or `null` if none set.
+     * @example
+     * map.getMaxBounds();
      */
     getMaxBounds(): LngLatBounds | null {
         return this.transform.getMaxBounds();
@@ -547,6 +551,14 @@ class Map extends Camera {
      *
      * @param {LngLatBoundsLike | null | undefined} bounds The maximum bounds to set. If `null` or `undefined` is provided, the function removes the map's maximum bounds.
      * @returns {Map} `this`
+     * @example
+     * // Define bounds that conform to the `LngLatBoundsLike` object.
+     * var bounds = [
+     *   [-74.04728, 40.68392], // Southwest coordinates
+     *   [-73.91058, 40.87764]  // Northeast coordinates
+     * ];
+     * // Set the map's max bounds.
+     * map.setMaxBounds(bounds);
      */
     setMaxBounds(bounds: LngLatBoundsLike) {
         this.transform.setMaxBounds(LngLatBounds.convert(bounds));

From 9878a47d62253360f24f6975f1b918d9a1b6694c Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Mon, 9 Sep 2019 17:45:53 -0700
Subject: [PATCH 04/15] add examples related to min and max zoom levels

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

diff --git a/src/ui/map.js b/src/ui/map.js
index 0d5bd7f6f62..98d3fcc394a 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -573,6 +573,8 @@ class Map extends Camera {
      * @param {number | null | undefined} minZoom The minimum zoom level to set (0-24).
      *   If `null` or `undefined` is provided, the function removes the current minimum zoom (i.e. sets it to 0).
      * @returns {Map} `this`
+     * @example
+     * map.setMinZoom(12.25);
      */
     setMinZoom(minZoom?: ?number) {
 
@@ -593,6 +595,8 @@ class Map extends Camera {
      * Returns the map's minimum allowable zoom level.
      *
      * @returns {number} minZoom
+     * @example
+     * map.getMinZoom();
      */
     getMinZoom() { return this.transform.minZoom; }
 
@@ -604,6 +608,8 @@ class Map extends Camera {
      * @param {number | null | undefined} maxZoom The maximum zoom level to set.
      *   If `null` or `undefined` is provided, the function removes the current maximum zoom (sets it to 22).
      * @returns {Map} `this`
+     * @example
+     * map.setMaxZoom(18.75);
      */
     setMaxZoom(maxZoom?: ?number) {
 
@@ -620,6 +626,16 @@ class Map extends Camera {
         } else throw new Error(`maxZoom must be greater than the current minZoom`);
     }
 
+    /**
+     * Returns the map's maximum allowable zoom level.
+     *
+     * @returns {number} maxZoom
+     * @example
+     * map.getMaxZoom();
+     */
+    getMaxZoom() { return this.transform.maxZoom; }
+
+
     /**
      * Returns the state of renderWorldCopies.
      *
@@ -638,13 +654,6 @@ class Map extends Camera {
         return this._update();
     }
 
-    /**
-     * Returns the map's maximum allowable zoom level.
-     *
-     * @returns {number} maxZoom
-     */
-    getMaxZoom() { return this.transform.maxZoom; }
-
     /**
      * Returns a {@link Point} representing pixel coordinates, relative to the map's `container`,
      * that correspond to the specified geographical location.

From 53807954a6aba7ac957267eb382a980f76a454a8 Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Mon, 9 Sep 2019 18:10:07 -0700
Subject: [PATCH 05/15] clarify what renderWorldCopies means, adds related
 examples

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

diff --git a/src/ui/map.js b/src/ui/map.js
index 98d3fcc394a..7ba902669f6 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -203,7 +203,7 @@ const defaultOptions = {
  * @param {number} [options.pitch=0] The initial pitch (tilt) of the map, measured in degrees away from the plane of the screen (0-60). If `pitch` is not specified in the constructor options, Mapbox GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0`.
  * @param {LngLatBoundsLike} [options.bounds] The initial bounds of the map. If `bounds` is specified, it overrides `center` and `zoom` constructor options.
  * @param {Object} [options.fitBoundsOptions] A [`fitBounds`](#map#fitbounds) options object to use _only_ when fitting the initial `bounds` provided above.
- * @param {boolean} [options.renderWorldCopies=true]  If `true`, multiple copies of the world will be rendered, when zoomed out.
+ * @param {boolean} [options.renderWorldCopies=true]  If `true`, multiple copies of the world will be rendered side by side when the map is zoomed out far enough that a single representation of the world does not fill the map's entire container.
  * @param {number} [options.maxTileCacheSize=null]  The maximum number of tiles stored in the tile cache for a given source. If omitted, the cache will be dynamically sized based on the current viewport.
  * @param {string} [options.localIdeographFontFamily='sans-serif'] Defines a CSS
  *   font-family for locally overriding generation of glyphs in the 'CJK Unified Ideographs', 'Hiragana', 'Katakana' and 'Hangul Syllables' ranges.
@@ -637,17 +637,24 @@ class Map extends Camera {
 
 
     /**
-     * Returns the state of renderWorldCopies.
+     * Returns the state of `renderWorldCopies`. If `true`, multiple copies of the world will be rendered side by side
+     * when the map is zoomed out far enough that a single representation of the world does not fill the map's entire container.
      *
      * @returns {boolean} renderWorldCopies
+     * @example
+     * map.getRenderWorldCopies();
      */
     getRenderWorldCopies() { return this.transform.renderWorldCopies; }
 
     /**
-     * Sets the state of renderWorldCopies.
+     * Sets the state of `renderWorldCopies`.
      *
-     * @param {boolean} renderWorldCopies If `true`, multiple copies of the world will be rendered, when zoomed out. `undefined` is treated as `true`, `null` is treated as `false`.
+     * @param {boolean} renderWorldCopies If `true`, multiple copies of the world will be rendered side by side when
+     * the map is zoomed out far enough that a single representation of the world does not fill the map's entire container.
+     * `undefined` is treated as `true`, `null` is treated as `false`.
      * @returns {Map} `this`
+     * @example
+     * map.setRenderWorldCopies(true);
      */
     setRenderWorldCopies(renderWorldCopies?: ?boolean) {
         this.transform.renderWorldCopies = renderWorldCopies;

From 872dd2055fe76c72936970825eabbbd14ea15d3b Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Mon, 9 Sep 2019 18:23:33 -0700
Subject: [PATCH 06/15] add examples related to project and unproject, remove
 old related link

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

diff --git a/src/ui/map.js b/src/ui/map.js
index 7ba902669f6..17bff7c2d97 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -667,6 +667,9 @@ class Map extends Camera {
      *
      * @param {LngLatLike} lnglat The geographical location to project.
      * @returns {Point} The {@link Point} corresponding to `lnglat`, relative to the map's `container`.
+     * @example
+     * var coordinate = [-122.420679, 37.772537];
+     * var point = map.project(coordinate);
      */
     project(lnglat: LngLatLike) {
         return this.transform.locationPoint(LngLat.convert(lnglat));
@@ -678,7 +681,11 @@ class Map extends Camera {
      *
      * @param {PointLike} point The pixel coordinates to unproject.
      * @returns {LngLat} The {@link LngLat} corresponding to `point`.
-     * @see [Show polygon information on click](https://www.mapbox.com/mapbox-gl-js/example/polygon-popup-on-click/)
+     * @example
+     * map.on('click', function(e) {
+     *   // When the map is clicked, get the geographic coordinate.
+     *   var coordinate = map.unproject(e.point);
+     * });
      */
     unproject(point: PointLike) {
         return this.transform.pointLocation(Point.convert(point));

From db30dac9c8ad9d1b5e142a23fb8ba767bc11e142 Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Mon, 9 Sep 2019 19:56:22 -0700
Subject: [PATCH 07/15] examples for isMoving, isZooming, isRotating

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

diff --git a/src/ui/map.js b/src/ui/map.js
index 17bff7c2d97..386258236be 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -693,6 +693,8 @@ class Map extends Camera {
 
     /**
      * Returns true if the map is panning, zooming, rotating, or pitching due to a camera animation or user gesture.
+     * @example
+     * map.isMoving();
      */
     isMoving(): boolean {
         return this._moving ||
@@ -703,6 +705,8 @@ class Map extends Camera {
 
     /**
      * Returns true if the map is zooming due to a camera animation or user gesture.
+     * @example
+     * map.isZooming();
      */
     isZooming(): boolean {
         return this._zooming ||
@@ -711,6 +715,8 @@ class Map extends Camera {
 
     /**
      * Returns true if the map is rotating due to a camera animation or user gesture.
+     * @example
+     * map.isRotating();
      */
     isRotating(): boolean {
         return this._rotating ||

From 9ae1ea72c1434c7b00d6ba1f4773074123dfece0 Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Mon, 9 Sep 2019 20:35:54 -0700
Subject: [PATCH 08/15] clean up query*Features

---
 src/ui/map.js | 29 +++++++++++++++++++----------
 1 file changed, 19 insertions(+), 10 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 386258236be..3688734826e 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -869,7 +869,7 @@ class Map extends Camera {
      * or with only a `options` argument) is equivalent to passing a bounding box encompassing the entire
      * map viewport.
      * @param {Object} [options]
-     * @param {Array<string>} [options.layers] An array of style layer IDs for the query to inspect.
+     * @param {Array<string>} [options.layers] An array of [style layer IDs](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layer-id) for the query to inspect.
      *   Only features within these layers will be returned. If this parameter is undefined, all layers will be checked.
      * @param {Array} [options.filter] A [filter](https://www.mapbox.com/mapbox-gl-js/style-spec/#other-filter)
      *   to limit query results.
@@ -885,9 +885,13 @@ class Map extends Camera {
      * representing the style layer to  which the feature belongs. Layout and paint properties in this object contain values
      * which are fully evaluated for the given zoom level and feature.
      *
-     * Features from layers whose `visibility` property is `"none"`, or from layers whose zoom range excludes the
-     * current zoom level are not included. Symbol features that have been hidden due to text or icon collision are
-     * not included. Features from all other layers are included, including features that may have no visible
+     * Only features that are currently rendered are included. Some features will not be included, like:
+     *
+     * - Features from layers whose `visibility` property is `"none"`
+     * - Features from layers whose zoom range excludes the current zoom level are not included.
+     * - Symbol features that have been hidden due to text or icon collision are not included.
+     *
+     * Features from all other layers are included, including features that may have no visible
      * contribution to the rendered result; for example, because the layer's opacity or color alpha component is set to
      * 0.
      *
@@ -931,7 +935,7 @@ class Map extends Camera {
      * var features = map.queryRenderedFeatures({ layers: ['my-layer-name'] });
      * @see [Get features under the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/queryrenderedfeatures/)
      * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)
-     * @see [Center the map on a clicked symbol](https://www.mapbox.com/mapbox-gl-js/example/center-on-symbol/)
+     * @see [Filter features within map view](https://www.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/)
      */
     queryRenderedFeatures(geometry?: PointLike | [PointLike, PointLike], options?: Object) {
         // The first parameter can be omitted entirely, making this effectively an overloaded method
@@ -974,8 +978,8 @@ class Map extends Camera {
      *
      * @param {string} sourceId The ID of the vector tile or GeoJSON source to query.
      * @param {Object} [parameters]
-     * @param {string} [parameters.sourceLayer] The name of the vector tile layer to query. *For vector tile
-     *   sources, this parameter is required.* For GeoJSON sources, it is ignored.
+     * @param {string} [parameters.sourceLayer] The name of the [source layer](https://docs.mapbox.com/help/glossary/source-layer/)
+     *   to query. *For vector tile sources, this parameter is required.* For GeoJSON sources, it is ignored.
      * @param {Array} [parameters.filter] A [filter](https://www.mapbox.com/mapbox-gl-js/style-spec/#other-filter)
      *   to limit query results.
      * @param {boolean} [parameters.validate=true] Whether to check if the [parameters.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.
@@ -983,8 +987,7 @@ class Map extends Camera {
      * @returns {Array<Object>} An array of [GeoJSON](http://geojson.org/)
      * [Feature objects](https://tools.ietf.org/html/rfc7946#section-3.2).
      *
-     * In contrast to {@link Map#queryRenderedFeatures}, this function
-     * returns all features matching the query parameters,
+     * In contrast to {@link Map#queryRenderedFeatures}, this function returns all features matching the query parameters,
      * whether or not they are rendered by the current style (i.e. visible). The domain of the query includes all currently-loaded
      * vector tiles and GeoJSON source tiles: this function does not check tiles outside the currently
      * visible viewport.
@@ -996,7 +999,13 @@ class Map extends Camera {
      * rectangle, even if the highway extends into other tiles, and the portion of the highway within each map tile
      * will be returned as a separate feature. Similarly, a point feature near a tile boundary may appear in multiple
      * tiles due to tile buffering.
-     * @see [Filter features within map view](https://www.mapbox.com/mapbox-gl-js/example/filter-features-within-map-view/)
+     *
+     * @example
+     * // Find all features in one source layer in a vector source
+     * var features = map.querySourceFeatures('your-source-id', {
+     *   sourceLayer: 'your-source-layer'
+     * });
+     *
      * @see [Highlight features containing similar data](https://www.mapbox.com/mapbox-gl-js/example/query-similar-features/)
      */
     querySourceFeatures(sourceId: string, parameters: ?{sourceLayer: ?string, filter: ?Array<any>, validate?: boolean}) {

From 2f0ea1e627519ffeae18ccd6114ba655e16c42e7 Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Tue, 10 Sep 2019 11:06:10 -0700
Subject: [PATCH 09/15] add more deailts to resize, add example

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

diff --git a/src/ui/map.js b/src/ui/map.js
index 3688734826e..a6dbf1a7e74 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -498,11 +498,19 @@ class Map extends Camera {
      * Resizes the map according to the dimensions of its
      * `container` element.
      *
-     * This method must be called after the map's `container` is resized by another script,
+     * Checks if the map container size changed and updates the map if it has changed.
+     * This method must be called after the map's `container` is resized by another script
      * or when the map is shown after being initially hidden with CSS.
      *
-     * @param eventData Additional properties to be added to event objects of events triggered by this method.
+     * @param eventData Additional properties to be passed to `movestart`, `move`, `resize`, and `moveend`
+     *   events that get triggered as a result of resize. This can be useful for differentiating the
+     *   source of an event (for example, user-initiated or programmatically-triggered events).
      * @returns {Map} `this`
+     * @example
+     * // Resize the map when the map container is shown
+     * // after being initially hidden with CSS.
+     * var mapDiv = document.getElementById('map');
+     * if (mapDiv.visibility === true) map.resize();
      */
     resize(eventData?: Object) {
         const dimensions = this._containerDimensions();

From 0a85632e946f5f7a0b2e576c8434c828d1be433d Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Tue, 10 Sep 2019 11:13:08 -0700
Subject: [PATCH 10/15] clean up copy

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

diff --git a/src/ui/map.js b/src/ui/map.js
index a6dbf1a7e74..7d074a00448 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -288,7 +288,7 @@ class Map extends Camera {
     boxZoom: BoxZoomHandler;
 
     /**
-     * The map's `DragRotateHandler, which implements rotating the map while dragging with the right
+     * The map's `DragRotateHandler`, which implements rotating the map while dragging with the right
      * mouse button or with the Control key pressed. Find more details and examples using `dragRotate` 
      * in the {@link DragRotateHandler} section.
      */
@@ -510,7 +510,7 @@ class Map extends Camera {
      * // Resize the map when the map container is shown
      * // after being initially hidden with CSS.
      * var mapDiv = document.getElementById('map');
-     * if (mapDiv.visibility === true) map.resize();
+     * if (mapDiv.style.visibility === true) map.resize();
      */
     resize(eventData?: Object) {
         const dimensions = this._containerDimensions();
@@ -893,11 +893,11 @@ class Map extends Camera {
      * representing the style layer to  which the feature belongs. Layout and paint properties in this object contain values
      * which are fully evaluated for the given zoom level and feature.
      *
-     * Only features that are currently rendered are included. Some features will not be included, like:
+     * Only features that are currently rendered are included. Some features will **not** be included, like:
      *
-     * - Features from layers whose `visibility` property is `"none"`
-     * - Features from layers whose zoom range excludes the current zoom level are not included.
-     * - Symbol features that have been hidden due to text or icon collision are not included.
+     * - Features from layers whose `visibility` property is `"none"`.
+     * - Features from layers whose zoom range excludes the current zoom level.
+     * - Symbol features that have been hidden due to text or icon collision.
      *
      * Features from all other layers are included, including features that may have no visible
      * contribution to the rendered result; for example, because the layer's opacity or color alpha component is set to

From 85207c63294e59ca5a6a883d68e4b3ed1993299d Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Wed, 11 Sep 2019 13:54:04 -0700
Subject: [PATCH 11/15] address feedback from @mourner and @andrewharvey

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

diff --git a/src/ui/map.js b/src/ui/map.js
index 7d074a00448..77e11a2686f 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -203,7 +203,11 @@ const defaultOptions = {
  * @param {number} [options.pitch=0] The initial pitch (tilt) of the map, measured in degrees away from the plane of the screen (0-60). If `pitch` is not specified in the constructor options, Mapbox GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0`.
  * @param {LngLatBoundsLike} [options.bounds] The initial bounds of the map. If `bounds` is specified, it overrides `center` and `zoom` constructor options.
  * @param {Object} [options.fitBoundsOptions] A [`fitBounds`](#map#fitbounds) options object to use _only_ when fitting the initial `bounds` provided above.
- * @param {boolean} [options.renderWorldCopies=true]  If `true`, multiple copies of the world will be rendered side by side when the map is zoomed out far enough that a single representation of the world does not fill the map's entire container.
+ * @param {boolean} [options.renderWorldCopies=true]  If `true`, multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to `false`:
+ * - When the map is zoomed out far enough that a single representation of the world does not fill the map's entire 
+ * container, there will be blank space beyond 180 and -180 degrees longitude.
+ * - Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the
+ * map and the other on the left edge of the map) at every zoom level.
  * @param {number} [options.maxTileCacheSize=null]  The maximum number of tiles stored in the tile cache for a given source. If omitted, the cache will be dynamically sized based on the current viewport.
  * @param {string} [options.localIdeographFontFamily='sans-serif'] Defines a CSS
  *   font-family for locally overriding generation of glyphs in the 'CJK Unified Ideographs', 'Hiragana', 'Katakana' and 'Hangul Syllables' ranges.
@@ -276,44 +280,44 @@ class Map extends Camera {
     _requestManager: RequestManager;
 
     /**
-     * The map's `ScrollZoomHandler`, which implements zooming in and out with a scroll wheel or trackpad.
+     * The map's {@link ScrollZoomHandler}, which implements zooming in and out with a scroll wheel or trackpad.
      * Find more details and examples using `scrollZoom` in the {@link ScrollZoomHandler} section.
      */
     scrollZoom: ScrollZoomHandler;
 
     /**
-     * The map's `BoxZoomHandler`, which implements zooming using a drag gesture with the Shift key pressed.
+     * The map's {@link BoxZoomHandler}, which implements zooming using a drag gesture with the Shift key pressed.
      * Find more details and examples using `boxZoom` in the {@link BoxZoomHandler} section.
      */
     boxZoom: BoxZoomHandler;
 
     /**
-     * The map's `DragRotateHandler`, which implements rotating the map while dragging with the right
+     * The map's {@link DragRotateHandler}, which implements rotating the map while dragging with the right
      * mouse button or with the Control key pressed. Find more details and examples using `dragRotate` 
      * in the {@link DragRotateHandler} section.
      */
     dragRotate: DragRotateHandler;
 
     /**
-     * The map's `DragPanHandler`, which implements dragging the map with a mouse or touch gesture.
+     * The map's {@link DragPanHandler}, which implements dragging the map with a mouse or touch gesture.
      * Find more details and examples using `dragPan` in the {@link DragPanHandler} section.
      */
     dragPan: DragPanHandler;
 
     /**
-     * The map's `KeyboardHandler`, which allows the user to zoom, rotate, and pan the map using keyboard
+     * The map's {@link KeyboardHandler}, which allows the user to zoom, rotate, and pan the map using keyboard
      * shortcuts. Find more details and examples using `keyboard` in the {@link KeyboardHandler} section.
      */
     keyboard: KeyboardHandler;
 
     /**
-     * The map's `DoubleClickZoomHandler`, which allows the user to zoom by double clicking.
+     * The map's {@link DoubleClickZoomHandler}, which allows the user to zoom by double clicking.
      * Find more details and examples using `doubleClickZoom` in the {@link DoubleClickZoomHandler} section.
      */
     doubleClickZoom: DoubleClickZoomHandler;
 
     /**
-     * The map's `TouchZoomRotateHandler`, which allows the user to zoom or rotate the map with touch gestures.
+     * The map's {@link TouchZoomRotateHandler}, which allows the user to zoom or rotate the map with touch gestures.
      * Find more details and examples using `touchZoomRotate` in the {@link TouchZoomRotateHandler} section.
      */
     touchZoomRotate: TouchZoomRotateHandler;
@@ -499,7 +503,7 @@ class Map extends Camera {
      * `container` element.
      *
      * Checks if the map container size changed and updates the map if it has changed.
-     * This method must be called after the map's `container` is resized by another script
+     * This method must be called after the map's `container` is resized programmatically
      * or when the map is shown after being initially hidden with CSS.
      *
      * @param eventData Additional properties to be passed to `movestart`, `move`, `resize`, and `moveend`
@@ -532,7 +536,7 @@ class Map extends Camera {
      * Returns the map's geographical bounds. When the bearing or pitch is non-zero, the visible region is not
      * an axis-aligned rectangle, and the result is the smallest bounds that encompasses the visible region.
      * @example
-     * map.getBounds();
+     * var bounds = map.getBounds();
      */
     getBounds(): LngLatBounds {
         return this.transform.getBounds();
@@ -541,7 +545,7 @@ class Map extends Camera {
     /**
      * Returns the maximum geographical bounds the map is constrained to, or `null` if none set.
      * @example
-     * map.getMaxBounds();
+     * var maxBounds = map.getMaxBounds();
      */
     getMaxBounds(): LngLatBounds | null {
         return this.transform.getMaxBounds();
@@ -562,8 +566,8 @@ class Map extends Camera {
      * @example
      * // Define bounds that conform to the `LngLatBoundsLike` object.
      * var bounds = [
-     *   [-74.04728, 40.68392], // Southwest coordinates
-     *   [-73.91058, 40.87764]  // Northeast coordinates
+     *   [-74.04728, 40.68392], // [west, south]
+     *   [-73.91058, 40.87764]  // [east, north]
      * ];
      * // Set the map's max bounds.
      * map.setMaxBounds(bounds);

From 7dab4133becec57085fea77d76b2b6e58014408c Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Wed, 11 Sep 2019 13:57:36 -0700
Subject: [PATCH 12/15] fix linting errors

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

diff --git a/src/ui/map.js b/src/ui/map.js
index 77e11a2686f..78297a968b6 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -204,7 +204,7 @@ const defaultOptions = {
  * @param {LngLatBoundsLike} [options.bounds] The initial bounds of the map. If `bounds` is specified, it overrides `center` and `zoom` constructor options.
  * @param {Object} [options.fitBoundsOptions] A [`fitBounds`](#map#fitbounds) options object to use _only_ when fitting the initial `bounds` provided above.
  * @param {boolean} [options.renderWorldCopies=true]  If `true`, multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to `false`:
- * - When the map is zoomed out far enough that a single representation of the world does not fill the map's entire 
+ * - When the map is zoomed out far enough that a single representation of the world does not fill the map's entire
  * container, there will be blank space beyond 180 and -180 degrees longitude.
  * - Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the
  * map and the other on the left edge of the map) at every zoom level.
@@ -293,7 +293,7 @@ class Map extends Camera {
 
     /**
      * The map's {@link DragRotateHandler}, which implements rotating the map while dragging with the right
-     * mouse button or with the Control key pressed. Find more details and examples using `dragRotate` 
+     * mouse button or with the Control key pressed. Find more details and examples using `dragRotate`
      * in the {@link DragRotateHandler} section.
      */
     dragRotate: DragRotateHandler;
@@ -647,7 +647,6 @@ class Map extends Camera {
      */
     getMaxZoom() { return this.transform.maxZoom; }
 
-
     /**
      * Returns the state of `renderWorldCopies`. If `true`, multiple copies of the world will be rendered side by side
      * when the map is zoomed out far enough that a single representation of the world does not fill the map's entire container.

From 947178dea13b60c10a7343d8a440c1a8d598c048 Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Date: Thu, 12 Sep 2019 09:52:55 -0700
Subject: [PATCH 13/15] apply @mourner's suggestions from code review

Co-Authored-By: Vladimir Agafonkin <agafonkin@gmail.com>
---
 src/ui/map.js | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 78297a968b6..64b843f4a10 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -608,7 +608,7 @@ class Map extends Camera {
      *
      * @returns {number} minZoom
      * @example
-     * map.getMinZoom();
+     * var minZoom = map.getMinZoom();
      */
     getMinZoom() { return this.transform.minZoom; }
 
@@ -643,7 +643,7 @@ class Map extends Camera {
      *
      * @returns {number} maxZoom
      * @example
-     * map.getMaxZoom();
+     * var maxZoom = map.getMaxZoom();
      */
     getMaxZoom() { return this.transform.maxZoom; }
 
@@ -653,7 +653,7 @@ class Map extends Camera {
      *
      * @returns {boolean} renderWorldCopies
      * @example
-     * map.getRenderWorldCopies();
+     * var worldCopiesRendered = map.getRenderWorldCopies();
      */
     getRenderWorldCopies() { return this.transform.renderWorldCopies; }
 
@@ -705,7 +705,7 @@ class Map extends Camera {
     /**
      * Returns true if the map is panning, zooming, rotating, or pitching due to a camera animation or user gesture.
      * @example
-     * map.isMoving();
+     * var isMoving = map.isMoving();
      */
     isMoving(): boolean {
         return this._moving ||
@@ -717,7 +717,7 @@ class Map extends Camera {
     /**
      * Returns true if the map is zooming due to a camera animation or user gesture.
      * @example
-     * map.isZooming();
+     * var isZooming = map.isZooming();
      */
     isZooming(): boolean {
         return this._zooming ||

From f625b5a44cba691c783d5bdee23deb1ae3667ca8 Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Date: Thu, 12 Sep 2019 10:13:17 -0700
Subject: [PATCH 14/15] add new language to getRenderWorldCopies and
 setRenderWorldCopies

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

diff --git a/src/ui/map.js b/src/ui/map.js
index 64b843f4a10..a2b4092f9d8 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -648,9 +648,11 @@ class Map extends Camera {
     getMaxZoom() { return this.transform.maxZoom; }
 
     /**
-     * Returns the state of `renderWorldCopies`. If `true`, multiple copies of the world will be rendered side by side
-     * when the map is zoomed out far enough that a single representation of the world does not fill the map's entire container.
-     *
+     * Returns the state of `renderWorldCopies`. If `true`, multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to `false`:
+     * - When the map is zoomed out far enough that a single representation of the world does not fill the map's entire
+     * container, there will be blank space beyond 180 and -180 degrees longitude.
+     * - Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the
+     * map and the other on the left edge of the map) at every zoom level.
      * @returns {boolean} renderWorldCopies
      * @example
      * var worldCopiesRendered = map.getRenderWorldCopies();
@@ -660,8 +662,12 @@ class Map extends Camera {
     /**
      * Sets the state of `renderWorldCopies`.
      *
-     * @param {boolean} renderWorldCopies If `true`, multiple copies of the world will be rendered side by side when
-     * the map is zoomed out far enough that a single representation of the world does not fill the map's entire container.
+     * @param {boolean} renderWorldCopies If `true`, multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to `false`:
+     * - When the map is zoomed out far enough that a single representation of the world does not fill the map's entire
+     * container, there will be blank space beyond 180 and -180 degrees longitude.
+     * - Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the
+     * map and the other on the left edge of the map) at every zoom level.
+     *
      * `undefined` is treated as `true`, `null` is treated as `false`.
      * @returns {Map} `this`
      * @example

From 39f09565667e38adbd4c001674652bc934f9e404 Mon Sep 17 00:00:00 2001
From: Colleen <colleen.j.mcginnis@gmail.com>
Date: Thu, 12 Sep 2019 13:06:23 -0700
Subject: [PATCH 15/15] add link to render-world-copies example

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

diff --git a/src/ui/map.js b/src/ui/map.js
index a2b4092f9d8..a3df2cd6fe4 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -656,6 +656,7 @@ class Map extends Camera {
      * @returns {boolean} renderWorldCopies
      * @example
      * var worldCopiesRendered = map.getRenderWorldCopies();
+     * @see [Render world copies](https://docs.mapbox.com/mapbox-gl-js/example/render-world-copies/)
      */
     getRenderWorldCopies() { return this.transform.renderWorldCopies; }
 
@@ -672,6 +673,7 @@ class Map extends Camera {
      * @returns {Map} `this`
      * @example
      * map.setRenderWorldCopies(true);
+     * @see [Render world copies](https://docs.mapbox.com/mapbox-gl-js/example/render-world-copies/)
      */
     setRenderWorldCopies(renderWorldCopies?: ?boolean) {
         this.transform.renderWorldCopies = renderWorldCopies;