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

diff --git a/platform/darwin/src/MGLRasterSource.h b/platform/darwin/src/MGLRasterSource.h
index bf561df8da..78f5af8a6a 100644
--- a/platform/darwin/src/MGLRasterSource.h
+++ b/platform/darwin/src/MGLRasterSource.h
@@ -15,9 +15,49 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @interface MGLRasterSource : MGLSource
 
+#pragma mark Initializing a Source
+
+/**
+ Returns a raster source initialized with an identifier, TileJSON configuration
+ URL, and tile size.
+ 
+ After initializing and configuring the source, add it to a map view’s style
+ using the `-[MGLStyle addSource:]` method.
+ 
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param url A URL to a TileJSON configuration file describing the source’s
+    contents and other metadata.
+ @param tileSize The height and width (measured in points) at which to display
+    each tile in this source when the map’s zoom level is an integer.
+ @return An initialized raster source.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier URL:(NSURL *)url tileSize:(CGFloat)tileSize NS_DESIGNATED_INITIALIZER;
+
+/**
+ Returns a raster source initialized with the given identifier, tile size, and
+ tile set.
+ 
+ After initializing and configuring the source, add it to a map view’s style
+ using the `-[MGLStyle addSource:]` method.
+
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param tileSet A tile set describing the source’s contents and other metadata.
+ @param tileSize The height and width (measured in points) at which to display
+    each tile in this source when the map’s zoom level is an integer.
+ @return An initialized raster source.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier tileSet:(MGLTileSet *)tileSet tileSize:(CGFloat)tileSize NS_DESIGNATED_INITIALIZER;
+
+#pragma mark Accessing a Source’s Content
+
 /**
- A URL to a TileJSON resource. Supported protocols are `http:`, `https:`, and 
- `mapbox://<mapid>`.
+ A URL to a TileJSON configuration file describing the source’s contents and
+ other metadata.
+ 
+ The URL may be a full HTTP or HTTPS URL or a Mapbox URL indicating the tile
+ set’s map ID (`mapbox://<mapid>`).
  
  @see <a href="https://www.mapbox.com/help/an-open-platform/#tilejson">The 
  TileJSON specification.</a>
@@ -25,8 +65,12 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, readonly, copy) NSURL *URL;
 
 /**
- The minimum visual size to display tiles for this source. Units in pixels. 
- Defaults to `512` on each tile side.
+ The height and width (measured in points) at which to display each tile in this
+ source when the map’s zoom level is an integer.
+ 
+ A tile may be scaled up or down when the zoom level is between two integers.
+ 
+ The default value of this property is 512 points.
  */
 @property (nonatomic, readonly, assign) NSUInteger tileSize;
 
@@ -40,26 +84,6 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property (nonatomic, readonly, nullable) MGLTileSet *tileSet;
 
-/**
- Initializes a source with the given identifier, TileJSON configuration
- URL, and tile size.
-
- @param sourceIdentifier A string that uniquely identifies the source.
- @param url A URL to a TileJSON resource.
- @param tileSize The minimum visual size to display tiles for the source.
- */
-- (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier URL:(NSURL *)url tileSize:(CGFloat)tileSize;
-
-/**
- Initializes a source with the given identifier, tile size, and tile 
- URL template set.
-
- @param sourceIdentifier A string that uniquely identifies the source.
- @param tileSet A tile set describing where to download tiles.
- @param tileSize The minimum visual size to display tiles for the source.
- */
-- (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier tileSet:(MGLTileSet *)tileSet tileSize:(CGFloat)tileSize;
-
 @end
 
 NS_ASSUME_NONNULL_END