[ios] Clarify location manager's API usage.

3 files changed, 45 insertions, 8 deletions

diff --git a/platform/darwin/src/MGLLocationManager.h b/platform/darwin/src/MGLLocationManager.h
index 9be10e5885..256cf5c813 100644
--- a/platform/darwin/src/MGLLocationManager.h
+++ b/platform/darwin/src/MGLLocationManager.h
@@ -6,15 +6,23 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol MGLLocationManagerDelegate;
 
 /**
- The `MGLLocationManager` protocol defines a set of methods that you
- use to receive location-related events.
+ The `MGLLocationManager` protocol defines a set of methods that a class must
+ implement in order to serve as the location manager of an `MGLMapView`. A location
+ manager is responsible for notifying the map view about location-related events,
+ such as a change in the user’s location. This protocol is similar to the
+ Core Location framework’s `CLLocationManager` class, but your implementation
+ does not need to be based on `CLLocationManager`.
+ 
  */
 @protocol MGLLocationManager <NSObject>
 
 @required
 
 /**
- The delegate to receive updates.
+ The delegate to receive location updates.
+ 
+ Do not set the location manager’s delegate yourself. `MGLMapView` sets this property
+ after the location manager becomes `MGLMapView`’s location manager.
  */
 @property (nonatomic, weak) id<MGLLocationManagerDelegate> delegate;
 
@@ -25,6 +33,8 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  Returns the current localization authorization status.
+ 
+ @see `+[CLLocationManger authorizationStatus]`
  */
 @property (nonatomic, readonly) CLAuthorizationStatus authorizationStatus;
 
@@ -74,24 +84,39 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  Notifies the delegate with the new location data.
+ 
+ @param manager The location manager reporting the update.
+ @param locations An array of `CLLocation` objects in chronological order,
+ with the last object representing the most recent location. This array
+ contains multiple `CLLocation` objects when `MGLMapView` uses  its
+ default location manager.
  */
 - (void)locationManager:(id<MGLLocationManager>)manager
      didUpdateLocations:(NSArray<CLLocation *> *)locations;
 
 /**
  Notifies the delegate with the new heading data.
+ 
+ @param manager The location manager reporting the update.
+ @param newHeading The new heading update.
  */
 - (void)locationManager:(id<MGLLocationManager>)manager
        didUpdateHeading:(CLHeading *)newHeading;
 
 /**
  Asks the delegate if the calibration alert should be displayed.
+ 
+ @param manager The location manager reporting the calibration.
  */
 - (BOOL)locationManagerShouldDisplayHeadingCalibration:(id<MGLLocationManager>)manager;
 
 /**
  Notifies the delegate that the location manager was unable to retrieve
  location updates.
+ 
+ @param manager The location manager reporting the error.
+ @param error An error object containing the error code that indicates
+ why the location manager failed.
  */
 - (void)locationManager:(id<MGLLocationManager>)manager
        didFailWithError:(nonnull NSError *)error;
diff --git a/platform/ios/app/MBXViewController.m b/platform/ios/app/MBXViewController.m
index 2b203b69ff..71bad66aee 100644
--- a/platform/ios/app/MBXViewController.m
+++ b/platform/ios/app/MBXViewController.m
@@ -445,7 +445,7 @@ CLLocationCoordinate2D randomWorldCoordinate() {
                 [NSString stringWithFormat:@"Show Labels in %@", (_localizingLabels ? @"Default Language" : [[NSLocale currentLocale] displayNameForKey:NSLocaleIdentifier value:[self bestLanguageForUser]])],
                 @"Show Snapshots",
                 [NSString stringWithFormat:@"%@ Camera Changes", (_shouldLimitCameraChanges ? @"Unlimit" : @"Limit")],
-                @"Show Custom Location Manager",
+                @"View Route Simulation",
             ]];
 
             if (self.debugLoggingEnabled)
diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index 2e56668e5e..d588d357a7 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -298,12 +298,21 @@ MGL_EXPORT IB_DESIGNABLE
 
 /**
  The object that this map view uses to start and stop the delivery of location-related
- events.
+ updates.
  
- If setting this property to `nil` and setting `showsUseLocation` to `YES`, or
- if no custom manager is provided it will use the default implementation.
+ To receive the current user location implement `MGLMapViewDelegate`s delegate methods:
  
- Set the custom location manager before calling `showUserLocation`.
+ `-[MGLMapViewDelegate mapView:didUpdateUserLocation:]`
+ `-[MGLMapViewDelegate mapView:didFailToLocateUserWithError:]`
+ 
+ If setting this property to `nil` and setting `showsUserLocation` to `YES`, or
+ if no custom manager is provided this property is set to the default
+ location manager.
+ 
+ `MGLMapView` uses a default location manager. If you want to substitute your own
+ location manager, you should do so by setting this property before setting
+ `showsUserLocation` to `YES`. To restore the default location manager, set this
+ property to `nil`.
  */
 @property (nonatomic, null_resettable) id<MGLLocationManager> locationManager;
 
@@ -323,6 +332,9 @@ MGL_EXPORT IB_DESIGNABLE
  `NSLocationAlwaysUsageDescription` in its `Info.plist` to satisfy the
  requirements of the underlying Core Location framework when enabling this
  property.
+ 
+ If you implement a custom location manager, set the `locationManager` before
+ calling `showsUserLocation`.
  */
 @property (nonatomic, assign) BOOL showsUserLocation;