[ios, macos] Specify units

Replaced pixels with points in documentation.

6 files changed, 84 insertions, 14 deletions

diff --git a/platform/darwin/scripts/generate-style-code.js b/platform/darwin/scripts/generate-style-code.js
index c84332a7b3..a99a0182a9 100644
--- a/platform/darwin/scripts/generate-style-code.js
+++ b/platform/darwin/scripts/generate-style-code.js
@@ -98,7 +98,15 @@ global.propertyDoc = function (property, layerType) {
         }
         return '`' + symbol + '`';
     });
-    return doc;
+    if ('units' in property) {
+        if (!property.units.match(/s$/)) {
+            property.units += 's';
+        }
+        doc += `
+
+ This property is measured in ${property.units}.`;
+    }
+    return doc.replace(/(p)ixel/gi, '$1oint').replace(/(\d)px\b/g, '$1pt');
 };
 
 global.parseColor = function (str) {
@@ -140,14 +148,18 @@ global.propertyDefault = function (property, layerType) {
             }
             return 'an `NSColor` or `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 (property.default.reduce((a, b) => a + b, 0) === 0) {
                 //    return '`NSEdgeInsetsZero` or `UIEdgeInsetsZero`';
                 //}
-                return `${property.default[0]} on the top, ${property.default[1]} on the right, ${property.default[2]} on the bottom, and ${property.default[3]} on the left`;
+                return `${property.default[0]}${units} on the top, ${property.default[1]}${units} on the right, ${property.default[2]}${units} on the bottom, and ${property.default[3]}${units} on the left`;
             }
             if (property.name.indexOf('offset') !== -1 || property.name.indexOf('translate') !== -1) {
-                return `${property.default[0]} from the left and ${property.default[1]} from the top`;
+                return `${property.default[0]}${units} from the left and ${property.default[1]}${units} from the top`;
             }
             return '`' + property.default.join('`, `') + '`';
         default:
diff --git a/platform/darwin/src/MGLCircleStyleLayer.h b/platform/darwin/src/MGLCircleStyleLayer.h
index 132d8e223e..a7391c43dc 100644
--- a/platform/darwin/src/MGLCircleStyleLayer.h
+++ b/platform/darwin/src/MGLCircleStyleLayer.h
@@ -23,6 +23,8 @@ typedef NS_ENUM(NSUInteger, MGLCircleStyleLayerCirclePitchScale) {
 /**
  Circle radius.
 
+ This property is measured in points.
+
  The default value of this property is `5`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> circleRadius;
@@ -51,7 +53,9 @@ typedef NS_ENUM(NSUInteger, MGLCircleStyleLayerCirclePitchScale) {
 /**
  The geometry's offset. Values are [x, y] where negatives indicate left and up, respectively.
 
- The default value of this property is 0 from the left and 0 from the top. Set this property to `nil` to reset it to the default.
+ This property is measured in points.
+
+ The default value of this property is 0 points from the left and 0 points from the top. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> circleTranslate;
 
diff --git a/platform/darwin/src/MGLFillStyleLayer.h b/platform/darwin/src/MGLFillStyleLayer.h
index 8b64a1c1bc..f5030a9dc6 100644
--- a/platform/darwin/src/MGLFillStyleLayer.h
+++ b/platform/darwin/src/MGLFillStyleLayer.h
@@ -23,14 +23,14 @@ typedef NS_ENUM(NSUInteger, MGLFillStyleLayerFillTranslateAnchor) {
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> fillAntialias;
 
 /**
- The opacity of the entire fill layer. In contrast to the fill-color, this value will also affect the 1px stroke around the fill, if the stroke is used.
+ The opacity of the entire fill layer. In contrast to the fill-color, this value will also affect the 1pt stroke around the fill, if the stroke is used.
 
  The default value of this property is `1`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> fillOpacity;
 
 /**
- The color of the filled part of this layer. This color can be specified as rgba with an alpha component and the color's opacity will not affect the opacity of the 1px stroke, if it is used.
+ The color of the filled part of this layer. This color can be specified as rgba with an alpha component and the color's opacity will not affect the opacity of the 1pt stroke, if it is used.
 
  The default value of this property is an `NSColor` or `UIColor`object whose RGB value is 0, 0, 0 and whose alpha value is 1. Set this property to `nil` to reset it to the default.
  */
@@ -44,7 +44,9 @@ typedef NS_ENUM(NSUInteger, MGLFillStyleLayerFillTranslateAnchor) {
 /**
  The geometry's offset. Values are [x, y] where negatives indicate left and up, respectively.
 
- The default value of this property is 0 from the left and 0 from the top. Set this property to `nil` to reset it to the default.
+ This property is measured in points.
+
+ The default value of this property is 0 points from the left and 0 points from the top. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> fillTranslate;
 
diff --git a/platform/darwin/src/MGLLineStyleLayer.h b/platform/darwin/src/MGLLineStyleLayer.h
index dcc8f8e8fe..226df74760 100644
--- a/platform/darwin/src/MGLLineStyleLayer.h
+++ b/platform/darwin/src/MGLLineStyleLayer.h
@@ -74,7 +74,9 @@ typedef NS_ENUM(NSUInteger, MGLLineStyleLayerLineTranslateAnchor) {
 /**
  The geometry's offset. Values are [x, y] where negatives indicate left and up, respectively.
 
- The default value of this property is 0 from the left and 0 from the top. Set this property to `nil` to reset it to the default.
+ This property is measured in points.
+
+ The default value of this property is 0 points from the left and 0 points from the top. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> lineTranslate;
 
@@ -88,6 +90,8 @@ typedef NS_ENUM(NSUInteger, MGLLineStyleLayerLineTranslateAnchor) {
 /**
  Stroke thickness.
 
+ This property is measured in points.
+
  The default value of this property is `1`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> lineWidth;
@@ -95,6 +99,8 @@ typedef NS_ENUM(NSUInteger, MGLLineStyleLayerLineTranslateAnchor) {
 /**
  Draws a line casing outside of a line's actual path. Value indicates the width of the inner gap.
 
+ This property is measured in points.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> lineGapWidth;
@@ -102,19 +108,25 @@ typedef NS_ENUM(NSUInteger, MGLLineStyleLayerLineTranslateAnchor) {
 /**
  The line's offset perpendicular to its direction. Values may be positive or negative, where positive indicates "rightwards" (if you were moving in the direction of the line) and negative indicates "leftwards."
 
+ This property is measured in points.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> lineOffset;
 
 /**
- Blur applied to the line, in pixels.
+ Blur applied to the line, in points.
+
+ This property is measured in points.
 
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> lineBlur;
 
 /**
- Specifies the lengths of the alternating dashes and gaps that form the dash pattern. The lengths are later scaled by the line width. To convert a dash length to pixels, multiply the length by the current line width.
+ Specifies the lengths of the alternating dashes and gaps that form the dash pattern. The lengths are later scaled by the line width. To convert a dash length to points, multiply the length by the current line width.
+
+ This property is measured in line widths.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> lineDasharray;
 
diff --git a/platform/darwin/src/MGLRasterStyleLayer.h b/platform/darwin/src/MGLRasterStyleLayer.h
index 7304130384..082bd37b10 100644
--- a/platform/darwin/src/MGLRasterStyleLayer.h
+++ b/platform/darwin/src/MGLRasterStyleLayer.h
@@ -20,6 +20,8 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Rotates hues around the color wheel.
 
+ This property is measured in degrees.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> rasterHueRotate;
@@ -55,6 +57,8 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Fade duration when a new tile is added.
 
+ This property is measured in milliseconds.
+
  The default value of this property is `300`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> rasterFadeDuration;
diff --git a/platform/darwin/src/MGLSymbolStyleLayer.h b/platform/darwin/src/MGLSymbolStyleLayer.h
index 3956e05f3a..d92ad55967 100644
--- a/platform/darwin/src/MGLSymbolStyleLayer.h
+++ b/platform/darwin/src/MGLSymbolStyleLayer.h
@@ -81,6 +81,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Distance between two symbol anchors.
 
+ This property is measured in points.
+
  The default value of this property is `250`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> symbolSpacing;
@@ -137,7 +139,9 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Size of padding area around the text-fit size in clockwise order: top, right, bottom, left.
 
- The default value of this property is 0 on the top, 0 on the right, 0 on the bottom, and 0 on the left. Set this property to `nil` to reset it to the default.
+ This property is measured in points.
+
+ The default value of this property is 0 points on the top, 0 points on the right, 0 points on the bottom, and 0 points on the left. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> iconTextFitPadding;
 
@@ -149,6 +153,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Rotates the icon clockwise.
 
+ This property is measured in degrees.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> iconRotate;
@@ -156,6 +162,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Size of the additional area around the icon bounding box used for detecting symbol collisions.
 
+ This property is measured in points.
+
  The default value of this property is `2`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> iconPadding;
@@ -203,6 +211,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Font size.
 
+ This property is measured in points.
+
  The default value of this property is `16`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textSize;
@@ -210,6 +220,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  The maximum line width for text wrapping.
 
+ This property is measured in ems.
+
  The default value of this property is `10`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textMaxWidth;
@@ -217,6 +229,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Text leading value for multi-line text.
 
+ This property is measured in ems.
+
  The default value of this property is `1.2`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textLineHeight;
@@ -224,6 +238,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Text tracking amount.
 
+ This property is measured in ems.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textLetterSpacing;
@@ -245,6 +261,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Maximum angle change between adjacent characters.
 
+ This property is measured in degrees.
+
  The default value of this property is `45`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textMaxAngle;
@@ -252,6 +270,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Rotates the text clockwise.
 
+ This property is measured in degrees.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textRotate;
@@ -259,6 +279,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Size of the additional area around the text bounding box used for detecting symbol collisions.
 
+ This property is measured in points.
+
  The default value of this property is `2`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textPadding;
@@ -280,7 +302,9 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Offset distance of text from its anchor. Positive values indicate right and down, while negative values indicate left and up.
 
- The default value of this property is 0 from the left and 0 from the top. Set this property to `nil` to reset it to the default.
+ This property is measured in ems.
+
+ The default value of this property is 0 ems from the left and 0 ems from the top. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textOffset;
 
@@ -331,6 +355,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Distance of halo to the icon outline.
 
+ This property is measured in points.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> iconHaloWidth;
@@ -338,6 +364,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Fade out the halo towards the outside.
 
+ This property is measured in points.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> iconHaloBlur;
@@ -345,7 +373,9 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Distance that the icon's anchor is moved from its original placement. Positive values indicate right and down, while negative values indicate left and up.
 
- The default value of this property is 0 from the left and 0 from the top. Set this property to `nil` to reset it to the default.
+ This property is measured in points.
+
+ The default value of this property is 0 points from the left and 0 points from the top. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> iconTranslate;
 
@@ -380,6 +410,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Distance of halo to the font outline. Max text halo width is 1/4 of the font-size.
 
+ This property is measured in points.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textHaloWidth;
@@ -387,6 +419,8 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  The halo's fadeout distance towards the outside.
 
+ This property is measured in points.
+
  The default value of this property is `0`. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textHaloBlur;
@@ -394,7 +428,9 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
 /**
  Distance that the text's anchor is moved from its original placement. Positive values indicate right and down, while negative values indicate left and up.
 
- The default value of this property is 0 from the left and 0 from the top. Set this property to `nil` to reset it to the default.
+ This property is measured in points.
+
+ The default value of this property is 0 points from the left and 0 points from the top. Set this property to `nil` to reset it to the default.
  */
 @property (nonatomic, null_resettable) id <MGLStyleAttributeValue> textTranslate;