[ios, macos] Expanded source documentation

Also fixed a few stray references to GeoJSON sources.

9 files changed, 64 insertions, 34 deletions

diff --git a/platform/darwin/src/MGLAttributionInfo.h b/platform/darwin/src/MGLAttributionInfo.h
index c0cb1578b5..84552722c9 100644
--- a/platform/darwin/src/MGLAttributionInfo.h
+++ b/platform/darwin/src/MGLAttributionInfo.h
@@ -8,7 +8,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  Information about an attribution statement, usually a copyright or trademark
- statement, associated with a map source.
+ statement, associated with a map content source.
  */
 @interface MGLAttributionInfo : NSObject
 
diff --git a/platform/darwin/src/MGLRasterSource.h b/platform/darwin/src/MGLRasterSource.h
index 78f5af8a6a..2940f05371 100644
--- a/platform/darwin/src/MGLRasterSource.h
+++ b/platform/darwin/src/MGLRasterSource.h
@@ -8,10 +8,12 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- A raster tile source.
- 
- @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-raster">The
- style specification.</a>
+ `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
+ appearance of content supplied by the raster source.
  */
 @interface MGLRasterSource : MGLSource
 
@@ -24,6 +26,9 @@ NS_ASSUME_NONNULL_BEGIN
  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>`).
+ 
  @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
@@ -56,8 +61,8 @@ NS_ASSUME_NONNULL_BEGIN
  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>`).
+ 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>
diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 5067466e6d..407d9c45a1 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -57,10 +57,15 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionBuffer;
 extern const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
 
 /**
- A shape source.
-
- @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson">The
-    style specification.</a>
+ `MGLShapeSource` is a map content source that supplies vector shapes to be
+ shown on the map. The shapes may be instances of `MGLShape` or `MGLFeature`,
+ or they may be defined by local or external
+ <a href="http://geojson.org/">GeoJSON</a> code. A shape source is added to an
+ `MGLStyle` object along with an `MGLVectorStyleLayer` object. The vector style
+ layer defines the appearance of any content supplied by the shape source.
+ 
+ Any vector style layer initialized with a shape source should have a `nil`
+ value in its `sourceLayerIdentifier` property.
  */
 @interface MGLShapeSource : MGLSource
 
@@ -109,12 +114,12 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
 #pragma mark Accessing a Source’s Content
 
 /**
- The contents of the source. A shape can represent a GeoJSON geometry, a feature, 
- or a collection of features.
+ The contents of the source. A shape can represent a GeoJSON geometry, a
+ feature, or a collection of features.
 
- If the receiver was initialized using `-initWithIdentifier:URL:options:`, this property
- is set to `nil`. This property is unavailable until the receiver is passed into
- `-[MGLStyle addSource]`.
+ If the receiver was initialized using `-initWithIdentifier:URL:options:`, this
+ property is set to `nil`. This property is unavailable until the receiver is
+ passed into `-[MGLStyle addSource]`.
  */
 @property (nonatomic, nullable) MGLShape *shape;
 
@@ -135,8 +140,8 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
 /**
  The URL to the GeoJSON document that specifies the contents of the source.
 
- If the receiver was initialized using `-initWithIdentifier:geoJSONData:options`, 
- this property is set to `nil`.
+ If the receiver was initialized using
+ `-initWithIdentifier:geoJSONData:options`, this property is set to `nil`.
  */
 @property (nonatomic, nullable) NSURL *URL;
 
diff --git a/platform/darwin/src/MGLSource.h b/platform/darwin/src/MGLSource.h
index ec3733bf08..f0a8aacecb 100644
--- a/platform/darwin/src/MGLSource.h
+++ b/platform/darwin/src/MGLSource.h
@@ -1,12 +1,20 @@
 #import <Foundation/Foundation.h>
 
 /**
- A source supplies data to be shown on the map. Sources don't contain styling 
- details like color or width. Use subclasses of `MGLStyleLayer` to give visual
- representation to sources.
+ `MGLSource` is an abstract base class for map content sources. A map content
+ source supplies content to be shown on the map. A source is added to an
+ `MGLStyle` object along with an `MGLForegroundStyleLayer` object. The
+ foreground style layer defines the appearance of any content supplied by the
+ source.
  
- You should use the concrete subclasses of `MGLSource` to create vector, 
- raster, GeoJSON, and other source types.
+ Each source defined by the style JSON file is represented at runtime by an
+ `MGLSource` object that you can use to refine the map’s content. You can also
+ add and remove sources dynamically using methods such as
+ `-[MGLStyle addSource:]` and `-[MGLStyle sourceWithIdentifier:]`.
+ 
+ Do not create instances of this class directly, and do not create your own
+ subclasses of this class. Instead, create instances of `MGLRasterSource`,
+ `MGLShapeSource`, and `MGLVectorSource`.
  */
 @interface MGLSource : NSObject
 
diff --git a/platform/darwin/src/MGLVectorSource.h b/platform/darwin/src/MGLVectorSource.h
index 6cfab09489..758b4c993f 100644
--- a/platform/darwin/src/MGLVectorSource.h
+++ b/platform/darwin/src/MGLVectorSource.h
@@ -6,10 +6,19 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- A vector tile source. Tiles must be in Mapbox Vector Tile format.
+ `MGLVectorSource` is a map content source that supplies tiled vector data in
+ <a href="https://www.mapbox.com/vector-tiles/">Mapbox Vector Tile</a> format to
+ be shown on the map. The location of and metadata about the vector tiles are
+ defined by either an `MGLTileSet` object or an external TileJSON resource. A
+ vector source is added to an `MGLStyle` object along with an
+ `MGLVectorStyleLayer` object. The vector style layer defines the appearance of
+ any content supplied by the vector source.
  
- @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-vector">The
-    style specification.</a>
+ Within each vector tile, each geometric coordinate must lie between
+ −1&nbsp;×&nbsp;<var>extent</var> and
+ (<var>extent</var>&nbsp;×&nbsp;2)&nbsp;−&nbsp;1, inclusive. Any vector style
+ layer initialized with a vector source must have a non-`nil` value in its
+ `sourceLayerIdentifier` property.
  */
 @interface MGLVectorSource : MGLSource
 
@@ -21,6 +30,9 @@ NS_ASSUME_NONNULL_BEGIN
  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>`).
+ 
  @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
@@ -48,8 +60,8 @@ NS_ASSUME_NONNULL_BEGIN
  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>`).
+ 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>`).
  
  If the receiver was initialized using `-initWithIdentifier:tileSet:`, this
  property is set to `nil`.
diff --git a/platform/darwin/test/MGLStyleTests.mm b/platform/darwin/test/MGLStyleTests.mm
index f2151988b9..0dd6e98c5d 100644
--- a/platform/darwin/test/MGLStyleTests.mm
+++ b/platform/darwin/test/MGLStyleTests.mm
@@ -121,7 +121,7 @@
 }
 
 - (void)testAddingSourcesTwice {
-    MGLShapeSource *shapeSource = [[MGLShapeSource alloc] initWithIdentifier:@"geoJSONSource" shape:nil options:nil];
+    MGLShapeSource *shapeSource = [[MGLShapeSource alloc] initWithIdentifier:@"shapeSource" shape:nil options:nil];
     [self.style addSource:shapeSource];
     XCTAssertThrowsSpecificNamed([self.style addSource:shapeSource], NSException, @"MGLRedundantSourceException");
 
@@ -143,7 +143,7 @@
 }
 
 - (void)testAddingLayersTwice {
-    MGLShapeSource *source = [[MGLShapeSource alloc] initWithIdentifier:@"geoJSONSource" shape:nil options:nil];
+    MGLShapeSource *source = [[MGLShapeSource alloc] initWithIdentifier:@"shapeSource" shape:nil options:nil];
 
     MGLBackgroundStyleLayer *backgroundLayer = [[MGLBackgroundStyleLayer alloc] initWithIdentifier:@"backgroundLayer"];
     [self.style addLayer:backgroundLayer];
diff --git a/platform/darwin/test/MGLStyleValueTests.swift b/platform/darwin/test/MGLStyleValueTests.swift
index 2d2792fdc0..e529af0634 100644
--- a/platform/darwin/test/MGLStyleValueTests.swift
+++ b/platform/darwin/test/MGLStyleValueTests.swift
@@ -22,8 +22,8 @@ extension MGLStyleValueTests {
     }
     
     func testFunctions() {
-        let geoJSONSource = MGLShapeSource(identifier: "test", shape: nil, options: nil)
-        let symbolStyleLayer = MGLSymbolStyleLayer(identifier: "test", source: geoJSONSource)
+        let shapeSource = MGLShapeSource(identifier: "test", shape: nil, options: nil)
+        let symbolStyleLayer = MGLSymbolStyleLayer(identifier: "test", source: shapeSource)
         
         // Boolean
         let stops: [NSNumber: MGLStyleValue<NSNumber>] = [
diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
index 5c63bdd2f5..565b709214 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -14,7 +14,7 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 
 * A new runtime styling API allows you to adjust the style and content of the base map dynamically. All the options available in [Mapbox Studio](https://www.mapbox.com/studio/) are now exposed via MGLStyle and subclasses of MGLStyleLayer and MGLSource. ([#5727](https://github.com/mapbox/mapbox-gl-native/pull/5727))
 * MGLMapView’s `styleURL` property can now be set to an absolute file URL. ([#6026](https://github.com/mapbox/mapbox-gl-native/pull/6026))
-* GeoJSON sources specified by the stylesheet at design time now support `cluster`, `clusterMaxZoom`, and `clusterRadius` attributes for clustering point features on the base map. ([#5724](https://github.com/mapbox/mapbox-gl-native/pull/5724))
+* MGLShapeSource objects, as well as GeoJSON sources specified by the stylesheet at design time, now support `cluster`, `clusterMaxZoom`, and `clusterRadius` attributes for clustering point features on the base map. ([#5724](https://github.com/mapbox/mapbox-gl-native/pull/5724))
 * Added [quadkey](https://msdn.microsoft.com/en-us/library/bb259689.aspx) support and limited WMS support in raster tile URL templates. ([#5628](https://github.com/mapbox/mapbox-gl-native/pull/5628))
 * TileJSON manifests can now specify `"scheme": "tms"` to indicate the use of [TMS](https://en.wikipedia.org/wiki/Tile_Map_Service) coordinates. ([#2270](https://github.com/mapbox/mapbox-gl-native/pull/2270))
 * Fixed an issue causing abstract MGLMultiPointFeature objects to be returned in feature query results. Now concrete MGLPointCollectionFeature objects are returned. ([#6742](https://github.com/mapbox/mapbox-gl-native/pull/6742))
diff --git a/platform/macos/CHANGELOG.md b/platform/macos/CHANGELOG.md
index ab85890edb..8482cc5e0b 100644
--- a/platform/macos/CHANGELOG.md
+++ b/platform/macos/CHANGELOG.md
@@ -13,7 +13,7 @@
 
 * A new runtime styling API allows you to adjust the style and content of the base map dynamically. All the options available in [Mapbox Studio](https://www.mapbox.com/studio/) are now exposed via MGLStyle and subclasses of MGLStyleLayer and MGLSource. ([#5727](https://github.com/mapbox/mapbox-gl-native/pull/5727))
 * MGLMapView’s `styleURL` property can now be set to an absolute file URL. ([#6026](https://github.com/mapbox/mapbox-gl-native/pull/6026))
-* GeoJSON sources specified by the stylesheet at design time now support `cluster`, `clusterMaxZoom`, and `clusterRadius` attributes for clustering point features on the base map. ([#5724](https://github.com/mapbox/mapbox-gl-native/pull/5724))
+* MGLShapeSource objects, as well as GeoJSON sources specified by the stylesheet at design time, now support `cluster`, `clusterMaxZoom`, and `clusterRadius` attributes for clustering point features on the base map. ([#5724](https://github.com/mapbox/mapbox-gl-native/pull/5724))
 * TileJSON manifests can now specify `"scheme": "tms"` to indicate the use of [TMS](https://en.wikipedia.org/wiki/Tile_Map_Service) coordinates. ([#2270](https://github.com/mapbox/mapbox-gl-native/pull/2270))
 * Fixed an issue causing abstract `MGLMultiPointFeature` objects to be returned in feature query results. Now concrete `MGLPointCollectionFeature` objects are returned. ([#6742](https://github.com/mapbox/mapbox-gl-native/pull/6742))
 * Fixed rendering artifacts and missing glyphs that occurred after viewing a large number of CJK characters on the map. ([#5908](https://github.com/mapbox/mapbox-gl-native/pull/5908))