Merge branch 'release-ios-v3.4.0' into 1ec5-release-ios-v3.4.1-master

8 files changed, 52 insertions, 17 deletions

diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
index 3d775c8a89..254a7cf219 100644
--- a/platform/darwin/docs/guides/For Style Authors.md.ejs
+++ b/platform/darwin/docs/guides/For Style Authors.md.ejs
@@ -42,9 +42,10 @@ underneath.
 The user location annotation view, the attribution button, any buttons in
 callout views, and any items in the navigation bar are influenced by your
 application’s tint color, so choose a tint color that constrasts well with your
-map style. If you intend your style to be used in the dark, consider the impact
-that Night Shift may have on your style’s colors.
+map style.
 <% } -%>
+If you intend your style to be used in the dark, consider the impact that Night
+Shift may have on your style’s colors.
 
 ### Typography and graphics
 
@@ -178,7 +179,7 @@ In style JSON | In the SDK
 `raster`      | `MGLRasterSource`
 `vector`      | `MGLVectorSource`
 
-`image` and `video` sources are not supported.
+`canvas`, `image`, and `video` sources are not supported.
 
 ### Tile sources
 
@@ -282,9 +283,15 @@ Array (`-padding`) | `NSValue.edgeInsetsValue` | `NSValue.edgeInsetsValue`
 <% } -%>
 
 For padding attributes, note that the arguments to
-`<%- cocoaPrefix %>EdgeInsetsMake()` in Objective-C and
-`EdgeInsets(top:left:bottom:right:)` in Swift are specified in counterclockwise
-order, in contrast to the clockwise order defined by the style specification.
+<% if (iOS) { -%>
+`UIEdgeInsetsMake()` in Objective-C and `UIEdgeInsets(top:left:bottom:right:)`
+in Swift
+<% } else { -%>
+`NSEdgeInsetsMake()` in Objective-C and `EdgeInsets(top:left:bottom:right:)` in
+Swift
+<% } -%>
+are specified in counterclockwise order, in contrast to the clockwise order
+defined by the style specification.
 
 <% if (macOS) { -%>
 Additionally, on macOS, a screen coordinate of (0, 0) is located at the
diff --git a/platform/darwin/scripts/update-examples.js b/platform/darwin/scripts/update-examples.js
index 6291326068..e6b747a460 100644
--- a/platform/darwin/scripts/update-examples.js
+++ b/platform/darwin/scripts/update-examples.js
@@ -108,10 +108,10 @@ function completeExamples(os) {
         }
         
         // Resolve conditional compilation blocks.
-        example = example.replace(/^(\s*)#if\s+os\((iOS|macOS)\)\n([^]*?)(?:^\1#else\n([^]*?))?^\1#endif\n/gm,
+        example = example.replace(/^(\s*)#if\s+os\((iOS|macOS)\)\n([^]*?)(?:^\1#else\n([^]*?))?^\1#endif\b\n?/gm,
                                   function (m, indentation, ifOs, ifCase, elseCase) {
           return (os === ifOs ? ifCase : elseCase).replace(new RegExp('^    ', 'gm'), '');
-        });
+        }).replace(/\n$/, '');
         
         // Insert the test method contents into the documentation comment just
         // above the substructure.
diff --git a/platform/darwin/src/MGLMapCamera.h b/platform/darwin/src/MGLMapCamera.h
index 3d492656af..584d370e6b 100644
--- a/platform/darwin/src/MGLMapCamera.h
+++ b/platform/darwin/src/MGLMapCamera.h
@@ -32,7 +32,7 @@ MGL_EXPORT
 + (instancetype)camera;
 
 /**
- Returns a new camera using based on information about the camera’s viewpoint
+ Returns a new camera based on information about the camera’s viewpoint
  and focus point.
  
  @param centerCoordinate The geographic coordinate on which the map should be
diff --git a/platform/darwin/src/MGLShapeCollection.h b/platform/darwin/src/MGLShapeCollection.h
index 5d2ce588c9..79b7e9223a 100644
--- a/platform/darwin/src/MGLShapeCollection.h
+++ b/platform/darwin/src/MGLShapeCollection.h
@@ -29,8 +29,8 @@ NS_ASSUME_NONNULL_BEGIN
  convenient to use an `MGLPointCollection`, `MGLMultiPolyline`, or
  `MGLMultiPolygon` object, respectively.
  
- A multipolyline is known as a
- <a href="https://tools.ietf.org/html/rfc7946#section-3.1.8">GeometryCollection</a>
+ A shape collection is known as a 
+ <a href="https://tools.ietf.org/html/rfc7946#section-3.1.8">GeometryCollection</a> 
  geometry in GeoJSON.
  */
 MGL_EXPORT
diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 34806c548d..54c5668260 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -21,6 +21,8 @@ typedef NSString *MGLShapeSourceOption NS_STRING_ENUM;
  This attribute corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-cluster"><code>cluster</code></a>
  source property in the Mapbox Style Specification.
+ 
+ This option only affects point features within a shape source.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClustered;
 
@@ -118,7 +120,7 @@ MGL_EXPORT
  the source.
  
  @param identifier A string that uniquely identifies the source.
- @param URL An HTTP(S) URL, absolute file URL, or local file URL relative to the
+ @param url An HTTP(S) URL, absolute file URL, or local file URL relative to the
     current application’s resource bundle.
  @param options An `NSDictionary` of options for this source.
  @return An initialized shape source.
diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 25096748f6..f11810fb65 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -363,7 +363,7 @@ MGL_EXPORT
 /**
  Currently active style classes, represented as an array of string identifiers.
  */
-@property (nonatomic) NS_ARRAY_OF(NSString *) *styleClasses;
+@property (nonatomic) NS_ARRAY_OF(NSString *) *styleClasses __attribute__((deprecated("This property will be removed in a future release.")));
 
 /**
  Returns a Boolean value indicating whether the style class with the given
@@ -372,14 +372,14 @@ MGL_EXPORT
  @param styleClass The style class to query for.
  @return Whether the style class is currently active.
  */
-- (BOOL)hasStyleClass:(NSString *)styleClass;
+- (BOOL)hasStyleClass:(NSString *)styleClass __attribute__((deprecated("This method will be removed in a future release.")));
 
 /**
  Activates the style class with the given identifier.
 
  @param styleClass The style class to activate.
  */
-- (void)addStyleClass:(NSString *)styleClass;
+- (void)addStyleClass:(NSString *)styleClass __attribute__((deprecated("This method will be removed in a future release.")));
 
 /**
  Deactivates the style class with the given identifier.
@@ -394,7 +394,7 @@ MGL_EXPORT
 
  @param styleClass The style class to deactivate.
  */
-- (void)removeStyleClass:(NSString *)styleClass;
+- (void)removeStyleClass:(NSString *)styleClass __attribute__((deprecated("This method will be removed in a future release.")));
 
 #pragma mark Managing a Style’s Images
 
diff --git a/platform/darwin/src/MGLStyleLayer.h b/platform/darwin/src/MGLStyleLayer.h
index ac40545398..d882ced6e6 100644
--- a/platform/darwin/src/MGLStyleLayer.h
+++ b/platform/darwin/src/MGLStyleLayer.h
@@ -29,9 +29,14 @@ MGL_EXPORT
 /**
  Returns a style layer object initialized with the given identifier.
  
+ The default implementation of this initializer in MGLStyleLayer creates an
+ invalid style layer. Call this initializer on `MGLBackgroundStyleLayer` or one of
+ the concrete subclasses of `MGLForegroundStyleLayer` to create a valid style
+ layer.
+ 
  After initializing and configuring the style layer, add it to a map view’s
  style using the `-[MGLStyle addLayer:]` or
- `-[MGLStyle insertLayer:belowLayer:]` method.
+ `-[MGLStyle insertLayer:belowLayer:]` method. 
  
  @param identifier A string that uniquely identifies the layer in the style to
     which it is added.
diff --git a/platform/darwin/test/MGLDocumentationExampleTests.swift b/platform/darwin/test/MGLDocumentationExampleTests.swift
index d796b4e708..9336db7e49 100644
--- a/platform/darwin/test/MGLDocumentationExampleTests.swift
+++ b/platform/darwin/test/MGLDocumentationExampleTests.swift
@@ -217,4 +217,25 @@ class MGLDocumentationExampleTests: XCTestCase, MGLMapViewDelegate {
 
         XCTAssertNotNil(mapView.style?.layer(withIdentifier: "contour"))
     }
+    
+    func testMGLMapView() {
+        //#-example-code
+        #if os(macOS)
+            class MapClickGestureRecognizer: NSClickGestureRecognizer {
+                override func shouldRequireFailure(of otherGestureRecognizer: NSGestureRecognizer) -> Bool {
+                    return otherGestureRecognizer is NSClickGestureRecognizer
+                }
+            }
+        #else
+            let mapTapGestureRecognizer = UITapGestureRecognizer(target: self, action: #selector(myCustomFunction))
+            for recognizer in mapView.gestureRecognizers! where recognizer is UITapGestureRecognizer {
+                mapTapGestureRecognizer.require(toFail: recognizer)
+            }
+            mapView.addGestureRecognizer(mapTapGestureRecognizer)
+        #endif
+        //#-end-example-code
+    }
+    
+    // For testMGLMapView().
+    func myCustomFunction() {}
 }