1 files changed, 36 insertions, 15 deletions
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