[ios, macos] Revamp predicate and expression guide (#11741)

* [ios, macos] Fact-checked expression guide

Corrected various factual inaccuracies in the “Predicates and Expressions” guide. Moved some explanation from the predicates section to the expressions section. Added sections for all the other expression types we support.

* [ios, macos] Reorganized custom function documentation

Reorganized the custom function documentation as a series of sections with headers and definition lists instead of a monolithic table. Copyedited various sections for accuracy. Linked references to custom functions. Added format string examples for all custom functions.

* [ios, macos] Made h3 more visible

* [ios, macos] Added Objective-C example of placeholders

* [ios, macos] Documented trig functions

* [ios, macos] Also increase h3 code size

* [ios, macos] Replaced Markdown with HTML in definition

* [ios, macos] Replaced Markdown with HTML in custom function documentation

* [ios, macos] Clarified stops

* [ios, macos] Cross-referenced functions

Each custom function definition cross-references the corresponding aftermarket function (or vice versa), the corresponding style specification expression operator, and any related NSExpression syntax.

* [ios, macos] Fixed links in predicate guide

* [ios, macos] Consolidated and documented NSExpression categories

Consolidated the NSExpression categories into a single category, with marks to separate different tasks. Documented the MGLAdditions category so that it shows up in the jazzy documentation.

* [ios, macos] Fixed NSExpression private category mixup

1 files changed, 20 insertions, 27 deletions

diff --git a/platform/darwin/src/NSExpression+MGLAdditions.mm b/platform/darwin/src/NSExpression+MGLAdditions.mm
index 46a463430b..df7e3e98f4 100644
--- a/platform/darwin/src/NSExpression+MGLAdditions.mm
+++ b/platform/darwin/src/NSExpression+MGLAdditions.mm
@@ -621,7 +621,24 @@ NS_DICTIONARY_OF(NSNumber *, NSExpression *) *MGLStopDictionaryByReplacingTokens
 }
 
 @end
-@implementation NSExpression (MGLVariableAdditions)
+
+@implementation NSExpression (MGLExpressionAdditions)
+
+- (NSExpression *)mgl_expressionWithContext:(NSDictionary<NSString *, NSExpression *> *)context {
+    [NSException raise:NSInternalInconsistencyException
+                format:@"Assignment expressions lack underlying Objective-C implementations."];
+    return self;
+}
+
+- (id)mgl_has:(id)element {
+    [NSException raise:NSInvalidArgumentException
+                format:@"Has expressions lack underlying Objective-C implementations."];
+    return nil;
+}
+
+@end
+
+@implementation NSExpression (MGLAdditions)
 
 + (NSExpression *)zoomLevelVariableExpression {
     return [NSExpression expressionForVariable:@"zoomLevel"];
@@ -643,10 +660,6 @@ NS_DICTIONARY_OF(NSNumber *, NSExpression *) *MGLStopDictionaryByReplacingTokens
     return [NSExpression expressionForVariable:@"featureProperties"];
 }
 
-@end
-
-@implementation NSExpression (MGLInitializerAdditions)
-
 + (instancetype)mgl_expressionForConditional:(nonnull NSPredicate *)conditionPredicate trueExpression:(nonnull NSExpression *)trueExpression falseExpresssion:(nonnull NSExpression *)falseExpression {
     if (@available(iOS 9.0, *)) {
         return [NSExpression expressionForConditional:conditionPredicate trueExpression:trueExpression falseExpression:falseExpression];
@@ -655,12 +668,12 @@ NS_DICTIONARY_OF(NSNumber *, NSExpression *) *MGLStopDictionaryByReplacingTokens
     }
 }
 
-+ (instancetype)mgl_expressionForSteppingExpression:(nonnull NSExpression*)steppingExpression fromExpression:(nonnull NSExpression *)minimumExpression stops:(nonnull NSExpression*)stops {
++ (instancetype)mgl_expressionForSteppingExpression:(nonnull NSExpression *)steppingExpression fromExpression:(nonnull NSExpression *)minimumExpression stops:(nonnull NSExpression *)stops {
     return [NSExpression expressionForFunction:@"mgl_step:from:stops:"
                                      arguments:@[steppingExpression, minimumExpression, stops]];
 }
 
-+ (instancetype)mgl_expressionForInterpolatingExpression:(nonnull NSExpression*)inputExpression withCurveType:(nonnull MGLExpressionInterpolationMode)curveType parameters:(nullable NSExpression *)parameters stops:(nonnull NSExpression*)stops {
++ (instancetype)mgl_expressionForInterpolatingExpression:(nonnull NSExpression *)inputExpression withCurveType:(nonnull MGLExpressionInterpolationMode)curveType parameters:(nullable NSExpression *)parameters stops:(nonnull NSExpression *)stops {
     NSExpression *sanitizeParams = parameters ? parameters : [NSExpression expressionForConstantValue:nil];
     return [NSExpression expressionForFunction:@"mgl_interpolate:withCurveType:parameters:stops:"
                                      arguments:@[inputExpression, [NSExpression expressionForConstantValue:curveType], sanitizeParams, stops]];
@@ -685,26 +698,6 @@ NS_DICTIONARY_OF(NSNumber *, NSExpression *) *MGLStopDictionaryByReplacingTokens
     return [NSExpression expressionForFunction:@"mgl_join:" arguments:@[subexpression]];
 }
 
-@end
-
-@implementation NSExpression (MGLExpressionAdditions)
-
-- (NSExpression *)mgl_expressionWithContext:(NSDictionary<NSString *, NSExpression *> *)context {
-    [NSException raise:NSInternalInconsistencyException
-                format:@"Assignment expressions lack underlying Objective-C implementations."];
-    return self;
-}
-
-- (id)mgl_has:(id)element {
-    [NSException raise:NSInvalidArgumentException
-                format:@"Has expressions lack underlying Objective-C implementations."];
-    return nil;
-}
-
-@end
-
-@implementation NSExpression (MGLAdditions)
-
 static NSDictionary<NSString *, NSString *> *MGLFunctionNamesByExpressionOperator;
 static NSDictionary<NSString *, NSString *> *MGLExpressionOperatorsByFunctionNames;