Document requirement about adding sources and layers (#7634)

* [ios, macos] Document requirement about adding sources and layers

Sources and layers added outside of mapView:didFinishLoadingStyle:
and mapViewDidFinishLoadingMap: are not guaranteed to appear
since the map may not be fully loaded and ready to accept new
sources and layers.

This also fixes a compiler warning in iosapp.

1 files changed, 22 insertions, 7 deletions

diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index ea7f8ed5cb..fcb464a303 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -40,10 +40,10 @@ static 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.
  */
 @interface MGLStyle : NSObject
 
@@ -213,8 +213,13 @@ static const NSInteger MGLStyleDefaultVersion = 9;
  @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;
@@ -264,7 +269,12 @@ static const NSInteger MGLStyleDefaultVersion = 9;
  
  @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`.
@@ -276,7 +286,12 @@ static const NSInteger MGLStyleDefaultVersion = 9;
  
  @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