5 files changed, 16 insertions, 9 deletions
diff --git a/platform/darwin/src/MGLMapCamera.h b/platform/darwin/src/MGLMapCamera.h
index 3d492656af..584d370e6b 100644
--- a/platform/darwin/src/MGLMapCamera.h
+++ b/platform/darwin/src/MGLMapCamera.h
@@ -32,7 +32,7 @@ MGL_EXPORT
 + (instancetype)camera;
 
 /**
- Returns a new camera using based on information about the camera’s viewpoint
+ Returns a new camera based on information about the camera’s viewpoint
  and focus point.
  
  @param centerCoordinate The geographic coordinate on which the map should be
diff --git a/platform/darwin/src/MGLShapeCollection.h b/platform/darwin/src/MGLShapeCollection.h
index 5d2ce588c9..79b7e9223a 100644
--- a/platform/darwin/src/MGLShapeCollection.h
+++ b/platform/darwin/src/MGLShapeCollection.h
@@ -29,8 +29,8 @@ NS_ASSUME_NONNULL_BEGIN
  convenient to use an `MGLPointCollection`, `MGLMultiPolyline`, or
  `MGLMultiPolygon` object, respectively.
  
- A multipolyline is known as a
- <a href="https://tools.ietf.org/html/rfc7946#section-3.1.8">GeometryCollection</a>
+ A shape collection is known as a 
+ <a href="https://tools.ietf.org/html/rfc7946#section-3.1.8">GeometryCollection</a> 
  geometry in GeoJSON.
  */
 MGL_EXPORT
diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 34806c548d..54c5668260 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -21,6 +21,8 @@ typedef NSString *MGLShapeSourceOption NS_STRING_ENUM;
  This attribute corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-cluster"><code>cluster</code></a>
  source property in the Mapbox Style Specification.
+ 
+ This option only affects point features within a shape source.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClustered;
 
@@ -118,7 +120,7 @@ MGL_EXPORT
  the source.
  
  @param identifier A string that uniquely identifies the source.
- @param URL An HTTP(S) URL, absolute file URL, or local file URL relative to the
+ @param url An HTTP(S) URL, absolute file URL, or local file URL relative to the
     current application’s resource bundle.
  @param options An `NSDictionary` of options for this source.
  @return An initialized shape source.
diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 25096748f6..f11810fb65 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -363,7 +363,7 @@ MGL_EXPORT
 /**
  Currently active style classes, represented as an array of string identifiers.
  */
-@property (nonatomic) NS_ARRAY_OF(NSString *) *styleClasses;
+@property (nonatomic) NS_ARRAY_OF(NSString *) *styleClasses __attribute__((deprecated("This property will be removed in a future release.")));
 
 /**
  Returns a Boolean value indicating whether the style class with the given
@@ -372,14 +372,14 @@ MGL_EXPORT
  @param styleClass The style class to query for.
  @return Whether the style class is currently active.
  */
-- (BOOL)hasStyleClass:(NSString *)styleClass;
+- (BOOL)hasStyleClass:(NSString *)styleClass __attribute__((deprecated("This method will be removed in a future release.")));
 
 /**
  Activates the style class with the given identifier.
 
  @param styleClass The style class to activate.
  */
-- (void)addStyleClass:(NSString *)styleClass;
+- (void)addStyleClass:(NSString *)styleClass __attribute__((deprecated("This method will be removed in a future release.")));
 
 /**
  Deactivates the style class with the given identifier.
@@ -394,7 +394,7 @@ MGL_EXPORT
 
  @param styleClass The style class to deactivate.
  */
-- (void)removeStyleClass:(NSString *)styleClass;
+- (void)removeStyleClass:(NSString *)styleClass __attribute__((deprecated("This method will be removed in a future release.")));
 
 #pragma mark Managing a Style’s Images
 
diff --git a/platform/darwin/src/MGLStyleLayer.h b/platform/darwin/src/MGLStyleLayer.h
index ac40545398..d882ced6e6 100644
--- a/platform/darwin/src/MGLStyleLayer.h
+++ b/platform/darwin/src/MGLStyleLayer.h
@@ -29,9 +29,14 @@ MGL_EXPORT
 /**
  Returns a style layer object initialized with the given identifier.
  
+ The default implementation of this initializer in MGLStyleLayer creates an
+ invalid style layer. Call this initializer on `MGLBackgroundStyleLayer` or one of
+ the concrete subclasses of `MGLForegroundStyleLayer` to create a valid style
+ layer.
+ 
  After initializing and configuring the style layer, add it to a map view’s
  style using the `-[MGLStyle addLayer:]` or
- `-[MGLStyle insertLayer:belowLayer:]` method.
+ `-[MGLStyle insertLayer:belowLayer:]` method. 
  
  @param identifier A string that uniquely identifies the layer in the style to
     which it is added.