[ios] fix unintentional omission of delegate sections & methods from docs

Adds these delegate methods that were missing:
  - `mapView:annotation:calloutAccessoryControlTapped:`
  - `mapView:didSelectAnnotation:`
  - `mapView:didDeselectAnnotation:`

Adds these section headers that were missing:
  - Responding to Map Position Changes
  - Managing Annotations
  - Selecting Annotations

Also reorders the sections by priority and grouping.

Fixes #2514

1 files changed, 94 insertions, 94 deletions

diff --git a/include/mbgl/ios/MGLMapView.h b/include/mbgl/ios/MGLMapView.h
index da500f1ef6..402972f763 100644
--- a/include/mbgl/ios/MGLMapView.h
+++ b/include/mbgl/ios/MGLMapView.h
@@ -406,6 +406,97 @@ IB_DESIGNABLE
 
 @optional
 
+#pragma mark - Responding to Map Position Changes
+
+/** @name Responding to Map Position Changes */
+
+/** Tells the delegate that the region displayed by the map view is about to change.
+ *
+ *   This method is called whenever the currently displayed map region will start changing.
+ *   @param mapView The map view whose visible region 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.
+ *
+ *   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.
+ *   @param mapView The map view whose visible region is changing. */
+- (void)mapViewRegionIsChanging:(MGLMapView *)mapView;
+
+/** Tells the delegate that the region displayed by the map view just changed.
+ *
+ *   This method is called whenever the currently displayed map region has finished changing.
+ *   @param mapView The map view whose visible region changed.
+ *   @param animated Whether the change caused an animated effect on the map. */
+- (void)mapView:(MGLMapView *)mapView regionDidChangeAnimated:(BOOL)animated;
+
+#pragma mark - Loading the Map Data
+
+/** @name Loading the Map Data */
+
+// TODO
+- (void)mapViewWillStartLoadingMap:(MGLMapView *)mapView;
+
+// TODO
+- (void)mapViewDidFinishLoadingMap:(MGLMapView *)mapView;
+
+// TODO
+- (void)mapViewDidFailLoadingMap:(MGLMapView *)mapView withError:(NSError *)error;
+
+// TODO
+- (void)mapViewWillStartRenderingMap:(MGLMapView *)mapView;
+
+// TODO
+- (void)mapViewDidFinishRenderingMap:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
+
+// TODO
+- (void)mapViewWillStartRenderingFrame:(MGLMapView *)mapView;
+
+// TODO
+- (void)mapViewDidFinishRenderingFrame:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
+
+#pragma mark - Tracking User Location
+
+/** @name Tracking User 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`.
+ *
+ *   @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.
+ *
+ *   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. */
+- (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.
+ *
+ *   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`. */
+- (void)mapView:(MGLMapView *)mapView didUpdateUserLocation:(nullable MGLUserLocation *)userLocation;
+
+/** 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. */
+- (void)mapView:(MGLMapView *)mapView didFailToLocateUserWithError:(NSError *)error;
+
+/** 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.
+ *
+ *   @param mapView The map view that changed its tracking mode.
+ *   @param mode The new tracking mode.
+ *   @param animated Whether the change caused an animated effect on the map. */
+- (void)mapView:(MGLMapView *)mapView didChangeUserTrackingMode:(MGLUserTrackingMode)mode animated:(BOOL)animated;
+
 #pragma mark - Managing the Display of Annotations
 
 /** @name Managing the Display of Annotations */
@@ -475,102 +566,11 @@ IB_DESIGNABLE
 *   @return The accessory view to display. */
 - (nullable UIView *)mapView:(MGLMapView *)mapView rightCalloutAccessoryViewForAnnotation:(id <MGLAnnotation>)annotation;
 
-#pragma mark - Responding to Map Position Changes
-
-// Responding to Map Position Changes
-
-/** Tells the delegate that the region displayed by the map view is about to change.
- *
- *   This method is called whenever the currently displayed map region will start changing.
- *   @param mapView The map view whose visible region 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.
- *
- *   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.
- *   @param mapView The map view whose visible region is changing. */
-- (void)mapViewRegionIsChanging:(MGLMapView *)mapView;
-
-/** Tells the delegate that the region displayed by the map view just changed.
- *
- *   This method is called whenever the currently displayed map region has finished changing.
- *   @param mapView The map view whose visible region changed.
- *   @param animated Whether the change caused an animated effect on the map. */
-- (void)mapView:(MGLMapView *)mapView regionDidChangeAnimated:(BOOL)animated;
-
-#pragma mark - Loading the Map Data
-
-// Loading the Map Data
-
-// TODO
-- (void)mapViewWillStartLoadingMap:(MGLMapView *)mapView;
-
-// TODO
-- (void)mapViewDidFinishLoadingMap:(MGLMapView *)mapView;
-
-// TODO
-- (void)mapViewDidFailLoadingMap:(MGLMapView *)mapView withError:(NSError *)error;
-
-// TODO
-- (void)mapViewWillStartRenderingMap:(MGLMapView *)mapView;
-
-// TODO
-- (void)mapViewDidFinishRenderingMap:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
-
-// TODO
-- (void)mapViewWillStartRenderingFrame:(MGLMapView *)mapView;
-
-// TODO
-- (void)mapViewDidFinishRenderingFrame:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
-
-#pragma mark - Tracking the User Location
-
-/** @name Tracking the User 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`.
-*
-*   @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.
-*
-*   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. */
-- (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.
-*
-*   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`. */
-- (void)mapView:(MGLMapView *)mapView didUpdateUserLocation:(nullable MGLUserLocation *)userLocation;
-
-/** 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. */
-- (void)mapView:(MGLMapView *)mapView didFailToLocateUserWithError:(NSError *)error;
-
-/** 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.
-*
-*   @param mapView The map view that changed its tracking mode.
-*   @param mode The new tracking mode.
-*   @param animated Whether the change caused an animated effect on the map. */
-- (void)mapView:(MGLMapView *)mapView didChangeUserTrackingMode:(MGLUserTrackingMode)mode animated:(BOOL)animated;
-
 #pragma mark - Managing Annotations
 
 /** @name Managing Annotations */
 
-/* Tells the delegate that the user tapped one of the annotation's accessory buttons.
+/** 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.
 *
@@ -585,7 +585,7 @@ IB_DESIGNABLE
 
 /** @name Selecting Annotations */
 
-/* Tells the delegate that one of its annotations was selected.
+/** Tells the delegate that one of its annotations was selected.
 *
 *  You can use this method to track changes in the selection state of annotations.
 *
@@ -593,7 +593,7 @@ IB_DESIGNABLE
 *  @param annotation The annotation that was selected. */
 - (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id <MGLAnnotation>)annotation;
 
-/* Tells the delegate that one of its annotations was deselected.
+/** Tells the delegate that one of its annotations was deselected.
 *
 *  You can use this method to track changes in the selection state of annotations.
 *