[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.

1 files changed, 177 insertions, 48 deletions

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