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

diff --git a/platform/darwin/src/MGLBaseStyleLayer.h b/platform/darwin/src/MGLBaseStyleLayer.h
index fee7707c64..cfdc03962f 100644
--- a/platform/darwin/src/MGLBaseStyleLayer.h
+++ b/platform/darwin/src/MGLBaseStyleLayer.h
@@ -5,15 +5,45 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- The base style layer class from which all other style layer classes 
- inherit. Style layers allow runtime customization of all map styling 
- properties.
+ `MGLStyleLayer` is an abstract base class for style layers. A style layer
+ manages the layout and appearance of content at a specific z-index in a style.
+ An `MGLStyle` object consists of one or more `MGLStyleLayer` objects.
  
- You should use the concrete subclasses of `MGLBaseStyleLayer` (which
- conform to `MGLStyleLayer`) to style fill, line, symbol, and other layer 
- types.
+ Each style layer defined by the style JSON file is represented at runtime by an
+ `MGLStyleLayer` object, which you can use to refine the map’s appearance. You
+ can also add and remove style layers dynamically.
+ 
+ Do not create instances of this class directly, and do not create your own
+ subclasses of this class. Instead, create instances of
+ `MGLBackgroundStyleLayer` and the concrete subclasses of
+ `MGLForegroundStyleLayer`.
+ */
+@interface MGLStyleLayer : NSObject
+
+#pragma mark Initializing a Style Layer
+
+/**
+ Returns a style layer object initialized with the given identifier.
+ 
+ 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 layer in the style to
+    which it is added.
+ @return An initialized style layer.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier;
+
+#pragma mark Identifying a Style Layer
+
+/**
+ A string that uniquely identifies the style layer in the style to which it is
+ added.
  */
-@interface MGLBaseStyleLayer : NSObject
+@property (nonatomic, copy, readonly) NSString *identifier;
+
+#pragma mark Configuring a Style Layer’s Visibility
 
 /**
  Whether this layer is displayed. A value of `NO` hides the layer.