1 files changed, 37 insertions, 9 deletions
diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 54ca267bab..96dd502c30 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -30,14 +30,24 @@ NS_ASSUME_NONNULL_BEGIN
 static const NSInteger MGLStyleDefaultVersion = 9;
 
 /**
- The proxy object for the current map style for customization purposes and a
- set of convenience methods for creating style URLs of default styles provided
- by Mapbox.
+ The proxy object for the current map style.
+ 
+ MGLStyle provides a set of convenience methods for changing Mapbox
+ default styles using `-[MGLMapView styleURL]`.
  <a href="https://www.mapbox.com/maps/">Learn more about Mapbox default styles</a>.
+ 
+ It is also possible to directly manipulate the current map style 
+ 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.
  */
 @interface MGLStyle : NSObject
 
-#pragma mark Accessing Common Styles
+#pragma mark Accessing Default Styles
 
 /**
  Returns the URL to version 8 of the
@@ -199,11 +209,11 @@ static const NSInteger MGLStyleDefaultVersion = 9;
 
 /**
  Adds a new source to the current style.
-
- @note Adding the same source instance more than once will result in a 
+ 
+ @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`.
+    `MGLRedundantSourceIdentifierException`.
  
  @param source The source to add to the current style.
  */
@@ -251,7 +261,7 @@ static const NSInteger MGLStyleDefaultVersion = 9;
 
 /**
  Adds a new layer on top of existing layers.
-
+ 
  @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.
@@ -372,10 +382,28 @@ static const NSInteger MGLStyleDefaultVersion = 9;
 #pragma mark Managing a Style’s Images
 
 /**
+ Returns the image associated with the given name in the style.
+ 
+ @note Names and their associated images are not guaranteed to exist across
+    styles or different versions of the same style. Applications that use this
+    API must first set the style URL to an explicitly versioned style using a
+    convenience method like `+[MGLStyle outdoorsStyleURLWithVersion:]`,
+    `MGLMapView`'s “Style URL” inspectable in Interface Builder, or a manually
+    constructed `NSURL`. This approach also avoids image name changes that will 
+    occur in the default style over time.
+ 
+ @param name The name associated with the image you want to obtain.
+ @return The image associated with the given name, or `nil` if no image is
+    associated with that name.
+ */
+- (nullable MGLImage *)imageForName:(NSString *)name;
+
+/**
  Adds or overrides an image used by the style’s layers.
  
  To use an image in a style layer, give it a unique name using this method, then
- set the `iconImage` property of an `MGLSymbolStyleLayer` object to that name.
+ set the `iconImageName` property of an `MGLSymbolStyleLayer` object to that
+ name.
  
  @param image The image for the name.
  @param name The name of the image to set to the style.