[ios, macos] outlined style spec documentation overrides

platform/darwin/scripts/generate-style-code.js

@@ -2,7 +2,7 @@
 
 const fs = require('fs');
 const ejs = require('ejs');
-const spec = require('mapbox-gl-style-spec').latest;
+const spec = override(require('mapbox-gl-style-spec').latest, require('./style-spec-overrides-v8.json'));
 
 const prefix = 'MGL';
 const suffix = 'StyleLayer';
@@ -97,6 +97,16 @@ global.testArrayImplementation = function (property) {
     }
 };
 
+global.enumDoc = function (property, value) {
+    if ('docs' in property) {
+        return `    /**
+     ${property.docs[property.values.indexOf(value)]}
+     */`;
+    } else {
+        return "#warning documentation missing.";
+    }
+}
+
 global.propertyDoc = function (property, layerType) {
     let doc = property.doc.replace(/`(.+?)`/g, function (m, symbol, offset, str) {
         if ('values' in property && property.values.indexOf(symbol) !== -1) {
@@ -295,6 +305,21 @@ global.convertedType = function(property) {
     }
 }
 
+global.isObjectNotArray = function(object) {
+    return (typeof object === 'object' && !Array.isArray(object));
+}
+
+global.override = function(base, override) {
+    Object.keys(override).forEach(function(key) {
+    if (isObjectNotArray(base[key]) && isObjectNotArray(override[key])) {
+      override(base[key], override[key]);
+    } else {
+      base[key] = override[key];
+    }
+  });
+  return base;
+}
+
 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/src/MGLRuntimeStylingTests.m.ejs', 'utf8'), { strict: true});

platform/darwin/scripts/style-spec-overrides-v8.json

@@ -0,0 +1,13 @@
+{
+  "layout_symbol": {
+    "text-transform": {
+      "doc": "Specifies how to capitalize text."
+    },
+    "symbol-placement": {
+      "docs": [
+        "Documentation for values[0]",
+        "Documentation for values[1]"
+      ]
+    }
+  }
+}

platform/darwin/src/MGLCircleStyleLayer.h

@@ -6,13 +6,19 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/** Control whether the translation is relative to the map (north) or viewport (screen) */
 typedef NS_ENUM(NSUInteger, MGLCircleStyleLayerCircleTranslateAnchor) {
+#warning documentation missing.
     MGLCircleStyleLayerCircleTranslateAnchorMap,
+#warning documentation missing.
     MGLCircleStyleLayerCircleTranslateAnchorViewport,
 };
 
+/** Controls the scaling behavior of the circle when the map is pitched. The value `map` scales circles according to their apparent distance to the camera. The value `viewport` results in no pitch-related scaling. */
 typedef NS_ENUM(NSUInteger, MGLCircleStyleLayerCirclePitchScale) {
+#warning documentation missing.
     MGLCircleStyleLayerCirclePitchScaleMap,
+#warning documentation missing.
     MGLCircleStyleLayerCirclePitchScaleViewport,
 };
 

platform/darwin/src/MGLFillStyleLayer.h

@@ -6,8 +6,11 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/** Control whether the translation is relative to the map (north) or viewport (screen) */
 typedef NS_ENUM(NSUInteger, MGLFillStyleLayerFillTranslateAnchor) {
+#warning documentation missing.
     MGLFillStyleLayerFillTranslateAnchorMap,
+#warning documentation missing.
     MGLFillStyleLayerFillTranslateAnchorViewport,
 };
 

platform/darwin/src/MGLLineStyleLayer.h

@@ -6,20 +6,31 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/** The display of line endings. */
 typedef NS_ENUM(NSUInteger, MGLLineStyleLayerLineCap) {
+#warning documentation missing.
     MGLLineStyleLayerLineCapButt,
+#warning documentation missing.
     MGLLineStyleLayerLineCapRound,
+#warning documentation missing.
     MGLLineStyleLayerLineCapSquare,
 };
 
+/** The display of lines when joining. */
 typedef NS_ENUM(NSUInteger, MGLLineStyleLayerLineJoin) {
+#warning documentation missing.
     MGLLineStyleLayerLineJoinBevel,
+#warning documentation missing.
     MGLLineStyleLayerLineJoinRound,
+#warning documentation missing.
     MGLLineStyleLayerLineJoinMiter,
 };
 
+/** Control whether the translation is relative to the map (north) or viewport (screen) */
 typedef NS_ENUM(NSUInteger, MGLLineStyleLayerLineTranslateAnchor) {
+#warning documentation missing.
     MGLLineStyleLayerLineTranslateAnchorMap,
+#warning documentation missing.
     MGLLineStyleLayerLineTranslateAnchorViewport,
 };
 

platform/darwin/src/MGLStyleLayer.h.ejs

@@ -15,8 +15,10 @@ NS_ASSUME_NONNULL_BEGIN
 
 <% for (const property of layoutProperties) { -%>
 <% if (property.type == "enum") { -%>
+/** <%- property.doc %> */
 typedef NS_ENUM(NSUInteger, MGL<%- camelize(type) %>StyleLayer<%- camelize(property.name) %>) {
 <% for (const value of property.values) { -%>
+<%- enumDoc(property, value) %>
     MGL<%- camelize(type) %>StyleLayer<%- camelize(property.name) %><%- camelize(value) %>,
 <% } -%>
 };
@@ -25,8 +27,10 @@ typedef NS_ENUM(NSUInteger, MGL<%- camelize(type) %>StyleLayer<%- camelize(prope
 <% } -%>
 <% for (const property of paintProperties) { -%>
 <% if (property.type == "enum") { -%>
+/** <%- property.doc %> */
 typedef NS_ENUM(NSUInteger, MGL<%- camelize(type) %>StyleLayer<%- camelize(property.name) %>) {
 <% for (const value of property.values) { -%>
+<%- enumDoc(property, value) %>
     MGL<%- camelize(type) %>StyleLayer<%- camelize(property.name) %><%- camelize(value) %>,
 <% } -%>
 };

platform/darwin/src/MGLSymbolStyleLayer.h

@@ -6,64 +6,109 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/** Label placement relative to its geometry. `line` can only be used on LineStrings and Polygons. */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerSymbolPlacement) {
+    /**
+     Documentation for values[0]
+     */
     MGLSymbolStyleLayerSymbolPlacementPoint,
+    /**
+     Documentation for values[1]
+     */
     MGLSymbolStyleLayerSymbolPlacementLine,
 };
 
+/** Orientation of icon when map is rotated. */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerIconRotationAlignment) {
+#warning documentation missing.
     MGLSymbolStyleLayerIconRotationAlignmentMap,
+#warning documentation missing.
     MGLSymbolStyleLayerIconRotationAlignmentViewport,
 };
 
+/** Position and scale an icon by the its corresponding text. */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerIconTextFit) {
+#warning documentation missing.
     MGLSymbolStyleLayerIconTextFitNone,
+#warning documentation missing.
     MGLSymbolStyleLayerIconTextFitBoth,
+#warning documentation missing.
     MGLSymbolStyleLayerIconTextFitWidth,
+#warning documentation missing.
     MGLSymbolStyleLayerIconTextFitHeight,
 };
 
+/** Aligns text to the plane of the `viewport` or the `map` when the map is pitched. Matches `text-rotation-alignment` if unspecified. */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextPitchAlignment) {
+#warning documentation missing.
     MGLSymbolStyleLayerTextPitchAlignmentMap,
+#warning documentation missing.
     MGLSymbolStyleLayerTextPitchAlignmentViewport,
 };
 
+/** Orientation of text when map is rotated. */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextRotationAlignment) {
+#warning documentation missing.
     MGLSymbolStyleLayerTextRotationAlignmentMap,
+#warning documentation missing.
     MGLSymbolStyleLayerTextRotationAlignmentViewport,
 };
 
+/** Text justification options. */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextJustify) {
+#warning documentation missing.
     MGLSymbolStyleLayerTextJustifyLeft,
+#warning documentation missing.
     MGLSymbolStyleLayerTextJustifyCenter,
+#warning documentation missing.
     MGLSymbolStyleLayerTextJustifyRight,
 };
 
+/** Part of the text placed closest to the anchor. */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextAnchor) {
+#warning documentation missing.
     MGLSymbolStyleLayerTextAnchorCenter,
+#warning documentation missing.
     MGLSymbolStyleLayerTextAnchorLeft,
+#warning documentation missing.
     MGLSymbolStyleLayerTextAnchorRight,
+#warning documentation missing.
     MGLSymbolStyleLayerTextAnchorTop,
+#warning documentation missing.
     MGLSymbolStyleLayerTextAnchorBottom,
+#warning documentation missing.
     MGLSymbolStyleLayerTextAnchorTopLeft,
+#warning documentation missing.
     MGLSymbolStyleLayerTextAnchorTopRight,
+#warning documentation missing.
     MGLSymbolStyleLayerTextAnchorBottomLeft,
+#warning documentation missing.
     MGLSymbolStyleLayerTextAnchorBottomRight,
 };
 
+/** Specifies how to capitalize text. */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTransform) {
+#warning documentation missing.
     MGLSymbolStyleLayerTextTransformNone,
+#warning documentation missing.
     MGLSymbolStyleLayerTextTransformUppercase,
+#warning documentation missing.
     MGLSymbolStyleLayerTextTransformLowercase,
 };
 
+/** Control whether the translation is relative to the map (north) or viewport (screen). */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerIconTranslateAnchor) {
+#warning documentation missing.
     MGLSymbolStyleLayerIconTranslateAnchorMap,
+#warning documentation missing.
     MGLSymbolStyleLayerIconTranslateAnchorViewport,
 };
 
+/** Control whether the translation is relative to the map (north) or viewport (screen). */
 typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
+#warning documentation missing.
     MGLSymbolStyleLayerTextTranslateAnchorMap,
+#warning documentation missing.
     MGLSymbolStyleLayerTextTranslateAnchorViewport,
 };
 
@@ -343,7 +388,7 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 @property (nonatomic, nullable) id <MGLStyleAttributeValue> textKeepUpright;
 
 /**
- Specifies how to capitalize text, similar to the CSS `text-transform` property.
+ Specifies how to capitalize text.
  
  If this property is set to `nil`, the layer uses an implicit default value of `MGLSymbolStyleLayerTextTransformNone`.