[ios, macos] Update MGLStyle API documentation with warnings for dupes

This adds notes to the methods for adding sources and layers to warn
of the hazards of using duplicate instances or identifiers.

1 files changed, 18 insertions, 12 deletions

diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 31808290f9..54ca267bab 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -199,9 +199,11 @@ static const NSInteger MGLStyleDefaultVersion = 9;
 
 /**
  Adds a new source to the current style.
- 
- @note Adding the same source instance more than once or reusing source 
-    identifers in the sources you add will trigger exceptions.
+
+ @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 
+    `MGLRedundantSourceIdentiferException`.
  
  @param source The source to add to the current style.
  */
@@ -250,8 +252,9 @@ static const NSInteger MGLStyleDefaultVersion = 9;
 /**
  Adds a new layer on top of existing layers.
 
- @note Adding the same layer instance more than once or reusing layer
-    identifers in the layers you add will trigger exceptions.
+ @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.
 
  @param layer The layer object to add to the map view. This object must be an
     instance of a concrete subclass of `MGLStyleLayer`.
@@ -261,9 +264,10 @@ static const NSInteger MGLStyleDefaultVersion = 9;
 /**
  Inserts a new layer into the style at the given index.
  
- @note Adding the same layer instance more than once or reusing layer
-    identifers in the layers you add will trigger exceptions.
- 
+ @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.
+
  @param layer The layer to insert.
  @param index The index at which to insert the layer. An index of 0 would send
     the layer to the back; an index equal to the number of objects in the
@@ -282,8 +286,9 @@ static const NSInteger MGLStyleDefaultVersion = 9;
     approach also avoids layer identifer name changes that will occur in the default
     style’s layers over time.
  
-    Adding the same layer instance more than once or reusing layer identifers in 
-    the layers you add will trigger exceptions.
+    Inserting 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.
 
  @param layer The layer to insert.
  @param sibling An existing layer in the style.
@@ -301,8 +306,9 @@ static const NSInteger MGLStyleDefaultVersion = 9;
     approach also avoids layer identifer name changes that will occur in the default
     style’s layers over time.
  
-    Adding the same layer instance more than once or reusing layer identifers in
-    the layers you add will trigger exceptions.
+    Inserting 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.
 
  @param layer The layer to insert.
  @param sibling An existing layer in the style.