[ios, macos] Clarify redrawing based on multipoint mutation

Clarified the documentation for various MGLMultiPoint methods to indicate that only shape annotations automatically redraw in response to the multipoint object being mutated; sources must be mutated explicitly.

1 files changed, 30 insertions, 10 deletions

diff --git a/platform/darwin/src/MGLMultiPoint.h b/platform/darwin/src/MGLMultiPoint.h
index ca08e5405a..429bbdb22d 100644
--- a/platform/darwin/src/MGLMultiPoint.h
+++ b/platform/darwin/src/MGLMultiPoint.h
@@ -58,8 +58,12 @@ MGL_EXPORT
 - (void)setCoordinates:(CLLocationCoordinate2D *)coords count:(NSUInteger)count;
 
 /**
- Inserts the given vertices into the shape. If the shape is currently visible on
- the map, it is redrawn immediately.
+ Inserts the given vertices into the shape.
+ 
+ If the shape is currently visible on the map as an annotation, it is redrawn
+ immediately. If the shape is part of an `MGLShapeSource` object, you must
+ explicitly set the `MGLShapeSource.shape` property in order for any style
+ layers that use the source to be redrawn.
 
  @param coords The array of coordinates to insert into the shape. The data in
     this array is copied to the shape’s `coordinates` property.
@@ -70,8 +74,12 @@ MGL_EXPORT
 - (void)insertCoordinates:(const CLLocationCoordinate2D *)coords count:(NSUInteger)count atIndex:(NSUInteger)index;
 
 /**
- Appends the given vertices to the shape. If the shape is currently visible on
- the map, it is redrawn immediately.
+ Appends the given vertices to the shape.
+ 
+ If the shape is currently visible on the map as an annotation, it is redrawn
+ immediately. If the shape is part of an `MGLShapeSource` object, you must
+ explicitly set the `MGLShapeSource.shape` property in order for any style
+ layers that use the source to be redrawn.
 
  @param coords The array of coordinates to add to the shape. The data in this
     array is copied to the shape’s `coordinates` property.
@@ -81,8 +89,12 @@ MGL_EXPORT
 
 /**
  Replaces the vertices at the given range in the shape with the same number of
- vertices from a given C array. If the shape is currently visible on the map, it
- is redrawn immediately.
+ vertices from a given C array.
+ 
+ If the shape is currently visible on the map as an annotation, it is redrawn
+ immediately. If the shape is part of an `MGLShapeSource` object, you must
+ explicitly set the `MGLShapeSource.shape` property in order for any style
+ layers that use the source to be redrawn.
 
  The number of coordinates in `coords` must be equal to the length of `range`.
  If you want to insert or delete one or more vertices, use the
@@ -103,8 +115,12 @@ MGL_EXPORT
 
 /**
  Replaces the vertices at the given range in the shape with the specified number
- of vertices from a given C array. If the shape is currently visible on the map,
- it is redrawn immediately.
+ of vertices from a given C array.
+ 
+ If the shape is currently visible on the map as an annotation, it is redrawn
+ immediately. If the shape is part of an `MGLShapeSource` object, you must
+ explicitly set the `MGLShapeSource.shape` property in order for any style
+ layers that use the source to be redrawn.
 
  If `count` is greater than the `length` field of `range`, some vertices will
  effectively be inserted into the shape. On the other hand, if `count` is less
@@ -128,8 +144,12 @@ MGL_EXPORT
 - (void)replaceCoordinatesInRange:(NSRange)range withCoordinates:(const CLLocationCoordinate2D *)coords count:(NSUInteger)count;
 
 /**
- Removes the vertices at the given range from the shape. If the shape is
- currently visible on the map, it is redrawn immediately.
+ Removes the vertices at the given range from the shape.
+ 
+ If the shape is currently visible on the map as an annotation, it is redrawn
+ immediately. If the shape is part of an `MGLShapeSource` object, you must
+ explicitly set the `MGLShapeSource.shape` property in order for any style
+ layers that use the source to be redrawn.
 
  If `range` extends beyond the shape’s `coordinates` property, an
  `NSRangeException` is raised.