17 files changed, 85 insertions, 35 deletions
diff --git a/platform/darwin/src/MGLBackgroundStyleLayer.mm b/platform/darwin/src/MGLBackgroundStyleLayer.mm
index 993645d3a8..acea3441fa 100644
--- a/platform/darwin/src/MGLBackgroundStyleLayer.mm
+++ b/platform/darwin/src/MGLBackgroundStyleLayer.mm
@@ -2,7 +2,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLCircleStyleLayer.mm b/platform/darwin/src/MGLCircleStyleLayer.mm
index 0be3920987..b85b3d9d4f 100644
--- a/platform/darwin/src/MGLCircleStyleLayer.mm
+++ b/platform/darwin/src/MGLCircleStyleLayer.mm
@@ -2,7 +2,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLFillExtrusionStyleLayer.mm b/platform/darwin/src/MGLFillExtrusionStyleLayer.mm
index 688ce4c1ac..ea29dff62d 100644
--- a/platform/darwin/src/MGLFillExtrusionStyleLayer.mm
+++ b/platform/darwin/src/MGLFillExtrusionStyleLayer.mm
@@ -2,7 +2,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLFillStyleLayer.mm b/platform/darwin/src/MGLFillStyleLayer.mm
index c975e28d6b..5be0decd4a 100644
--- a/platform/darwin/src/MGLFillStyleLayer.mm
+++ b/platform/darwin/src/MGLFillStyleLayer.mm
@@ -2,7 +2,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLHeatmapStyleLayer.mm b/platform/darwin/src/MGLHeatmapStyleLayer.mm
index a394dbda3b..b4bf4c9566 100644
--- a/platform/darwin/src/MGLHeatmapStyleLayer.mm
+++ b/platform/darwin/src/MGLHeatmapStyleLayer.mm
@@ -2,7 +2,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLHillshadeStyleLayer.mm b/platform/darwin/src/MGLHillshadeStyleLayer.mm
index 2383c1ce26..70fab24e33 100644
--- a/platform/darwin/src/MGLHillshadeStyleLayer.mm
+++ b/platform/darwin/src/MGLHillshadeStyleLayer.mm
@@ -2,7 +2,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLLineStyleLayer.mm b/platform/darwin/src/MGLLineStyleLayer.mm
index 619cc70afe..b359c424a2 100644
--- a/platform/darwin/src/MGLLineStyleLayer.mm
+++ b/platform/darwin/src/MGLLineStyleLayer.mm
@@ -2,7 +2,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLRasterStyleLayer.mm b/platform/darwin/src/MGLRasterStyleLayer.mm
index 94a58409de..0e31512491 100644
--- a/platform/darwin/src/MGLRasterStyleLayer.mm
+++ b/platform/darwin/src/MGLRasterStyleLayer.mm
@@ -2,7 +2,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLShapeSource.mm b/platform/darwin/src/MGLShapeSource.mm
index dcc3fd97f5..af26b7ea13 100644
--- a/platform/darwin/src/MGLShapeSource.mm
+++ b/platform/darwin/src/MGLShapeSource.mm
@@ -6,7 +6,7 @@
 #import "MGLFeature_Private.h"
 #import "MGLShape_Private.h"
 
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSURL+MGLAdditions.h"
 
 #include <mbgl/map/map.hpp>
diff --git a/platform/darwin/src/MGLStyleLayer.mm.ejs b/platform/darwin/src/MGLStyleLayer.mm.ejs
index 42940083b5..ead246fb03 100644
--- a/platform/darwin/src/MGLStyleLayer.mm.ejs
+++ b/platform/darwin/src/MGLStyleLayer.mm.ejs
@@ -8,7 +8,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLSymbolStyleLayer.mm b/platform/darwin/src/MGLSymbolStyleLayer.mm
index 0d9fac4808..4236e04238 100644
--- a/platform/darwin/src/MGLSymbolStyleLayer.mm
+++ b/platform/darwin/src/MGLSymbolStyleLayer.mm
@@ -2,7 +2,7 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
diff --git a/platform/darwin/src/MGLVectorTileSource.mm b/platform/darwin/src/MGLVectorTileSource.mm
index c1f7267e4a..96629997d6 100644
--- a/platform/darwin/src/MGLVectorTileSource.mm
+++ b/platform/darwin/src/MGLVectorTileSource.mm
@@ -6,7 +6,7 @@
 #import "MGLStyle_Private.h"
 #import "MGLMapView_Private.h"
 
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSURL+MGLAdditions.h"
 
 #include <mbgl/map/map.hpp>
diff --git a/platform/darwin/src/NSCompoundPredicate+MGLAdditions.mm b/platform/darwin/src/NSCompoundPredicate+MGLAdditions.mm
index 5a98b763ea..a8ae19b172 100644
--- a/platform/darwin/src/NSCompoundPredicate+MGLAdditions.mm
+++ b/platform/darwin/src/NSCompoundPredicate+MGLAdditions.mm
@@ -2,7 +2,7 @@
 
 #import "MGLStyleValue_Private.h"
 
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 #import "NSExpression+MGLPrivateAdditions.h"
 
 #include <mbgl/style/conversion/property_value.hpp>
diff --git a/platform/darwin/src/NSExpression+MGLAdditions.mm b/platform/darwin/src/NSExpression+MGLAdditions.mm
index 7881b79370..b2bcf72caf 100644
--- a/platform/darwin/src/NSExpression+MGLAdditions.mm
+++ b/platform/darwin/src/NSExpression+MGLAdditions.mm
@@ -913,7 +913,7 @@ NSArray *MGLSubexpressionsWithJSONObjects(NSArray *objects) {
             
             for (NSUInteger index = 0; index < argumentObjects.count; index++) {
                 if (index % 2 == 0 && index != argumentObjects.count - 1) {
-                    NSPredicate *predicate = [NSPredicate mgl_predicateWithJSONObject:argumentObjects[index]];
+                    NSPredicate *predicate = [NSPredicate predicateWithMGLJSONObject:argumentObjects[index]];
                     NSExpression *argument = [NSExpression expressionForConstantValue:predicate];
                     [arguments addObject:argument];
                 } else {
diff --git a/platform/darwin/src/NSPredicate+MGLAdditions.h b/platform/darwin/src/NSPredicate+MGLAdditions.h
index a73b1a61ba..6c4b878d37 100644
--- a/platform/darwin/src/NSPredicate+MGLAdditions.h
+++ b/platform/darwin/src/NSPredicate+MGLAdditions.h
@@ -1,23 +1,44 @@
 #import <Foundation/Foundation.h>
 
-#import "NSExpression+MGLPrivateAdditions.h"
+NS_ASSUME_NONNULL_BEGIN
 
 @interface NSPredicate (MGLAdditions)
 
-- (mbgl::style::Filter)mgl_filter;
-
-+ (instancetype)mgl_predicateWithFilter:(mbgl::style::Filter)filter;
-
-@end
-
-@interface NSPredicate (MGLExpressionAdditions)
-
-+ (instancetype)mgl_predicateWithJSONObject:(id)object;
-
+#pragma mark Converting JSON Expressions
+
+/**
+ Returns a predicate equivalent to the given Foundation object deserialized
+ from JSON data.
+ 
+ The Foundation object is interpreted according to the
+ [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions).
+ See the
+ “[Predicates and Expressions](../predicates-and-expressions.html)”
+ guide for a correspondence of operators and types between the style
+ specification and the `NSPredicate` representation used by this SDK.
+ 
+ @param object A Foundation object deserialized from JSON data, for example
+ using `NSJSONSerialization`.
+ @return An initialized predicate equivalent to `object`, suitable for use
+ with the `MGLVectorStyleLayer.predicate` property.
+ */
++ (instancetype)predicateWithMGLJSONObject:(id)object NS_SWIFT_NAME(init(mglJSONObject:));
+
+/**
+ An equivalent Foundation object that can be serialized as JSON.
+ 
+ The Foundation object conforms to the
+ [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions).
+ See the
+ “[Predicates and Expressions](../predicates-and-expressions.html)”
+ guide for a correspondence of operators and types between the style
+ specification and the `NSPredicate` representation used by this SDK.
+ 
+ You can use `NSJSONSerialization` to serialize the Foundation object as data to
+ write to a file.
+ */
 @property (nonatomic, readonly) id mgl_jsonExpressionObject;
 
-- (id)mgl_if:(id)firstValue, ...;
-
-- (id)mgl_match:(NSExpression *)firstCase, ...;
-
 @end
+
+NS_ASSUME_NONNULL_END
diff --git a/platform/darwin/src/NSPredicate+MGLAdditions.mm b/platform/darwin/src/NSPredicate+MGLAdditions.mm
index bbd324bb63..07154cb246 100644
--- a/platform/darwin/src/NSPredicate+MGLAdditions.mm
+++ b/platform/darwin/src/NSPredicate+MGLAdditions.mm
@@ -1,4 +1,4 @@
-#import "NSPredicate+MGLAdditions.h"
+#import "NSPredicate+MGLPrivateAdditions.h"
 
 #import "MGLValueEvaluator.h"
 #import "MGLStyleValue_Private.h"
@@ -200,11 +200,11 @@ public:
     
     NSPredicate *operator()(mbgl::style::ExpressionFilter filter) {
         id jsonObject = MGLJSONObjectFromMBGLExpression(*filter.expression);
-        return [NSPredicate mgl_predicateWithJSONObject:jsonObject];
+        return [NSPredicate predicateWithMGLJSONObject:jsonObject];
     }
 };
 
-@implementation NSPredicate (MGLAdditions)
+@implementation NSPredicate (MGLPrivateAdditions)
 
 - (mbgl::style::Filter)mgl_filter
 {
@@ -230,18 +230,18 @@ public:
 
 @end
 
-@implementation NSPredicate (MGLExpressionAdditions)
+@implementation NSPredicate (MGLAdditions)
 
 NSArray *MGLSubpredicatesWithJSONObjects(NSArray *objects) {
     NSMutableArray *subpredicates = [NSMutableArray arrayWithCapacity:objects.count];
     for (id object in objects) {
-        NSPredicate *predicate = [NSPredicate mgl_predicateWithJSONObject:object];
+        NSPredicate *predicate = [NSPredicate predicateWithMGLJSONObject:object];
         [subpredicates addObject:predicate];
     }
     return subpredicates;
 }
 
-+ (instancetype)mgl_predicateWithJSONObject:(id)object {
++ (instancetype)predicateWithMGLJSONObject:(id)object {
     if ([object isEqual:@YES]) {
         return [NSPredicate predicateWithValue:YES];
     }
@@ -360,6 +360,10 @@ NSArray *MGLSubpredicatesWithJSONObjects(NSArray *objects) {
     return nil;
 }
 
+@end
+
+@implementation NSPredicate (MGLExpressionAdditions)
+
 - (id)mgl_if:(id)firstValue, ... {
 
     if ([self evaluateWithObject:nil]) {
diff --git a/platform/darwin/src/NSPredicate+MGLPrivateAdditions.h b/platform/darwin/src/NSPredicate+MGLPrivateAdditions.h
new file mode 100644
index 0000000000..1828009678
--- /dev/null
+++ b/platform/darwin/src/NSPredicate+MGLPrivateAdditions.h
@@ -0,0 +1,25 @@
+#import <Foundation/Foundation.h>
+
+#import "NSPredicate+MGLAdditions.h"
+
+#include <mbgl/style/filter.hpp>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface NSPredicate (MGLPrivateAdditions)
+
+- (mbgl::style::Filter)mgl_filter;
+
++ (instancetype)mgl_predicateWithFilter:(mbgl::style::Filter)filter;
+
+@end
+
+@interface NSPredicate (MGLExpressionAdditions)
+
+- (id)mgl_if:(id)firstValue, ...;
+
+- (id)mgl_match:(NSExpression *)firstCase, ...;
+
+@end
+
+NS_ASSUME_NONNULL_END