10 files changed, 123 insertions, 21 deletions
diff --git a/platform/darwin/src/MGLCircleStyleLayer.h b/platform/darwin/src/MGLCircleStyleLayer.h
index b57e245da2..d2e043e22a 100644
--- a/platform/darwin/src/MGLCircleStyleLayer.h
+++ b/platform/darwin/src/MGLCircleStyleLayer.h
@@ -59,8 +59,21 @@ typedef NS_ENUM(NSUInteger, MGLCircleTranslateAnchor) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new circle style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
-
- <!--EXAMPLE: MGLCircleStyleLayer-->
+ 
+ ### Example
+ 
+ ```swift
+ let layer = MGLCircleStyleLayer(identifier: "circles", source: population)
+ layer.sourceLayerIdentifier = "population"
+ layer.circleColor = MGLStyleValue(rawValue: .green)
+ layer.circleRadius = MGLStyleValue(interpolationBase: 1.75, stops: [
+     12: MGLStyleValue(rawValue: 2),
+     22: MGLStyleValue(rawValue: 180)
+ ])
+ layer.circleOpacity = MGLStyleValue(rawValue: 0.7)
+ layer.predicate = NSPredicate(format: "%K == %@", "marital-status", "married")
+ mapView.style.addLayer(layer)
+ ```
  */
 @interface MGLCircleStyleLayer : MGLVectorStyleLayer
 
diff --git a/platform/darwin/src/MGLFillStyleLayer.h b/platform/darwin/src/MGLFillStyleLayer.h
index 2638e85aa5..184f44ef65 100644
--- a/platform/darwin/src/MGLFillStyleLayer.h
+++ b/platform/darwin/src/MGLFillStyleLayer.h
@@ -37,8 +37,16 @@ typedef NS_ENUM(NSUInteger, MGLFillTranslateAnchor) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new fill style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
-
- <!--EXAMPLE: MGLFillStyleLayer-->
+ 
+ ### Example
+ 
+ ```swift
+ let layer = MGLFillStyleLayer(identifier: "parks", source: parks)
+ layer.sourceLayerIdentifier = "parks"
+ layer.fillColor = MGLStyleValue(rawValue: .green)
+ layer.predicate = NSPredicate(format: "type == %@", "national-park")
+ mapView.style.addLayer(layer)
+ ```
  */
 @interface MGLFillStyleLayer : MGLVectorStyleLayer
 
diff --git a/platform/darwin/src/MGLLineStyleLayer.h b/platform/darwin/src/MGLLineStyleLayer.h
index c3371aa2a7..f049ae1db1 100644
--- a/platform/darwin/src/MGLLineStyleLayer.h
+++ b/platform/darwin/src/MGLLineStyleLayer.h
@@ -87,8 +87,21 @@ typedef NS_ENUM(NSUInteger, MGLLineTranslateAnchor) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new line style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
-
- <!--EXAMPLE: MGLLineStyleLayer-->
+ 
+ ### Example
+ 
+ ```swift
+ let layer = MGLLineStyleLayer(identifier: "trails-path", source: trails)
+ layer.sourceLayerIdentifier = "trails"
+ layer.lineWidth = MGLStyleValue(interpolationBase: 1.5, stops: [
+     14: MGLStyleValue(rawValue: 2),
+     18: MGLStyleValue(rawValue: 20),
+ ])
+ layer.lineColor = MGLStyleValue(rawValue: .brown)
+ layer.lineCap = MGLStyleValue(rawValue: NSValue(mglLineCap: .round))
+ layer.predicate = NSPredicate(format: "%K == %@", "trail-type", "mountain-biking")
+ mapView.style.addLayer(layer)
+ ```
  */
 @interface MGLLineStyleLayer : MGLVectorStyleLayer
 
diff --git a/platform/darwin/src/MGLRasterSource.h b/platform/darwin/src/MGLRasterSource.h
index 3efd84f383..cd95e85c5b 100644
--- a/platform/darwin/src/MGLRasterSource.h
+++ b/platform/darwin/src/MGLRasterSource.h
@@ -35,8 +35,19 @@ extern const MGLTileSourceOption MGLTileSourceOptionTileSize;
  `MGLRasterSource` object that you can use to initialize new style layers. You
  can also add and remove sources dynamically using methods such as
  `-[MGLStyle addSource:]` and `-[MGLStyle sourceWithIdentifier:]`.
-
- <!--EXAMPLE: MGLRasterSource-->
+ 
+ ### Example
+ 
+ ```swift
+ let source = MGLRasterSource(identifier: "clouds", tileURLTemplates: ["https://example.com/raster-tiles/{z}/{x}/{y}.png"], options: [
+     .minimumZoomLevel: 9,
+     .maximumZoomLevel: 16,
+     .tileSize: 512,
+     .attributionInfos: [
+         MGLAttributionInfo(title: NSAttributedString(string: "© Mapbox"), url: URL(string: "http://mapbox.com"))
+     ]
+ ])
+ mapView.style.addSource(source)
  ```
  */
 @interface MGLRasterSource : MGLTileSource
diff --git a/platform/darwin/src/MGLRasterStyleLayer.h b/platform/darwin/src/MGLRasterStyleLayer.h
index 7b53eebf96..45ab25a8f1 100644
--- a/platform/darwin/src/MGLRasterStyleLayer.h
+++ b/platform/darwin/src/MGLRasterStyleLayer.h
@@ -23,8 +23,14 @@ NS_ASSUME_NONNULL_BEGIN
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new raster style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
-
- <!--EXAMPLE: MGLRasterStyleLayer-->
+ 
+ ### Example
+ 
+ ```swift
+ let layer = MGLRasterStyleLayer(identifier: "clouds", source: source)
+ layer.rasterOpacity = MGLStyleValue(rawValue: 0.5)
+ mapView.style.addLayer(layer)
+ ```
  */
 @interface MGLRasterStyleLayer : MGLForegroundStyleLayer
 
diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 0eb454437b..30e299d2b1 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -74,8 +74,18 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
  
  Any vector style layer initialized with a shape source should have a `nil`
  value in its `sourceLayerIdentifier` property.
-
- <!--EXAMPLE: MGLShapeSource-->
+ 
+ ### 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 shape = MGLShapeCollectionFeature(shapes: [polyline])
+ let source = MGLShapeSource(identifier: "lines", shape: shape, options: nil)
+ mapView.style.addSource(source)
  ```
  */
 @interface MGLShapeSource : MGLSource
diff --git a/platform/darwin/src/MGLStyleLayer.h.ejs b/platform/darwin/src/MGLStyleLayer.h.ejs
index ac95022ea7..17529b8f9d 100644
--- a/platform/darwin/src/MGLStyleLayer.h.ejs
+++ b/platform/darwin/src/MGLStyleLayer.h.ejs
@@ -67,8 +67,11 @@ typedef NS_ENUM(NSUInteger, MGL<%- camelize(property.name) %>) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new <%- type %> style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
-
- <!--EXAMPLE: MGL<%- camelize(type) %>StyleLayer-->
+ 
+ ### Example
+ 
+ ```swift
+ ```
  */
 <% } -%>
 @interface MGL<%- camelize(type) %>StyleLayer : MGL<%-
diff --git a/platform/darwin/src/MGLSymbolStyleLayer.h b/platform/darwin/src/MGLSymbolStyleLayer.h
index 052d67617a..ca34698159 100644
--- a/platform/darwin/src/MGLSymbolStyleLayer.h
+++ b/platform/darwin/src/MGLSymbolStyleLayer.h
@@ -260,8 +260,21 @@ typedef NS_ENUM(NSUInteger, MGLTextTranslateAnchor) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new symbol style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
-
- <!--EXAMPLE: MGLSymbolStyleLayer-->
+ 
+ ### Example
+ 
+ ```swift
+ let layer = MGLSymbolStyleLayer(identifier: "coffeeshops", source: pois)
+ layer.sourceLayerIdentifier = "pois"
+ layer.iconImageName = MGLStyleValue(rawValue: "coffee")
+ layer.iconScale = MGLStyleValue(rawValue: 0.5)
+ layer.textField = MGLStyleValue(rawValue: "{name}")
+ layer.textTranslate = MGLStyleValue(rawValue: NSValue(cgVector: CGVector(dx: 10, dy: 0)))
+ layer.textJustification = MGLStyleValue(rawValue: NSValue(mglTextJustification: .left))
+ layer.textAnchor = MGLStyleValue(rawValue: NSValue(mglTextAnchor: .left))
+ layer.predicate = NSPredicate(format: "%K == %@", "venue-type", "coffee")
+ mapView.style.addLayer(layer)
+ ```
  */
 @interface MGLSymbolStyleLayer : MGLVectorStyleLayer
 
diff --git a/platform/darwin/src/MGLVectorSource.h b/platform/darwin/src/MGLVectorSource.h
index ba8f075b5a..aa867adb6c 100644
--- a/platform/darwin/src/MGLVectorSource.h
+++ b/platform/darwin/src/MGLVectorSource.h
@@ -24,8 +24,19 @@ NS_ASSUME_NONNULL_BEGIN
  (<var>extent</var>&nbsp;×&nbsp;2)&nbsp;−&nbsp;1, inclusive. Any vector style
  layer initialized with a vector source must have a non-`nil` value in its
  `sourceLayerIdentifier` property.
-
- <!--EXAMPLE: MGLVectorSource-->
+ 
+ ### Example
+ 
+ ```swift
+ let source = MGLVectorSource(identifier: "pois", tileURLTemplates: ["https://example.com/vector-tiles/{z}/{x}/{y}.mvt"], options: [
+     .minimumZoomLevel: 9,
+     .maximumZoomLevel: 16,
+     .attributionInfos: [
+         MGLAttributionInfo(title: NSAttributedString(string: "© Mapbox"), url: URL(string: "http://mapbox.com"))
+     ]
+ ])
+ mapView.style.addSource(source)
+ ```
  */
 @interface MGLVectorSource : MGLTileSource
 
diff --git a/platform/darwin/src/MGLVectorStyleLayer.h b/platform/darwin/src/MGLVectorStyleLayer.h
index 50e56d8643..d33494c3e4 100644
--- a/platform/darwin/src/MGLVectorStyleLayer.h
+++ b/platform/darwin/src/MGLVectorStyleLayer.h
@@ -59,7 +59,10 @@ NS_ASSUME_NONNULL_BEGIN
  <li><code>NSContainsPredicateOperatorType</code> (<code>CONTAINS</code>)</li>
  </ul>
  
- To test whether a feature has or lacks a specific attribute, compare the attribute to `NULL` or `NIL`. Predicates created using the `+[NSPredicate predicateWithValue:]` method are also supported. String operators and custom operators are not supported.
+ To test whether a feature has or lacks a specific attribute, compare the
+ attribute to `NULL` or `NIL`. Predicates created using the
+ `+[NSPredicate predicateWithValue:]` method are also supported. String
+ operators and custom operators are not supported.
  
  For details about the predicate format string syntax, consult the “Predicate
  Format String Syntax” chapter of the
@@ -130,8 +133,19 @@ NS_ASSUME_NONNULL_BEGIN
  style attributes and also `hyphen-minus` and `tag:subtag`. However, you must use
  `%K` in the format string to represent these variables:
  `@"%K == 'LineString'", @"$type"`.
-
- <!--EXAMPLE: MGLVectorStyleLayer.predicate-->
+ 
+ ### Example
+ 
+ To filter the layer to include only the features whose `index` attribute is 5
+ or 10 and whose `ele` attribute is at least 1,500, you could create an
+ `NSCompoundPredicate` along these lines:
+ 
+ ```swift
+ let layer = MGLLineStyleLayer(identifier: "contour", source: terrain)
+ layer.sourceLayerIdentifier = "contours"
+ layer.predicate = NSPredicate(format: "(index == 5 || index == 10) && ele >= 1500.0")
+ mapView.style.addLayer(layer)
+ ```
  */
 @property (nonatomic, nullable) NSPredicate *predicate;