[ios] Warn about using MGLFeature-conforming annotations w/querying

2 files changed, 15 insertions, 5 deletions

diff --git a/platform/darwin/docs/guides/Working with GeoJSON Data.md b/platform/darwin/docs/guides/Working with GeoJSON Data.md
index 57aaa3855d..f3b3dc0918 100644
--- a/platform/darwin/docs/guides/Working with GeoJSON Data.md
+++ b/platform/darwin/docs/guides/Working with GeoJSON Data.md
@@ -81,8 +81,10 @@ Linear ring         | `MGLPolygon.coordinates`, `MGLPolygon.interiorPolygons`
 A `Feature` object in GeoJSON corresponds to an instance of an `MGLShape`
 subclass conforming to the `MGLFeature` protocol. There is a distinct
 `MGLFeature`-conforming class for each type of geometry that a GeoJSON feature
-can contain. This allows features to be used as shapes where convenient. For
-example, some features can be added to a map view as annotations.
+can contain. This allows features to be used as raw shapes where convenient. For
+example, some features can be added to a map view as annotations. Note that
+identifiers and attributes will not be available for feature querying when a
+feature is used as an annotation.
 
 In contrast to the GeoJSON standard, it is possible for `MGLShape` subclasses
 other than `MGLPointAnnotation` to straddle the antimeridian.
diff --git a/platform/darwin/src/MGLFeature.h b/platform/darwin/src/MGLFeature.h
index 491c89b608..a13821cf96 100644
--- a/platform/darwin/src/MGLFeature.h
+++ b/platform/darwin/src/MGLFeature.h
@@ -18,15 +18,23 @@ NS_ASSUME_NONNULL_BEGIN
  You can add custom data to display on the map by creating feature objects and
  adding them to an `MGLShapeSource` using the
  `-[MGLShapeSource initWithIdentifier:shape:options:]` method or
- `MGLShapeSource.shape` property. Similarly, you can add `MGLPointFeature`,
- `MGLPolylineFeature`, and `MGLPolygonFeature` objects to the map as annotations
- using `-[MGLMapView addAnnotations:]` and related methods.
+ `MGLShapeSource.shape` property.
 
  In addition to adding data to the map, you can also extract data from the map:
  `-[MGLMapView visibleFeaturesAtPoint:]` and related methods return feature
  objects that correspond to features in the source. This enables you to inspect
  the properties of features in vector tiles loaded by `MGLVectorSource` objects.
  You also reuse these feature objects as overlay annotations.
+
+ While it is possible to add `MGLFeature`-conforming objects to the map as
+ annotations using `-[MGLMapView addAnnotations:]` and related methods, doing so
+ has trade-offs:
+
+ - Features added as annotations will not have `identifier` or `attributes`
+ properties when used with feature querying.
+
+ - Features added as annotations become interactive. Taps and selection can be
+ handled in `-[MGLMapViewDelegate mapView:didSelectAnnotation:]`.
  */
 @protocol MGLFeature <MGLAnnotation>