[ios, macos] Revamped MGLStyleLayer, MGLSource inheritance

Removed the MGLStyleLayer protocol, because almost none of its members was actually implemented in every class that adopted the protocol. Removed the unused mapView backpointer property with no replacement. Renamed MGLBaseStyleLayer to MGLStyleLayer. Created the intermediate abstract classes MGLForegroundStyleLayer and MGLVectorStyleLayer to cover subsets of style layer classes with like functionality.

Moved each MGLBaseStyleLayer initializer and the corresponding properties down to an abstract subclass such that the initializer makes sense for all concrete subclasses. Moved more initializers and the predicate property up to MGLVectorStyleLayer to eliminate duplication among the concrete subclasses. Marked these initializers as designated initializers.

Removed “source” or “layer” before identifier wherever the type of identifier is apparent. Removed extra MGLGeoJSONSource initializer variants in favor of nullable parameters.

Added copious documentation comments for source and style layer classes, including several previously undocumented methods and properties. In particular, some preconditions and postconditions have been documented. Added pragma marks to break up the jazzy documentation pages into sections. Reformatted exceptions for consistency.

1 files changed, 68 insertions, 6 deletions

diff --git a/platform/darwin/src/MGLStyleLayer.h b/platform/darwin/src/MGLStyleLayer.h
index d4ed525a3f..763854f44c 100644
--- a/platform/darwin/src/MGLStyleLayer.h
+++ b/platform/darwin/src/MGLStyleLayer.h
@@ -1,12 +1,74 @@
 #import <Foundation/Foundation.h>
 
-@class MGLMapView;
+#import "MGLBaseStyleLayer.h"
 
-@protocol MGLStyleLayer <NSObject>
+NS_ASSUME_NONNULL_BEGIN
 
-@property (nonatomic, weak) MGLMapView *mapView;
-@property (nonatomic, copy, readonly) NSString *layerIdentifier;
-@property (nonatomic, readonly) NSString *sourceIdentifier;
-@property (nonatomic, readonly) NSString *sourceLayerIdentifier;
+@class MGLSource;
+
+/**
+ `MGLForegroundStyleLayer` is an abstract superclass for style layers whose
+ content is defined by an `MGLSource` object.
+ 
+ Do not create instances of this class directly, and do not create your own
+ subclasses of this class. Instead, create instances of `MGLRasterStyleLayer`
+ and the concrete subclasses of `MGLVectorStyleLayer`.
+ */
+@interface MGLForegroundStyleLayer : MGLStyleLayer
+
+#pragma mark Initializing a Style Layer
+
+/**
+ Returns a foreground style layer initialized with an identifier and source.
+ 
+ After initializing and configuring the style layer, add it to a map view’s
+ style using the `-[MGLStyle addLayer:]` or
+ `-[MGLStyle insertLayer:belowLayer:]` method.
+ 
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param source The source from which to obtain the data to style. If the source
+    has not yet been added to the current style, the behavior is undefined.
+ @return An initialized foreground style layer.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source NS_DESIGNATED_INITIALIZER;
+
+#pragma mark Specifying a Style Layer’s Content
+
+/**
+ Identifier of the source from which the receiver obtains the data to style.
+ */
+@property (nonatomic, readonly, nullable) NSString *sourceIdentifier;
+
+@end
+
+/**
+ `MGLVectorStyleLayer` is an abstract superclass for style layers whose content
+ is defined by an `MGLGeoJSONSource` or `MGLVectorSource` object.
+ 
+ Do not create instances of this class directly, and do not create your own
+ subclasses of this class. Instead, create instances of the following concrete
+ subclasses: `MGLCircleStyleLayer`, `MGLFillStyleLayer`, `MGLLineStyleLayer`,
+ and `MGLSymbolStyleLayer`.
+ */
+@interface MGLVectorStyleLayer : MGLForegroundStyleLayer
+
+#pragma mark Refining a Style Layer’s Content
+
+/**
+ Identifier of the layer within the source identified by the `sourceIdentifier`
+ property from which the receiver obtains the data to style.
+ */
+@property (nonatomic, nullable) NSString *sourceLayerIdentifier;
+
+/**
+ A predicate that corresponds to the layer's <a href='https://www.mapbox.com/mapbox-gl-style-spec/#types-filter'>filter</a>.
+ 
+ The predicate's left expression must be a string that identifies a feature
+ property, or one of the special keys.
+ */
+@property (nonatomic, nullable) NSPredicate *predicate;
 
 @end
+
+NS_ASSUME_NONNULL_END