[ios] Additional comments about single tap delegate method vs gestures.

2 files changed, 25 insertions, 2 deletions

diff --git a/platform/ios/app/MBXViewController.m b/platform/ios/app/MBXViewController.m
index 8146e62a89..03931170c4 100644
--- a/platform/ios/app/MBXViewController.m
+++ b/platform/ios/app/MBXViewController.m
@@ -207,6 +207,12 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
 
     // Add fall-through single tap gesture recognizer. This will be called when
     // the map view's tap recognizers fail.
+
+    // NOTE: Since MBXViewController implements `mapView:didSingleTapAtCoordinate` the following
+    // gesture recognizer WILL NOT be triggered, since the default single tap gesture does not fail.
+    //
+    // If you need a custom tap gesture to be trigger consider not implementing `mapView:didSingleTapAtCoordinate`
+
     UITapGestureRecognizer *singleTap = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleSingleTap:)];
     for (UIGestureRecognizer *gesture in self.mapView.gestureRecognizers) {
         if ([gesture isKindOfClass:[UITapGestureRecognizer class]]) {
diff --git a/platform/ios/src/MGLMapViewDelegate.h b/platform/ios/src/MGLMapViewDelegate.h
index dd5eb68d88..1ed6c4e01a 100644
--- a/platform/ios/src/MGLMapViewDelegate.h
+++ b/platform/ios/src/MGLMapViewDelegate.h
@@ -171,11 +171,28 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Tells the delegate that the user has tapped on the map view.
 
+ This method will not be called when the user single taps on an annotation, or if an annotation
+ is currently selected.
+
  @param mapView The map view that was tapped.
  @param coordinate Location of tap in world coordinates.
 
- @note This method will not be called when the user single taps on an annotation, or if an annotation
- is currently selected.
+ @note If  you implement this method, custom tap gesture recognizers that are installed in the following
+ way
+
+```
+UITapGestureRecognizer *singleTap = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleSingleTap:)];
+for (UIGestureRecognizer *gesture in self.mapView.gestureRecognizers)
+{
+    if ([gesture isKindOfClass:[UITapGestureRecognizer class]])
+    {
+        [singleTap requireGestureRecognizerToFail:gesture];
+    }
+}
+[self.mapView addGestureRecognizer:singleTap];
+```
+
+ will fail to trigger, since the built-in single tap recognizer will no longer fail.
  */
 - (void)mapView:(MGLMapView *)mapView didSingleTapAtCoordinate:(CLLocationCoordinate2D)coordinate;