[ios, macos] Clarify current best practices with animated camera changes

1 files changed, 16 insertions, 8 deletions

diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index e6f66e39ae..6d9b30e467 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -748,7 +748,8 @@ MGL_EXPORT
  Changes the center coordinate of the map and optionally animates the change.
 
  Changing the center coordinate centers the map on the new coordinate without
- changing the current zoom level.
+ changing the current zoom level. For animated changes, wait until the map view has 
+ finished loading before calling this method.
 
  @param coordinate The new center coordinate for the map.
  @param animated Specify `YES` if you want the map view to scroll to the new
@@ -762,7 +763,8 @@ MGL_EXPORT
 
 /**
  Changes the center coordinate and zoom level of the map and optionally animates
- the change.
+ the change. For animated changes, wait until the map view has 
+ finished loading before calling this method.
 
  @param centerCoordinate The new center coordinate for the map.
  @param zoomLevel The new zoom level for the map.
@@ -777,7 +779,8 @@ MGL_EXPORT
 
 /**
  Changes the center coordinate, zoom level, and direction of the map and
- optionally animates the change.
+ optionally animates the change. For animated changes, wait until the map view has 
+ finished loading before calling this method.
 
  @param centerCoordinate The new center coordinate for the map.
  @param zoomLevel The new zoom level for the map.
@@ -794,7 +797,8 @@ MGL_EXPORT
 
 /**
  Changes the center coordinate, zoom level, and direction of the map, calling a
- completion handler at the end of an optional animation.
+ completion handler at the end of an optional animation. For animated changes, 
+ wait until the map view has finished loading before calling this method.
 
  @param centerCoordinate The new center coordinate for the map.
  @param zoomLevel The new zoom level for the map.
@@ -1065,7 +1069,8 @@ MGL_EXPORT
 
 /**
  Moves the viewpoint to a different location with respect to the map with an
- optional transition animation.
+ optional transition animation. For animated changes, wait until the map view has 
+ finished loading before calling this method.
 
  @param camera The new viewpoint.
  @param animated Specify `YES` if you want the map view to animate the change to
@@ -1081,7 +1086,8 @@ MGL_EXPORT
 
 /**
  Moves the viewpoint to a different location with respect to the map with an
- optional transition duration and timing function.
+ optional transition duration and timing function. For animated changes, wait 
+ until the map view has finished loading before calling this method.
 
  @param camera The new viewpoint.
  @param duration The amount of time, measured in seconds, that the transition
@@ -1100,7 +1106,8 @@ MGL_EXPORT
 
 /**
  Moves the viewpoint to a different location with respect to the map with an
- optional transition duration and timing function.
+ optional transition duration and timing function. For animated changes, wait 
+ until the map view has finished loading before calling this method.
 
  @param camera The new viewpoint.
  @param duration The amount of time, measured in seconds, that the transition
@@ -1116,7 +1123,8 @@ MGL_EXPORT
 /**
  Moves the viewpoint to a different location with respect to the map with an
  optional transition duration and timing function, and optionally some additional
- padding on each side.
+ padding on each side. For animated changes, wait until the map view has 
+ finished loading before calling this method.
 
  @param camera The new viewpoint.
  @param duration The amount of time, measured in seconds, that the transition