[ios, macos] Clarified source options

Also moved options to the primary classes that use them.

5 files changed, 73 insertions, 29 deletions

diff --git a/platform/darwin/src/MGLComputedShapeSource.h b/platform/darwin/src/MGLComputedShapeSource.h
index 3647819420..25d2d4d0b2 100644
--- a/platform/darwin/src/MGLComputedShapeSource.h
+++ b/platform/darwin/src/MGLComputedShapeSource.h
@@ -14,8 +14,8 @@ NS_ASSUME_NONNULL_BEGIN
  
  Setting this option to `YES` affects rendering performance.
  
- This option is ignored when creating an instance of a class besides
- `MGLComputedShapeSource`.
+ This option is used with the `MGLComputedShapeSource` class; it is ignored when
+ creating an `MGLShapeSource` object.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionWrapsCoordinates;
 
@@ -27,8 +27,8 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionWrapsCoordinate
  Setting this option to `YES` affects rendering performance. Use this option to
  clip `MGLPolyline`s and `MGLPolygon`s at tile boundaries without artifacts.
  
- This option is ignored when creating an instance of a class besides
- `MGLComputedShapeSource`.
+ This option is used with the `MGLComputedShapeSource` class; it is ignored when
+ creating an `MGLShapeSource` object.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClipsCoordinates;
 
@@ -93,8 +93,10 @@ MGL_EXPORT
  
  This class supports the following options:
  `MGLShapeSourceOptionMinimumZoomLevel`, `MGLShapeSourceOptionMaximumZoomLevel`,
- `MGLShapeSourceOptionBuffer`, and
- `MGLShapeSourceOptionSimplificationTolerance`. Shapes provided by a computed
+ `MGLShapeSourceOptionBuffer`,
+ `MGLShapeSourceOptionSimplificationTolerance`,
+ `MGLShapeSourceOptionWrapsCoordinates`, and
+ `MGLShapeSourceOptionClipsCoordinates`. Shapes provided by a computed
  shape source cannot be clustered.
 
  @param identifier A string that uniquely identifies the source.
@@ -110,9 +112,11 @@ MGL_EXPORT
  
  This class supports the following options:
  `MGLShapeSourceOptionMinimumZoomLevel`, `MGLShapeSourceOptionMaximumZoomLevel`,
- `MGLShapeSourceOptionBuffer`, and
- `MGLShapeSourceOptionSimplificationTolerance`. Shapes provided by a computed
- shape source cannot be clustered.
+ `MGLShapeSourceOptionBuffer`,
+ `MGLShapeSourceOptionSimplificationTolerance`,
+ `MGLShapeSourceOptionWrapsCoordinates`, and
+ `MGLShapeSourceOptionClipsCoordinates`. Shapes provided by a computed shape
+ source cannot be clustered.
 
  @param identifier A string that uniquely identifies the source.
  @param options An `NSDictionary` of options for this source.
diff --git a/platform/darwin/src/MGLRasterDEMSource.h b/platform/darwin/src/MGLRasterDEMSource.h
index c53ca9867d..d439fe1645 100644
--- a/platform/darwin/src/MGLRasterDEMSource.h
+++ b/platform/darwin/src/MGLRasterDEMSource.h
@@ -3,6 +3,19 @@
 #import "MGLRasterTileSource.h"
 
 /**
+ An `NSNumber` object containing an unsigned integer that specifies the encoding
+ formula for raster-dem tilesets. The integer corresponds to one of
+ the constants described in `MGLDEMEncoding`.
+ 
+ The default value for this option is `MGLDEMEncodingMapbox`.
+ 
+ This option cannot be represented in a TileJSON or style JSON file. It is used
+ with the `MGLRasterDEMSource` class and is ignored when creating an
+ `MGLRasterTileSource` or `MGLVectorTileSource` object.
+ */
+extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionDEMEncoding;
+
+/**
  `MGLRasterDEMSource` is a map content source that supplies rasterized
  <a href="https://en.wikipedia.org/wiki/Digital_elevation_model">digital elevation model</a>
  (DEM) tiles to be shown on the map. The location of and metadata about the
diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 6f7ca00bc8..6fa93476be 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -17,11 +17,12 @@ typedef NSString *MGLShapeSourceOption NS_STRING_ENUM;
  If the `shape` property contains point shapes, setting this option to
  `YES` clusters the points by radius into groups. The default value is `NO`.
  
- This attribute corresponds to the
+ This option corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-cluster"><code>cluster</code></a>
  source property in the Mapbox Style Specification.
  
- This option only affects point features within a shape source.
+ This option only affects point features within an `MGLShapeSource` object; it
+ is ignored when creating an `MGLComputedShapeSource` object.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClustered;
 
@@ -29,6 +30,9 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClustered;
  An `NSNumber` object containing an integer; specifies the radius of each
  cluster if clustering is enabled. A value of 512 produces a radius equal to
  the width of a tile. The default value is 50.
+ 
+ This option only affects point features within an `MGLShapeSource` object; it
+ is ignored when creating an `MGLComputedShapeSource` object.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClusterRadius;
 
@@ -38,9 +42,12 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClusterRadius;
  less than the value of `MGLShapeSourceOptionMaximumZoomLevel` so that, at the
  maximum zoom level, the shapes are not clustered.
  
- This attribute corresponds to the
+ This option corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-clusterMaxZoom"><code>clusterMaxZoom</code></a>
  source property in the Mapbox Style Specification.
+ 
+ This option only affects point features within an `MGLShapeSource` object; it
+ is ignored when creating an `MGLComputedShapeSource` object.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLevelForClustering;
 
@@ -48,7 +55,7 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLeve
  An `NSNumber` object containing an integer; specifies the minimum zoom level at
  which to create vector tiles. The default value is 0.
 
- This attribute corresponds to the
+ This option corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-minzoom"><code>minzoom</code></a>
  source property in the Mapbox Style Specification.
  */
@@ -59,7 +66,7 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionMinimumZoomLeve
  which to create vector tiles. A greater value produces greater detail at high
  zoom levels. The default value is 18.
  
- This attribute corresponds to the
+ This option corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-maxzoom"><code>maxzoom</code></a>
  source property in the Mapbox Style Specification.
  */
@@ -71,7 +78,7 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLeve
  buffer as wide as the tile itself. Larger values produce fewer rendering
  artifacts near tile edges and slower performance. The default value is 128.
  
- This attribute corresponds to the
+ This option corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-buffer"><code>buffer</code></a>
  source property in the Mapbox Style Specification.
  */
@@ -82,7 +89,7 @@ extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionBuffer;
  simplification tolerance. A greater value produces simpler geometries and
  improves performance. The default value is 0.375.
  
- This attribute corresponds to the
+ This option corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-tolerance"><code>tolerance</code></a>
  source property in the Mapbox Style Specification.
  */
@@ -132,6 +139,14 @@ MGL_EXPORT
 /**
  Returns a shape source with an identifier, URL, and dictionary of options for
  the source.
+ 
+ This class supports the following options: `MGLShapeSourceOptionClustered`,
+ `MGLShapeSourceOptionClusterRadius`,
+ `MGLShapeSourceOptionMaximumZoomLevelForClustering`,
+ `MGLShapeSourceOptionMinimumZoomLevel`, `MGLShapeSourceOptionMaximumZoomLevel`,
+ `MGLShapeSourceOptionBuffer`, and
+ `MGLShapeSourceOptionSimplificationTolerance`. Shapes provided by a shape
+ source are not clipped or wrapped automatically.
 
  @param identifier A string that uniquely identifies the source.
  @param url An HTTP(S) URL, absolute file URL, or local file URL relative to the
@@ -144,6 +159,14 @@ MGL_EXPORT
 /**
  Returns a shape source with an identifier, a shape, and dictionary of options
  for the source.
+ 
+ This class supports the following options: `MGLShapeSourceOptionClustered`,
+ `MGLShapeSourceOptionClusterRadius`,
+ `MGLShapeSourceOptionMaximumZoomLevelForClustering`,
+ `MGLShapeSourceOptionMinimumZoomLevel`, `MGLShapeSourceOptionMaximumZoomLevel`,
+ `MGLShapeSourceOptionBuffer`, and
+ `MGLShapeSourceOptionSimplificationTolerance`. Shapes provided by a shape
+ source are not clipped or wrapped automatically.
 
  To specify attributes about the shape, use an instance of an `MGLShape`
  subclass that conforms to the `MGLFeature` protocol, such as `MGLPointFeature`.
@@ -165,6 +188,14 @@ MGL_EXPORT
 /**
  Returns a shape source with an identifier, an array of features, and a dictionary
  of options for the source.
+ 
+ This class supports the following options: `MGLShapeSourceOptionClustered`,
+ `MGLShapeSourceOptionClusterRadius`,
+ `MGLShapeSourceOptionMaximumZoomLevelForClustering`,
+ `MGLShapeSourceOptionMinimumZoomLevel`, `MGLShapeSourceOptionMaximumZoomLevel`,
+ `MGLShapeSourceOptionBuffer`, and
+ `MGLShapeSourceOptionSimplificationTolerance`. Shapes provided by a shape
+ source are not clipped or wrapped automatically.
 
  Unlike `-initWithIdentifier:shapes:options:`, this method accepts `MGLFeature`
  instances, such as `MGLPointFeature` objects, whose attributes you can use when
@@ -184,6 +215,14 @@ MGL_EXPORT
 /**
  Returns a shape source with an identifier, an array of shapes, and a dictionary of
  options for the source.
+ 
+ This class supports the following options: `MGLShapeSourceOptionClustered`,
+ `MGLShapeSourceOptionClusterRadius`,
+ `MGLShapeSourceOptionMaximumZoomLevelForClustering`,
+ `MGLShapeSourceOptionMinimumZoomLevel`, `MGLShapeSourceOptionMaximumZoomLevel`,
+ `MGLShapeSourceOptionBuffer`, and
+ `MGLShapeSourceOptionSimplificationTolerance`. Shapes provided by a shape
+ source are not clipped or wrapped automatically.
 
  Any `MGLFeature` instance passed into this initializer is treated as an ordinary
  shape, causing any attributes to be inaccessible to an `MGLVectorStyleLayer` when
diff --git a/platform/darwin/src/MGLTileSource.h b/platform/darwin/src/MGLTileSource.h
index 4bf09026f2..b0020e4a19 100644
--- a/platform/darwin/src/MGLTileSource.h
+++ b/platform/darwin/src/MGLTileSource.h
@@ -117,7 +117,6 @@ extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionAttributionInfos;
  */
 extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionTileCoordinateSystem;
 
-
 /**
  Tile coordinate systems that determine how tile coordinates in tile URLs are
  interpreted.
@@ -142,18 +141,6 @@ typedef NS_ENUM(NSUInteger, MGLTileCoordinateSystem) {
     MGLTileCoordinateSystemTMS
 };
 
-
-/**
- An `NSNumber` object containing an unsigned integer that specifies the encoding
- formula for raster-dem tilesets. The integer corresponds to one of
- the constants described in `MGLDEMEncoding`.
-
- The default value for this option is `MGLDEMEncodingMapbox`.
-
- This option is not supported by the TileJSON spec.
- */
-extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionDEMEncoding;
-
 /**
  The encoding formula used to generate the raster-dem tileset
 */
diff --git a/platform/darwin/src/MGLTileSource.mm b/platform/darwin/src/MGLTileSource.mm
index c37812ab8e..87ac5be9c2 100644
--- a/platform/darwin/src/MGLTileSource.mm
+++ b/platform/darwin/src/MGLTileSource.mm
@@ -2,6 +2,7 @@
 
 #import "MGLAttributionInfo_Private.h"
 #import "MGLGeometry_Private.h"
+#import "MGLRasterDEMSource.h"
 #import "NSString+MGLAdditions.h"
 #import "NSValue+MGLAdditions.h"