From 5cc641ecad4944921d2e82458ef0522d39430a3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Minh=20Nguy=E1=BB=85n?= <mxn@1ec5.org>
Date: Fri, 5 May 2017 14:14:56 -0700
Subject: [ios, macos] Moved DDS guide examples to Swift unit test

Moved example code from DDS guide to a unit test written in Swift. The code is inserted into the guide at codegen time.
---
 .../guides/Using Style Functions at Runtime.md.ejs |  75 +-------
 platform/darwin/scripts/generate-style-code.js     |  35 ++++
 platform/darwin/scripts/update-examples.js         |   2 +-
 .../darwin/test/MGLDocumentationGuideTests.swift   | 214 +++++++++++++++++++++
 .../guides/Using Style Functions at Runtime.md     |  71 ++++---
 platform/ios/ios.xcodeproj/project.pbxproj         |   6 +-
 .../guides/Using Style Functions at Runtime.md     |  71 ++++---
 platform/macos/macos.xcodeproj/project.pbxproj     |   4 +
 8 files changed, 344 insertions(+), 134 deletions(-)
 create mode 100644 platform/darwin/test/MGLDocumentationGuideTests.swift

(limited to 'platform')

diff --git a/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs b/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs
index 7745ab07a1..e41ac1c832 100644
--- a/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs	
+++ b/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs	
@@ -1,9 +1,9 @@
-
 <%
   const os = locals.os;
   const iOS = os === 'iOS';
   const macOS = os === 'macOS';
   const cocoaPrefix = iOS ? 'UI' : 'NS';
+  const guide = 'UsingStyleFunctionsAtRuntime';
 -%>
 <!--
   This file is generated.
@@ -36,13 +36,7 @@ The documentation for each individual style layer property notes which style fun
 
 Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key.
 
-```swift
-let stops = [0: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .yellow),
-             2.5: MGLStyleValue(rawValue: .orange),
-             5: MGLStyleValue(rawValue: .red),
-             7.5: MGLStyleValue(rawValue: .blue),
-             10: MGLStyleValue(rawValue: .white)]
-```
+<%- guideExample(guide, 'Stops', os) %>
 
 ## Interpolation mode
 
@@ -54,28 +48,7 @@ The effect a key has on the style value is determined by the interpolation mode.
 
 The stops dictionary below, for example, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value.
 
-```swift
-let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson")!
-let symbolSource = MGLSource(identifier: "source")!
-let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource)
-
-let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil)
-style.addSource(source)
-
-let stops = [0: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .yellow),
-             2.5: MGLStyleValue(rawValue: .orange),
-             5: MGLStyleValue(rawValue: .red),
-             7.5: MGLStyleValue(rawValue: .blue),
-             10: MGLStyleValue(rawValue: .white)]
-
-let layer = MGLCircleStyleLayer(identifier: "circles", source: source)
-layer.circleColor = MGLStyleValue(interpolationMode: .exponential,
-                                  sourceStops: stops,
-                                  attributeName: "mag",
-                                  options: [.defaultValue: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .green)])
-layer.circleRadius = MGLStyleValue(rawValue: 10)
-style.insertLayer(layer, below: symbolLayer)
-```
+<%- guideExample(guide, 'Linear', os) %>
 
 ![exponential mode](img/data-driven-styling/exponential.png)
 
@@ -90,15 +63,7 @@ Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](wo
 
 The example below increases a layer’s `circleRadius` exponentially based on a map’s zoom level. The `MGLStyleFunctionOptionInterpolationBase` is `1.5`.
 
-```swift
-let stops = [12: MGLStyleValue<NSNumber>(rawValue: 0.5),
-             14: MGLStyleValue(rawValue: 2),
-             18: MGLStyleValue(rawValue: 18)]
-
-layer.circleRadius = MGLStyleValue(interpolationMode: .exponential,
-                                  cameraStops: stops,
-                                  options: [.interpolationBase: 1.5])
-```
+<%- guideExample(guide, 'Exponential', os) %>
 
 ### Interval
 
@@ -106,18 +71,7 @@ layer.circleRadius = MGLStyleValue(interpolationMode: .exponential,
 
 When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on.
 
-```swift
-let stops = [0: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .yellow),
-             2.5: MGLStyleValue(rawValue: .orange),
-             5: MGLStyleValue(rawValue: .red),
-             7.5: MGLStyleValue(rawValue: .blue),
-             10: MGLStyleValue(rawValue: .white)]
-
-layer.circleColor = MGLStyleValue(interpolationMode: .interval,
-                                  sourceStops: stops,
-                                  attributeName: "mag",
-                                  options: [.defaultValue: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .green)])
-```
+<%- guideExample(guide, 'Interval', os) %>
 
 ![interval mode](img/data-driven-styling/interval.png)
 
@@ -127,17 +81,7 @@ At each stop, `MGLInterpolationModeCategorical` produces an output value equal t
 
 There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of blue to catch any events that do not fall into any of those categories.
 
-```swift
-let categoricalStops = ["earthquake": MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .orange),
-                        "explosion": MGLStyleValue(rawValue: .red),
-                        "quarry blast": MGLStyleValue(rawValue: .yellow)]
-
-layer.circleColor = MGLStyleValue(interpolationMode: .categorical,
-                                  sourceStops: categoricalStops,
-                                  attributeName: "type",
-                                  options: [.defaultValue: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .blue)])
-
-```
+<%- guideExample(guide, 'Categorical', os) %>
 
 ![categorical mode](img/data-driven-styling/categorical1.png) ![categorical mode](img/data-driven-styling/categorical2.png)
 
@@ -145,12 +89,7 @@ layer.circleColor = MGLStyleValue(interpolationMode: .categorical,
 
 `MGLInterpolationModeIdentity` uses the attribute’s value as the style value. For example, you can set the `circleRadius` to the earthquake’s magnitude. Since the attribute value itself will be used as the style value, `sourceStops` should be set to `nil`.
 
-```swift
-layer.circleRadius = MGLStyleValue(interpolationMode: .identity,
-                                   sourceStops: nil,
-                                   attributeName: "mag",
-                                   options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)])
-```
+<%- guideExample(guide, 'Identity', os) %>
 
 ![identity mode](img/data-driven-styling/identity.png)
 
diff --git a/platform/darwin/scripts/generate-style-code.js b/platform/darwin/scripts/generate-style-code.js
index 5d5adbbef6..330a8f1d03 100644
--- a/platform/darwin/scripts/generate-style-code.js
+++ b/platform/darwin/scripts/generate-style-code.js
@@ -600,6 +600,41 @@ for (var layer of layers) {
     fs.writeFileSync(`platform/darwin/test/${prefix}${camelize(layer.type)}${suffix}Tests.mm`, testLayers(layer));
 }
 
+// Extract examples for guides from unit tests.
+let examplesSrc = fs.readFileSync('platform/darwin/test/MGLDocumentationGuideTests.swift', 'utf8');
+const exampleRegex = /func test([\w$]+)\s*\(\)\s*\{[^]*?\n([ \t]+)\/\/#-example-code\n([^]+?)\n\2\/\/#-end-example-code\n/gm;
+
+let examples = {};
+let match;
+while ((match = exampleRegex.exec(examplesSrc)) !== null) {
+    let testMethodName = match[1],
+        indentation = match[2],
+        exampleCode = match[3];
+    
+    // Trim leading whitespace from the example code.
+    exampleCode = exampleCode.replace(new RegExp('^' + indentation, 'gm'), '');
+    
+    examples[testMethodName] = exampleCode;
+}
+
+global.guideExample = function (guide, exampleId, os) {
+    // Get the contents of the test method whose name matches the symbol path.
+    let testMethodName = `${guide}$${exampleId}`;
+    let example = examples[testMethodName];
+    if (!example) {
+        console.error(`MGLDocumentationExampleTests.test${testMethodName}() not found.`);
+        process.exit(1);
+    }
+    
+    // Resolve conditional compilation blocks.
+    example = example.replace(/^(\s*)#if\s+os\((iOS|macOS)\)\n([^]*?)(?:^\1#else\n([^]*?))?^\1#endif\b\n?/gm,
+                              function (m, indentation, ifOs, ifCase, elseCase) {
+      return (os === ifOs ? ifCase : elseCase).replace(new RegExp('^    ', 'gm'), '');
+    }).replace(/\n$/, '');
+    
+    return '```swift\n' + example + '\n```';
+};
+
 fs.writeFileSync(`platform/ios/docs/guides/For Style Authors.md`, guideMD({
     os: 'iOS',
     renamedProperties: renamedPropertiesByLayerType,
diff --git a/platform/darwin/scripts/update-examples.js b/platform/darwin/scripts/update-examples.js
index 404cda102a..d453c0e4ba 100644
--- a/platform/darwin/scripts/update-examples.js
+++ b/platform/darwin/scripts/update-examples.js
@@ -103,7 +103,7 @@ function completeExamples(os) {
         let testMethodName = symbolPath.join('$').replace(/\$[+-]/, '$').replace(/:/g, '_');
         let example = examples[testMethodName];
         if (!example) {
-          console.error(`MGLDocumentationExampleTests.${testMethodName}() not found.`);
+          console.error(`MGLDocumentationExampleTests.test${testMethodName}() not found.`);
           process.exit(1);
         }
 
diff --git a/platform/darwin/test/MGLDocumentationGuideTests.swift b/platform/darwin/test/MGLDocumentationGuideTests.swift
new file mode 100644
index 0000000000..c71f1b46c7
--- /dev/null
+++ b/platform/darwin/test/MGLDocumentationGuideTests.swift
@@ -0,0 +1,214 @@
+import Foundation
+import Mapbox
+#if os(iOS)
+    import UIKit
+#else
+    import Cocoa
+#endif
+
+/**
+ Test cases that ensure the inline examples in the jazzy guides compile.
+
+ To add an example:
+ 1. Add a test case named in the form `testGuideName$ExampleName`.
+ 2. Wrap the code you’d like to appear in the documentation within the
+    following comment blocks:
+    ```
+    //#-example-code
+    ...
+    //#-end-example-code
+    ```
+ 3. Insert a call to `guideExample()`  where you’d like the example code to be
+    inserted in the guide’s Markdown.
+    ```
+    <%- guideExample('GuideName', 'ExampleName', 'iOS') %>
+    ```
+ 4. Run `make darwin-style-code` to extract example code from the test method
+    below and insert it into the guide.
+ */
+class MGLDocumentationGuideTests: XCTestCase, MGLMapViewDelegate {
+    var mapView: MGLMapView!
+    var styleLoadingExpectation: XCTestExpectation!
+    
+    override func setUp() {
+        super.setUp()
+        let styleURL = Bundle(for: MGLDocumentationGuideTests.self).url(forResource: "one-liner", withExtension: "json")
+        mapView = MGLMapView(frame: CGRect(x: 0, y: 0, width: 256, height: 256), styleURL: styleURL)
+        mapView.delegate = self
+        styleLoadingExpectation = expectation(description: "Map view should finish loading style")
+        waitForExpectations(timeout: 1, handler: nil)
+    }
+    
+    override func tearDown() {
+        mapView = nil
+        styleLoadingExpectation = nil
+        super.tearDown()
+    }
+    
+    func mapView(_ mapView: MGLMapView, didFinishLoading style: MGLStyle) {
+        styleLoadingExpectation.fulfill()
+    }
+    
+    func testUsingStyleFunctionsAtRuntime$Stops() {
+        //#-example-code
+        #if os(macOS)
+            let stops = [
+                0: MGLStyleValue<NSColor>(rawValue: .yellow),
+                2.5: MGLStyleValue(rawValue: .orange),
+                5: MGLStyleValue(rawValue: .red),
+                7.5: MGLStyleValue(rawValue: .blue),
+                10: MGLStyleValue(rawValue: .white),
+            ]
+        #else
+            let stops = [
+                0: MGLStyleValue<UIColor>(rawValue: .yellow),
+                2.5: MGLStyleValue(rawValue: .orange),
+                5: MGLStyleValue(rawValue: .red),
+                7.5: MGLStyleValue(rawValue: .blue),
+                10: MGLStyleValue(rawValue: .white),
+            ]
+        #endif
+        //#-end-example-code
+        
+        let _ = MGLStyleValue(interpolationMode: .exponential, cameraStops: stops, options: nil)
+    }
+    
+    func testUsingStyleFunctionsAtRuntime$Linear() {
+        //#-example-code
+        let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson")!
+        let symbolSource = MGLSource(identifier: "source")
+        let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource)
+        
+        let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil)
+        mapView.style?.addSource(source)
+        
+        #if os(macOS)
+            let stops = [
+                0: MGLStyleValue<NSColor>(rawValue: .yellow),
+                2.5: MGLStyleValue(rawValue: .orange),
+                5: MGLStyleValue(rawValue: .red),
+                7.5: MGLStyleValue(rawValue: .blue),
+                10: MGLStyleValue(rawValue: .white),
+            ]
+        #else
+            let stops = [
+                0: MGLStyleValue<UIColor>(rawValue: .yellow),
+                2.5: MGLStyleValue(rawValue: .orange),
+                5: MGLStyleValue(rawValue: .red),
+                7.5: MGLStyleValue(rawValue: .blue),
+                10: MGLStyleValue(rawValue: .white),
+            ]
+        #endif
+        
+        let layer = MGLCircleStyleLayer(identifier: "circles", source: source)
+        #if os(macOS)
+            layer.circleColor = MGLStyleValue(interpolationMode: .exponential,
+                                              sourceStops: stops,
+                                              attributeName: "mag",
+                                              options: [.defaultValue: MGLStyleValue<NSColor>(rawValue: .green)])
+        #else
+            layer.circleColor = MGLStyleValue(interpolationMode: .exponential,
+                                              sourceStops: stops,
+                                              attributeName: "mag",
+                                              options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)])
+        #endif
+        layer.circleRadius = MGLStyleValue(rawValue: 10)
+        mapView.style?.insertLayer(layer, below: symbolLayer)
+        //#-end-example-code
+    }
+    
+    func testUsingStyleFunctionsAtRuntime$Exponential() {
+        let source = MGLShapeSource(identifier: "circles", shape: nil, options: nil)
+        let layer = MGLCircleStyleLayer(identifier: "circles", source: source)
+        
+        //#-example-code
+        let stops = [
+            12: MGLStyleValue<NSNumber>(rawValue: 0.5),
+            14: MGLStyleValue(rawValue: 2),
+            18: MGLStyleValue(rawValue: 18),
+        ]
+        
+        layer.circleRadius = MGLStyleValue(interpolationMode: .exponential,
+                                           cameraStops: stops,
+                                           options: [.interpolationBase: 1.5])
+        //#-end-example-code
+    }
+    
+    func testUsingStyleFunctionsAtRuntime$Interval() {
+        let source = MGLShapeSource(identifier: "circles", shape: nil, options: nil)
+        let layer = MGLCircleStyleLayer(identifier: "circles", source: source)
+        
+        //#-example-code
+        #if os(macOS)
+            let stops = [
+                0: MGLStyleValue<NSColor>(rawValue: .yellow),
+                2.5: MGLStyleValue(rawValue: .orange),
+                5: MGLStyleValue(rawValue: .red),
+                7.5: MGLStyleValue(rawValue: .blue),
+                10: MGLStyleValue(rawValue: .white),
+            ]
+            
+            layer.circleColor = MGLStyleValue(interpolationMode: .interval,
+                                              sourceStops: stops,
+                                              attributeName: "mag",
+                                              options: [.defaultValue: MGLStyleValue<NSColor>(rawValue: .green)])
+        #else
+            let stops = [
+                0: MGLStyleValue<UIColor>(rawValue: .yellow),
+                2.5: MGLStyleValue(rawValue: .orange),
+                5: MGLStyleValue(rawValue: .red),
+                7.5: MGLStyleValue(rawValue: .blue),
+                10: MGLStyleValue(rawValue: .white),
+            ]
+            
+            layer.circleColor = MGLStyleValue(interpolationMode: .interval,
+                                              sourceStops: stops,
+                                              attributeName: "mag",
+                                              options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)])
+        #endif
+        //#-end-example-code
+    }
+    
+    func testUsingStyleFunctionsAtRuntime$Categorical() {
+        let source = MGLShapeSource(identifier: "circles", shape: nil, options: nil)
+        let layer = MGLCircleStyleLayer(identifier: "circles", source: source)
+        
+        //#-example-code
+        #if os(macOS)
+            let categoricalStops = [
+                "earthquake": MGLStyleValue<NSColor>(rawValue: .orange),
+                "explosion": MGLStyleValue(rawValue: .red),
+                "quarry blast": MGLStyleValue(rawValue: .yellow),
+            ]
+            
+            layer.circleColor = MGLStyleValue(interpolationMode: .categorical,
+                                              sourceStops: categoricalStops,
+                                              attributeName: "type",
+                                              options: [.defaultValue: MGLStyleValue<NSColor>(rawValue: .blue)])
+        #else
+            let categoricalStops = [
+                "earthquake": MGLStyleValue<UIColor>(rawValue: .orange),
+                "explosion": MGLStyleValue(rawValue: .red),
+                "quarry blast": MGLStyleValue(rawValue: .yellow),
+            ]
+            
+            layer.circleColor = MGLStyleValue(interpolationMode: .categorical,
+                                              sourceStops: categoricalStops,
+                                              attributeName: "type",
+                                              options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .blue)])
+        #endif
+        //#-end-example-code
+    }
+    
+    func testUsingStyleFunctionsAtRuntime$Identity() {
+        let source = MGLShapeSource(identifier: "circles", shape: nil, options: nil)
+        let layer = MGLCircleStyleLayer(identifier: "circles", source: source)
+        
+        //#-example-code
+        layer.circleRadius = MGLStyleValue(interpolationMode: .identity,
+                                           sourceStops: nil,
+                                           attributeName: "mag",
+                                           options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)])
+        //#-end-example-code
+    }
+}
diff --git a/platform/ios/docs/guides/Using Style Functions at Runtime.md b/platform/ios/docs/guides/Using Style Functions at Runtime.md
index c4f36ca51d..c1fcaa00e9 100644
--- a/platform/ios/docs/guides/Using Style Functions at Runtime.md	
+++ b/platform/ios/docs/guides/Using Style Functions at Runtime.md	
@@ -1,4 +1,3 @@
-
 <!--
   This file is generated.
   Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
@@ -31,11 +30,13 @@ The documentation for each individual style layer property notes which style fun
 Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key.
 
 ```swift
-let stops = [0: MGLStyleValue<UIColor>(rawValue: .yellow),
-             2.5: MGLStyleValue(rawValue: .orange),
-             5: MGLStyleValue(rawValue: .red),
-             7.5: MGLStyleValue(rawValue: .blue),
-             10: MGLStyleValue(rawValue: .white)]
+let stops = [
+    0: MGLStyleValue<UIColor>(rawValue: .yellow),
+    2.5: MGLStyleValue(rawValue: .orange),
+    5: MGLStyleValue(rawValue: .red),
+    7.5: MGLStyleValue(rawValue: .blue),
+    10: MGLStyleValue(rawValue: .white),
+]
 ```
 
 ## Interpolation mode
@@ -48,19 +49,21 @@ The effect a key has on the style value is determined by the interpolation mode.
 
 The stops dictionary below, for example, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value.
 
-``` swift
+```swift
 let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson")!
 let symbolSource = MGLSource(identifier: "source")
 let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource)
 
 let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil)
-style.addSource(source)
+mapView.style?.addSource(source)
 
-let stops = [0: MGLStyleValue<UIColor>(rawValue: .yellow),
-             2.5: MGLStyleValue(rawValue: .orange),
-             5: MGLStyleValue(rawValue: .red),
-             7.5: MGLStyleValue(rawValue: .blue),
-             10: MGLStyleValue(rawValue: .white)]
+let stops = [
+    0: MGLStyleValue<UIColor>(rawValue: .yellow),
+    2.5: MGLStyleValue(rawValue: .orange),
+    5: MGLStyleValue(rawValue: .red),
+    7.5: MGLStyleValue(rawValue: .blue),
+    10: MGLStyleValue(rawValue: .white),
+]
 
 let layer = MGLCircleStyleLayer(identifier: "circles", source: source)
 layer.circleColor = MGLStyleValue(interpolationMode: .exponential,
@@ -68,7 +71,7 @@ layer.circleColor = MGLStyleValue(interpolationMode: .exponential,
                                   attributeName: "mag",
                                   options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)])
 layer.circleRadius = MGLStyleValue(rawValue: 10)
-style.insertLayer(layer, below: symbolLayer)
+mapView.style?.insertLayer(layer, below: symbolLayer)
 ```
 
 ![exponential mode](img/data-driven-styling/exponential.png)
@@ -85,13 +88,15 @@ Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](wo
 The example below increases a layer’s `circleRadius` exponentially based on a map’s zoom level. The `MGLStyleFunctionOptionInterpolationBase` is `1.5`.
 
 ```swift
-let stops = [12: MGLStyleValue(rawValue: 0.5),
-             14: MGLStyleValue(rawValue: 2),
-             18: MGLStyleValue(rawValue: 18)]
+let stops = [
+    12: MGLStyleValue<NSNumber>(rawValue: 0.5),
+    14: MGLStyleValue(rawValue: 2),
+    18: MGLStyleValue(rawValue: 18),
+]
 
 layer.circleRadius = MGLStyleValue(interpolationMode: .exponential,
-                                  cameraStops: stops,
-                                  options: [.interpolationBase: 1.5])
+                                   cameraStops: stops,
+                                   options: [.interpolationBase: 1.5])
 ```
 
 ### Interval
@@ -100,12 +105,14 @@ layer.circleRadius = MGLStyleValue(interpolationMode: .exponential,
 
 When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on.
 
-``` swift
-let stops = [0: MGLStyleValue<UIColor>(rawValue: .yellow),
-             2.5: MGLStyleValue(rawValue: .orange),
-             5: MGLStyleValue(rawValue: .red),
-             7.5: MGLStyleValue(rawValue: .blue),
-             10: MGLStyleValue(rawValue: .white)]
+```swift
+let stops = [
+    0: MGLStyleValue<UIColor>(rawValue: .yellow),
+    2.5: MGLStyleValue(rawValue: .orange),
+    5: MGLStyleValue(rawValue: .red),
+    7.5: MGLStyleValue(rawValue: .blue),
+    10: MGLStyleValue(rawValue: .white),
+]
 
 layer.circleColor = MGLStyleValue(interpolationMode: .interval,
                                   sourceStops: stops,
@@ -121,16 +128,17 @@ At each stop, `MGLInterpolationModeCategorical` produces an output value equal t
 
 There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of blue to catch any events that do not fall into any of those categories.
 
-``` swift
-let categoricalStops = ["earthquake": MGLStyleValue<UIColor>(rawValue: .orange),
-                        "explosion": MGLStyleValue(rawValue: .red),
-                        "quarry blast": MGLStyleValue(rawValue: .yellow)]
+```swift
+let categoricalStops = [
+    "earthquake": MGLStyleValue<UIColor>(rawValue: .orange),
+    "explosion": MGLStyleValue(rawValue: .red),
+    "quarry blast": MGLStyleValue(rawValue: .yellow),
+]
 
 layer.circleColor = MGLStyleValue(interpolationMode: .categorical,
                                   sourceStops: categoricalStops,
                                   attributeName: "type",
                                   options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .blue)])
-
 ```
 
 ![categorical mode](img/data-driven-styling/categorical1.png) ![categorical mode](img/data-driven-styling/categorical2.png)
@@ -139,12 +147,11 @@ layer.circleColor = MGLStyleValue(interpolationMode: .categorical,
 
 `MGLInterpolationModeIdentity` uses the attribute’s value as the style value. For example, you can set the `circleRadius` to the earthquake’s magnitude. Since the attribute value itself will be used as the style value, `sourceStops` should be set to `nil`.
 
-``` swift
+```swift
 layer.circleRadius = MGLStyleValue(interpolationMode: .identity,
                                    sourceStops: nil,
                                    attributeName: "mag",
                                    options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)])
-
 ```
 
 ![identity mode](img/data-driven-styling/identity.png)
diff --git a/platform/ios/ios.xcodeproj/project.pbxproj b/platform/ios/ios.xcodeproj/project.pbxproj
index 6bf138c9e1..cd2549a9c9 100644
--- a/platform/ios/ios.xcodeproj/project.pbxproj
+++ b/platform/ios/ios.xcodeproj/project.pbxproj
@@ -216,6 +216,7 @@
 		DA1DC99B1CB6E064006E619F /* MBXViewController.m in Sources */ = {isa = PBXBuildFile; fileRef = DA1DC99A1CB6E064006E619F /* MBXViewController.m */; };
 		DA1DC99D1CB6E076006E619F /* Default-568h@2x.png in Resources */ = {isa = PBXBuildFile; fileRef = DA1DC99C1CB6E076006E619F /* Default-568h@2x.png */; };
 		DA1DC99F1CB6E088006E619F /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = DA1DC99E1CB6E088006E619F /* Assets.xcassets */; };
+		DA1F8F3D1EBD287B00367E42 /* MGLDocumentationGuideTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = DA1F8F3C1EBD287B00367E42 /* MGLDocumentationGuideTests.swift */; };
 		DA2207BF1DC0805F0002F84D /* MGLStyleValueTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = DA2207BE1DC0805F0002F84D /* MGLStyleValueTests.swift */; };
 		DA25D5C01CCD9F8400607828 /* Root.plist in Resources */ = {isa = PBXBuildFile; fileRef = DA25D5BF1CCD9F8400607828 /* Root.plist */; };
 		DA25D5C61CCDA06800607828 /* Root.strings in Resources */ = {isa = PBXBuildFile; fileRef = DA25D5C41CCDA06800607828 /* Root.strings */; };
@@ -707,6 +708,7 @@
 		DA1DC99A1CB6E064006E619F /* MBXViewController.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MBXViewController.m; sourceTree = "<group>"; };
 		DA1DC99C1CB6E076006E619F /* Default-568h@2x.png */ = {isa = PBXFileReference; lastKnownFileType = image.png; path = "Default-568h@2x.png"; sourceTree = "<group>"; };
 		DA1DC99E1CB6E088006E619F /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
+		DA1F8F3C1EBD287B00367E42 /* MGLDocumentationGuideTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; name = MGLDocumentationGuideTests.swift; path = ../../darwin/test/MGLDocumentationGuideTests.swift; sourceTree = "<group>"; };
 		DA2207BE1DC0805F0002F84D /* MGLStyleValueTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; name = MGLStyleValueTests.swift; path = ../../darwin/test/MGLStyleValueTests.swift; sourceTree = "<group>"; };
 		DA25D5B91CCD9EDE00607828 /* Settings.bundle */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = Settings.bundle; sourceTree = BUILT_PRODUCTS_DIR; };
 		DA25D5BF1CCD9F8400607828 /* Root.plist */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.plist.xml; path = Root.plist; sourceTree = "<group>"; };
@@ -927,7 +929,7 @@
 		DD9BE4F61EB263C50079A3AF /* UIViewController+MGLAdditions.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "UIViewController+MGLAdditions.m"; sourceTree = "<group>"; };
 		FA68F1481E9D656600F9F6C2 /* MGLFillExtrusionStyleLayer.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MGLFillExtrusionStyleLayer.h; sourceTree = "<group>"; };
 		FA68F1491E9D656600F9F6C2 /* MGLFillExtrusionStyleLayer.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = MGLFillExtrusionStyleLayer.mm; sourceTree = "<group>"; };
-	  FAE1CDC81E9D79C600C40B5B /* MGLFillExtrusionStyleLayerTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; name = MGLFillExtrusionStyleLayerTests.mm; path = ../../darwin/test/MGLFillExtrusionStyleLayerTests.mm; sourceTree = "<group>"; };
+		FAE1CDC81E9D79C600C40B5B /* MGLFillExtrusionStyleLayerTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; name = MGLFillExtrusionStyleLayerTests.mm; path = ../../darwin/test/MGLFillExtrusionStyleLayerTests.mm; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -1249,6 +1251,7 @@
 				DA35A2C41CCA9F8300E826B2 /* MGLCompassDirectionFormatterTests.m */,
 				DA35A2A91CCA058D00E826B2 /* MGLCoordinateFormatterTests.m */,
 				6407D66F1E0085FD00F6A9C3 /* MGLDocumentationExampleTests.swift */,
+				DA1F8F3C1EBD287B00367E42 /* MGLDocumentationGuideTests.swift */,
 				DD58A4C51D822BD000E1F038 /* MGLExpressionTests.mm */,
 				3598544C1E1D38AA00B29F84 /* MGLDistanceFormatterTests.m */,
 				DA0CD58F1CF56F6A00A5F5A5 /* MGLFeatureTests.mm */,
@@ -2153,6 +2156,7 @@
 				DA2E88611CC0382C00F24E7B /* MGLGeometryTests.mm in Sources */,
 				357579801D501E09000B822E /* MGLFillStyleLayerTests.mm in Sources */,
 				35D9DDE21DA25EEC00DAAD69 /* MGLCodingTests.m in Sources */,
+				DA1F8F3D1EBD287B00367E42 /* MGLDocumentationGuideTests.swift in Sources */,
 				3598544D1E1D38AA00B29F84 /* MGLDistanceFormatterTests.m in Sources */,
 				DA2DBBCE1D51E80400D38FF9 /* MGLStyleLayerTests.m in Sources */,
 				DA35A2C61CCA9F8300E826B2 /* MGLCompassDirectionFormatterTests.m in Sources */,
diff --git a/platform/macos/docs/guides/Using Style Functions at Runtime.md b/platform/macos/docs/guides/Using Style Functions at Runtime.md
index c03a35006a..ea772a93a2 100644
--- a/platform/macos/docs/guides/Using Style Functions at Runtime.md	
+++ b/platform/macos/docs/guides/Using Style Functions at Runtime.md	
@@ -1,4 +1,3 @@
-
 <!--
   This file is generated.
   Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
@@ -31,11 +30,13 @@ The documentation for each individual style layer property notes which style fun
 Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key.
 
 ```swift
-let stops = [0: MGLStyleValue<NSColor>(rawValue: .yellow),
-             2.5: MGLStyleValue(rawValue: .orange),
-             5: MGLStyleValue(rawValue: .red),
-             7.5: MGLStyleValue(rawValue: .blue),
-             10: MGLStyleValue(rawValue: .white)]
+let stops = [
+    0: MGLStyleValue<NSColor>(rawValue: .yellow),
+    2.5: MGLStyleValue(rawValue: .orange),
+    5: MGLStyleValue(rawValue: .red),
+    7.5: MGLStyleValue(rawValue: .blue),
+    10: MGLStyleValue(rawValue: .white),
+]
 ```
 
 ## Interpolation mode
@@ -48,19 +49,21 @@ The effect a key has on the style value is determined by the interpolation mode.
 
 The stops dictionary below, for example, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value.
 
-``` swift
+```swift
 let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson")!
 let symbolSource = MGLSource(identifier: "source")
 let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource)
 
 let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil)
-style.addSource(source)
+mapView.style?.addSource(source)
 
-let stops = [0: MGLStyleValue<NSColor>(rawValue: .yellow),
-             2.5: MGLStyleValue(rawValue: .orange),
-             5: MGLStyleValue(rawValue: .red),
-             7.5: MGLStyleValue(rawValue: .blue),
-             10: MGLStyleValue(rawValue: .white)]
+let stops = [
+    0: MGLStyleValue<NSColor>(rawValue: .yellow),
+    2.5: MGLStyleValue(rawValue: .orange),
+    5: MGLStyleValue(rawValue: .red),
+    7.5: MGLStyleValue(rawValue: .blue),
+    10: MGLStyleValue(rawValue: .white),
+]
 
 let layer = MGLCircleStyleLayer(identifier: "circles", source: source)
 layer.circleColor = MGLStyleValue(interpolationMode: .exponential,
@@ -68,7 +71,7 @@ layer.circleColor = MGLStyleValue(interpolationMode: .exponential,
                                   attributeName: "mag",
                                   options: [.defaultValue: MGLStyleValue<NSColor>(rawValue: .green)])
 layer.circleRadius = MGLStyleValue(rawValue: 10)
-style.insertLayer(layer, below: symbolLayer)
+mapView.style?.insertLayer(layer, below: symbolLayer)
 ```
 
 ![exponential mode](img/data-driven-styling/exponential.png)
@@ -85,13 +88,15 @@ Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](wo
 The example below increases a layer’s `circleRadius` exponentially based on a map’s zoom level. The `MGLStyleFunctionOptionInterpolationBase` is `1.5`.
 
 ```swift
-let stops = [12: MGLStyleValue(rawValue: 0.5),
-             14: MGLStyleValue(rawValue: 2),
-             18: MGLStyleValue(rawValue: 18)]
+let stops = [
+    12: MGLStyleValue<NSNumber>(rawValue: 0.5),
+    14: MGLStyleValue(rawValue: 2),
+    18: MGLStyleValue(rawValue: 18),
+]
 
 layer.circleRadius = MGLStyleValue(interpolationMode: .exponential,
-                                  cameraStops: stops,
-                                  options: [.interpolationBase: 1.5])
+                                   cameraStops: stops,
+                                   options: [.interpolationBase: 1.5])
 ```
 
 ### Interval
@@ -100,12 +105,14 @@ layer.circleRadius = MGLStyleValue(interpolationMode: .exponential,
 
 When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on.
 
-``` swift
-let stops = [0: MGLStyleValue<NSColor>(rawValue: .yellow),
-             2.5: MGLStyleValue(rawValue: .orange),
-             5: MGLStyleValue(rawValue: .red),
-             7.5: MGLStyleValue(rawValue: .blue),
-             10: MGLStyleValue(rawValue: .white)]
+```swift
+let stops = [
+    0: MGLStyleValue<NSColor>(rawValue: .yellow),
+    2.5: MGLStyleValue(rawValue: .orange),
+    5: MGLStyleValue(rawValue: .red),
+    7.5: MGLStyleValue(rawValue: .blue),
+    10: MGLStyleValue(rawValue: .white),
+]
 
 layer.circleColor = MGLStyleValue(interpolationMode: .interval,
                                   sourceStops: stops,
@@ -121,16 +128,17 @@ At each stop, `MGLInterpolationModeCategorical` produces an output value equal t
 
 There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of blue to catch any events that do not fall into any of those categories.
 
-``` swift
-let categoricalStops = ["earthquake": MGLStyleValue<NSColor>(rawValue: .orange),
-                        "explosion": MGLStyleValue(rawValue: .red),
-                        "quarry blast": MGLStyleValue(rawValue: .yellow)]
+```swift
+let categoricalStops = [
+    "earthquake": MGLStyleValue<NSColor>(rawValue: .orange),
+    "explosion": MGLStyleValue(rawValue: .red),
+    "quarry blast": MGLStyleValue(rawValue: .yellow),
+]
 
 layer.circleColor = MGLStyleValue(interpolationMode: .categorical,
                                   sourceStops: categoricalStops,
                                   attributeName: "type",
                                   options: [.defaultValue: MGLStyleValue<NSColor>(rawValue: .blue)])
-
 ```
 
 ![categorical mode](img/data-driven-styling/categorical1.png) ![categorical mode](img/data-driven-styling/categorical2.png)
@@ -139,12 +147,11 @@ layer.circleColor = MGLStyleValue(interpolationMode: .categorical,
 
 `MGLInterpolationModeIdentity` uses the attribute’s value as the style value. For example, you can set the `circleRadius` to the earthquake’s magnitude. Since the attribute value itself will be used as the style value, `sourceStops` should be set to `nil`.
 
-``` swift
+```swift
 layer.circleRadius = MGLStyleValue(interpolationMode: .identity,
                                    sourceStops: nil,
                                    attributeName: "mag",
                                    options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)])
-
 ```
 
 ![identity mode](img/data-driven-styling/identity.png)
diff --git a/platform/macos/macos.xcodeproj/project.pbxproj b/platform/macos/macos.xcodeproj/project.pbxproj
index 2e459a5088..9a18ce4a0e 100644
--- a/platform/macos/macos.xcodeproj/project.pbxproj
+++ b/platform/macos/macos.xcodeproj/project.pbxproj
@@ -96,6 +96,7 @@
 		DA551B831DB496AC0009AFAF /* MGLTileSource_Private.h in Headers */ = {isa = PBXBuildFile; fileRef = DA551B801DB496AC0009AFAF /* MGLTileSource_Private.h */; };
 		DA551B841DB496AC0009AFAF /* MGLTileSource.mm in Sources */ = {isa = PBXBuildFile; fileRef = DA551B811DB496AC0009AFAF /* MGLTileSource.mm */; };
 		DA5589771D320C41006B7F64 /* wms.json in Resources */ = {isa = PBXBuildFile; fileRef = DA5589761D320C41006B7F64 /* wms.json */; };
+		DA57D4B11EBC699800793288 /* MGLDocumentationGuideTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = DA57D4B01EBC699800793288 /* MGLDocumentationGuideTests.swift */; };
 		DA6408D71DA4E5DA00908C90 /* MGLVectorStyleLayer.h in Headers */ = {isa = PBXBuildFile; fileRef = DA6408D51DA4E5DA00908C90 /* MGLVectorStyleLayer.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		DA6408D81DA4E5DA00908C90 /* MGLVectorStyleLayer.m in Sources */ = {isa = PBXBuildFile; fileRef = DA6408D61DA4E5DA00908C90 /* MGLVectorStyleLayer.m */; };
 		DA7262071DEEDD460043BB89 /* MGLOpenGLStyleLayer.h in Headers */ = {isa = PBXBuildFile; fileRef = DA7262051DEEDD460043BB89 /* MGLOpenGLStyleLayer.h */; settings = {ATTRIBUTES = (Public, ); }; };
@@ -374,6 +375,7 @@
 		DA551B801DB496AC0009AFAF /* MGLTileSource_Private.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MGLTileSource_Private.h; sourceTree = "<group>"; };
 		DA551B811DB496AC0009AFAF /* MGLTileSource.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = MGLTileSource.mm; sourceTree = "<group>"; };
 		DA5589761D320C41006B7F64 /* wms.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; path = wms.json; sourceTree = "<group>"; };
+		DA57D4B01EBC699800793288 /* MGLDocumentationGuideTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; name = MGLDocumentationGuideTests.swift; path = ../../darwin/test/MGLDocumentationGuideTests.swift; sourceTree = "<group>"; };
 		DA6023EF1E4CE8E500DBFF23 /* sv */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = sv; path = sv.lproj/Foundation.strings; sourceTree = "<group>"; };
 		DA6023F01E4CE8FF00DBFF23 /* sv */ = {isa = PBXFileReference; lastKnownFileType = text.plist.stringsdict; name = sv; path = sv.lproj/Foundation.stringsdict; sourceTree = "<group>"; };
 		DA618B131E68850300CB7F44 /* ru */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = ru; path = ru.lproj/Localizable.strings; sourceTree = "<group>"; };
@@ -981,6 +983,7 @@
 				DA35A2B51CCA14D700E826B2 /* MGLCompassDirectionFormatterTests.m */,
 				DA35A2A71CC9F41600E826B2 /* MGLCoordinateFormatterTests.m */,
 				DA2987591E1A4290002299F5 /* MGLDocumentationExampleTests.swift */,
+				DA57D4B01EBC699800793288 /* MGLDocumentationGuideTests.swift */,
 				DD58A4C71D822C6200E1F038 /* MGLExpressionTests.mm */,
 				35C6DF861E214C1800ACA483 /* MGLDistanceFormatterTests.m */,
 				1F95931A1E6DE2B600D5B294 /* MGLNSDateAdditionsTests.mm */,
@@ -1470,6 +1473,7 @@
 				3526EABD1DF9B19800006B43 /* MGLCodingTests.m in Sources */,
 				DA87A9A21DC9DCF100810D09 /* MGLFillStyleLayerTests.mm in Sources */,
 				3599A3E81DF70E2000E77FB2 /* MGLStyleValueTests.m in Sources */,
+				DA57D4B11EBC699800793288 /* MGLDocumentationGuideTests.swift in Sources */,
 				DAEDC4321D6033F1000224FF /* MGLAttributionInfoTests.m in Sources */,
 				DA0CD58E1CF56F5800A5F5A5 /* MGLFeatureTests.mm in Sources */,
 				556660D61E1D07E400E2C41B /* MGLVersionNumber.m in Sources */,
-- 
cgit v1.2.1