[ios, macos] Expanded feature querying documentation

Also fixed a couple incorrect Swift method names on macOS.

3 files changed, 62 insertions, 22 deletions

diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 07045490bd..d0097f748e 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -211,18 +211,32 @@ MGL_EXPORT
 @property (nonatomic, copy, nullable) NSURL *URL;
 
 /**
- Returns an array of map features for this source, filtered by the given predicate.
+ Returns an array of map features for this source, filtered by the given
+ predicate.
 
  Each object in the returned array represents a feature for the current style
- and provides access to attributes specified by the source
+ and provides access to attributes specified via the `shape` property.
 
  Features come from tiled GeoJSON data that is converted to tiles internally,
  so feature geometries are clipped at tile boundaries and features
- may appear duplicated across tiles.
-
- @param predicate A predicate to filter the returned features.
+ may appear duplicated across tiles. For example, suppose this source contains a
+ long polyline representing a road. The resulting array includes those parts of
+ the road that lie within the map tiles that the source has loaded, even if the
+ road extends into other tiles. The portion of the road within each map tile is
+ included individually.
+ 
+ Returned features may not necessarily be visible to the user at the time they
+ are loaded: the style may lack a layer that draws the features in question. To
+ obtain only _visible_ features, use the
+ `-[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:predicate:]`
+ or
+ `-[MGLMapView visibleFeaturesInRect:inStyleLayersWithIdentifiers:predicate:]`
+ method.
+
+ @param predicate A predicate to filter the returned features. Use `nil` to
+    include all features in the source.
  @return An array of objects conforming to the `MGLFeature` protocol that
- represent features in the sources used by the current style.
+    represent features in the source that match the predicate.
  */
 - (NS_ARRAY_OF(id <MGLFeature>) *)featuresMatchingPredicate:(nullable NSPredicate *)predicate;
 
diff --git a/platform/darwin/src/MGLTileSource.h b/platform/darwin/src/MGLTileSource.h
index bc29b0f95c..54c756332d 100644
--- a/platform/darwin/src/MGLTileSource.h
+++ b/platform/darwin/src/MGLTileSource.h
@@ -135,6 +135,10 @@ typedef NS_ENUM(NSUInteger, MGLTileCoordinateSystem) {
  A tile source is added to an `MGLStyle` object along with one or more
  `MGLRasterStyleLayer` or `MGLVectorStyleLayer` objects. Use a style layer to
  control the appearance of content supplied by the tile source.
+ 
+ A tile source is also known as a tile set. To learn about the structure of a
+ Mapbox-hosted tile set, view it in
+ <a href="https://www.mapbox.com/studio/tilesets/">Mapbox Studio’s Tilesets editor</a>.
 
  Do not create instances of this class directly, and do not create your own
  subclasses of this class. Instead, create instances of `MGLRasterSource` and
diff --git a/platform/darwin/src/MGLVectorSource.h b/platform/darwin/src/MGLVectorSource.h
index 8634316809..83926fd287 100644
--- a/platform/darwin/src/MGLVectorSource.h
+++ b/platform/darwin/src/MGLVectorSource.h
@@ -26,6 +26,12 @@ NS_ASSUME_NONNULL_BEGIN
  (<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.
+ 
+ Commonly used vector sources include
+ <a href="https://www.mapbox.com/vector-tiles/mapbox-streets/">Mapbox Streets</a>,
+ <a href="https://www.mapbox.com/vector-tiles/mapbox-terrain/">Mapbox Terrain</a>,
+ and
+ <a href="https://www.mapbox.com/vector-tiles/mapbox-traffic-v1/">Mapbox Traffic</a>.
 
  ### Example
 
@@ -52,23 +58,39 @@ MGL_EXPORT
 #pragma mark Accessing a Source’s Content
 
 /**
- Returns an array of map features loaded by this source, restricted to the
- given source layers and filtered by the given predicate.
-
- Each object in the returned array represents a feature for the
- current style and provides access to attributes specified by the
- <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">source</a>.
-
- Features come from tiled vector data that is converted to tiles internally,
- so feature geometries are clipped at tile boundaries and features
- may appear duplicated across tiles.
-
- @param sourceLayerIdentifiers The source layers to include in the query. Only the
-    features contained in these source layers are included in the returned array. At
-    least one source layer is required.
- @param predicate A predicate to filter the returned features.
+ Returns an array of map features loaded by this source, restricted to the given
+ source layers and filtered by the given predicate.
+
+ Each object in the returned array represents a feature loaded by the source and
+ provides access to attributes specified as part of the loaded feature. The
+ source loads a feature if the source is added to an `MGLMapView`’s style; that
+ style has a layer that uses the source; and the map view has recently scrolled
+ to the region containing the feature.
+
+ Features come from tiled vector data that is converted to tiles internally, so
+ feature geometries are clipped at tile boundaries and features may appear
+ duplicated across tiles. For example, suppose part of a lengthy polyline
+ representing a road has recently scrolled into view. The resulting array
+ includes those parts of the road that lie within the map tiles that the source
+ has loaded, even if the road extends into other tiles. The portion of the road
+ within each map tile is included individually.
+ 
+ Returned features may not necessarily be visible to the user at the time they
+ are loaded: the style may contain a layer that forces the source’s tiles to
+ load but filters out the features in question, preventing them from being
+ drawn. To obtain only _visible_ features, use the
+ `-[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:predicate:]`
+ or
+ `-[MGLMapView visibleFeaturesInRect:inStyleLayersWithIdentifiers:predicate:]`
+ method.
+
+ @param sourceLayerIdentifiers The source layers to include in the query. Only
+    the features contained in these source layers are included in the returned
+    array. This array may not be empty.
+ @param predicate A predicate to filter the returned features. Use `nil` to
+    include all loaded features.
  @return An array of objects conforming to the `MGLFeature` protocol that
-    represent features in the sources used by the current style.
+    represent features loaded by the source that match the predicate.
  */
 - (NS_ARRAY_OF(id <MGLFeature>) *)featuresInSourceLayersWithIdentifiers:(NS_SET_OF(NSString *) *)sourceLayerIdentifiers predicate:(nullable NSPredicate *)predicate NS_SWIFT_NAME(features(sourceLayerIdentifiers:predicate:));