[ios, macos] Additional documentation changes.upstream/jrex-3249-fit-annotation

3 files changed, 23 insertions, 10 deletions

diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
index f7e604a91f..e281425905 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -37,7 +37,7 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 * Improved performance of `MGLAnnotationView`-backed annotations that have `scalesWithViewingDistance` enabled. ([#10951](https://github.com/mapbox/mapbox-gl-native/pull/10951))
 * Fix an issue where a wrong annotation may selected if annotations were set close together. ([#11438](https://github.com/mapbox/mapbox-gl-native/pull/11438))
 * The `MGLMapView.selectedAnnotations` property (backed by `-[MGLMapView setSelectedAnnotations:]`) now selects annotations that are off-screen. ([#9790](https://github.com/mapbox/mapbox-gl-native/issues/9790))
-* The `animated` parameter to `-[MGLMapView selectAnnotation:animated:]` now controls whether the annotation and its callout are brought on-screen. If `animated` is `NO` then the annotation is selected if offscreen, but the map is not panned. Currently only point annotations are supported. Setting the `MGLMapView.selectedAnnotations` property now animates (matching macOS). ([#3249](https://github.com/mapbox/mapbox-gl-native/issues/3249))
+* The `animated` parameter to `-[MGLMapView selectAnnotation:animated:]` now controls whether the annotation and its callout are brought on-screen. If `animated` is `NO` then the annotation is selected if offscreen, but the map is not panned. Currently only point annotations are supported. Setting the `MGLMapView.selectedAnnotations` property now animates. ([#3249](https://github.com/mapbox/mapbox-gl-native/issues/3249))
 
 ### Map snapshots
 
diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index eb6cf85e39..2d566f26a0 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -1201,25 +1201,31 @@ MGL_EXPORT IB_DESIGNABLE
  Assigning a new array to this property selects only the first annotation in
  the array.
 
- @note In versions prior to `4.0.0` if the annotation was offscreen it was not selected.
+ If the annotation is of type `MGLPointAnnotation` and is offscreen, the camera
+ will animate to bring the annotation and its callout just on screen. If you
+ need finer control, consider using `-selectAnnotation:animated:`.
+
+ @note In versions prior to `4.0.0` if the annotation was offscreen it was not
+ selected.
  */
 @property (nonatomic, copy) NS_ARRAY_OF(id <MGLAnnotation>) *selectedAnnotations;
 
 /**
  Selects an annotation and displays its callout view.
 
- The `animated` parameter determines whether the map is panned to bring the annotation on-screen,
- specifically:
+ The `animated` parameter determines whether the map is panned to bring the
+ annotation on-screen, specifically:
 
  | `animated` parameter | Effect |
  |------------------|--------|
  | `NO`             | The annotation is selected, and the callout is presented. However the map is not panned to bring the annotation or callout onscreen. The presentation of the callout is animated. |
- | `YES`            | The annotation is selected, and the callout is presented. If the annotation is offscreen, the map is panned so that the annotation and its callout are brought just onscreen. The annotation is *not* centered within the viewport. |
+ | `YES`            | The annotation is selected, and the callout is presented. If the annotation is offscreen *and* is of type `MGLPointAnnotation`, the map is panned so that the annotation and its callout are brought just onscreen. The annotation is *not* centered within the viewport. |
 
  @param annotation The annotation object to select.
  @param animated If `YES`, the annotation and callout view are animated on-screen.
 
- @note In versions prior to `4.0.0` selecting an offscreen annotation did not change the camera.
+ @note In versions prior to `4.0.0` selecting an offscreen annotation did not
+ change the camera.
  */
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
 
diff --git a/platform/macos/src/MGLMapView.h b/platform/macos/src/MGLMapView.h
index 786f1cf3a1..74224622d4 100644
--- a/platform/macos/src/MGLMapView.h
+++ b/platform/macos/src/MGLMapView.h
@@ -722,19 +722,26 @@ MGL_EXPORT IB_DESIGNABLE
  Assigning a new array to this property selects only the first annotation in the
  array.
 
- @note In versions prior to `4.0.0` if the annotation was offscreen it was not selected.
+ If the annotation is of type `MGLPointAnnotation` and is offscreen, the map is
+ panned so that the annotation and its callout are brought just onscreen. The
+ annotation is *not* centered within the viewport.
+
+ @note In versions prior to `4.0.0` if the annotation was offscreen it was not
+ selected.
  */
 @property (nonatomic, copy) NS_ARRAY_OF(id <MGLAnnotation>) *selectedAnnotations;
 
 /**
  Selects an annotation and displays a callout popover for it.
 
- If the annotation is offscreen, the map is panned so that the annotation and its callout are brought
- just onscreen. The annotation is *not* centered within the viewport.
+ If the annotation is of type `MGLPointAnnotation` and is offscreen, the map is
+ panned so that the annotation and its callout are brought just onscreen. The
+ annotation is *not* centered within the viewport.
 
  @param annotation The annotation object to select.
 
- @note In versions prior to `4.0.0` selecting an offscreen annotation did not change the camera.
+ @note In versions prior to `4.0.0` selecting an offscreen annotation did not
+ change the camera.
  */
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation;