1 files changed, 77 insertions, 1 deletions
diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 7bd85c8d1f..34806c548d 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -17,6 +17,10 @@ typedef NSString *MGLShapeSourceOption NS_STRING_ENUM;
  An `NSNumber` object containing a Boolean enabling or disabling clustering.
  If the `shape` property contains point shapes, setting this option to
  `YES` clusters the points by radius into groups. The default value is `NO`.
+
+ 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.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClustered;
 
@@ -32,6 +36,10 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClusterRadius;
  which to cluster points if clustering is enabled. Defaults to one zoom level 
  less than the value of `MGLShapeSourceOptionMaximumZoomLevel` so that, at the
  maximum zoom level, the shapes are not clustered.
+
+ This attribute corresponds to the
+ <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-clusterMaxZoom"><code>clusterMaxZoom</code></a>
+ source property in the Mapbox Style Specification.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLevelForClustering;
 
@@ -39,6 +47,10 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLeve
  An `NSNumber` object containing an integer; specifies the maximum zoom level at
  which to create vector tiles. A greater value produces greater detail at high
  zoom levels. The default value is 18.
+
+ This attribute corresponds to the
+ <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-maxzoom"><code>maxzoom</code></a>
+ source property in the Mapbox Style Specification.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLevel;
 
@@ -47,6 +59,10 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLeve
  buffer on each side. A value of 0 produces no buffer. A value of 512 produces a 
  buffer as wide as the tile itself. Larger values produce fewer rendering 
  artifacts near tile edges and slower performance. The default value is 128.
+
+ This attribute corresponds to the
+ <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-buffer"><code>buffer</code></a>
+ source property in the Mapbox Style Specification.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionBuffer;
 
@@ -54,6 +70,10 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionBuffer;
  An `NSNumber` object containing a double; specifies the Douglas-Peucker
  simplification tolerance. A greater value produces simpler geometries and
  improves performance. The default value is 0.375.
+
+ This attribute corresponds to the
+ <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-tolerance"><code>tolerance</code></a>
+ source property in the Mapbox Style Specification.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
 
@@ -75,6 +95,18 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionSimplificationT
  
  Any vector style layer initialized with a shape source should have a `nil`
  value in its `sourceLayerIdentifier` property.
+ 
+ ### Example
+ 
+ ```swift
+ var coordinates: [CLLocationCoordinate2D] = [
+     CLLocationCoordinate2D(latitude: 37.77, longitude: -122.42),
+     CLLocationCoordinate2D(latitude: 38.91, longitude: -77.04),
+ ]
+ let polyline = MGLPolylineFeature(coordinates: &coordinates, count: UInt(coordinates.count))
+ let source = MGLShapeSource(identifier: "lines", features: [polyline], options: nil)
+ mapView.style?.addSource(source)
+ ```
  */
 MGL_EXPORT
 @interface MGLShapeSource : MGLSource
@@ -100,7 +132,9 @@ MGL_EXPORT
  To specify attributes about the shape, use an instance of an `MGLShape`
  subclass that conforms to the `MGLFeature` protocol, such as `MGLPointFeature`.
  To include multiple shapes in the source, use an `MGLShapeCollection` or
- `MGLShapeCollectionFeature` object.
+ `MGLShapeCollectionFeature` object, or use the
+ `-initWithIdentifier:features:options:` or 
+ `-initWithIdentifier:shapes:options:` methods.
  
  To create a shape from GeoJSON source code, use the
  `+[MGLShape shapeWithData:encoding:error:]` method.
@@ -112,6 +146,45 @@ MGL_EXPORT
  */
 - (instancetype)initWithIdentifier:(NSString *)identifier shape:(nullable MGLShape *)shape options:(nullable NS_DICTIONARY_OF(MGLShapeSourceOption, id) *)options NS_DESIGNATED_INITIALIZER;
 
+/**
+ Returns a shape source with an identifier, an array of features, and a dictionary
+ of options for the source.
+ 
+ Unlike `-initWithIdentifier:shapes:options:`, this method accepts `MGLFeature`
+ instances, such as `MGLPointFeature` objects, whose attributes you can use when
+ applying a predicate to `MGLVectorStyleLayer` or configuring a style layer’s
+ appearance.
+
+ To create a shape from GeoJSON source code, use the
+ `+[MGLShape shapeWithData:encoding:error:]` method.
+
+ @param identifier A string that uniquely identifies the source.
+ @param features An array of objects that conform to the MGLFeature protocol.
+ @param options An `NSDictionary` of options for this source.
+ @return An initialized shape source.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier features:(NS_ARRAY_OF(MGLShape<MGLFeature> *) *)features options:(nullable NS_DICTIONARY_OF(MGLShapeSourceOption, id) *)options;
+
+/**
+ Returns a shape source with an identifier, an array of shapes, and a dictionary of
+ options for the source.
+ 
+ Any `MGLFeature` instance passed into this initializer is treated as an ordinary
+ shape, causing any attributes to be inaccessible to an `MGLVectorStyleLayer` when
+ evaluating a predicate or configuring certain layout or paint attributes. To 
+ preserve the attributes associated with each feature, use the 
+ `-initWithIdentifier:features:options:` method instead.
+
+ To create a shape from GeoJSON source code, use the
+ `+[MGLShape shapeWithData:encoding:error:]` method.
+
+ @param identifier A string that uniquely identifies the source.
+ @param shapes An array of shapes; each shape is a member of a concrete subclass of MGLShape.
+ @param options An `NSDictionary` of options for this source.
+ @return An initialized shape source.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier shapes:(NS_ARRAY_OF(MGLShape *) *)shapes options:(nullable NS_DICTIONARY_OF(MGLShapeSourceOption, id) *)options;
+
 #pragma mark Accessing a Source’s Content
 
 /**
@@ -121,6 +194,9 @@ MGL_EXPORT
  If the receiver was initialized using `-initWithIdentifier:URL:options:`, this
  property is set to `nil`. This property is unavailable until the receiver is
  passed into `-[MGLStyle addSource:]`.
+ 
+ You can get/set the shapes within a collection via this property. Actions must 
+ be performed on the application's main thread.
  */
 @property (nonatomic, copy, nullable) MGLShape *shape;