[ios, macos] Compare source options to specs

4 files changed, 120 insertions, 2 deletions

diff --git a/platform/darwin/docs/guides/For Style Authors.md b/platform/darwin/docs/guides/For Style Authors.md
index b7de36516b..927dd18392 100644
--- a/platform/darwin/docs/guides/For Style Authors.md
+++ b/platform/darwin/docs/guides/For Style Authors.md
@@ -70,7 +70,7 @@ _Human Interface Guidelines_ document for
 [iOS](https://developer.apple.com/ios/human-interface-guidelines/) or
 [macOS](https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/OSXHIGuidelines/).
 
-## Setting the style
+## Applying your style
 
 You set an `MGLMapView` object’s style either in code, by setting the
 `MGLMapView.styleURL` property, or in Interface Builder, by setting the “Style
@@ -121,6 +121,45 @@ In style JSON | In the SDK
 
 `image` and `video` sources are not supported.
 
+### Tile sources
+
+Raster and vector sources may be defined in TileJSON configuration files. This
+SDK supports the properties defined in the style specification, which are a
+subset of the keys defined in version 2.1.0 of the
+[TileJSON](https://github.com/mapbox/tilejson-spec/tree/master/2.1.0)
+specification. As an alternative to authoring a custom TileJSON file, you may
+supply various tile source options when creating a raster or vector source.
+These options are detailed in the `MGLTileSourceOption` documentation:
+
+In style JSON | In TileJSON   | In the SDK
+--------------|---------------|-----------
+`url`         | —             | `configurationURL` parameter in `-[MGLTileSource initWithIdentifier:configurationURL:]`
+`tiles`       | `tiles`       | `tileURLTemplates` parameter in `-[MGLTileSource initWithIdentifier:tileURLTemplates:options:]`
+`minzoom`     | `minzoom`     | `MGLTileSourceOptionMinimumZoomLevel`
+`maxzoom`     | `maxzoom`     | `MGLTileSourceOptionMaximumZoomLevel`
+`tileSize`    | —             | `MGLTileSourceOptionTileSize`
+`attribution` | `attribution` | `MGLTileSourceOptionAttributionHTMLString` (but consider specifying `MGLTileSourceOptionAttributionInfos` instead for improved security)
+`scheme`      | `scheme`      | `MGLTileSourceOptionTileCoordinateSystem`
+
+### Shape sources
+
+Shape sources also accept various options. These options are detailed in the
+`MGLShapeSourceOption` documentation:
+
+In style JSON    | In the SDK
+-----------------|-----------
+`data`           | `url` parameter in `-[MGLShapeSource initWithIdentifier:URL:options:]`
+`maxzoom`        | `MGLShapeSourceOptionMaximumZoomLevel`
+`buffer`         | `MGLShapeSourceOptionBuffer`
+`tolerance`      | `MGLShapeSourceOptionSimplificationTolerance`
+`cluster`        | `MGLShapeSourceOptionClustered`
+`clusterRadius`  | `MGLShapeSourceOptionClusterRadius`
+`clusterMaxZoom` | `MGLShapeSourceOptionMaximumZoomLevelForClustering`
+
+To create a shape source from local GeoJSON data, first
+[convert the GeoJSON data into a shape](working-with-geojson-data.html#converting-geojson-data-into-shape-objects),
+then use the `-[MGLShapeSource initWithIdentifier:shape:options:]` method.
+
 ## Configuring the map content’s appearance
 
 Each layer defined by the style JSON file is represented at runtime by a style
diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
index 32cef9344b..a56f48acae 100644
--- a/platform/darwin/docs/guides/For Style Authors.md.ejs
+++ b/platform/darwin/docs/guides/For Style Authors.md.ejs
@@ -74,7 +74,7 @@ _Human Interface Guidelines_ document for
 [iOS](https://developer.apple.com/ios/human-interface-guidelines/) or
 [macOS](https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/OSXHIGuidelines/).
 
-## Setting the style
+## Applying your style
 
 You set an `MGLMapView` object’s style either in code, by setting the
 `MGLMapView.styleURL` property, or in Interface Builder, by setting the “Style
@@ -125,6 +125,45 @@ In style JSON | In the SDK
 
 `image` and `video` sources are not supported.
 
+### Tile sources
+
+Raster and vector sources may be defined in TileJSON configuration files. This
+SDK supports the properties defined in the style specification, which are a
+subset of the keys defined in version 2.1.0 of the
+[TileJSON](https://github.com/mapbox/tilejson-spec/tree/master/2.1.0)
+specification. As an alternative to authoring a custom TileJSON file, you may
+supply various tile source options when creating a raster or vector source.
+These options are detailed in the `MGLTileSourceOption` documentation:
+
+In style JSON | In TileJSON   | In the SDK
+--------------|---------------|-----------
+`url`         | —             | `configurationURL` parameter in `-[MGLTileSource initWithIdentifier:configurationURL:]`
+`tiles`       | `tiles`       | `tileURLTemplates` parameter in `-[MGLTileSource initWithIdentifier:tileURLTemplates:options:]`
+`minzoom`     | `minzoom`     | `MGLTileSourceOptionMinimumZoomLevel`
+`maxzoom`     | `maxzoom`     | `MGLTileSourceOptionMaximumZoomLevel`
+`tileSize`    | —             | `MGLTileSourceOptionTileSize`
+`attribution` | `attribution` | `MGLTileSourceOptionAttributionHTMLString` (but consider specifying `MGLTileSourceOptionAttributionInfos` instead for improved security)
+`scheme`      | `scheme`      | `MGLTileSourceOptionTileCoordinateSystem`
+
+### Shape sources
+
+Shape sources also accept various options. These options are detailed in the
+`MGLShapeSourceOption` documentation:
+
+In style JSON    | In the SDK
+-----------------|-----------
+`data`           | `url` parameter in `-[MGLShapeSource initWithIdentifier:URL:options:]`
+`maxzoom`        | `MGLShapeSourceOptionMaximumZoomLevel`
+`buffer`         | `MGLShapeSourceOptionBuffer`
+`tolerance`      | `MGLShapeSourceOptionSimplificationTolerance`
+`cluster`        | `MGLShapeSourceOptionClustered`
+`clusterRadius`  | `MGLShapeSourceOptionClusterRadius`
+`clusterMaxZoom` | `MGLShapeSourceOptionMaximumZoomLevelForClustering`
+
+To create a shape source from local GeoJSON data, first
+[convert the GeoJSON data into a shape](working-with-geojson-data.html#converting-geojson-data-into-shape-objects),
+then use the `-[MGLShapeSource initWithIdentifier:shape:options:]` method.
+
 ## Configuring the map content’s appearance
 
 Each layer defined by the style JSON file is represented at runtime by a style
diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 30e299d2b1..a276864be7 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -16,6 +16,10 @@ typedef NSString *MGLShapeSourceOption NS_STRING_ENUM;
  An `NSNumber` object containing a Boolean enabling or disabling clustering.
  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
+ <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-cluster"><code>cluster</code></a>
+ source property in the Mapbox Style Specification.
  */
 extern const MGLShapeSourceOption MGLShapeSourceOptionClustered;
 
@@ -31,6 +35,10 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionClusterRadius;
  which to cluster points if clustering is enabled. Defaults to one zoom level 
  less than the value of `MGLShapeSourceOptionMaximumZoomLevel` so that, at the
  maximum zoom level, the shapes are not clustered.
+
+ This attribute 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.
  */
 extern const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLevelForClustering;
 
@@ -38,6 +46,10 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLevelForCluster
  An `NSNumber` object containing an integer; specifies the maximum zoom level at
  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
+ <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-maxzoom"><code>maxzoom</code></a>
+ source property in the Mapbox Style Specification.
  */
 extern const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLevel;
 
@@ -46,6 +58,10 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionMaximumZoomLevel;
  buffer on each side. A value of 0 produces no buffer. A value of 512 produces a 
  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
+ <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-buffer"><code>buffer</code></a>
+ source property in the Mapbox Style Specification.
  */
 extern const MGLShapeSourceOption MGLShapeSourceOptionBuffer;
 
@@ -53,6 +69,10 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionBuffer;
  An `NSNumber` object containing a double; specifies the Douglas-Peucker
  simplification tolerance. A greater value produces simpler geometries and
  improves performance. The default value is 0.375.
+
+ This attribute 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.
  */
 extern const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
 
diff --git a/platform/darwin/src/MGLTileSource.h b/platform/darwin/src/MGLTileSource.h
index 12bc72538c..db5bc73338 100644
--- a/platform/darwin/src/MGLTileSource.h
+++ b/platform/darwin/src/MGLTileSource.h
@@ -19,6 +19,10 @@ typedef NSString *MGLTileSourceOption NS_STRING_ENUM;
  The value should be between 0 and 22, inclusive, and less than
  `MGLTileSourceOptionMaximumZoomLevel`, if specified. The default value for this
  option is 0.
+
+ This option corresponds to the `minzoom` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern const MGLTileSourceOption MGLTileSourceOptionMinimumZoomLevel;
 
@@ -29,6 +33,10 @@ extern const MGLTileSourceOption MGLTileSourceOptionMinimumZoomLevel;
  The value should be between 0 and 22, inclusive, and less than
  `MGLTileSourceOptionMinimumZoomLevel`, if specified. The default value for this
  option is 22.
+
+ This option corresponds to the `maxzoom` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern const MGLTileSourceOption MGLTileSourceOptionMaximumZoomLevel;
 
@@ -41,6 +49,10 @@ extern const MGLTileSourceOption MGLTileSourceOptionMaximumZoomLevel;
  By default, no attribution statements are displayed. If the
  `MGLTileSourceOptionAttributionInfos` option is specified, this option is
  ignored.
+
+ This option corresponds to the `attribution` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern const MGLTileSourceOption MGLTileSourceOptionAttributionHTMLString;
 
@@ -60,6 +72,10 @@ extern const MGLTileSourceOption MGLTileSourceOptionAttributionInfos;
  By default, no attribution statements are displayed. If the
  `MGLTileSourceOptionAttributionInfos` option is specified, this option is
  ignored.
+
+ This option corresponds to the `attribution` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern const MGLTileSourceOption MGLTileSourceOptionAttributionHTMLString;
 
@@ -79,6 +95,10 @@ extern const MGLTileSourceOption MGLTileSourceOptionAttributionInfos;
  the constants described in `MGLTileCoordinateSystem`.
  
  The default value for this option is `MGLTileCoordinateSystemXYZ`.
+
+ This option corresponds to the `scheme` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern const MGLTileSourceOption MGLTileSourceOptionTileCoordinateSystem;