1 files changed, 32 insertions, 14 deletions
diff --git a/platform/darwin/src/MGLBackgroundStyleLayer.h b/platform/darwin/src/MGLBackgroundStyleLayer.h
index e0773d14d9..06d7c9ee08 100644
--- a/platform/darwin/src/MGLBackgroundStyleLayer.h
+++ b/platform/darwin/src/MGLBackgroundStyleLayer.h
@@ -8,10 +8,18 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- A map style's background layer is the bottommost layer and is used to style a color 
- or pattern to show below all other map features. You can query an `MGLMapView` for its 
- `style` and obtain the background layer using the `-[MGLStyle layerWithIdentifier:]` 
- method and passing `background` for the identifier. 
+ An `MGLBackgroundStyleLayer` is a style layer that covers the entire map. Use a
+ background style layer to configure a color or pattern to show below all other
+ map content. If the style’s other layers use the Mapbox Streets source, the
+ background style layer is responsible for drawing land, whereas the oceans and
+ other bodies of water are drawn by `MGLFillStyleLayer` objects.
+ 
+ A background style layer is typically the bottommost layer in a style, because
+ it covers the entire map and can occlude any layers below it. You can therefore
+ access it by getting the last item in the `MGLStyle.layers` array.
+ 
+ If the background style layer is transparent or omitted from the style, any
+ portion of the map view that does not show another style layer is transparent.
  */
 MGL_EXPORT
 @interface MGLBackgroundStyleLayer : MGLStyleLayer
@@ -24,31 +32,41 @@ MGL_EXPORT
 /**
  The color with which the background will be drawn.
  
- The default value of this property is an `MGLStyleValue` object containing `UIColor.blackColor`. Set this property to `nil` to reset it to the default value.
-
- This property is only applied to the style if `backgroundPattern` is set to `nil`. Otherwise, it is ignored.
+ The default value of this property is an `MGLStyleValue` object containing
+ `UIColor.blackColor`. Set this property to `nil` to reset it to the default
+ value.
+ 
+ This property is only applied to the style if `backgroundPattern` is set to
+ `nil`. Otherwise, it is ignored.
  */
-@property (nonatomic, null_resettable) MGLStyleValue<MGLColor *> *backgroundColor;
+@property (nonatomic, null_resettable) MGLStyleValue<UIColor *> *backgroundColor;
 #else
 /**
  The color with which the background will be drawn.
  
- The default value of this property is an `MGLStyleValue` object containing `NSColor.blackColor`. Set this property to `nil` to reset it to the default value.
-
- This property is only applied to the style if `backgroundPattern` is set to `nil`. Otherwise, it is ignored.
+ The default value of this property is an `MGLStyleValue` object containing
+ `NSColor.blackColor`. Set this property to `nil` to reset it to the default
+ value.
+ 
+ This property is only applied to the style if `backgroundPattern` is set to
+ `nil`. Otherwise, it is ignored.
  */
-@property (nonatomic, null_resettable) MGLStyleValue<MGLColor *> *backgroundColor;
+@property (nonatomic, null_resettable) MGLStyleValue<NSColor *> *backgroundColor;
 #endif
 
 /**
  The opacity at which the background will be drawn.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `1`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `1`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *backgroundOpacity;
 
 /**
- Name of image in style images to use for drawing an image background. For seamless patterns, image width and height must be a factor of two (2, 4, 8, ..., 512).
+ Name of image in style images to use for drawing an image background. For
+ seamless patterns, image width and height must be a factor of two (2, 4, 8,
+ ..., 512).
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSString *> *backgroundPattern;