[ios, macos] Rewrote MGLMapViewDelegate, MGLAnnotationView docs

Reorganized MGLMapViewDelegate and MGLAnnotationView symbols into sections by task. Wrapped documentation comments at column 80 for readability.

Added documentation for -mapViewWillStartRenderingFrame: and -mapViewDidFinishRenderingFrame:fullyRendered:, which are supported and behave as expected (except for the part that has been left undocumented). Synchronized iOS and macOS documentation for MGLMapViewDelegate. Added cross-references between annotation image and annotation view delegate methods and among the various callout delegate methods.

Added missing MGLAnnotationViewDragState documentation and also added the symbol to jazzy’s table of contents. Rewrote MGLAnnotationView documentation.

4 files changed, 515 insertions, 175 deletions

diff --git a/platform/ios/jazzy.yml b/platform/ios/jazzy.yml
index b9eabe8304..aec0d5fe9f 100644
--- a/platform/ios/jazzy.yml
+++ b/platform/ios/jazzy.yml
@@ -34,6 +34,7 @@ custom_categories:
       - MGLAnnotationImage
       - MGLAnnotationVerticalAlignment
       - MGLAnnotationView
+      - MGLAnnotationViewDragState
       - MGLCalloutView
       - MGLCalloutViewDelegate
       - MGLMultiPoint
diff --git a/platform/ios/src/MGLAnnotationView.h b/platform/ios/src/MGLAnnotationView.h
index 18e4985884..1c8704e181 100644
--- a/platform/ios/src/MGLAnnotationView.h
+++ b/platform/ios/src/MGLAnnotationView.h
@@ -6,112 +6,241 @@ NS_ASSUME_NONNULL_BEGIN
 
 @protocol MGLAnnotation;
 
+/** These constants indicate the current drag state of an annotation view. **/
 typedef NS_ENUM(NSUInteger, MGLAnnotationViewDragState) {
-    MGLAnnotationViewDragStateNone = 0,     // View is sitting on the map.
-    MGLAnnotationViewDragStateStarting,     // View is beginning to drag.
-    MGLAnnotationViewDragStateDragging,     // View is being dragged.
-    MGLAnnotationViewDragStateCanceling,    // View dragging was cancelled and will be returned to its starting positon.
-    MGLAnnotationViewDragStateEnding        // View was dragged.
+    /**
+     The view is not involved in a drag operation.
+     */
+    MGLAnnotationViewDragStateNone = 0,
+    /**
+     An action occurred that indicated the view should begin dragging.
+     
+     The map view automatically moves draggable annotation views to this state
+     in response to the dragging the view after pressing and holding on it.
+     */
+    MGLAnnotationViewDragStateStarting,
+    /**
+     The view is in the midst of a drag operation and is actively tracking the
+     user’s gesture.
+     */
+    MGLAnnotationViewDragStateDragging,
+    /**
+     An action occurred that indicated the view should cancel the drag
+     operation.
+     */
+    MGLAnnotationViewDragStateCanceling,
+    /**
+     An action occurred that indicated the view was dropped by the user.
+     
+     The map view automatically moves annotation views to this state in response
+     to the user lifting their finger at the end of a drag gesture.
+     */
+    MGLAnnotationViewDragStateEnding,
 };
 
-/** The MGLAnnotationView class is responsible for representing point-based annotation markers as a view. Annotation views represent an annotation object, which is an object that corresponds to the MGLAnnotation protocol. When an annotation’s coordinate point is visible on the map view, the map view delegate is asked to provide a corresponding annotation view. If an annotation view is created with a reuse identifier, the map view may recycle the view when it goes offscreen. */
+/**
+ The `MGLAnnotationView` class is responsible for marking a point annotation
+ with a view. Annotation views represent an annotation object, which is an
+ object that corresponds to the `MGLAnnotation` protocol. When an annotation’s
+ geographic coordinate is visible in the map view, the map view asks its
+ delegate to a corresponding annotation view. If an annotation view is created
+ with a reuse identifier, the map view may recycle the view when it goes
+ offscreen.
+ 
+ Annotation views are compatible with UIKit, Core Animation, and other Cocoa
+ Touch frameworks. On the other hand, if you do not need animation or
+ interactivity such as dragging, you can use an `MGLAnnotationImage` instead to
+ conserve memory and optimize drawing performance.
+ */
 @interface MGLAnnotationView : UIView
 
+#pragma mark Initializing and Preparing the View
+
 /**
  Initializes and returns a new annotation view object.
  
- @param reuseIdentifier The string that identifies that this annotation view is reusable.
+ The reuse identifier provides a way for you to improve performance by recycling
+ annotation views as they enter and leave the map’s viewport. As an annotation
+ leaves the viewport, the map view moves its associated view to a reuse queue.
+ When a new annotation becomes visible, you can request a view for that
+ annotation by passing the appropriate reuse identifier string to the
+ `-[MGLMapView dequeueReusableAnnotationViewWithIdentifier:` method.
+ 
+ @param reuseIdentifier A unique string identifier for this view that allows you
+    to reuse this view with multiple similar annotations. You can set this
+    parameter to `nil` if you don’t intend to reuse the view, but it is a good
+    idea in general to specify a reuse identifier to avoid creating redundant
+    views.
  @return The initialized annotation view object.
  */
 - (instancetype)initWithReuseIdentifier:(nullable NSString *)reuseIdentifier;
 
 /**
- This property will be set to the associated annotation when the view is visible.
+ Called when the view is removed from the reuse queue.
+ 
+ The default implementation of this method does nothing. You can override it in
+ your custom annotation view implementation to put the view in a known state
+ before it is returned to your map view delegate.
+ */
+- (void)prepareForReuse;
+
+/**
+ The annotation object currently associated with the view.
  
- When the view is queued and waiting to be reused, the value will be set to nil.
+ You should not change the value of this property directly. This property
+ contains a non-`nil` value while the annotation view is visible on the map. If
+ the view is queued, waiting to be reused, the value is `nil`.
  */
 @property (nonatomic, readonly, nullable) id <MGLAnnotation> annotation;
 
 /**
- The string that identifies that this annotation view is reusable. (read-only)
+ The string that identifies that this annotation view is reusable.
  
- You specify the reuse identifier when you create the view. You use the identifier later to retrieve an annotation view that was
- created previously but which is currently unused because its annotation is not on screen.
+ You specify the reuse identifier when you create the view. You use the
+ identifier later to retrieve an annotation view that was created previously but
+ which is currently unused because its annotation is not on-screen.
  
- If you define distinctly different types of annotations (with distinctly different annotation views to go with them), you can
- differentiate between the annotation types by specifying different reuse identifiers for each one.
+ If you define distinctly different types of annotations (with distinctly
+ different annotation views to go with them), you can differentiate between the
+ annotation types by specifying different reuse identifiers for each one.
  */
 @property (nonatomic, readonly, nullable) NSString *reuseIdentifier;
 
+#pragma mark Configuring the Appearance
+
 /**
- Annotation view is centered at the coordinate point of the associated annotation.
+ The offset, measured in points, at which to place the center of the view.
+ 
+ By default, the center point of an annotation view is placed at the geographic
+ coordinate point of the associated annotation. If you do not want the view to
+ be centered, you can use this property to reposition the view. The offset’s
+ `dx` and `dy` values are measured in points. Positive offset values move the
+ annotation view down and to the right, while negative values move it up and to
+ the left.
  
- By changing this property you can reposition the view as needed. The offset is measured in points.
- Positive offset moves the annotation view towards the bottom right, while negative offset moves it towards the top left.
+ Set the offset if the annotation view’s visual center point is somewhere other
+ than the logical center of the view. For example, the view may contain an image
+ that depicts a downward-pointing pushpin or thumbtack, with the tip positioned
+ at the center-bottom of the view. In that case, you would set the offset’s `dx`
+ to zero and its `dy` to half the height of the view.
  */
 @property (nonatomic) CGVector centerOffset;
 
-
 /**
- Setting this property to YES will force the annotation view to tilt according to the associated map view.
+ A Boolean value indicating whether the view lies flat against the map as it
+ tilts.
+ 
+ If this option is unset, the annotation view remains unchanged as the map’s
+ pitch increases, so that the view appears to stand upright on the tilted map.
+ If this option is set, the annotation view tilts as the map’s pitch increases,
+ so that the view appears to lie flat against the tilted map.
+ 
+ For example, you would set this option if the annotation view depicts an arrow
+ that should always point due south. You would unset this option if the arrow
+ should always point down towards the ground.
  */
 @property (nonatomic, assign, getter=isFlat) BOOL flat;
 
 /**
- Defaults to NO and becomes YES when the view is tapped on.
+ A Boolean value that determines whether the annotation view grows and shrinks
+ as the distance between the viewpoint and the annotation view changes on a
+ tilted map.
+ 
+ When the value of this property is `YES` and the map is tilted, the annotation
+ view appears smaller if it is towards the top of the view (closer to the
+ horizon) and larger if it is towards the bottom of the view (closer to the
+ viewpoint). This is also the behavior of `MGLAnnotationImage` objects. When the
+ value of this property is `NO` or the map’s pitch is zero, the annotation view
+ remains the same size regardless of its position on-screen.
  
- Selecting another view will first deselect the currently selected view.
- This property should not be changed directly.
+ The default value of this property is `YES`. Set this property to `NO` if the
+ view’s legibility is important.
+ */
+@property (nonatomic, assign, getter=isScaledWithViewingDistance) BOOL scalesWithViewingDistance;
+
+#pragma mark Managing the Selection State
+
+/**
+ A Boolean value indicating whether the annotation view is currently selected.
+ 
+ You should not set the value of this property directly. If the property is set
+ to `YES`, the annotation view is displaying a callout.
+ 
+ By default, this property is set to `NO` and becomes `YES` when the user taps
+ the view. Selecting another annotation, whether it is associated with an
+ `MGLAnnotationView` or `MGLAnnotationImage` object, deselects any currently
+ selected view.
+ 
+ Setting this property changes the view’s appearance to reflect the new value
+ immediately. If you want the change to be animated, use the
+ `-setSelected:animated:` method instead.
  */
 @property (nonatomic, assign, getter=isSelected) BOOL selected;
 
 /**
- Subclasses may override this method in order to customize appearance.
- This method should not be called directly.
+ Sets the selection state of the annotation view with an optional animation.
+ 
+ You should not call this method directly. A map view calls this method in
+ response to user interactions with the annotation. Subclasses may override this
+ method in order to customize the appearance of the view depending on its
+ selection state.
+ 
+ @param selected `YES` if the view should display itself as selected; `NO`
+    if it should display itself as unselected.
+ @param animated `YES` if the change in selection state is animated; `NO` if the
+    change is immediate.
  */
 - (void)setSelected:(BOOL)selected animated:(BOOL)animated;
 
 /*
- This property defaults to YES. Setting it to NO will cause the annotation view to ignore all touch events.
- Subclasses may use this property to customize the appearance.
+ A Boolean value indicating whether the annotation is enabled.
+ 
+ The default value of this property is `YES`. If the value of this property is
+ `NO`, the annotation view ignores touch events and cannot be selected.
+ Subclasses may also customize the appearance of the view depending on its
+ enabled state.
  */
 @property (nonatomic, assign, getter=isEnabled) BOOL enabled;
 
+#pragma mark Supporting Drag Operations
+
 /**
- Setting this property to YES will make the view draggable. Long-press followed by a pan gesture will start to move the
- view around the map. `-mapView:didDragAnnotationView:toCoordinate:` will be called when a view is dropped.
+ A Boolean value indicating whether the annotation view is draggable.
+ 
+ If this property is set to `YES`, the user can drag the annotation after
+ pressing and holding the view, and the associated annotation object must also
+ implement the `-setCoordinate:` method. The default value of this property is
+ `NO`.
+ 
+ Setting this property to `YES` lets the map view know that the annotation is
+ always draggable. In other words, you cannot conditionalize drag operations by
+ attempting to stop an operation that has already been initiated; doing so can
+ lead to undefined behavior. Once begun, the drag operation should always
+ continue to completion.
+ 
+ `-mapView:didDragAnnotationView:toCoordinate:` is called when a view is
+ dropped.
  */
 @property (nonatomic, assign, getter=isDraggable) BOOL draggable;
 
 /**
- All states are handled automatically when `draggable` is set to YES.
- Custom animations can be achieved by overriding setDragState:animated:
+ The current drag state of the annotation view.
+ 
+ All states are handled automatically when the `draggable` property is set to
+ `YES`. To perform a custom animation in response to a change to this property,
+ override the `-setDragState:animated:` method.
  */
 @property (nonatomic, readonly) MGLAnnotationViewDragState dragState;
 
 /**
- Called when the `dragState` changes.
+ Sets the current drag state for the annotation view.
  
- Implementer may override this method in order to customize animations in subclasses.
+ You can override this method to animate a custom annotation view as the user
+ drags it. As the system detects user actions that would indicate a drag, it
+ calls this method to update the drag state.
  */
 - (void)setDragState:(MGLAnnotationViewDragState)dragState animated:(BOOL)animated NS_REQUIRES_SUPER;
 
-/**
- Setting this property to YES will cause the annotation view to shrink as it approaches the horizon and grow as it moves away from the
- horizon when the associated map view is tilted. Conversely, setting this property to NO will ensure that the annotation view maintains
- a constant size even when the map view is tilted. To maintain consistency with annotation representations that are not backed by an
- MGLAnnotationView object, the default value of this property is YES.
- */
-@property (nonatomic, assign, getter=isScaledWithViewingDistance) BOOL scalesWithViewingDistance;
-
-/**
- Called when the view is removed from the reuse queue.
-
- The default implementation of this method does nothing. You can override it in your custom annotation views and use it to put the view 
- in a known state before it is returned to your map view delegate.
- */
-- (void)prepareForReuse;
-
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/platform/ios/src/MGLMapViewDelegate.h b/platform/ios/src/MGLMapViewDelegate.h
index f425964e97..c117c5d159 100644
--- a/platform/ios/src/MGLMapViewDelegate.h
+++ b/platform/ios/src/MGLMapViewDelegate.h
@@ -6,7 +6,15 @@ NS_ASSUME_NONNULL_BEGIN
 
 @class MGLMapView;
 
-/** The MGLMapViewDelegate protocol defines a set of optional methods that you can use to receive map-related update messages. Because many map operations require the `MGLMapView` class to load data asynchronously, the map view calls these methods to notify your application when specific operations complete. The map view also uses these methods to request annotation marker symbology and to manage interactions with those markers. */
+/**
+ The `MGLMapViewDelegate` protocol defines a set of optional methods that you
+ can use to receive map-related update messages. Because many map operations
+ require the `MGLMapView` class to load data asynchronously, the map view calls
+ these methods to notify your application when specific operations complete. The
+ map view also uses these methods to request information about annotations
+ displayed on the map, such as the styles and interaction modes to apply to
+ individual annotations.
+ */
 @protocol MGLMapViewDelegate <NSObject>
 
 @optional
@@ -14,30 +22,39 @@ NS_ASSUME_NONNULL_BEGIN
 #pragma mark Responding to Map Position Changes
 
 /**
- Tells the delegate that the region displayed by the map view is about to change.
+ Tells the delegate that the viewpoint depicted by the map view is about to
+ change.
  
- This method is called whenever the currently displayed map region will start changing.
+ This method is called whenever the currently displayed map camera will start
+ changing for any reason.
  
- @param mapView The map view whose visible region will change.
+ @param mapView The map view whose viewpoint will change.
  @param animated Whether the change will cause an animated effect on the map.
  */
 - (void)mapView:(MGLMapView *)mapView regionWillChangeAnimated:(BOOL)animated;
 
 /**
- Tells the delegate that the region displayed by the map view is changing.
+ Tells the delegate that the viewpoint depicted by the map view is changing.
  
- This method is called whenever the currently displayed map region changes. During movement, this method may be called many times to report updates to the map position. Therefore, your implementation of this method should be as lightweight as possible to avoid affecting performance.
+ This method is called as the currently displayed map camera changes as part of
+ an animation, whether due to a user gesture or due to a call to a method such
+ as `-[MGLMapView setCamera:animated:]`. During the animation, this method may
+ be called many times to report updates to the viewpoint. Therefore, your
+ implementation of this method should be as lightweight as possible to avoid
+ affecting performance.
  
- @param mapView The map view whose visible region is changing.
+ @param mapView The map view whose viewpoint is changing.
  */
 - (void)mapViewRegionIsChanging:(MGLMapView *)mapView;
 
 /**
- Tells the delegate that the region displayed by the map view just changed.
+ Tells the delegate that the viewpoint depicted by the map view has finished
+ changing.
  
- This method is called whenever the currently displayed map region has finished changing.
+ This method is called whenever the currently displayed map camera has finished
+ changing, after any calls to `-mapViewRegionIsChanging:` due to animation.
  
- @param mapView The map view whose visible region changed.
+ @param mapView The map view whose viewpoint has changed.
  @param animated Whether the change caused an animated effect on the map.
  */
 - (void)mapView:(MGLMapView *)mapView regionDidChangeAnimated:(BOOL)animated;
@@ -47,7 +64,8 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Tells the delegate that the map view will begin to load.
  
- This method is called whenever the map view starts loading, including when a new style has been set and the map must reload.
+ This method is called whenever the map view starts loading, including when a
+ new style has been set and the map must reload.
  
  @param mapView The map view that is starting to load.
  */
@@ -56,7 +74,8 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Tells the delegate that the map view has finished loading.
  
- This method is called whenever the map view finishes loading, either after the initial load or after a style change has forced a reload.
+ This method is called whenever the map view finishes loading, either after the
+ initial load or after a style change has forced a reload.
  
  @param mapView The map view that has finished loading.
  */
@@ -71,56 +90,87 @@ NS_ASSUME_NONNULL_BEGIN
 // TODO
 - (void)mapViewDidFinishRenderingMap:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
 
-// TODO
+/**
+ Tells the delegate that the map view is about to redraw.
+ 
+ This method is called any time the map view needs to redraw due to a change in
+ the viewpoint or style property transition. This method may be called very
+ frequently, even moreso than `-mapViewRegionIsChanging:`. Therefore, your
+ implementation of this method should be as lightweight as possible to avoid
+ affecting performance.
+ 
+ @param mapView The map view that is about to redraw.
+ */
 - (void)mapViewWillStartRenderingFrame:(MGLMapView *)mapView;
 
-// TODO
+/**
+ Tells the delegate that the map view has just redrawn.
+ 
+ This method is called any time the map view needs to redraw due to a change in
+ the viewpoint or style property transition. This method may be called very
+ frequently, even moreso than `-mapViewRegionIsChanging:`. Therefore, your
+ implementation of this method should be as lightweight as possible to avoid
+ affecting performance.
+ 
+ @param mapView The map view that has just redrawn.
+ */
 - (void)mapViewDidFinishRenderingFrame:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
 
 #pragma mark Tracking User Location
 
 /**
- Tells the delegate that the map view will begin tracking the user's location.
+ Tells the delegate that the map view will begin tracking the user’s location.
  
- This method is called when the value of the `showsUserLocation` property changes to `YES`.
+ This method is called when the value of the `showsUserLocation` property
+ changes to `YES`.
  
- @param mapView The map view that is tracking the user's location.
+ @param mapView The map view that is tracking the user’s location.
  */
 - (void)mapViewWillStartLocatingUser:(MGLMapView *)mapView;
 
 /**
- Tells the delegate that the map view has stopped tracking the user's location.
+ Tells the delegate that the map view has stopped tracking the user’s location.
  
- This method is called when the value of the `showsUserLocation` property changes to `NO`.
+ This method is called when the value of the `showsUserLocation` property
+ changes to `NO`.
  
- @param mapView The map view that is tracking the user's location.
+ @param mapView The map view that is tracking the user’s location.
  */
 - (void)mapViewDidStopLocatingUser:(MGLMapView *)mapView;
 
 /**
  Tells the delegate that the location of the user was updated.
  
- While the `showsUserLocation` property is set to `YES`, this method is called whenever a new location update is received by the map view. This method is also called if the map view's user tracking mode is set to `MGLUserTrackingModeFollowWithHeading` and the heading changes, or if it is set to `MGLUserTrackingModeFollowWithCourse` and the course changes.
+ While the `showsUserLocation` property is set to `YES`, this method is called
+ whenever a new location update is received by the map view. This method is also
+ called if the map view’s user tracking mode is set to
+ `MGLUserTrackingModeFollowWithHeading` and the heading changes, or if it is set
+ to `MGLUserTrackingModeFollowWithCourse` and the course changes.
  
- This method is not called if the application is currently running in the background. If you want to receive location updates while running in the background, you must use the Core Location framework.
+ This method is not called if the application is currently running in the
+ background. If you want to receive location updates while running in the
+ background, you must use the Core Location framework.
  
- @param mapView The map view that is tracking the user's location.
- @param userLocation The location object representing the user's latest location. This property may be `nil`.
+ @param mapView The map view that is tracking the user’s location.
+ @param userLocation The location object representing the user’s latest
+    location. This property may be `nil`.
  */
 - (void)mapView:(MGLMapView *)mapView didUpdateUserLocation:(nullable MGLUserLocation *)userLocation;
 
 /**
- Tells the delegate that an attempt to locate the user's position failed.
+ Tells the delegate that an attempt to locate the user’s position failed.
  
- @param mapView The map view that is tracking the user's location.
- @param error An error object containing the reason why location tracking failed.
+ @param mapView The map view that is tracking the user’s location.
+ @param error An error object containing the reason why location tracking
+    failed.
  */
 - (void)mapView:(MGLMapView *)mapView didFailToLocateUserWithError:(NSError *)error;
 
 /**
- Tells the delegate that the map view's user tracking mode has changed.
+ Tells the delegate that the map view’s user tracking mode has changed.
  
- This method is called after the map view asynchronously changes to reflect the new user tracking mode, for example by beginning to zoom or rotate.
+ This method is called after the map view asynchronously changes to reflect the
+ new user tracking mode, for example by beginning to zoom or rotate.
  
  @param mapView The map view that changed its tracking mode.
  @param mode The new tracking mode.
@@ -128,28 +178,46 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (void)mapView:(MGLMapView *)mapView didChangeUserTrackingMode:(MGLUserTrackingMode)mode animated:(BOOL)animated;
 
-#pragma mark Managing the Display of Annotations
+#pragma mark Managing the Appearance of Annotations
 
 /**
- Returns an image object to use for the marker for the specified point annotation object.
+ Returns an annotation image object to mark the given point annotation object on
+ the map.
+ 
+ Implement this method to mark a point annotation with a static image. If you
+ want to mark a particular point annotation with an annotation view instead,
+ omit this method or have it return `nil` for that annotation, then implement
+ `-mapView:viewForAnnotation:`.
+ 
+ Static annotation images use less memory and draw more quickly than annotation
+ views. On the other hand, annotation views are compatible with UIKit, Core
+ Animation, and other Cocoa Touch frameworks.
  
  @param mapView The map view that requested the annotation image.
- @param annotation The object representing the annotation that is about to be displayed.
- @return The image object to display for the specified annotation or `nil` if you want to display the default marker image.
+ @param annotation The object representing the annotation that is about to be
+    displayed.
+ @return The annotation image object to display for the given annotation or
+    `nil` if you want to display the default marker image or an annotation view.
  */
 - (nullable MGLAnnotationImage *)mapView:(MGLMapView *)mapView imageForAnnotation:(id <MGLAnnotation>)annotation;
 
 /**
- Returns the alpha value to use when rendering a shape annotation. Defaults to `1.0`.
+ Returns the alpha value to use when rendering a shape annotation.
+ 
+ A value of 0.0 results in a completely transparent shape. A value of 1.0, the
+ default, results in a completely opaque shape.
  
  @param mapView The map view rendering the shape annotation.
  @param annotation The annotation being rendered.
- @return An alpha value between `0` and `1.0`.
+ @return An alpha value between 0 and 1.0.
  */
 - (CGFloat)mapView:(MGLMapView *)mapView alphaForShapeAnnotation:(MGLShape *)annotation;
 
 /**
- Returns the stroke color to use when rendering a shape annotation. Defaults to the map view’s tint color.
+ Returns the color to use when rendering the outline of a shape annotation.
+ 
+ The default stroke color is the map view’s tint color. If a pattern color is
+ specified, the result is undefined.
  
  @param mapView The map view rendering the shape annotation.
  @param annotation The annotation being rendered.
@@ -158,95 +226,84 @@ NS_ASSUME_NONNULL_BEGIN
 - (UIColor *)mapView:(MGLMapView *)mapView strokeColorForShapeAnnotation:(MGLShape *)annotation;
 
 /**
- Returns the fill color to use when rendering a polygon annotation. Defaults to the map view’s tint color.
+ Returns the color to use when rendering the fill of a polygon annotation.
+ 
+ The default fill color is the map view’s tint color. If a pattern color is
+ specified, the result is undefined.
  
  @param mapView The map view rendering the polygon annotation.
  @param annotation The annotation being rendered.
- @return A color to use for the polygon interior.
+ @return The polygon’s interior fill color.
  */
 - (UIColor *)mapView:(MGLMapView *)mapView fillColorForPolygonAnnotation:(MGLPolygon *)annotation;
 
 /**
- Returns the line width to use when rendering a polyline annotation. Defaults to `3.0`.
+ Returns the line width in points to use when rendering the outline of a
+ polyline annotation.
+ 
+ By default, the polyline is outlined with a line 3.0 points wide.
  
  @param mapView The map view rendering the polygon annotation.
  @param annotation The annotation being rendered.
- @return A line width for the polyline.
+ @return A line width for the polyline, measured in points.
  */
 - (CGFloat)mapView:(MGLMapView *)mapView lineWidthForPolylineAnnotation:(MGLPolyline *)annotation;
 
-/**
- Returns a Boolean value indicating whether the annotation is able to display extra information in a callout bubble.
- 
- If the value returned is `YES`, a standard callout bubble is shown when the user taps a selected annotation. The callout uses the title and subtitle text from the associated annotation object. If there is no title text, though, the annotation will not show a callout. The callout also displays any custom callout views returned by the delegate for the left and right callout accessory views.
- 
- If the value returned is `NO`, the value of the title and subtitle strings are ignored.
- 
- @param mapView The map view that requested the annotation callout ability.
- @param annotation The object representing the annotation.
- @return A Boolean indicating whether the annotation should show a callout.
- */
-- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation;
-
-/**
- Returns a callout view to display for the specified annotation.
- 
- If this method is present in the delegate, it must return a new instance of a view dedicated to display the callout bubble. It will be configured by the map view. If this method is not present, or if it returns `nil`, a standard, two-line, bubble-like callout view is displayed by default.
- 
- @param mapView The map view that requested the callout view.
- @param annotation The object representing the annotation.
- @return A view conforming to the `MGLCalloutView` protocol, or `nil` to use the default callout view.
- */
-- (nullable UIView <MGLCalloutView> *)mapView:(MGLMapView *)mapView calloutViewForAnnotation:(id <MGLAnnotation>)annotation;
+#pragma mark Managing Annotation Views
 
 /**
- Returns the view to display on the left side of the standard callout bubble.
+ Returns a view object to mark the given point annotation object on the map.
  
- The default value is treated as if `nil`. The left callout view is typically used to display information about the annotation or to link to custom information provided by your application.
+ Implement this method to mark a point annotation with a view object. If you
+ want to mark a particular point annotation with a static image instead, omit
+ this method or have it return `nil` for that annotation, then implement
+ `-mapView:imageForAnnotation:` instead.
  
- If the view you specify is also a descendant of the `UIControl` class, you can use the map view's delegate to receive notifications when your control is tapped. If it does not descend from `UIControl`, your view is responsible for handling any touch events within its bounds.
+ Annotation views are compatible with UIKit, Core Animation, and other Cocoa
+ Touch frameworks. On the other hand, static annotation images use less memory
+ and draw more quickly than annotation views.
  
- @param mapView The map view presenting the annotation callout.
- @param annotation The object representing the annotation with the callout.
- @return The accessory view to display.
+ @param mapView The map view that requested the annotation view.
+ @param annotation The object representing the annotation that is about to be
+    displayed.
+ @return The view object to display for the given annotation or `nil` if you
+    want to display an annotation image instead.
  */
-- (nullable UIView *)mapView:(MGLMapView *)mapView leftCalloutAccessoryViewForAnnotation:(id <MGLAnnotation>)annotation;
+- (nullable MGLAnnotationView *)mapView:(MGLMapView *)mapView viewForAnnotation:(id <MGLAnnotation>)annotation;
 
 /**
- Returns the view to display on the right side of the standard callout bubble.
+ Tells the delegate that one or more annotation views have been added and
+ positioned on the map.
  
- The default value is treated is if `nil`. The right callout view is typically used to link to more detailed information about the annotation. A common view to specify for this property is `UIButton` object whose type is set to `UIButtonTypeDetailDisclosure`.
+ This method is called just after the views are added to the map. You can
+ implement this method to animate the addition of the annotation views.
  
- If the view you specify is also a descendant of the `UIControl` class, you can use the map view's delegate to receive notifications when your control is tapped. If it does not descend from `UIControl`, your view is responsible for handling any touch events within its bounds.
- 
- @param mapView The map view presenting the annotation callout.
- @param annotation The object representing the annotation with the callout.
- @return The accessory view to display.
+ @param mapView The map view to which the annotation views were added.
+ @param annotationViews An array of `MGLAnnotationView` objects representing the
+    views that were added.
  */
-- (nullable UIView *)mapView:(MGLMapView *)mapView rightCalloutAccessoryViewForAnnotation:(id <MGLAnnotation>)annotation;
+- (void)mapView:(MGLMapView *)mapView didAddAnnotationViews:(NS_ARRAY_OF(MGLAnnotationView *) *)annotationViews;
 
-#pragma mark Managing Annotations
+#pragma mark Dragging Annotation Views
 
 /**
- Tells the delegate that the user tapped one of the annotation's accessory buttons.
- 
- Accessory views contain custom content and are positioned on either side of the annotation title text. If a view you specify is a descendant of the `UIControl` class, the map view calls this method as a convenience whenever the user taps your view. You can use this method to respond to taps and perform any actions associated with that control. For example, if your control displayed additional information about the annotation, you could use this method to present a modal panel with that information.
+ Tells the delegate that the user has dragged the given annotation view to a new
+ location.
  
- If your custom accessory views are not descendants of the `UIControl` class, the map view does not call this method.
+ This method is called as soon as the user finishes dragging and drops the
+ annotation view at a new location.
  
- @param mapView The map view containing the specified annotation.
- @param annotation The annotation whose button was tapped.
- @param control The control that was tapped.
- */
-- (void)mapView:(MGLMapView *)mapView annotation:(id <MGLAnnotation>)annotation calloutAccessoryControlTapped:(UIControl *)control;
-
-/**
- Tells the delegate that the user tapped on an annotation's callout view.
+ To permanently move the corresponding annotation to the new geographic
+ coordinate, set the annotation’s `coordinate` property to the given coordinate.
+ Otherwise, the annotation view will return to the original location
+ corresponding to that property’s value.
  
- @param mapView The map view containing the specified annotation.
- @param annotation The annotation whose callout was tapped.
+ @param mapView The map view containing the annotation view.
+ @param annotationView The annotation view that was dragged.
+ @param coordinate The geographic coordinate corresponding to the location to
+    which the user has dragged the annotation view.
  */
-- (void)mapView:(MGLMapView *)mapView tapOnCalloutForAnnotation:(id <MGLAnnotation>)annotation;
+- (void)mapView:(MGLMapView *)mapView didDragAnnotationView:(MGLAnnotationView *)annotationView toCoordinate:(CLLocationCoordinate2D)coordinate;
 
 #pragma mark Selecting Annotations
 
@@ -255,6 +312,10 @@ NS_ASSUME_NONNULL_BEGIN
  
  You can use this method to track changes in the selection state of annotations.
  
+ If the annotation is associated with an annotation view, you can also implement
+ `-mapView:didSelectAnnotationView:`, which is called immediately after this
+ method is called.
+ 
  @param mapView The map view containing the annotation.
  @param annotation The annotation that was selected.
  */
@@ -265,6 +326,10 @@ NS_ASSUME_NONNULL_BEGIN
  
  You can use this method to track changes in the selection state of annotations.
  
+ If the annotation is associated with an annotation view, you can also implement
+ `-mapView:didDeselectAnnotationView:`, which is called immediately after this
+ method is called.
+ 
  @param mapView The map view containing the annotation.
  @param annotation The annotation that was deselected.
  */
@@ -273,7 +338,13 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Tells the delegate that one of its annotation views was selected.
  
- You can use this method to track changes in the selection state of annotation views.
+ You can use this method to track changes in the selection state of annotation
+ views.
+ 
+ This method is only called for annotation views. To track changes in the
+ selection state of all annotations, including those associated with static
+ annotation images, implement `-mapView:didSelectAnnotation:`, which is called
+ immediately before this method is called.
  
  @param mapView The map view containing the annotation.
  @param annotationView The annotation view that was selected.
@@ -283,45 +354,158 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Tells the delegate that one of its annotation views was deselected.
  
- You can use this method to track changes in the selection state of annotation views.
+ You can use this method to track changes in the selection state of annotation
+ views.
+ 
+ This method is only called for annotation views. To track changes in the
+ selection state of all annotations, including those associated with static
+ annotation images, implement `-mapView:didDeselectAnnotation:`, which is called
+ immediately before this method is called.
  
  @param mapView The map view containing the annotation.
  @param annotationView The annotation view that was deselected.
  */
 - (void)mapView:(MGLMapView *)mapView didDeselectAnnotationView:(MGLAnnotationView *)annotationView;
 
-#pragma mark Managing annotation views
+#pragma mark Managing Callout Views
 
 /**
- Returns a view object to use for the marker for the specified point annotation object.
+ Returns a Boolean value indicating whether the annotation is able to display
+ extra information in a callout bubble.
  
- @param mapView The map view that requested the annotation view.
- @param annotation The object representing the annotation that is about to be displayed.
- @return The view object to display for the specified annotation or `nil` if you want to display the default marker image.
+ This method is called after an annotation is selected, before any callout is
+ displayed for the annotation.
+ 
+ If the return value is `YES`, a callout view is shown when the user taps on an
+ annotation, selecting it. The default callout displays the annotation’s title
+ and subtitle. You can add accessory views to either end of the callout by
+ implementing the `-mapView:leftCalloutAccessoryViewForAnnotation:` and
+ `-mapView:rightCalloutAccessoryViewForAnnotation:` methods. You can further
+ customize the callout’s contents by implementing the
+ `-mapView:calloutViewForAnnotation:` method.
+ 
+ If the return value is `NO`, or if this method is absent from the delegate, or
+ if the annotation lacks a title, the annotation will not show a callout even
+ when selected.
+ 
+ @param mapView The map view that has selected the annotation.
+ @param annotation The object representing the annotation.
+ @return A Boolean value indicating whether the annotation should show a
+    callout.
  */
-- (nullable MGLAnnotationView *)mapView:(MGLMapView *)mapView viewForAnnotation:(id <MGLAnnotation>)annotation;
+- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation;
 
 /**
- Tells the delegate that new annotation views have been added and positioned on the map.
+ Returns a callout view to display for the given annotation.
+ 
+ If this method is present in the delegate, it must return a new instance of a
+ view dedicated to display the callout. The returned view will be configured by
+ the map view.
  
- You can use this method to animate the adding of the annotation views.
+ If this method is absent from the delegate, or if it returns `nil`, a standard,
+ two-line, bubble-like callout view is displayed by default.
  
- @param mapView The map view containing the annotation views.
- @param annotationViews The annotation views that was added.
+ @param mapView The map view that requested the callout view.
+ @param annotation The object representing the annotation.
+ @return A view conforming to the `MGLCalloutView` protocol, or `nil` to use the
+    default callout view.
  */
-- (void)mapView:(MGLMapView *)mapView didAddAnnotationViews:(NS_ARRAY_OF(MGLAnnotationView *) *)annotationViews;
+- (nullable UIView <MGLCalloutView> *)mapView:(MGLMapView *)mapView calloutViewForAnnotation:(id <MGLAnnotation>)annotation;
 
 /**
- Tells the delegate that one if its annotation views was dragged to a new coordinate.
+ Returns the view to display on the left side of the standard callout bubble.
  
- In order to make the new location persistent, you have to update the `coordinate` property of the associated annotation.
+ The left callout view is typically used to convey information about the
+ annotation or to link to custom information provided by your application.
  
- @param mapView The map view containing the annotation view.
- @param annotationView The annotation view that was dragged.
- @param coordinate The coordinate that the annotation view was dropped on.
+ If the view you specify is a descendant of the `UIControl` class, you can use
+ the map view’s delegate to receive notifications when your control is tapped,
+ by implementing the `-mapView:annotation:calloutAccessoryControlTapped:`
+ method. If the view you specify does not descend from `UIControl`, your view is
+ responsible for handling any touch events within its bounds.
+ 
+ If this method is absent from the delegate, or if it returns `nil`, the
+ standard callout view has no accessory view on its left side. The return value
+ of this method is ignored if `-mapView:calloutViewForAnnotation:` is present in
+ the delegate.
  
+ To display a view on the callout’s right side, implement the
+ `-mapView:rightCalloutAccessoryViewForAnnotation:` method.
+ 
+ @param mapView The map view presenting the annotation callout.
+ @param annotation The object representing the annotation with the callout.
+ @return The accessory view to display.
  */
-- (void)mapView:(MGLMapView *)mapView didDragAnnotationView:(MGLAnnotationView *)annotationView toCoordinate:(CLLocationCoordinate2D)coordinate;
+- (nullable UIView *)mapView:(MGLMapView *)mapView leftCalloutAccessoryViewForAnnotation:(id <MGLAnnotation>)annotation;
+
+/**
+ Returns the view to display on the right side of the standard callout bubble.
+ 
+ The right callout view is typically used to convey information about the
+ annotation or to link to custom information provided by your application.
+ 
+ If the view you specify is a descendant of the `UIControl` class, you can use
+ the map view’s delegate to receive notifications when your control is tapped,
+ by implementing the `-mapView:annotation:calloutAccessoryControlTapped:`
+ method. If the view you specify does not descend from `UIControl`, your view is
+ responsible for handling any touch events within its bounds.
+ 
+ If this method is absent from the delegate, or if it returns `nil`, the
+ standard callout view has no accessory view on its right side. The return value
+ of this method is ignored if `-mapView:calloutViewForAnnotation:` is present in
+ the delegate.
+ 
+ To display a view on the callout’s left side, implement the
+ `-mapView:leftCalloutAccessoryViewForAnnotation:` method.
+ 
+ @param mapView The map view presenting the annotation callout.
+ @param annotation The object representing the annotation with the callout.
+ @return The accessory view to display.
+ */
+- (nullable UIView *)mapView:(MGLMapView *)mapView rightCalloutAccessoryViewForAnnotation:(id <MGLAnnotation>)annotation;
+
+/**
+ Tells the delegate that the user tapped one of the accessory controls in the
+ annotation’s callout view.
+ 
+ In a standard callout view, accessory views contain custom content and are
+ positioned on either side of the annotation title text. If an accessory view
+ you specify is a descendant of the `UIControl` class, the map view calls this
+ method as a convenience whenever the user taps your view. You can use this
+ method to respond to taps and perform any actions associated with that control.
+ For example, if your control displays additional information about the
+ annotation, you could use this method to present a modal panel with that
+ information.
+ 
+ If your custom accessory views are not descendants of the `UIControl` class,
+ the map view does not call this method. If the annotation has a custom callout
+ view via the `-mapView:calloutViewForAnnotation:` method, you can specify the
+ custom accessory views using the `MGLCalloutView` protocol’s
+ `leftAccessoryView` and `rightAccessoryView` properties.
+ 
+ @param mapView The map view containing the specified annotation.
+ @param annotation The annotation whose accessory view was tapped.
+ @param control The control that was tapped.
+ */
+- (void)mapView:(MGLMapView *)mapView annotation:(id <MGLAnnotation>)annotation calloutAccessoryControlTapped:(UIControl *)control;
+
+/**
+ Tells the delegate that the user tapped on an annotation’s callout view.
+ 
+ This method is called when the user taps on the body of the callout view, as
+ opposed to the callout’s left or right accessory view. If the annotation has a
+ custom callout view via the `-mapView:calloutViewForAnnotation:` method, this
+ method is only called whenever the callout view calls its delegate’s
+ `-[MGLCalloutViewDelegate calloutViewTapped:]` method.
+ 
+ If this method is present on the delegate, the standard callout view’s body
+ momentarily highlights when the user taps it, whether or not this method does
+ anything in response to the tap.
+ 
+ @param mapView The map view containing the specified annotation.
+ @param annotation The annotation whose callout was tapped.
+ */
+- (void)mapView:(MGLMapView *)mapView tapOnCalloutForAnnotation:(id <MGLAnnotation>)annotation;
 
 @end
 
diff --git a/platform/macos/src/MGLMapViewDelegate.h b/platform/macos/src/MGLMapViewDelegate.h
index 0b7eec84ac..6ea69f845a 100644
--- a/platform/macos/src/MGLMapViewDelegate.h
+++ b/platform/macos/src/MGLMapViewDelegate.h
@@ -40,10 +40,12 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Tells the delegate that the viewpoint depicted by the map view is changing.
  
- This method is called as the currently displayed map camera changes due to
- animation. During movement, this method may be called many times to report
- updates to the viewpoint. Therefore, your implementation of this method should
- be as lightweight as possible to avoid affecting performance.
+ This method is called as the currently displayed map camera changes as part of
+ an animation, whether due to a user gesture or due to a call to a method such
+ as `-[MGLMapView setCamera:animated:]`. During the animation, this method may
+ be called many times to report updates to the viewpoint. Therefore, your
+ implementation of this method should be as lightweight as possible to avoid
+ affecting performance.
  
  @param mapView The map view whose viewpoint is changing.
  */
@@ -54,7 +56,7 @@ NS_ASSUME_NONNULL_BEGIN
  changing.
  
  This method is called whenever the currently displayed map camera has finished
- changing.
+ changing, after any calls to `-mapViewRegionIsChanging:` due to animation.
  
  @param mapView The map view whose viewpoint has changed.
  @param animated Whether the change caused an animated effect on the map.
@@ -85,10 +87,34 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (void)mapViewWillStartRenderingMap:(MGLMapView *)mapView;
 - (void)mapViewDidFinishRenderingMap:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
+
+/**
+ Tells the delegate that the map view is about to redraw.
+ 
+ This method is called any time the map view needs to redraw due to a change in
+ the viewpoint or style property transition. This method may be called very
+ frequently, even moreso than `-mapViewRegionIsChanging:`. Therefore, your
+ implementation of this method should be as lightweight as possible to avoid
+ affecting performance.
+ 
+ @param mapView The map view that is about to redraw.
+ */
 - (void)mapViewWillStartRenderingFrame:(MGLMapView *)mapView;
+
+/**
+ Tells the delegate that the map view has just redrawn.
+ 
+ This method is called any time the map view needs to redraw due to a change in
+ the viewpoint or style property transition. This method may be called very
+ frequently, even moreso than `-mapViewRegionIsChanging:`. Therefore, your
+ implementation of this method should be as lightweight as possible to avoid
+ affecting performance.
+ 
+ @param mapView The map view that has just redrawn.
+ */
 - (void)mapViewDidFinishRenderingFrame:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
 
-#pragma mark Managing the Display of Annotations
+#pragma mark Managing the Appearance of Annotations
 
 /**
  Returns an annotation image object to mark the given point annotation object on
@@ -129,7 +155,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Returns the color to use when rendering the fill of a polygon annotation.
  
- The default fill color is selected menu item color. If a pattern color is
+ The default fill color is the selected menu item color. If a pattern color is
  specified, the result is undefined.
  
  @param mapView The map view rendering the polygon annotation.
@@ -172,7 +198,7 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (void)mapView:(MGLMapView *)mapView didDeselectAnnotation:(id <MGLAnnotation>)annotation;
 
-#pragma mark Displaying Information About Annotations
+#pragma mark Managing Callout Popovers
 
 /**
  Returns a Boolean value indicating whether the annotation is able to display
@@ -182,13 +208,13 @@ NS_ASSUME_NONNULL_BEGIN
  displayed for the annotation.
  
  If the return value is `YES`, a callout popover is shown when the user clicks
- on a selected annotation. The default callout displays the annotation’s title
- and subtitle. You can customize the popover’s contents by implementing the
- `-mapView:calloutViewControllerForAnnotation:` method.
+ on an annotation, selecting it. The default callout displays the annotation’s
+ title and subtitle. You can customize the popover’s contents by implementing
+ the `-mapView:calloutViewControllerForAnnotation:` method.
  
- If the return value is `NO`, or if this method is unimplemented, or if the
- annotation lacks a title, the annotation will not show a callout even when
- selected.
+ If the return value is `NO`, or if this method is absent from the delegate, or
+ if the annotation lacks a title, the annotation will not show a callout even
+ when selected.
  
  @param mapView The map view that has selected the annotation.
  @param annotation The object representing the annotation.