[ios, macos] Document how to avoid gesture recognizer conflicts (#7816)

* Expand on Gesture Implementation

Adding Gesture info as discussed: https://github.com/mapbox/mapbox-gl-native/issues/2278#issuecomment-273685832

Not sure if using codeblocks is kosher.

* Update styling and verbiage

* More updates

* [ios] -requireGestureRecognizerToFail: seems to be enough

* [macos] Added corresponding macOS documentation

2 files changed, 29 insertions, 0 deletions

diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index 715f3338c3..0d65ea2fb1 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -73,8 +73,22 @@ typedef NS_ENUM(NSUInteger, MGLAnnotationVerticalAlignment) {
  your Mapbox account. They also deter other developers from using your styles
  without your permission.
  
+ Adding your own gesture recognizer to `MGLMapView` will block the corresponding
+ gesture recognizer built into `MGLMapView`. To avoid conflicts, define which
+ gesture takes precedence. For example, you can create your own
+ `UITapGestureRecognizer` that will be invoked only if the default `MGLMapView`
+ tap gesture fails:
+ 
+ ```swift
+ let mapTapGestureRecognizer = UITapGestureRecognizer(target: self, action: #selector(myCustomFunction))
+ for recognizer in mapView.gestureRecognizers! where recognizer is UITapGestureRecognizer {
+     mapTapGestureRecognizer.require(toFail: recognizer)
+ }
+ ```
+ 
  @note You are responsible for getting permission to use the map data and for
  ensuring that your use adheres to the relevant terms of use.
+
  */
 IB_DESIGNABLE
 @interface MGLMapView : UIView
diff --git a/platform/macos/src/MGLMapView.h b/platform/macos/src/MGLMapView.h
index 954e5a2c75..5f34976ca4 100644
--- a/platform/macos/src/MGLMapView.h
+++ b/platform/macos/src/MGLMapView.h
@@ -44,6 +44,21 @@ NS_ASSUME_NONNULL_BEGIN
  your Mapbox account. They also deter other developers from using your styles
  without your permission.
  
+ Adding your own gesture recognizer to `MGLMapView` will block the corresponding
+ gesture recognizer built into `MGLMapView`. To avoid conflicts, define which
+ gesture recognizer takes precedence. For example, you can subclass
+ `NSClickGestureRecognizer` and override `-[NSGestureRecognizer shouldRequireFailureOfGestureRecognizer:]`,
+ so that your subclass will be invoked only if the default `MGLMapView` click
+ gesture recognizer fails:
+ 
+ ```swift
+ class MapClickGestureRecognizer: NSClickGestureRecognizer {
+     override func shouldRequireFailure(of otherGestureRecognizer: NSGestureRecognizer) -> Bool {
+         return otherGestureRecognizer is NSClickGestureRecognizer
+     }
+ }
+ ```
+ 
  @note You are responsible for getting permission to use the map data and for
     ensuring that your use adheres to the relevant terms of use.
  */