[ios, macos] Update format expression documentation.upstream/fabian-format-expression-12739

8 files changed, 41 insertions, 7 deletions

diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
index 764ba2e018..cf0f79f419 100644
--- a/platform/darwin/docs/guides/For Style Authors.md.ejs
+++ b/platform/darwin/docs/guides/For Style Authors.md.ejs
@@ -403,7 +403,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `zoom`                 | `NSExpression.zoomLevelVariableExpression` | `$zoomLevel`
 `heatmap-density`      | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity`
 `line-progress`        | `NSExpression.lineProgressVariableExpression` | `$lineProgress`
-`format`               | `mgl_attributed:` | `mgl_attributed({x, y, z})`
+`format`               | `+[NSExpression mgl_expressionForAttributedExpressions:]` or `mgl_attributed:`  | `mgl_attributed({x, y, z})`
 
 For operators that have no corresponding `NSExpression` symbol, use the
 `MGL_FUNCTION()` format string syntax.
diff --git a/platform/darwin/docs/guides/Predicates and Expressions.md b/platform/darwin/docs/guides/Predicates and Expressions.md
index 27bf35f712..5f5d9a22a8 100644
--- a/platform/darwin/docs/guides/Predicates and Expressions.md
+++ b/platform/darwin/docs/guides/Predicates and Expressions.md
@@ -543,10 +543,11 @@ operator in the Mapbox Style Specification.
 <dd><code>mgl_attributed({x, y, z})</code></dd>
 </dl>
 
-Returns formatted text containing annotations for use in mixed-format `text-field`  entries.
+Concatenates and returns the array of `MGLAttributedExpression` objects, for use 
+with the `MGLSymbolStyleLayer.text` property.
 
 This function corresponds to the
-[`mgl_attributed`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-types-format)
+[`format`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-types-format)
 operator in the Mapbox Style Specification.
 
 ### `MGL_LET`
diff --git a/platform/darwin/src/MGLAttributedExpression.h b/platform/darwin/src/MGLAttributedExpression.h
index fa3f61aabd..aa5d51c66e 100644
--- a/platform/darwin/src/MGLAttributedExpression.h
+++ b/platform/darwin/src/MGLAttributedExpression.h
@@ -8,8 +8,8 @@ FOUNDATION_EXTERN MGL_EXPORT MGLAttributedExpressionKey const MGLFontNamesAttrib
 FOUNDATION_EXTERN MGL_EXPORT MGLAttributedExpressionKey const MGLFontSizeAttribute;
 
 /**
- An `NSExpression` that has associated text formatting attibutes (such as font size or
- font names).
+ An `MGLAttributedExpression` object associates text formatting attibutes (such as font size or
+ font names) to an `NSExpression`.
  */
 MGL_EXPORT
 @interface MGLAttributedExpression : NSObject
diff --git a/platform/darwin/src/NSExpression+MGLAdditions.h b/platform/darwin/src/NSExpression+MGLAdditions.h
index c7a5f5a969..a19ec1af2e 100644
--- a/platform/darwin/src/NSExpression+MGLAdditions.h
+++ b/platform/darwin/src/NSExpression+MGLAdditions.h
@@ -152,6 +152,14 @@ FOUNDATION_EXTERN MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionI
  */
 + (instancetype)mgl_expressionForMatchingExpression:(nonnull NSExpression *)inputExpression inDictionary:(nonnull NSDictionary<NSExpression *, NSExpression *> *)matchedExpressions defaultExpression:(nonnull NSExpression *)defaultExpression NS_SWIFT_NAME(init(forMGLMatchingKey:in:default:));
 
+/**
+ Returns an attributed function expression specifying an `MGLAttributedExpression` constant
+ expression array.
+ 
+ @param attributedExpressions The `MGLAttributedExpression` constant expression array.
+ */
++ (instancetype)mgl_expressionForAttributedExpressions:(nonnull NSArray<NSExpression *> *)attributedExpressions NS_SWIFT_NAME(init(forAttributedExpressions:));
+
 #pragma mark Concatenating String Expressions
 
 /**
diff --git a/platform/darwin/src/NSExpression+MGLAdditions.mm b/platform/darwin/src/NSExpression+MGLAdditions.mm
index ec8ea813fb..f72e263d25 100644
--- a/platform/darwin/src/NSExpression+MGLAdditions.mm
+++ b/platform/darwin/src/NSExpression+MGLAdditions.mm
@@ -598,6 +598,10 @@ const MGLExpressionInterpolationMode MGLExpressionInterpolationModeCubicBezier =
                                      arguments:optionsArray];
 }
 
++ (instancetype)mgl_expressionForAttributedExpressions:(nonnull NSArray<NSExpression *> *)attributedExpressions {
+    return [NSExpression expressionWithFormat:@"mgl_attributed(%@)", attributedExpressions];
+}
+
 - (instancetype)mgl_expressionByAppendingExpression:(nonnull NSExpression *)expression {
     NSExpression *subexpression = [NSExpression expressionForAggregate:@[self, expression]];
     return [NSExpression expressionForFunction:@"mgl_join:" arguments:@[subexpression]];
diff --git a/platform/darwin/test/MGLExpressionTests.mm b/platform/darwin/test/MGLExpressionTests.mm
index 278d61765a..c0a3b67428 100644
--- a/platform/darwin/test/MGLExpressionTests.mm
+++ b/platform/darwin/test/MGLExpressionTests.mm
@@ -1046,6 +1046,27 @@ using namespace std::string_literals;
         XCTAssertEqualObjects(expression.mgl_jsonExpressionObject, jsonExpression);
         XCTAssertEqualObjects([NSExpression expressionWithMGLJSONObject:jsonExpression], expression);
     }
+    {
+        MGLAttributedExpression *attribute1 = [MGLAttributedExpression attributedExpression:[NSExpression expressionForConstantValue:@"foo"]
+                                                                                  fontNames:nil
+                                                                                   fontSize:@(1.2)];
+        MGLAttributedExpression *attribute2 = [MGLAttributedExpression attributedExpression:[NSExpression expressionForConstantValue:@"biz"]
+                                                                                  fontNames:nil
+                                                                                   fontSize:@(1.0)];
+        MGLAttributedExpression *attribute3 = [MGLAttributedExpression attributedExpression:[NSExpression expressionForConstantValue:@"bar"]
+                                                                                  fontNames:nil
+                                                                                   fontSize:@(0.8)];
+        MGLAttributedExpression *attribute4 = [MGLAttributedExpression attributedExpression:[NSExpression expressionForConstantValue:@"\n"]
+                                                                                  fontNames:@[]
+                                                                                   fontSize:nil];
+        NSExpression *expression = [NSExpression mgl_expressionForAttributedExpressions:@[MGLConstantExpression(attribute1),
+                                                                                          MGLConstantExpression(attribute4),
+                                                                                          MGLConstantExpression(attribute2),
+                                                                                          MGLConstantExpression(attribute3)]];
+        NSArray *jsonExpression = @[@"format", @"foo", @{@"font-scale": @1.2}, @"\n", @{}, @"biz", @{@"font-scale": @1.0}, @"bar", @{@"font-scale": @0.8}];
+        XCTAssertEqualObjects(expression.mgl_jsonExpressionObject, jsonExpression);
+        XCTAssertEqualObjects([NSExpression expressionWithMGLJSONObject:jsonExpression], expression);
+    }
 }
 
 - (void)testGenericExpressionObject {
diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md
index 3c3738b647..73394ff6ed 100644
--- a/platform/ios/docs/guides/For Style Authors.md
+++ b/platform/ios/docs/guides/For Style Authors.md
@@ -390,7 +390,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `zoom`                 | `NSExpression.zoomLevelVariableExpression` | `$zoomLevel`
 `heatmap-density`      | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity`
 `line-progress`        | `NSExpression.lineProgressVariableExpression` | `$lineProgress`
-`format`               | `mgl_attributed:` | `mgl_attributed({x, y, z})`
+`format`               | `+[NSExpression mgl_expressionForAttributedExpressions:]` or `mgl_attributed:`  | `mgl_attributed({x, y, z})`
 
 For operators that have no corresponding `NSExpression` symbol, use the
 `MGL_FUNCTION()` format string syntax.
diff --git a/platform/macos/docs/guides/For Style Authors.md b/platform/macos/docs/guides/For Style Authors.md
index 6a167c7abf..038ddf1f93 100644
--- a/platform/macos/docs/guides/For Style Authors.md
+++ b/platform/macos/docs/guides/For Style Authors.md
@@ -383,7 +383,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `zoom`                 | `NSExpression.zoomLevelVariableExpression` | `$zoomLevel`
 `heatmap-density`      | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity`
 `line-progress`        | `NSExpression.lineProgressVariableExpression` | `$lineProgress`
-`format`               | `mgl_attributed:` | `mgl_attributed({x, y, z})`
+`format`               | `+[NSExpression mgl_expressionForAttributedExpressions:]` or `mgl_attributed:`  | `mgl_attributed({x, y, z})`
 
 For operators that have no corresponding `NSExpression` symbol, use the
 `MGL_FUNCTION()` format string syntax.