[ios, macos] Simplify MGLSource and subclasses (#7377)

* [ios, macos] Audited source headers for nullability

* [macos] Made MGLTileSet public

* [ios, macos] Replaced MGLTileSet with MGLTileSource

MGLRasterSource and MGLVectorSource now share a common abstract superclass, MGLTileSource. MGLTileSet has been removed. MGLTileSource is modeled after mbgl::style::RasterSource and mbgl::style::VectorSource. It has initializers that incorporate the parameters of MGLTileSet’s initializers, but it lacks getters for everything but the attribution string. MGLTileSet’s properties have been converted into options that can be passed into MGLTileSource’s initializers in a dictionary.

Properly implement rawSource as a covariant property so that it doesn’t end up getting autosynthesized as a shadow ivar. This prevents concrete subclasses of MGLSource from setting _rawSource directly but getting a different value out of self.rawSource.

Marked -[MGLSource init] as unavailable and ensured that concrete subclasses of MGLSource have the right set of initializers marked as designated initializers.

Documentation comments for each concrete source class identify the corresponding source type in the style specification. Clarified the purpose of MGLTileSetScheme, now known as MGLTileCoordinateSystem.

* [ios, macos] Clarified tile size interpretation

Sticking to a default value of 256 for mapbox: URLs, but other URLs get the standard 512 value.

* [ios, macos] rawSource is always set

* [ios, macos] Cleaned up MGLShapeSource initialization

rawSource is never nil, so there’s no need for a -commonInit method. Extracted -geoJSONOptions from MGLShapeSource into a standalone function for easier testing.

* [ios, macos] Synchronized headers in project

Realphabetized headers in groups. Added headers missing from one project or the other.

* [ios, macos] Added MGLShape methods to (de)serialize GeoJSON data

Added a class initializer and instance method to MGLShape that deserialize and serialize the shape as GeoJSON data, respectively. The new initializer handles parsing errors gracefully.

Removed methods specific to GeoJSON data from MGLShapeSource, in an effort to reduce parallel state. Developers are now expected to go through the new MGLShape initializer to get an MGLShape representation. Alternatively, a local file URL can be passed into the other MGLShapeSource initializer.

* [ios, macos] Typo in assertion message

* [ios, macos] Simplified GeoJSON serialization

Every MGLShape now knows its most specific mbgl::GeoJSON representation.

* [ios, macos] Reremoved MGLFeaturePrivate

mbgl::GeoJSON, which is a variant, allows a single GeoJSON representation method to traffic in whatever type is needed for a particular shape class. This change removes some hidden private protocols, which are a bug waiting to happen.

* [ios, macos] Fixed covariant rawLayer property

Properly implement rawLayer as a covariant property so that it doesn’t end up getting autosynthesized as a shadow ivar. This prevents concrete subclasses of MGLStyleLayer from setting _rawLayer directly but getting a different value out of self.rawLayer.

* [ios, macos] Use MGLAttributionInfo for source attribution

Made MGLAttributionInfo public. Replaced MGLTileSource’s attribution property with an attributionInfos property set to an array of MGLAttributionInfo objects. Added an MGLTileSourceOption for specifying an array of MGLAttributionInfo objects instead of an HTML string (either is acceptable when creating an MGLTileSource).

* [ios, macos] Corrected method references in documentation

1 files changed, 58 insertions, 57 deletions

diff --git a/platform/darwin/src/MGLRasterSource.h b/platform/darwin/src/MGLRasterSource.h
index 2940f05371..262e8f2ce1 100644
--- a/platform/darwin/src/MGLRasterSource.h
+++ b/platform/darwin/src/MGLRasterSource.h
@@ -1,93 +1,94 @@
-#import "MGLSource.h"
-#import "MGLTypes.h"
+#import "MGLTileSource.h"
 
 #import <CoreGraphics/CoreGraphics.h>
 
-@class MGLTileSet;
-
 NS_ASSUME_NONNULL_BEGIN
 
 /**
+ An `NSNumber` object containing a floating-point number that specifies the
+ width and height (measured in points) at which the map displays each raster
+ image tile when the map’s zoom level is an integer. The raster source scales
+ its images up or down when the map’s zoom level falls between two integers.
+ 
+ The default value for this option is 512. Version 4 of the
+ <a href="https://www.mapbox.com/api-documentation/#maps">Mapbox Maps API</a>
+ requires a value of 256, as do many third-party tile servers, so consult your
+ provider’s documentation for the correct value.
+ 
+ This option is only applicable to `MGLRasterSource` objects; it is ignored when
+ initializing `MGLVectorSource` objects.
+ */
+extern const MGLTileSourceOption MGLTileSourceOptionTileSize;
+
+/**
  `MGLRasterSource` is a map content source that supplies raster image tiles to
- be shown on the map. The location of and metadata about the raster tiles are
- defined by either an `MGLTileSet` object or an external TileJSON resource. A
- raster source is added to an `MGLStyle` object along with an
- `MGLRasterStyleLayer` object. Use a raster style layer to control the
+ be shown on the map. The location of and metadata about the tiles are defined
+ either by an option dictionary or by an external file that conforms to the
+ <a href="https://github.com/mapbox/tilejson-spec/">TileJSON specification</a>.
+ A raster source is added to an `MGLStyle` object along with one or more
+ `MGLRasterStyleLayer` objects. Use a raster style layer to control the
  appearance of content supplied by the raster source.
+ 
+ Each
+ <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-raster"><code>raster</code></a>
+ source defined by the style JSON file is represented at runtime by an
+ `MGLRasterSource` object that you can use to initialize new style layers. You
+ can also add and remove sources dynamically using methods such as
+ `-[MGLStyle addSource:]` and `-[MGLStyle sourceWithIdentifier:]`.
  */
-@interface MGLRasterSource : MGLSource
+@interface MGLRasterSource : MGLTileSource
 
 #pragma mark Initializing a Source
 
 /**
- Returns a raster source initialized with an identifier, TileJSON configuration
- URL, and tile size.
+ Returns a raster source initialized with an identifier and configuration URL.
  
  After initializing and configuring the source, add it to a map view’s style
  using the `-[MGLStyle addSource:]` method.
  
  The URL may be a full HTTP or HTTPS URL or, for tile sets hosted by Mapbox, a
- Mapbox URL indicating a map identifier (`mapbox://<mapid>`).
+ Mapbox URL indicating a map identifier (`mapbox://<mapid>`). The URL should
+ point to a JSON file that conforms to the
+ <a href="https://github.com/mapbox/tilejson-spec/">TileJSON specification</a>.
+ 
+ If a Mapbox URL is specified, this source uses a tile size of 256. For all
+ other tile sets, the default value is 512. (See the
+ `MGLTileSourceOptionTileSize` documentation for more information about tile
+ sizes.) If you need to use a tile size other than the default, use the
+ `-initWithIdentifier:configurationURL:tileSize:` 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.
+ @param configurationURL A URL to a TileJSON configuration file describing the
+    source’s contents and other metadata.
  @return An initialized raster source.
  */
-- (instancetype)initWithIdentifier:(NSString *)identifier URL:(NSURL *)url tileSize:(CGFloat)tileSize NS_DESIGNATED_INITIALIZER;
+- (instancetype)initWithIdentifier:(NSString *)identifier configurationURL:(NSURL *)configurationURL;
 
 /**
- Returns a raster source initialized with the given identifier, tile size, and
- tile set.
+ Returns a raster source initialized with an identifier, 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 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 configuration file describing the source’s contents and
- other metadata.
  
  The URL may be a full HTTP or HTTPS URL or, for tile sets hosted by Mapbox, a
- Mapbox URL indicating a map identifier (`mapbox://<mapid>`).
- 
- @see <a href="https://www.mapbox.com/help/an-open-platform/#tilejson">The 
- TileJSON specification.</a>
- */
-@property (nonatomic, readonly, copy) NSURL *URL;
-
-/**
- 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.
+ Mapbox URL indicating a map identifier (`mapbox://<mapid>`). The URL should
+ point to a JSON file that conforms to the
+ <a href="https://github.com/mapbox/tilejson-spec/">TileJSON specification</a>.
  
- The default value of this property is 512 points.
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param configurationURL A URL to a TileJSON configuration file describing the
+ source’s contents and other metadata.
+ @param tileSize The width and height (measured in points) of each tiled image
+    in the raster source. See the `MGLTileSourceOptionTileSize` documentation
+    for details.
+ @return An initialized raster source.
  */
-@property (nonatomic, readonly, assign) NSUInteger tileSize;
+- (instancetype)initWithIdentifier:(NSString *)identifier configurationURL:(NSURL *)configurationURL tileSize:(CGFloat)tileSize NS_DESIGNATED_INITIALIZER;
 
-/**
- The tile set used to locate and download tiles. 
- 
- A tile set holds the raster tile URL template strings and associated
- configuration for those strings. It can be passed in place of the URL
- to TileJSON in order to create a source configured to download tiles
- from ordinary web URLs.
- */
-@property (nonatomic, readonly, nullable) MGLTileSet *tileSet;
+- (instancetype)initWithIdentifier:(NSString *)identifier tileURLTemplates:(NS_ARRAY_OF(NSString *) *)tileURLTemplates options:(nullable NS_DICTIONARY_OF(MGLTileSourceOption, id) *)options NS_DESIGNATED_INITIALIZER;
 
 @end