[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, 25 insertions, 15 deletions

diff --git a/platform/darwin/src/NSExpression+MGLAdditions.h b/platform/darwin/src/NSExpression+MGLAdditions.h
index 39a841543d..64cbe97418 100644
--- a/platform/darwin/src/NSExpression+MGLAdditions.h
+++ b/platform/darwin/src/NSExpression+MGLAdditions.h
@@ -16,7 +16,7 @@ typedef NSString *MGLExpressionInterpolationMode NS_TYPED_ENUM;
  
  This attribute corresponds to the `linear` value in the
  <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-interpolate"><code>interpolate</code></a>
- expression reference in the Mapbox Style Specification.
+ expression operator in the Mapbox Style Specification.
  */
 extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolationModeLinear;
 
@@ -25,7 +25,7 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
  
  This attribute corresponds to the `exponential` value in the
  <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-interpolate"><code>interpolate</code></a>
- expression reference in the Mapbox Style Specification.
+ expression operator in the Mapbox Style Specification.
  */
 extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolationModeExponential;
 
@@ -34,50 +34,55 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
  
  This attribute corresponds to the `cubic-bezier` value in the
  <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-interpolate"><code>interpolate</code></a>
- expression reference in the Mapbox Style Specification.
+ expression operator in the Mapbox Style Specification.
  */
 extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolationModeCubicBezier;
 
-@interface NSExpression (MGLVariableAdditions)
+/**
+ Methods for creating expressions that use Mapbox-specific functionality and for
+ converting to and from the JSON format defined in the
+ <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions">Mapbox Style Specification</a>.
+ */
+@interface NSExpression (MGLAdditions)
+
+#pragma mark Creating Variable Expressions
 
 /**
  `NSExpression` variable that corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-zoom"><code>zoom</code></a>
- expression reference in the Mapbox Style Specification.
+ expression operator in the Mapbox Style Specification.
  */
 @property (class, nonatomic, readonly) NSExpression *zoomLevelVariableExpression;
 
 /**
  `NSExpression` variable that corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-heatmap-density"><code>heatmap-density</code></a>
- expression reference in the Mapbox Style Specification.
+ expression operator in the Mapbox Style Specification.
  */
 @property (class, nonatomic, readonly) NSExpression *heatmapDensityVariableExpression;
 
 /**
  `NSExpression` variable that corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#eexpressions-geometry-type"><code>geometry-type</code></a>
- expression reference in the Mapbox Style Specification.
+ expression operator in the Mapbox Style Specification.
  */
 @property (class, nonatomic, readonly) NSExpression *geometryTypeVariableExpression;
 
 /**
  `NSExpression` variable that corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-id"><code>id</code></a>
- expression reference in the Mapbox Style Specification.
+ expression operator in the Mapbox Style Specification.
  */
 @property (class, nonatomic, readonly) NSExpression *featureIdentifierVariableExpression;
 
 /**
  `NSExpression` variable that corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-properties"><code>properties</code></a>
- expression reference in the Mapbox Style Specification.
+ expression operator in the Mapbox Style Specification.
  */
 @property (class, nonatomic, readonly) NSExpression *featurePropertiesVariableExpression;
 
-@end
-
-@interface NSExpression (MGLInitializerAdditions)
+#pragma mark Creating Conditional Expressions
 
 /**
  Returns a conditional function expression specifying the string predicate, and
@@ -89,6 +94,8 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
  */
 + (instancetype)mgl_expressionForConditional:(nonnull NSPredicate *)conditionPredicate trueExpression:(nonnull NSExpression *)trueExpression falseExpresssion:(nonnull NSExpression *)falseExpression NS_SWIFT_NAME(init(forMGLConditional:trueExpression:falseExpression:));
 
+#pragma mark Creating Ramp, Scale, and Curve Expressions
+
 /**
  Returns a step function expression specifying the stepping, from expression
  and stops.
@@ -121,6 +128,9 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
  @param defaultExpression The defaultValue expression to be used in case there is no match.
  */
 + (instancetype)mgl_expressionForMatchingExpression:(nonnull NSExpression *)inputExpression inDictionary:(nonnull NSDictionary<NSExpression *, NSExpression *> *)matchedExpressions defaultExpression:(nonnull NSExpression *)defaultExpression NS_SWIFT_NAME(init(forMGLMatchingKey:in:default:));
+
+#pragma mark Concatenating String Expressions
+
 /**
  Returns a constant expression appending the passed expression.
  
@@ -131,9 +141,7 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
  */
 - (instancetype)mgl_expressionByAppendingExpression:(nonnull NSExpression *)expression NS_SWIFT_NAME(mgl_appending(_:));
 
-@end
-
-@interface NSExpression (MGLAdditions)
+#pragma mark Converting JSON Expressions
 
 /**
  Returns an expression equivalent to the given Foundation object deserialized
@@ -168,6 +176,8 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
  */
 @property (nonatomic, readonly) id mgl_jsonExpressionObject;
 
+#pragma mark Localizing the Expression
+
 /**
  Returns a copy of the receiver localized into the given locale.