Merge branch 'release-ios-v3.4.0' into 1ec5-release-ios-v3.4.0-beta.7

1 files changed, 25 insertions, 10 deletions

diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 6192632e75..9bd35142c2 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -41,10 +41,10 @@ static MGL_EXPORT const NSInteger MGLStyleDefaultVersion = 9;
  via `-[MGLMapView style]` by updating the style's data sources or layers.
  
  @note Wait until the map style has finished loading before modifying a map's
-    style via any of the MGLStyle instance methods below.
-    You can use the `MGLMapViewDelegate` methods `-mapViewDidFinishLoadingMap:`
-    or `-mapView:didFinishLoadingStyle:` as indicators that it's safe
-    to modify the map's style.
+    style via any of the `MGLStyle` instance methods below. You can use the 
+    `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]` or
+    `-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]` methods as indicators
+    that it's safe to modify the map's style.
  */
 MGL_EXPORT
 @interface MGLStyle : NSObject
@@ -191,7 +191,7 @@ MGL_EXPORT
 /**
  A set containing the style’s sources.
  */
-@property (nonatomic, strong) NS_MUTABLE_SET_OF(MGLSource *) *sources;
+@property (nonatomic, strong) NS_SET_OF(__kindof MGLSource *) *sources;
 
 /**
  Returns a source with the given identifier in the current style.
@@ -215,8 +215,13 @@ MGL_EXPORT
  @note Adding the same source instance more than once will result in a
     `MGLRedundantSourceException`. Reusing the same source identifier, even with
     different source instances, will result in a 
-    `MGLRedundantSourceIdentifierException`.
+    `MGLRedundantSourceIdentifierException`. 
  
+ @note Sources should be added in 
+    `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]` or
+    `-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]` to ensure that the map 
+    has loaded the style and is ready to accept a new source.
+
  @param source The source to add to the current style.
  */
 - (void)addSource:(MGLSource *)source;
@@ -239,10 +244,10 @@ MGL_EXPORT
 #pragma mark Managing Style Layers
 
 /**
- The layers included in the style, arranged according to their front-to-back
+ The layers included in the style, arranged according to their back-to-front
  ordering on the screen.
  */
-@property (nonatomic, strong) NS_MUTABLE_ARRAY_OF(MGLStyleLayer *) *layers;
+@property (nonatomic, strong) NS_ARRAY_OF(__kindof MGLStyleLayer *) *layers;
 
 /**
  Returns a style layer with the given identifier in the current style.
@@ -266,7 +271,12 @@ MGL_EXPORT
  
  @note Adding the same layer instance more than once will result in a
     `MGLRedundantLayerException`. Reusing the same layer identifer, even with
-    different layer instances, will also result in an exception.
+    different layer instances, will also result in an exception. 
+ 
+ @note Layers should be added in 
+    `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]` or
+    `-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]` to ensure that the map 
+    has loaded the style and is ready to accept a new layer.
 
  @param layer The layer object to add to the map view. This object must be an
     instance of a concrete subclass of `MGLStyleLayer`.
@@ -278,7 +288,12 @@ MGL_EXPORT
  
  @note Adding the same layer instance more than once will result in a
     `MGLRedundantLayerException`. Reusing the same layer identifer, even with
-    different layer instances, will also result in an exception.
+    different layer instances, will also result in an exception. 
+ 
+ @note Layers should be added in
+    `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]` or
+    `-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]` to ensure that the map 
+    has loaded the style and is ready to accept a new layer.
 
  @param layer The layer to insert.
  @param index The index at which to insert the layer. An index of 0 would send