Merge branch 'release-ios-v3.4.0' into 1ec5-release-ios-v3.4.0-beta.7

4 files changed, 449 insertions, 83 deletions

diff --git a/platform/darwin/scripts/generate-style-code.js b/platform/darwin/scripts/generate-style-code.js
index 6606c956f2..3998246580 100644
--- a/platform/darwin/scripts/generate-style-code.js
+++ b/platform/darwin/scripts/generate-style-code.js
@@ -55,17 +55,38 @@ _.forOwn(cocoaConventions, function (properties, kind) {
     })
 });
 
+String.prototype.wrap = function (cols, indent) {
+	let wrapRe = new RegExp(`(.{1,${cols - indent}})(?: +|\n|$)`, "gm");
+	return this.replace(wrapRe, "$1\n").replace(/\s+$/, "").indent(indent);
+};
+
+String.prototype.indent = function (cols) {
+	return this.replace(/^|\n/g, "$&" + " ".repeat(cols));
+};
+
+global.camelize = function (str) {
+    return str.replace(/(?:^|-)(.)/g, function (_, x) {
+        return x.toUpperCase();
+    });
+};
+
+global.camelizeWithLeadingLowercase = function (str) {
+    return str.replace(/-(.)/g, function (_, x) {
+        return x.toUpperCase();
+    });
+};
+
 global.objCName = function (property) {
     return camelizeWithLeadingLowercase(property.name);
-}
+};
 
 global.objCGetter = function (property) {
     return camelizeWithLeadingLowercase(property.getter || property.name);
-}
+};
 
 global.objCType = function (layerType, propertyName) {
     return `${prefix}${camelize(propertyName)}`;
-}
+};
 
 global.arrayType = function (property) {
     return property.type === 'array' ? originalPropertyName(property).split('-').pop() : false;
@@ -74,7 +95,87 @@ global.arrayType = function (property) {
 global.testImplementation = function (property, layerType, isFunction) {
     let helperMsg = testHelperMessage(property, layerType, isFunction);
     return `layer.${objCName(property)} = [MGLRuntimeStylingHelper ${helperMsg}];`;
-}
+};
+
+global.objCTestValue = function (property, layerType, indent) {
+    let propertyName = originalPropertyName(property);
+    switch (property.type) {
+        case 'boolean':
+            return property.default ? '@NO' : '@YES';
+        case 'number':
+            return '@0xff';
+        case 'string':
+            return `@"${_.startCase(propertyName)}"`;
+        case 'enum':
+            let type = objCType(layerType, property.name);
+            let value = `${type}${camelize(_.last(_.keys(property.values)))}`;
+            return `[NSValue valueWith${type}:${value}]`;
+        case 'color':
+            return '[MGLColor redColor]';
+        case 'array':
+            switch (arrayType(property)) {
+                case 'dasharray':
+                    return '@[@1, @2]';
+                case 'font':
+                    return `@[@"${_.startCase(propertyName)}", @"${_.startCase(_.reverse(propertyName.split('')).join(''))}"]`;
+                case 'padding': {
+                    let iosValue = '[NSValue valueWithUIEdgeInsets:UIEdgeInsetsMake(1, 1, 1, 1)]'.indent(indent * 4);
+                    let macosValue = '[NSValue valueWithEdgeInsets:NSEdgeInsetsMake(1, 1, 1, 1)]'.indent(indent * 4);
+                    return `\n#if TARGET_OS_IPHONE\n${iosValue}\n#else\n${macosValue}\n#endif\n${''.indent((indent - 1) * 4)}`;
+                }
+                case 'offset':
+                case 'translate':
+                    let iosValue = '[NSValue valueWithCGVector:CGVectorMake(1, 1)]'.indent(indent * 4);
+                    let macosValue = '[NSValue valueWithMGLVector:CGVectorMake(1, -1)]'.indent(indent * 4);
+                    return `\n#if TARGET_OS_IPHONE\n${iosValue}\n#else\n${macosValue}\n#endif\n${''.indent((indent - 1) * 4)}`;
+                default:
+                    throw new Error(`unknown array type for ${property.name}`);
+            }
+        default:
+            throw new Error(`unknown type for ${property.name}`);
+    }
+};
+
+global.mbglTestValue = function (property, layerType) {
+    let propertyName = originalPropertyName(property);
+    switch (property.type) {
+        case 'boolean':
+            return property.default ? 'false' : 'true';
+        case 'number':
+            return '0xff';
+        case 'string':
+            return `"${_.startCase(propertyName)}"`;
+        case 'enum': {
+            let type = camelize(originalPropertyName(property));
+            if (/-translate-anchor$/.test(originalPropertyName(property))) {
+                type = 'TranslateAnchor';
+            }
+            if (/-(rotation|pitch)-alignment$/.test(originalPropertyName(property))) {
+                type = 'Alignment';
+            }
+            let value = camelize(_.last(_.keys(property.values)));
+            return `mbgl::style::${type}Type::${value}`;
+        }
+        case 'color':
+            return '{ 1, 0, 0, 1 }';
+        case 'array':
+            switch (arrayType(property)) {
+                case 'dasharray':
+                    return '{1, 2}';
+                case 'font':
+                    return `{ "${_.startCase(propertyName)}", "${_.startCase(_.reverse(propertyName.split('')).join(''))}" }`;
+                case 'padding':
+                    return '{ 1, 1, 1, 1 }';
+                case 'offset':
+                case 'translate':
+                    return '{ 1, 1 }';
+                default:
+                    throw new Error(`unknown array type for ${property.name}`);
+            }
+        default:
+            throw new Error(`unknown type for ${property.name}`);
+    }
+};
 
 global.testGetterImplementation = function (property, layerType, isFunction) {
     let helperMsg = testHelperMessage(property, layerType, isFunction);
@@ -87,7 +188,7 @@ global.testGetterImplementation = function (property, layerType, isFunction) {
     XCTAssertEqualObjects(gLayer.${objCName(property)}, ${value});`;
     }
     return `XCTAssertEqualObjects(gLayer.${objCName(property)}, ${value});`;
-}
+};
 
 global.testHelperMessage = function (property, layerType, isFunction) {
     let fnSuffix = isFunction ? 'Function' : '';
@@ -123,7 +224,7 @@ global.testHelperMessage = function (property, layerType, isFunction) {
     }
 };
 
-global.propertyDoc = function (propertyName, property, layerType) {
+global.propertyDoc = function (propertyName, property, layerType, kind) {
     // Match references to other property names & values. 
     // Requires the format 'When `foo` is set to `bar`,'.
     let doc = property.doc.replace(/`([^`]+?)` is set to `([^`]+?)`/g, function (m, peerPropertyName, propertyValue, offset, str) {
@@ -141,7 +242,7 @@ global.propertyDoc = function (propertyName, property, layerType) {
     // Requires symbols to be surrounded by backticks.
     doc = doc.replace(/`(.+?)`/g, function (m, symbol, offset, str) {
         if ('values' in property && Object.keys(property.values).indexOf(symbol) !== -1) {
-            let objCType = objCType(layerType, property.name);
+            let objCType = global.objCType(layerType, property.name);
             return '`' + `${objCType}${camelize(symbol)}` + '`';
         }
         if (str.substr(offset - 4, 3) !== 'CSS') {
@@ -154,11 +255,33 @@ global.propertyDoc = function (propertyName, property, layerType) {
         if (!property.units.match(/s$/)) {
             property.units += 's';
         }
-        doc += `
-
- This property is measured in ${property.units}.`;
+        doc += `\n\nThis property is measured in ${property.units}.`;
+    }
+    doc = doc.replace(/(p)ixel/gi, '$1oint').replace(/(\d)px\b/g, '$1pt');
+    if (kind !== 'enum') {
+        if ('default' in property) {
+            doc += `\n\nThe default value of this property is ${propertyDefault(property, layerType)}.`;
+            if (!property.required) {
+                doc += ' Set this property to `nil` to reset it to the default value.';
+            }
+        }
+        if ('requires' in property) {
+            doc += '\n\n' + propertyReqs(property, spec[`${kind}_${layerType}`], layerType);
+        }
+        if ('original' in property) {
+            let anchor;
+            switch (kind) {
+                case 'layout':
+                    anchor = `layout-${layerType}-${property.original}`;
+                    break;
+                case 'paint':
+                    anchor = `paint-${property.original}`;
+                    break;
+            }
+            doc += `\n\nThis attribute corresponds to the <a href="https://www.mapbox.com/mapbox-gl-style-spec/#${anchor}"><code>${property.original}</code></a> layout property in the Mapbox Style Specification.`;
+        }
     }
-    return doc.replace(/(p)ixel/gi, '$1oint').replace(/(\d)px\b/g, '$1pt');
+    return doc;
 };
 
 global.propertyReqs = function (property, propertiesByName, type) {
@@ -217,30 +340,32 @@ global.describeValue = function (value, property, layerType) {
                 throw new Error(`unrecognized color format in default value of ${property.name}`);
             }
             if (color.r === 0 && color.g === 0 && color.b === 0 && color.a === 0) {
-                return '`MGLColor.clearColor`';
+                return '`UIColor.clearColor`';
             }
             if (color.r === 0 && color.g === 0 && color.b === 0 && color.a === 1) {
-                return '`MGLColor.blackColor`';
+                return '`UIColor.blackColor`';
             }
             if (color.r === 1 && color.g === 1 && color.b === 1 && color.a === 1) {
-                return '`MGLColor.whiteColor`';
+                return '`UIColor.whiteColor`';
             }
-            return 'an `MGLColor`' + ` object whose RGB value is ${color.r}, ${color.g}, ${color.b} and whose alpha value is ${color.a}`;
+            return 'a `UIColor`' + ` object whose RGB value is ${color.r}, ${color.g}, ${color.b} and whose alpha value is ${color.a}`;
         case 'array':
             let units = property.units || '';
             if (units) {
                 units = ` ${units}`.replace(/pixel/, 'point');
             }
-            if (property.name.indexOf('padding') !== -1) {
-                if (value[0] === 0 && value[1] === 0 && value[2] === 0 && value[3] === 0) {
-                    return 'an `NSValue` object containing `NSEdgeInsetsZero` or `UIEdgeInsetsZero`';
-                }
-                return 'an `NSValue` object containing an `NSEdgeInsets` or `UIEdgeInsets` struct set to' + ` ${value[0]}${units} on the top, ${value[3]}${units} on the left, ${value[2]}${units} on the bottom, and ${value[1]}${units} on the right`;
-            }
-            if (property.name.indexOf('offset') !== -1 || property.name.indexOf('translate') !== -1) {
-                return 'an `NSValue` object containing a `CGVector` struct set to' + ` ${value[0]}${units} from the left and ${value[1]}${units} from the top`;
+            switch (arrayType(property)) {
+                case 'padding':
+                    if (value[0] === 0 && value[1] === 0 && value[2] === 0 && value[3] === 0) {
+                        return 'an `NSValue` object containing `UIEdgeInsetsZero`';
+                    }
+                    return 'an `NSValue` object containing a `UIEdgeInsets` struct set to' + ` ${value[0]}${units} on the top, ${value[3]}${units} on the left, ${value[2]}${units} on the bottom, and ${value[1]}${units} on the right`;
+                case 'offset':
+                case 'translate':
+                    return 'an `NSValue` object containing a `CGVector` struct set to' + ` ${value[0]}${units} rightward and ${value[1]}${units} downward`;
+                default:
+                    return 'the array `' + value.join('`, `') + '`';
             }
-            return 'the array `' + value.join('`, `') + '`';
         default:
             throw new Error(`unknown type for ${property.name}`);
     }
@@ -252,7 +377,7 @@ global.propertyDefault = function (property, layerType) {
 
 global.originalPropertyName = function (property) {
     return property.original || property.name;
-}
+};
 
 global.propertyType = function (property) {
     switch (property.type) {
@@ -317,100 +442,144 @@ global.valueTransformerArguments = function (property) {
     }
 };
 
+global.mbglType = function(property) {
+    switch (property.type) {
+        case 'boolean':
+            return 'bool';
+        case 'number':
+            return 'float';
+        case 'string':
+            return 'std::string';
+        case 'enum': {
+            let type = camelize(originalPropertyName(property));
+            if (/-translate-anchor$/.test(originalPropertyName(property))) {
+                type = 'TranslateAnchor';
+            }
+            if (/-(rotation|pitch)-alignment$/.test(originalPropertyName(property))) {
+                type = 'Alignment';
+            }
+            return `mbgl::style::${type}Type`;
+        }
+        case 'color':
+            return 'mbgl::Color';
+        case 'array':
+            switch (arrayType(property)) {
+                case 'dasharray':
+                    return 'std::vector<float>';
+                case 'font':
+                    return 'std::vector<std::string>';
+                case 'padding':
+                    return 'std::array<float, 4>';
+                case 'offset':
+                case 'translate':
+                    return 'std::array<float, 2>';
+                default:
+                    throw new Error(`unknown array type for ${property.name}`);
+            }
+        default:
+            throw new Error(`unknown type for ${property.name}`);
+    }
+};
+
 global.initLayer = function (layerType) {
     if (layerType == "background") {
        return `_layer = new mbgl::style::${camelize(layerType)}Layer(identifier.UTF8String);`
     } else {
         return `_layer = new mbgl::style::${camelize(layerType)}Layer(identifier.UTF8String, source.identifier.UTF8String);`
     }
-}
+};
 
 global.setSourceLayer = function() {
-   return `_layer->setSourceLayer(sourceLayer.UTF8String);`
-}
-
-global.mbglType = function(property) {
-    let mbglType = camelize(originalPropertyName(property)) + 'Type';
-    if (/-translate-anchor$/.test(originalPropertyName(property))) {
-        mbglType = 'TranslateAnchorType';
-    }
-    if (/-(rotation|pitch)-alignment$/.test(originalPropertyName(property))) {
-        mbglType = 'AlignmentType';
-    }
-    return mbglType;
-}
+    return `_layer->setSourceLayer(sourceLayer.UTF8String);`
+};
 
 const layerH = ejs.compile(fs.readFileSync('platform/darwin/src/MGLStyleLayer.h.ejs', 'utf8'), { strict: true });
 const layerM = ejs.compile(fs.readFileSync('platform/darwin/src/MGLStyleLayer.mm.ejs', 'utf8'), { strict: true});
-const testLayers = ejs.compile(fs.readFileSync('platform/darwin/test/MGLStyleLayerTests.m.ejs', 'utf8'), { strict: true});
-const categoryH = ejs.compile(fs.readFileSync('platform/darwin/src/NSValue+MGLStyleEnumAttributeAdditions.h.ejs', 'utf8'), { strict: true});
-const categoryM = ejs.compile(fs.readFileSync('platform/darwin/src/NSValue+MGLStyleEnumAttributeAdditions.mm.ejs', 'utf8'), { strict: true});
+const testLayers = ejs.compile(fs.readFileSync('platform/darwin/test/MGLStyleLayerTests.mm.ejs', 'utf8'), { strict: true});
+const guideMD = ejs.compile(fs.readFileSync('platform/darwin/docs/guides/For Style Authors.md.ejs', 'utf8'), { strict: true });
 
-const layers = Object.keys(spec.layer.type.values).map((type) => {
-    const layoutProperties = Object.keys(spec[`layout_${type}`]).reduce((memo, name) => {
+const layers = _(spec.layer.type.values).map((value, layerType) => {
+    const layoutProperties = Object.keys(spec[`layout_${layerType}`]).reduce((memo, name) => {
         if (name !== 'visibility') {
-            spec[`layout_${type}`][name].name = name;
-            memo.push(spec[`layout_${type}`][name]);
+            spec[`layout_${layerType}`][name].name = name;
+            memo.push(spec[`layout_${layerType}`][name]);
         }
         return memo;
     }, []);
 
-    const paintProperties = Object.keys(spec[`paint_${type}`]).reduce((memo, name) => {
-        spec[`paint_${type}`][name].name = name;
-        memo.push(spec[`paint_${type}`][name]);
+    const paintProperties = Object.keys(spec[`paint_${layerType}`]).reduce((memo, name) => {
+        spec[`paint_${layerType}`][name].name = name;
+        memo.push(spec[`paint_${layerType}`][name]);
         return memo;
     }, []);
 
     return {
-        type: type,
+        doc: spec.layer.type.values[layerType].doc,
+        type: layerType,
         layoutProperties: _.sortBy(layoutProperties, ['name']),
         paintProperties: _.sortBy(paintProperties, ['name']),
-        layoutPropertiesByName: spec[`layout_${type}`],
-        paintPropertiesByName: spec[`paint_${type}`],
     };
-});
+}).sortBy(['type']).value();
 
 function duplicatePlatformDecls(src) {
-    // Look for a documentation comment that contains “MGLColor” and the
-    // subsequent function, method, or property declaration. Try not to match
-    // greedily.
-    return src.replace(/(\/\*\*(?:\*[^\/]|[^*])*?\bMGLColor\b[\s\S]*?\*\/)(\s*.+?;)/g,
+    // Look for a documentation comment that contains “MGLColor” or “UIColor”
+    // and the subsequent function, method, or property declaration. Try not to
+    // match greedily.
+    return src.replace(/(\/\*\*(?:\*[^\/]|[^*])*?\*\/)(\s*[^;]+?\b(?:MGL|NS|UI)(?:Color|EdgeInsets(?:Zero)?)\b[^;]+?;)/g,
                        (match, comment, decl) => {
-        let iosComment = comment.replace(/\bMGLColor\b/g, 'UIColor')
+        let macosComment = comment.replace(/\b(?:MGL|UI)(Color|EdgeInsets(?:Zero)?)\b/g, 'NS$1')
             // Use the correct indefinite article.
-            .replace(/\b(a)n(\s+`?UIColor)\b/gi, '$1$2');
-        let macosComment = comment.replace(/\bMGLColor\b/g, 'NSColor');
+            .replace(/\ba(\s+`?NS(?:Color|EdgeInsets))\b/gi, 'an$1');
+        let iosDecl = decl.replace(/\bMGL(Color|EdgeInsets)\b/g, 'UI$1');
+        let macosDecl = decl.replace(/\b(?:MGL|UI)(Color|EdgeInsets)\b/g, 'NS$1');
         return `\
 #if TARGET_OS_IPHONE
-${iosComment}${decl}
+${comment}${iosDecl}
+#else
+${macosComment}${macosDecl}
+#endif`;
+    })
+        // Do the same for CGVector-typed properties.
+        .replace(/(\/\*\*(?:\*[^\/]|[^*])*?\b(?:CGVector|UIEdgeInsets(?:Zero)?)\b[\s\S]*?\*\/)(\s*.+?;)/g,
+                       (match, comment, decl) => {
+        let macosComment = comment.replace(/\bdownward\b/g, 'upward')
+            .replace(/\bUI(EdgeInsets(?:Zero)?)\b/g, 'NS$1');
+        return `\
+#if TARGET_OS_IPHONE
+${comment}${decl}
 #else
 ${macosComment}${decl}
 #endif`;
     });
 }
 
-var allLayoutProperties = [];
-var allPaintProperties = [];
-var allTypes = [];
+var renamedPropertiesByLayerType = {};
 
 for (var layer of layers) {
-    allLayoutProperties.push(layer.layoutProperties);
-    allPaintProperties.push(layer.paintProperties);
-    allTypes.push(layer.type);
-    const containsEnumerationProperties =  _.filter(layer.layoutProperties, function(property){ return property["type"] === "enum"; }).length  || _.filter(layer.paintProperties, function(property){ return property["type"] === "enum"; }).length;
-    layer.containsEnumerationProperties = containsEnumerationProperties;
+    layer.properties = _.concat(layer.layoutProperties, layer.paintProperties);
+    let enumProperties = _.filter(layer.properties, prop => prop.type === 'enum');
+    if (enumProperties.length) {
+        layer.enumProperties = enumProperties;
+    }
+    
+    let renamedProperties = {};
+    _.assign(renamedProperties, _.filter(layer.properties, prop => 'original' in prop || 'getter' in prop));
+    if (!_.isEmpty(renamedProperties)) {
+        renamedPropertiesByLayerType[layer.type] = renamedProperties;
+    }
     
-    writeIfModified(`platform/darwin/src/${prefix}${camelize(layer.type)}${suffix}.h`, duplicatePlatformDecls(layerH(layer)));
-    writeIfModified(`platform/darwin/src/${prefix}${camelize(layer.type)}${suffix}.mm`, layerM(layer));
-    writeIfModified(`platform/darwin/test/${prefix}${camelize(layer.type)}${suffix}Tests.m`, testLayers(layer));
+    fs.writeFileSync(`platform/darwin/src/${prefix}${camelize(layer.type)}${suffix}.h`, duplicatePlatformDecls(layerH(layer)));
+    fs.writeFileSync(`platform/darwin/src/${prefix}${camelize(layer.type)}${suffix}.mm`, layerM(layer));
+    fs.writeFileSync(`platform/darwin/test/${prefix}${camelize(layer.type)}${suffix}Tests.mm`, testLayers(layer));
 }
 
-fs.writeFileSync(`platform/darwin/src/NSValue+MGLStyleEnumAttributeAdditions.h`, categoryH({
-    layoutProperties: _.flatten(allLayoutProperties),
-    paintProperties: _.flatten(allPaintProperties),
-    types: allTypes
+fs.writeFileSync(`platform/ios/docs/guides/For Style Authors.md`, guideMD({
+    os: 'iOS',
+    renamedProperties: renamedPropertiesByLayerType,
+    layers: layers,
 }));
-fs.writeFileSync(`platform/darwin/src/NSValue+MGLStyleEnumAttributeAdditions.mm`, categoryM({
-    layoutProperties: _.flatten(allLayoutProperties),
-    paintProperties: _.flatten(allPaintProperties)
+fs.writeFileSync(`platform/macos/docs/guides/For Style Authors.md`, guideMD({
+    os: 'macOS',
+    renamedProperties: renamedPropertiesByLayerType,
+    layers: layers,
 }));
diff --git a/platform/darwin/scripts/style-spec-cocoa-conventions-v8.json b/platform/darwin/scripts/style-spec-cocoa-conventions-v8.json
index 49cf515e3e..9d80ff3896 100644
--- a/platform/darwin/scripts/style-spec-cocoa-conventions-v8.json
+++ b/platform/darwin/scripts/style-spec-cocoa-conventions-v8.json
@@ -9,13 +9,26 @@
     "icon-size": "icon-scale",
     "symbol-avoid-edges": "symbol-avoids-edges",
     "text-allow-overlap": "text-allows-overlap",
+    "text-field": "text",
+    "text-font": "text-font-names",
     "text-ignore-placement": "text-ignores-placement",
     "text-justify": "text-justification",
     "text-keep-upright": "keeps-text-upright",
     "text-max-angle": "maximum-text-angle",
     "text-max-width": "maximum-text-width",
     "text-optional": "is-text-optional",
-    "text-rotate": "text-rotation"
+    "text-rotate": "text-rotation",
+    "text-size": "text-font-size"
+  },
+  "paint_circle": {
+    "circle-pitch-scale": "circle-scale-alignment",
+    "circle-translate": "circle-translation",
+    "circle-translate-anchor": "circle-translation-anchor"
+  },
+  "paint_fill": {
+    "fill-antialias": "is-fill-antialiased",
+    "fill-translate": "fill-translation",
+    "fill-translate-anchor": "fill-translation-anchor"
   },
   "paint_raster": {
     "raster-brightness-min": "minimum-raster-brightness",
@@ -23,9 +36,14 @@
     "raster-hue-rotate": "raster-hue-rotation"
   },
   "paint_line": {
-    "line-dasharray": "line-dash-pattern"
+    "line-dasharray": "line-dash-pattern",
+    "line-translate": "line-translation",
+    "line-translate-anchor": "line-translation-anchor"
   },
-  "paint_fill": {
-    "fill-antialias": "is-fill-antialiased"
+  "paint_symbol": {
+    "icon-translate": "icon-translation",
+    "icon-translate-anchor": "icon-translation-anchor",
+    "text-translate": "text-translation",
+    "text-translate-anchor": "text-translation-anchor"
   }
 }
\ No newline at end of file
diff --git a/platform/darwin/scripts/style-spec-overrides-v8.json b/platform/darwin/scripts/style-spec-overrides-v8.json
index cfda85b7fb..28740d458b 100644
--- a/platform/darwin/scripts/style-spec-overrides-v8.json
+++ b/platform/darwin/scripts/style-spec-overrides-v8.json
@@ -1,4 +1,28 @@
 {
+  "layer": {
+    "type": {
+      "values": {
+        "fill": {
+          "doc": "An `MGLFillStyleLayer` is a style layer that renders one or more filled (and optionally stroked) polygons on the map.\n\nUse a fill style layer to configure the visual appearance of polygon or multipolygon features in vector tiles loaded by an `MGLVectorSource` object or `MGLPolygon`, `MGLPolygonFeature`, `MGLMultiPolygon`, or `MGLMultiPolygonFeature` instances in an `MGLShapeSource` object."
+        },
+        "line": {
+          "doc": "An `MGLLineStyleLayer` is a style layer that renders one or more stroked polylines on the map.\n\nUse a line style layer to configure the visual appearance of polyline or multipolyline features in vector tiles loaded by an `MGLVectorSource` object or `MGLPolyline`, `MGLPolylineFeature`, `MGLMultiPolyline`, or `MGLMultiPolylineFeature` instances in an `MGLShapeSource` object."
+        },
+        "symbol": {
+          "doc": "An `MGLSymbolStyleLayer` is a style layer that renders icon and text labels at points or along lines on the map.\n\nUse a symbol style layer to configure the visual appearance of labels for features in vector tiles loaded by an `MGLVectorSource` object or `MGLShape` or `MGLFeature` instances in an `MGLShapeSource` object."
+        },
+        "circle": {
+          "doc": "An `MGLCircleStyleLayer` is a style layer that renders one or more filled circles on the map.\n\nUse a circle style layer to configure the visual appearance of point or point collection features in vector tiles loaded by an `MGLVectorSource` object or `MGLPointAnnotation`, `MGLPointFeature`, `MGLPointCollection`, or `MGLPointCollectionFeature` instances in an `MGLShapeSource` object.\n\nA circle style layer renders circles whose radii are measured in screen units. To display circles on the map whose radii correspond to real-world distances, use many-sided regular polygons and configure their appearance using an `MGLFillStyleLayer` object."
+        },
+        "raster": {
+          "doc": "An `MGLRasterStyleLayer` is a style layer that renders raster tiles on the map.\n\nUse a raster style layer to configure the color parameters of raster tiles loaded by an `MGLRasterSource` object. For example, you could use a raster style layer to render <a href=\"https://www.mapbox.com/satellite/\">Mapbox Satellite</a> imagery, a <a href=\"https://www.mapbox.com/help/define-tileset/#raster-tilesets\">raster tile set</a> uploaded to Mapbox Studio, or a raster map authored in <a href=\"https://tilemill-project.github.io/tilemill/\">TileMill</a>, the classic Mapbox Editor, or Mapbox Studio Classic."
+        },
+        "background": {
+          "doc": "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.\n\nA 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.\n\nIf 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."
+        }
+      }
+    }
+  },
   "layout_symbol": {
     "icon-text-fit-padding": {
       "doc": "Size of the additional area added to dimensions determined by `icon-text-fit`."
@@ -6,6 +30,9 @@
     "icon-offset": {
       "doc": "Offset distance of icon from its anchor."
     },
+    "text-font": {
+      "doc": "An array of font face names used to display the text.\n\nEach font name must be included in the `{fontstack}` portion of the JSON stylesheet’s <a href=\"https://www.mapbox.com/mapbox-gl-style-spec/#glyphs\"><code>glyphs</code></a> property. You can register a custom font when designing the style in Mapbox Studio. Fonts installed on the system are not used.\n\nThe first font named in the array is applied to the text. For each character in the text, if the first font lacks a glyph for the character, the next font is applied as a fallback, and so on."
+    },
     "text-offset": {
       "doc": "Offset distance of text from its anchor."
     },
diff --git a/platform/darwin/scripts/update-examples.js b/platform/darwin/scripts/update-examples.js
new file mode 100644
index 0000000000..6291326068
--- /dev/null
+++ b/platform/darwin/scripts/update-examples.js
@@ -0,0 +1,152 @@
+'use strict';
+
+const fs = require('fs');
+const execFileSync = require('child_process').execFileSync;
+const _ = require('lodash');
+
+const examplesSrc = fs.readFileSync('platform/darwin/test/MGLDocumentationExampleTests.swift', 'utf8');
+
+// Regex extracts the following block
+// /** Front matter to describe the example. **/
+// func testMGLClass$member() {
+//     ...
+//     //#-example-code
+//     let sampleCode: String?
+//     //#-end-example-code
+//     ...
+// }
+//
+// into the following regex groups:
+// 1 (test method name): "MGLClass" or "MGLClass$member" or "MGLClass$initWithArg_anotherArg_"
+// 2 (indentation): "    "
+// 3 (sample code): "let sampleCode: String?"
+const exampleRegex = /func test([\w$]+)\s*\(\)\s*\{[^]*?\n([ \t]+)\/\/#-example-code\n([^]+?)\n\2\/\/#-end-example-code\n/gm;
+
+/**
+ * Returns the given source with example code inserted into the documentation
+ * comment for the symbol at the given one-based line.
+ *
+ * @param {String} src Source code to insert the example code into.
+ * @param {Number} line One-based line number of the symbol being documented.
+ * @param {String} exampleCode Example code to insert.
+ * @returns {String} `src` with `exampleCode` inserted just above `line`.
+ */
+function completeSymbolInSource(src, line, exampleCode) {
+  // Split the file contents right before the symbol declaration (but after its documentation comment).
+  let srcUpToSymbol = src.split('\n', line - 1).join('\n');
+  let srcFromSymbol = src.substr(srcUpToSymbol.length);
+  
+  // Match the documentation comment block that is not followed by the beginning or end of a declaration.
+  let commentMatch = srcUpToSymbol.match(/\/\*\*\s*(?:[^*]|\*(?!\/))+?\s*\*\/[^;{}]*?$/);
+  
+  // Replace the Swift code block with the test method’s contents.
+  let completedComment = commentMatch[0].replace(/^([ \t]*)```swift\n[^]*?```/m, function (m, indentation) {
+    // Apply the original indentation to each line.
+    return ('```swift\n' + exampleCode + '\n```').replace(/^/gm, indentation);
+  });
+  
+  // Splice the modified comment into the overall file contents.
+  srcUpToSymbol = (srcUpToSymbol.substr(0, commentMatch.index) + completedComment +
+                   srcUpToSymbol.substr(commentMatch.index + commentMatch[0].length));
+  return srcUpToSymbol + srcFromSymbol;
+}
+
+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;
+}
+
+function completeExamples(os) {
+  console.log(`Installing ${os} SDK examples…`);
+  
+  let sdk = os === 'iOS' ? 'iphonesimulator' : 'macosx';
+  let sysroot = execFileSync('xcrun', ['--show-sdk-path', '--sdk', sdk]).toString().trim();
+  let umbrellaPath = `platform/${os.toLowerCase()}/src/Mapbox.h`;
+  let docArgs = ['doc', '--objc', umbrellaPath, '--',
+                 '-x', 'objective-c', '-I', 'platform/darwin/src/', '-isysroot', sysroot];
+  let docStr = execFileSync('sourcekitten', docArgs).toString().trim();
+  let docJson = JSON.parse(docStr);
+  _.forEach(docJson, function (result) {
+    _.forEach(result, function (structure, path) {
+      let src;
+      let newSrc;
+      // Recursively search for code blocks in documentation comments and populate
+      // them with example code from the test methods. Find and replace the code
+      // blocks in reverse to keep the SourceKitten line numbers accurate.
+      _.forEachRight(structure['key.substructure'], function completeSubstructure(substructure, idx, substructures, symbolPath) {
+        if (!symbolPath) {
+          symbolPath = [substructure['key.name']];
+        }
+        _.forEachRight(substructure['key.substructure'], function (substructure, idx, substructures) {
+          completeSubstructure(substructure, idx, substructures, _.concat(symbolPath, substructure['key.name']));
+        });
+        
+        let comment = substructure['key.doc.comment'];
+        if (!comment || !comment.match(/^(?:\s*)```swift\n/m)) {
+          return;
+        }
+        
+        // Lazily read in the existing file.
+        if (!src) {
+          newSrc = src = fs.readFileSync(path, 'utf8');
+        }
+        
+        // Get the contents of the test method whose name matches the symbol path.
+        let testMethodName = symbolPath.join('$').replace(/\$[+-]/, '$').replace(/:/g, '_');
+        let example = examples[testMethodName];
+        if (!example) {
+          console.error(`MGLDocumentationExampleTests.${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\n/gm,
+                                  function (m, indentation, ifOs, ifCase, elseCase) {
+          return (os === ifOs ? ifCase : elseCase).replace(new RegExp('^    ', 'gm'), '');
+        });
+        
+        // Insert the test method contents into the documentation comment just
+        // above the substructure.
+        let startLine = substructure['key.parsed_scope.start'];
+        newSrc = completeSymbolInSource(newSrc, startLine, example);
+      });
+      
+      if (!src) {
+        return;
+      }
+      
+      // Write out the modified file contents.
+      if (src === newSrc) {
+        console.log('Skipping', path);
+      } else {
+        console.log('Updating', path);
+        if (['0', 'false'].indexOf(process.env.DRY_RUN || '0') !== -1) {
+          fs.writeFileSync(path, newSrc);
+        }
+      }
+    });
+  });
+}
+
+function ensureSourceKittenIsInstalled() {
+  try {
+    execFileSync('which', ['sourcekitten']);
+  } catch (e) {
+    console.log(`Installing SourceKitten via Homebrew…`);
+    execFileSync('brew', ['install', 'sourcekitten']);
+  }
+}
+
+ensureSourceKittenIsInstalled();
+
+// Where a particular comment is part of both SDKs, prefer the iOS example.
+completeExamples('macOS');
+completeExamples('iOS');