[ios] more inline docs updates for jazzy

- Change all smart quotes to dumb quotes to workaround SourceKitten bug.
- Port changes from OS X (#3135)

1 files changed, 464 insertions, 238 deletions

diff --git a/include/mbgl/ios/MGLMapView.h b/include/mbgl/ios/MGLMapView.h
index 88c27d160b..6d6031261f 100644
--- a/include/mbgl/ios/MGLMapView.h
+++ b/include/mbgl/ios/MGLMapView.h
@@ -19,19 +19,44 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol MGLOverlay;
 
 /**
- An MGLMapView object provides an embeddable map interface, similar to the one provided by Apple's MapKit. You use this class to display map information and to manipulate the map contents from your application. You can center the map on a given coordinate, specify the size of the area you want to display, and style the features of the map to fit your application's use case.
- 
- Use of MGLMapView requires a Mapbox API access token. Obtain an access token on the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). If you instantiate an MGLMapView from Interface Builder, rendering of the map won't begin until the accessToken property has been set.
- 
- @warning Please note that you are responsible for getting permission to use the map data, and for ensuring your use adheres to the relevant terms of use.
+ An interactive, customizable map view with an interface similar to the one
+ provided by Apple's MapKit.
+ 
+ Using `MGLMapView`, you can embed the map inside a view, allow users to
+ manipulate it with standard gestures, animate the map between different
+ viewpoints, and present information in the form of annotations and overlays.
+ 
+ The map view loads scalable vector tiles that conform to the
+ [Mapbox Vector Tile Specification](https://github.com/mapbox/vector-tile-spec).
+ It styles them with a style that conforms to the
+ [Mapbox GL style specification](https://www.mapbox.com/mapbox-gl-style-spec/).
+ Such styles can be designed in [Mapbox Studio](https://www.mapbox.com/studio/)
+ and hosted on mapbox.com.
+ 
+ A collection of Mapbox-hosted styles is available through the `MGLStyle`
+ class. These basic styles use
+ [Mapbox Streets](https://www.mapbox.com/developers/vector-tiles/mapbox-streets)
+ or [Mapbox Satellite](https://www.mapbox.com/satellite/) data sources, but
+ you can specify a custom style that makes use of your own data.
+ 
+ Mapbox-hosted vector tiles and styles require an API access token, which you
+ can obtain from the
+ [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access
+ tokens associate requests to Mapbox's vector tile and style APIs with your
+ Mapbox account. They also deter other developers from using your styles
+ without your permission.
+ 
+ @note You are responsible for getting permission to use the map data and for
+ ensuring that your use adheres to the relevant terms of use.
  */
 IB_DESIGNABLE
 @interface MGLMapView : UIView
 
-#pragma mark Initializing a Map View
+#pragma mark Creating Instances
 
 /**
- Initializes and returns a newly allocated map view with the specified frame and the default style.
+ Initializes and returns a newly allocated map view with the specified frame
+ and the default style.
  
  @param frame The frame for the view, measured in points.
  @return An initialized map view.
@@ -39,177 +64,395 @@ IB_DESIGNABLE
 - (instancetype)initWithFrame:(CGRect)frame;
 
 /**
- Initializes and returns a newly allocated map view with the specified frame and style URL.
+ Initializes and returns a newly allocated map view with the specified frame
+ and style URL.
  
  @param frame The frame for the view, measured in points.
- @param styleURL The map style URL to use. Can be either an HTTP/HTTPS URL or a Mapbox map ID style URL (`mapbox://styles/my_user_name/abcd1234`). Specify `nil` for the default style.
+ @param styleURL URL of the map style to display. The URL may be a full HTTP
+    or HTTPS URL, a Mapbox URL indicating the style's map ID
+    (`mapbox://styles/{user}/{style}`), or a path to a local file relative
+    to the application's resource path. Specify `nil` for the default style.
  @return An initialized map view.
  */
 - (instancetype)initWithFrame:(CGRect)frame styleURL:(nullable NSURL *)styleURL;
 
-#pragma mark Accessing Map Properties
+#pragma mark Accessing the Delegate
 
 /**
- A Boolean value that determines whether the user may zoom the map.
+ The receiver's delegate.
  
- This property controls only user interactions with the map. If you set the value of this property to `NO`, you may still change the map zoom programmatically.
+ A map view sends messages to its delegate to notify it of changes to its
+ contents or the viewpoint. The delegate also provides information about
+ annotations displayed on the map, such as the styles to apply to individual
+ annotations.
+ */
+@property(nonatomic, weak, nullable) IBOutlet id<MGLMapViewDelegate> delegate;
+
+#pragma mark Configuring the Map's Appearance
+
+/**
+ URLs of the styles bundled with the library.
  
- The default value of this property is `YES`.
+ @deprecated Call the relevant class method of `MGLStyle` for the URL of a
+    particular default style.
  */
-@property(nonatomic, getter=isZoomEnabled) BOOL zoomEnabled;
+@property (nonatomic, readonly) NS_ARRAY_OF(NSURL *) *bundledStyleURLs __attribute__((deprecated("Call the relevant class method of MGLStyle for the URL of a particular default style.")));
 
 /**
- A Boolean value that determines whether the user may scroll around the map.
+ URL of the style currently displayed in the receiver.
  
- This property controls only user interactions with the map. If you set the value of this property to `NO`, you may still change the map location programmatically.
+ The URL may be a full HTTP or HTTPS URL, a Mapbox URL indicating the style's
+ map ID (`mapbox://styles/{user}/{style}`), or a path to a local file
+ relative to the application's resource path.
  
- The default value of this property is `YES`.
+ If you set this property to `nil`, the receiver will use the default style
+ and this property will automatically be set to that style's URL.
  */
-@property(nonatomic, getter=isScrollEnabled) BOOL scrollEnabled;
+@property (nonatomic, null_resettable) NSURL *styleURL;
 
 /**
- A Boolean value that determines whether the user may rotate the map.
+ A control indicating the map's direction and allowing the user to manipulate
+ the direction, positioned in the upper-right corner.
+ */
+@property (nonatomic, readonly) UIImageView *compassView;
+
+/**
+ The Mapbox logo, positioned in the lower-left corner.
  
- This property controls only user interactions with the map. If you set the value of this property to `NO`, you may still rotate the map programmatically.
+ @note The Mapbox terms of service, which governs the use of Mapbox-hosted
+    vector tiles and styles,
+    [requires](https://www.mapbox.com/help/mapbox-logo/) most Mapbox
+    customers to display the Mapbox logo. If this applies to you, do not
+    hide this view or change its contents.
+ */
+@property (nonatomic, readonly) UIImageView *logoView;
+
+/** 
+ A view showing legally required copyright notices, positioned at the
+ bottom-right of the map view.
  
- The default value of this property is `YES`.
+ @note The Mapbox terms of service, which governs the use of Mapbox-hosted
+    vector tiles and styles,
+    [requires](https://www.mapbox.com/help/attribution/) these copyright
+    notices to accompany any map that features Mapbox-designed styles,
+    OpenStreetMap data, or other Mapbox data such as satellite or terrain
+    data. If that applies to this map view, do not hide this view or remove
+    any notices from it.
  */
-@property(nonatomic, getter=isRotateEnabled) BOOL rotateEnabled;
+@property (nonatomic, readonly) UIButton *attributionButton;
+
+/** 
+ Currently active style classes, represented as an array of string identifiers.
+ */
+@property (nonatomic) NS_ARRAY_OF(NSString *) *styleClasses;
 
 /**
- A Boolean value that determines whether the user may change the pitch (tilt) of the map.
+ Returns a Boolean value indicating whether the style class with the given
+ identifier is currently active.
  
- This property controls only user interactions with the map. If you set the value of this property to `NO`, you may still change the pitch of the map programmatically.
+ @param styleClass The style class to query for.
+ @return Whether the style class is currently active.
+ */
+- (BOOL)hasStyleClass:(NSString *)styleClass;
+
+/**
+ Activates the style class with the given identifier.
  
- The default value of this property is `YES`.
+ @param styleClass The style class to activate.
  */
-@property(nonatomic, getter=isPitchEnabled) BOOL pitchEnabled;
+- (void)addStyleClass:(NSString *)styleClass;
 
-/** The compass image view shown in the upper-right when the map is rotated. */
-@property (nonatomic, readonly) UIImageView *compassView;
+/**
+ Deactivates the style class with the given identifier.
+ 
+ @param styleClass The style class to deactivate.
+ */
+- (void)removeStyleClass:(NSString *)styleClass;
 
-/** The Mapbox logo image view shown in the lower-left of the map. */
-@property (nonatomic, readonly) UIImageView *logoView;
+#pragma mark Displaying the User's Location
 
-/** The button shown in the lower-right of the map which when pressed displays the map attribution information. */
-@property (nonatomic, readonly) UIButton *attributionButton;
+/**
+ A Boolean value indicating whether the map may display the user location.
+ 
+ Setting this property to `YES` causes the map view to use the Core Location
+ framework to find the current location. As long as this property is `YES`, the
+ map view continues to track the user's location and update it periodically.
+ 
+ This property does not indicate whether the user's position is actually visible
+ on the map, only whether the map view is allowed to display it. To determine
+ whether the user's position is visible, use the `userLocationVisible` property.
+ The default value of this property is `NO`.
+ 
+ On iOS 8 and above, your app must specify a value for
+ `NSLocationWhenInUseUsageDescription` or `NSLocationAlwaysUsageDescription` in
+ its `Info.plist` to satisfy the requirements of the underlying Core Location
+ framework when enabling this property.
+ */
+@property (nonatomic, assign) BOOL showsUserLocation;
 
-#pragma mark Accessing the Delegate
+/** 
+ A Boolean value indicating whether the device's current location is visible in
+ the map view.
+ 
+ Use `showsUserLocation` to control the visibility of the on-screen user
+ location annotation.
+ */
+@property (nonatomic, assign, readonly, getter=isUserLocationVisible) BOOL userLocationVisible;
 
-// TODO
-@property(nonatomic, weak, nullable) IBOutlet id<MGLMapViewDelegate> delegate;
+/**
+ Returns the annotation object indicating the user's current location.
+ */
+@property (nonatomic, readonly, nullable) MGLUserLocation *userLocation;
 
-#pragma mark Manipulating the Visible Portion of the Map
+/** 
+ The mode used to track the user location.
+ */
+@property (nonatomic, assign) MGLUserTrackingMode userTrackingMode;
 
 /**
- The map coordinate at the center of the map view.
+ Whether the map view should display a heading calibration alert when necessary.
+ The default value is `YES`.
+ */
+@property (nonatomic, assign) BOOL displayHeadingCalibration;
+
+#pragma mark Configuring How the User Interacts with the Map
+
+/**
+ A Boolean value that determines whether the user may zoom the map in and
+ out, changing the zoom level.
  
- Changing the value in this property centers the map on the new coordinate without changing the current zoom level.
+ When this property is set to `YES`, the default, the user may zoom the map
+ in and out by pinching two fingers or by double tapping, holding, and moving
+ the finger up and down.
  
- Changing the value of this property updates the map view immediately. If you want to animate the change, use the `-setCenterCoordinate:animated:` method instead.
+ This property controls only user interactions with the map. If you set the
+ value of this property to `NO`, you may still change the map zoom
+ programmatically.
  */
-@property (nonatomic) CLLocationCoordinate2D centerCoordinate;
+@property(nonatomic, getter=isZoomEnabled) BOOL zoomEnabled;
 
 /**
- Changes the center coordinate of the map and optionally animates the change.
+ A Boolean value that determines whether the user may scroll around the map,
+ changing the center coordinate.
  
- @param coordinate The new center coordinate for the map.
- @param animated Specify `YES` if you want the map view to scroll to the new location or `NO` if you want the map to display the new location immediately.
+ When this property is set to `YES`, the default, the user may scroll the map
+ by dragging or swiping with one finger.
  
- Changing the center coordinate centers the map on the new coordinate without changing the current zoom level.
+ This property controls only user interactions with the map. If you set the
+ value of this property to `NO`, you may still change the map location
+ programmatically.
  */
-- (void)setCenterCoordinate:(CLLocationCoordinate2D)coordinate animated:(BOOL)animated;
+@property(nonatomic, getter=isScrollEnabled) BOOL scrollEnabled;
 
 /**
- The zoom level of the map view.
+ A Boolean value that determines whether the user may rotate the map,
+ changing the direction.
  
- Changing the value in this property zooms the map in or out without changing the center coordinate. At zoom level 0, tiles cover the entire world map; at zoom level 1, tiles cover 1/4 of the world; at zoom level 2, tiles cover 1/16 of the world, and so on.
+ When this property is set to `YES`, the default, the user may rotate the map
+ by moving two fingers in a circular motion.
  
- Changing the value of this property updates the map view immediately. If you want to animate the change, use the `-setZoomLevel:animated:` method instead.
+ This property controls only user interactions with the map. If you set the
+ value of this property to `NO`, you may still rotate the map
+ programmatically.
  */
-@property (nonatomic) double zoomLevel;
+@property(nonatomic, getter=isRotateEnabled) BOOL rotateEnabled;
 
 /**
- Changes the zoom level of the map and optionally animates the change.
+ A Boolean value that determines whether the user may change the pitch (tilt) of
+ the map.
  
- @param zoomLevel The new zoom level for the map.
- @param animated Specify `YES` if you want the map view to animate the change to the new zoom level or `NO` if you want the map to display the new zoom level immediately.
+ When this property is set to `YES`, the default, the user may tilt the map by
+ vertically dragging two fingers.
+ 
+ This property controls only user interactions with the map. If you set the
+ value of this property to `NO`, you may still change the pitch of the map
+ programmatically.
  
- Changing the zoom level scales the map without changing the current center coordinate. At zoom level 0, tiles cover the entire world map; at zoom level 1, tiles cover 1/4 of the world; at zoom level 2, tiles cover 1/16 of the world, and so on.
+ The default value of this property is `YES`.
  */
-- (void)setZoomLevel:(double)zoomLevel animated:(BOOL)animated;
+@property(nonatomic, getter=isPitchEnabled) BOOL pitchEnabled;
+
+#pragma mark Manipulating the Viewpoint
+
+/**
+ The geographic coordinate at the center of the map view.
+ 
+ Changing the value of this property centers the map on the new coordinate
+ without changing the current zoom level.
+ 
+ Changing the value of this property updates the map view immediately. If you
+ want to animate the change, use the `-setCenterCoordinate:animated:` method
+ instead.
+ */
+@property (nonatomic) CLLocationCoordinate2D centerCoordinate;
 
 /**
- Changes the center coordinate and zoom level of the map and optionally animates the change.
+ Changes the center coordinate of the map and optionally animates the change.
+ 
+ Changing the center coordinate centers the map on the new coordinate without
+ changing the current zoom level.
+ 
+ @param coordinate The new center coordinate for the map.
+ @param animated Specify `YES` if you want the map view to scroll to the new
+    location or `NO` if you want the map to display the new location
+    immediately.
+ */
+- (void)setCenterCoordinate:(CLLocationCoordinate2D)coordinate animated:(BOOL)animated;
+
+/**
+ Changes the center coordinate and zoom level of the map and optionally animates
+ the change.
  
  @param centerCoordinate The new center coordinate for the map.
  @param zoomLevel The new zoom level for the map.
- @param animated Specify `YES` if you want the map view to animate scrolling and zooming to the new location or `NO` if you want the map to display the new location immediately.
+ @param animated Specify `YES` if you want the map view to animate scrolling and
+    zooming to the new location or `NO` if you want the map to display the new
+    location immediately.
  */
 - (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate zoomLevel:(double)zoomLevel animated:(BOOL)animated;
 
 /**
- Changes the center coordinate, zoom level, and direction of the map and optionally animates the change.
+ Changes the center coordinate, zoom level, and direction of the map and
+ optionally animates the change.
  
  @param centerCoordinate The new center coordinate for the map.
  @param zoomLevel The new zoom level for the map.
- @param direction The new direction for the map, measured in degrees relative to true north.
- @param animated Specify `YES` if you want the map view to animate scrolling, zooming, and rotating to the new location or `NO` if you want the map to display the new location immediately.
+ @param direction The new direction for the map, measured in degrees relative to
+    true north.
+ @param animated Specify `YES` if you want the map view to animate scrolling,
+    zooming, and rotating to the new location or `NO` if you want the map to
+    display the new location immediately.
  */
 - (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate zoomLevel:(double)zoomLevel direction:(CLLocationDirection)direction animated:(BOOL)animated;
 
 /**
- Changes the center coordinate, zoom level, and direction of the map, calling a completion handler at the end of an optional animation.
+ Changes the center coordinate, zoom level, and direction of the map, calling a
+ completion handler at the end of an optional animation.
  
  @param centerCoordinate The new center coordinate for the map.
  @param zoomLevel The new zoom level for the map.
- @param direction The new direction for the map, measured in degrees relative to true north.
- @param animated Specify `YES` if you want the map view to animate scrolling, zooming, and rotating to the new location or `NO` if you want the map to display the new location immediately.
+ @param direction The new direction for the map, measured in degrees relative to
+    true north.
+ @param animated Specify `YES` if you want the map view to animate scrolling,
+    zooming, and rotating to the new location or `NO` if you want the map to
+    display the new location immediately.
  @param completion The block executed after the animation finishes.
  */
 - (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate zoomLevel:(double)zoomLevel direction:(CLLocationDirection)direction animated:(BOOL)animated completionHandler:(nullable void (^)(void))completion;
 
+/** The zoom level of the receiver.
+ 
+ In addition to affecting the visual size and detail of features on the map,
+ the zoom level affects the size of the vector tiles that are loaded. At zoom
+ level 0, each tile covers the entire world map; at zoom level 1, it covers ¼
+ of the world; at zoom level 2, <sup>1</sup>⁄<sub>16</sub> of the world, and
+ so on.
+ 
+ Changing the value of this property updates the map view immediately. If you
+ want to animate the change, use the `-setZoomLevel:animated:` method instead.
+ */
+@property (nonatomic) double zoomLevel;
+
+/**
+ Changes the zoom level of the map and optionally animates the change.
+ 
+ Changing the zoom level scales the map without changing the current center
+ coordinate.
+ 
+ @param zoomLevel The new zoom level for the map.
+ @param animated Specify `YES` if you want the map view to animate the change
+    to the new zoom level or `NO` if you want the map to display the new
+    zoom level immediately.
+ */
+- (void)setZoomLevel:(double)zoomLevel animated:(BOOL)animated;
+
+/**
+ The heading of the map, measured in degrees clockwise from true north.
+ 
+ The value `0` means that the top edge of the map view corresponds to true
+ north. The value `90` means the top of the map is pointing due east. The
+ value `180` means the top of the map points due south, and so on.
+ 
+ Changing the value of this property updates the map view immediately. If you
+ want to animate the change, use the `-setDirection:animated:` method instead.
+ */
+@property (nonatomic) CLLocationDirection direction;
+
+/**
+ Changes the heading of the map and optionally animates the change.
+ 
+ @param direction The heading of the map, measured in degrees clockwise from
+    true north.
+ @param animated Specify `YES` if you want the map view to animate the change
+    to the new heading or `NO` if you want the map to display the new
+    heading immediately.
+ 
+ Changing the heading rotates the map without changing the current center
+ coordinate or zoom level.
+ */
+- (void)setDirection:(CLLocationDirection)direction animated:(BOOL)animated;
+
+/**
+ Resets the map rotation to a northern heading — a `direction` of `0` degrees.
+ */
+- (IBAction)resetNorth;
+
 /**
- The coordinate bounds visible in the receiver’s viewport.
+ The coordinate bounds visible in the receiver's viewport.
  
- Changing the value of this property updates the receiver immediately. If you want to animate the change, call `-setVisibleCoordinateBounds:animated:` instead.
+ Changing the value of this property updates the receiver immediately. If you
+ want to animate the change, call `-setVisibleCoordinateBounds:animated:`
+ instead.
  */
 @property (nonatomic) MGLCoordinateBounds visibleCoordinateBounds;
 
 /**
- Changes the receiver’s viewport to fit the given coordinate bounds, optionally animating the change.
+ Changes the receiver’s viewport to fit the given coordinate bounds,
+ optionally animating the change.
  
  @param bounds The bounds that the viewport will show in its entirety.
- @param animated Specify `YES` to animate the change by smoothly scrolling and zooming or `NO` to immediately display the given bounds.
+ @param animated Specify `YES` to animate the change by smoothly scrolling
+    and zooming or `NO` to immediately display the given bounds.
  */
 - (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds animated:(BOOL)animated;
 
 /**
- Changes the receiver’s viewport to fit the given coordinate bounds and optionally some additional padding on each side.
+ Changes the receiver's viewport to fit the given coordinate bounds and
+ optionally some additional padding on each side.
  
  @param bounds The bounds that the viewport will show in its entirety.
- @param insets The minimum padding (in screen points) that will be visible around the given coordinate bounds.
- @param animated Specify `YES` to animate the change by smoothly scrolling and zooming or `NO` to immediately display the given bounds.
+ @param insets The minimum padding (in screen points) that will be visible
+    around the given coordinate bounds.
+ @param animated Specify `YES` to animate the change by smoothly scrolling and
+    zooming or `NO` to immediately display the given bounds.
  */
 - (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds edgePadding:(UIEdgeInsets)insets animated:(BOOL)animated;
 
 /**
- Changes the receiver’s viewport to fit all of the given coordinates and optionally some additional padding on each side.
+ Changes the receiver's viewport to fit all of the given coordinates and
+ optionally some additional padding on each side.
  
  @param coordinates The coordinates that the viewport will show.
- @param count The number of coordinates. This number must not be greater than the number of elements in `coordinates`.
- @param insets The minimum padding (in screen points) that will be visible around the given coordinate bounds.
- @param animated Specify `YES` to animate the change by smoothly scrolling and zooming or `NO` to immediately display the given bounds.
+ @param count The number of coordinates. This number must not be greater than
+    the number of elements in `coordinates`.
+ @param insets The minimum padding (in screen points) that will be visible
+    around the given coordinate bounds.
+ @param animated Specify `YES` to animate the change by smoothly scrolling and
+    zooming or `NO` to immediately display the given bounds.
  */
 - (void)setVisibleCoordinates:(CLLocationCoordinate2D *)coordinates count:(NSUInteger)count edgePadding:(UIEdgeInsets)insets animated:(BOOL)animated;
 
 /**
- Changes the receiver’s viewport to fit all of the given coordinates and optionally some additional padding on each side.
+ Changes the receiver's viewport to fit all of the given coordinates and
+ optionally some additional padding on each side.
  
  @param coordinates The coordinates that the viewport will show.
- @param count The number of coordinates. This number must not be greater than the number of elements in `coordinates`.
- @param insets The minimum padding (in screen points) that will be visible around the given coordinate bounds.
- @param direction The direction to rotate the map to, measured in degrees relative to true north.
+ @param count The number of coordinates. This number must not be greater than
+    the number of elements in `coordinates`.
+ @param insets The minimum padding (in screen points) that will be visible
+    around the given coordinate bounds.
+ @param direction The direction to rotate the map to, measured in degrees
+    relative to true north.
  @param duration The duration to animate the change in seconds.
  @param function The timing function to animate the change.
  @param completion The block executed after the animation finishes.
@@ -219,67 +462,67 @@ IB_DESIGNABLE
 /**
  Sets the visible region so that the map displays the specified annotations.
  
- Calling this method updates the value in the visibleCoordinateBounds property and potentially other properties to reflect the new map region.
+ Calling this method updates the value in the visibleCoordinateBounds property
+ and potentially other properties to reflect the new map region.
  
  @param annotations The annotations that you want to be visible in the map.
- @param animated `YES` if you want the map region change to be animated, or `NO` if you want the map to display the new region immediately without animations.
+ @param animated `YES` if you want the map region change to be animated, or `NO`
+    if you want the map to display the new region immediately without animations.
  */
 - (void)showAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations animated:(BOOL)animated;
 
 /**
- The heading of the map (measured in degrees) relative to true north.
- 
- The value `0` means that the top edge of the map view corresponds to true north. The value `90` means the top of the map is pointing due east. The value `180` means the top of the map points due south, and so on.
+ A camera representing the current viewpoint of the map.
  */
-@property (nonatomic) CLLocationDirection direction;
-
-/**
- Changes the heading of the map and optionally animates the changes.
- 
- @param direction The heading of the map (measured in degrees) relative to true north.
- @param animated Specify `YES` if you want the map view to animate the change to the new heading or `NO` if you want the map to display the new heading immediately.
- 
- Changing the heading rotates the map without changing the current center coordinate or zoom level.
- */
-- (void)setDirection:(CLLocationDirection)direction animated:(BOOL)animated;
-
-/** Resets the map rotation to a northern heading. */
-- (IBAction)resetNorth;
-
-/** A camera representing the current viewpoint of the map. */
 @property (nonatomic, copy) MGLMapCamera *camera;
 
 /**
- Moves the viewpoint to a different location with respect to the map with an optional transition animation.
+ Moves the viewpoint to a different location with respect to the map with an
+ optional transition animation.
  
  @param camera The new viewpoint.
- @param animated Specify `YES` if you want the map view to animate the change to the new viewpoint or `NO` if you want the map to display the new viewpoint immediately.
+ @param animated Specify `YES` if you want the map view to animate the change to
+    the new viewpoint or `NO` if you want the map to display the new viewpoint
+    immediately.
  */
 - (void)setCamera:(MGLMapCamera *)camera animated:(BOOL)animated;
 
 /**
- Moves the viewpoint to a different location with respect to the map with an optional transition duration and timing function.
+ Moves the viewpoint to a different location with respect to the map with an
+ optional transition duration and timing function.
  
  @param camera The new viewpoint.
- @param duration The amount of time, measured in seconds, that the transition animation should take. Specify `0` to jump to the new viewpoint instantaneously.
- @param function A timing function used for the animation. Set this parameter to `nil` for a transition that matches most system animations. If the duration is `0`, this parameter is ignored.
+ @param duration The amount of time, measured in seconds, that the transition
+    animation should take. Specify `0` to jump to the new viewpoint
+    instantaneously.
+ @param function A timing function used for the animation. Set this parameter to
+    `nil` for a transition that matches most system animations. If the duration
+    is `0`, this parameter is ignored.
  */
 - (void)setCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration animationTimingFunction:(nullable CAMediaTimingFunction *)function;
 
 /**
- Moves the viewpoint to a different location with respect to the map with an optional transition duration and timing function.
+ Moves the viewpoint to a different location with respect to the map with an
+ optional transition duration and timing function.
  
  @param camera The new viewpoint.
- @param duration The amount of time, measured in seconds, that the transition animation should take. Specify `0` to jump to the new viewpoint instantaneously.
- @param function A timing function used for the animation. Set this parameter to `nil` for a transition that matches most system animations. If the duration is `0`, this parameter is ignored.
+ @param duration The amount of time, measured in seconds, that the transition
+    animation should take. Specify `0` to jump to the new viewpoint
+    instantaneously.
+ @param function A timing function used for the animation. Set this parameter to
+    `nil` for a transition that matches most system animations. If the duration
+    is `0`, this parameter is ignored.
  @param completion The block to execute after the animation finishes.
  */
 - (void)setCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration animationTimingFunction:(nullable CAMediaTimingFunction *)function completionHandler:(nullable void (^)(void))completion;
 
 /**
- Moves the viewpoint to a different location using a transition animation that evokes powered flight and a default duration based on the length of the flight path.
+ Moves the viewpoint to a different location using a transition animation that
+ evokes powered flight and a default duration based on the length of the flight
+ path.
  
- The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.
+ The transition animation seamlessly incorporates zooming and panning to help
+ the user find his or her bearings even after traversing a great distance.
  
  @param camera The new viewpoint.
  @param completion The block to execute after the animation finishes.
@@ -287,29 +530,42 @@ IB_DESIGNABLE
 - (void)flyToCamera:(MGLMapCamera *)camera completionHandler:(nullable void (^)(void))completion;
 
 /**
- Moves the viewpoint to a different location using a transition animation that evokes powered flight and an optional transition duration.
+ Moves the viewpoint to a different location using a transition animation that
+ evokes powered flight and an optional transition duration.
  
- The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.
+ The transition animation seamlessly incorporates zooming and panning to help
+ the user find his or her bearings even after traversing a great distance.
  
  @param camera The new viewpoint.
- @param duration The amount of time, measured in seconds, that the transition animation should take. Specify `0` to jump to the new viewpoint instantaneously. Specify a negative value to use the default duration, which is based on the length of the flight path.
+ @param duration The amount of time, measured in seconds, that the transition
+    animation should take. Specify `0` to jump to the new viewpoint
+    instantaneously. Specify a negative value to use the default duration, which
+    is based on the length of the flight path.
  @param completion The block to execute after the animation finishes.
  */
 - (void)flyToCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration completionHandler:(nullable void (^)(void))completion;
 
 /**
- Moves the viewpoint to a different location using a transition animation that evokes powered flight and an optional transition duration and peak altitude.
+ Moves the viewpoint to a different location using a transition animation that
+ evokes powered flight and an optional transition duration and peak altitude.
  
- The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.
+ The transition animation seamlessly incorporates zooming and panning to help
+ the user find his or her bearings even after traversing a great distance.
  
  @param camera The new viewpoint.
- @param duration The amount of time, measured in seconds, that the transition animation should take. Specify `0` to jump to the new viewpoint instantaneously. Specify a negative value to use the default duration, which is based on the length of the flight path.
- @param peakAltitude The altitude, measured in meters, at the midpoint of the animation. The value of this parameter is ignored if it is negative or if the animation transition resulting from a similar call to `-setCamera:animated:` would have a midpoint at a higher altitude.
+ @param duration The amount of time, measured in seconds, that the transition
+    animation should take. Specify `0` to jump to the new viewpoint
+    instantaneously. Specify a negative value to use the default duration, which
+    is based on the length of the flight path.
+ @param peakAltitude The altitude, measured in meters, at the midpoint of the
+    animation. The value of this parameter is ignored if it is negative or if
+    the animation transition resulting from a similar call to
+    `-setCamera:animated:` would have a midpoint at a higher altitude.
  @param completion The block to execute after the animation finishes.
  */
 - (void)flyToCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration peakAltitude:(CLLocationDistance)peakAltitude completionHandler:(nullable void (^)(void))completion;
 
-#pragma mark Converting Map Coordinates
+#pragma mark Converting Geographic Coordinates
 
 /**
  Converts a point in the specified view’s coordinate system to a map coordinate.
@@ -321,135 +577,119 @@ IB_DESIGNABLE
 - (CLLocationCoordinate2D)convertPoint:(CGPoint)point toCoordinateFromView:(nullable UIView *)view;
 
 /**
- Converts a map coordinate to a point in the specified view.
+ Converts a geographic coordinate to a point in the given view's coordinate
+ system.
  
- @param coordinate The map coordinate for which you want to find the corresponding point.
- @param view The view in whose coordinate system you want to locate the specified map coordinate. If this parameter is `nil`, the returned point is specified in the window’s coordinate system. If `view` is not `nil`, it must belong to the same window as the map view.
- @return The point (in the appropriate view or window coordinate system) corresponding to the specified latitude and longitude value.
+ @param coordinate The geographic coordinate to convert.
+ @param view The view in whose coordinate system the returned point should be
+    expressed. If this parameter is `nil`, the returned point is expressed
+    in the window's coordinate system. If `view` is not `nil`, it must
+    belong to the same window as the map view.
+ @return The point (in the appropriate view or window coordinate system)
+    corresponding to the given geographic coordinate.
  */
 - (CGPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(nullable UIView *)view;
 
 /**
- Returns the distance spanned by one point in the map view's coordinate system at the given latitude and current zoom level.
+ Returns the distance spanned by one point in the map view's coordinate system
+ at the given latitude and current zoom level.
  
- The distance between points decreases as the latitude approaches the poles. This relationship parallels the relationship between longitudinal coordinates at different latitudes.
+ The distance between points decreases as the latitude approaches the poles.
+ This relationship parallels the relationship between longitudinal coordinates
+ at different latitudes.
  
- @param latitude The latitude of the geographic coordinate represented by the point.
+ @param latitude The latitude of the geographic coordinate represented by the
+    point.
  @return The distance in meters spanned by a single point.
  */
 - (CLLocationDistance)metersPerPointAtLatitude:(CLLocationDegrees)latitude;
 
 - (CLLocationDistance)metersPerPixelAtLatitude:(CLLocationDegrees)latitude __attribute__((deprecated("Use -metersPerPointAtLatitude:.")));
 
-#pragma mark Styling the Map
-
-@property (nonatomic, nullable) NSString *styleID __attribute__((unavailable("Set styleURL to an NSURL of the form <mapbox://styles/STYLE_ID>, where STYLE_ID would have been the value of this property.")));
-
-/**
- URLs of the styles bundled with the library.
- 
- @deprecated Call the relevant class method of `MGLStyle` for the URL of a particular default style.
- */
-@property (nonatomic, readonly) NS_ARRAY_OF(NSURL *) *bundledStyleURLs __attribute__((deprecated("Call the relevant class method of MGLStyle for the URL of a particular default style.")));
-
-/**
- URL of the style currently displayed in the receiver.
- 
- The URL may be a full HTTP or HTTPS URL or a Mapbox URL indicating the style’s map ID (`mapbox://styles/my_user_name/abcd1234`).
- 
- To display the default style, set this property to `nil`.
- */
-@property (nonatomic, null_resettable) NSURL *styleURL;
-
-/** Currently active style classes, represented as an array of string identifiers. */
-@property (nonatomic) NS_ARRAY_OF(NSString *) *styleClasses;
-
-/**
- Returns a Boolean value indicating whether the style class with the given identifier is currently active.
- 
- @param styleClass The style class to query for.
- @return Whether the style class is currently active.
- */
-- (BOOL)hasStyleClass:(NSString *)styleClass;
-
-/**
- Activates the style class with the given identifier.
- 
- @param styleClass The style class to activate.
- */
-- (void)addStyleClass:(NSString *)styleClass;
-
-/**
- Deactivates the style class with the given identifier.
- 
- @param styleClass The style class to deactivate.
- */
-- (void)removeStyleClass:(NSString *)styleClass;
-
 #pragma mark Annotating the Map
 
 /**
  The complete list of annotations associated with the receiver. (read-only)
  
- The objects in this array must adopt the MGLAnnotation protocol. If no annotations are associated with the map view, the value of this property is `nil`.
+ The objects in this array must adopt the `MGLAnnotation` protocol. If no
+ annotations are associated with the map view, the value of this property is
+ `nil`.
  */
 @property (nonatomic, readonly, nullable) NS_ARRAY_OF(id <MGLAnnotation>) *annotations;
 
 /**
- Adds the specified annotation to the map view.
+ Adds an annotation to the map view.
  
- @param annotation The annotation object to add to the receiver. This object must conform to the MGLAnnotation protocol. The map view retains the specified object.
- */
+ @param annotation The annotation object to add to the receiver. This object
+    must conform to the `MGLAnnotation` protocol. The map view retains the
+    annotation object. */
 - (void)addAnnotation:(id <MGLAnnotation>)annotation;
 
 /**
- Adds an array of annotation objects to the map view.
+ Adds an array of annotations to the map view.
  
- @param annotations An array of annotation objects. Each object in the array must conform to the MGLAnnotation protocol. The map view retains the individual annotation objects.
+ @param annotations An array of annotation objects. Each object in the array
+    must conform to the `MGLAnnotation` protocol. The map view retains each
+    individual annotation object.
  */
 - (void)addAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations;
 
 /**
- Removes the specified annotation object from the map view.
+ Removes an annotation from the map view, deselecting it if it is selected.
  
- Removing an annotation object disassociates it from the map view entirely, preventing it from being displayed on the map. Thus, you would typically call this method only when you want to hide or delete a given annotation.
+ Removing an annotation object dissociates it from the map view entirely,
+ preventing it from being displayed on the map. Thus you would typically call
+ this method only when you want to hide or delete a given annotation.
  
- @param annotation The annotation object to remove. This object must conform to the MGLAnnotation protocol.
+ @param annotation The annotation object to remove. This object must conform
+    to the `MGLAnnotation` protocol
  */
 - (void)removeAnnotation:(id <MGLAnnotation>)annotation;
 
 /**
- Removes an array of annotation objects from the map view.
+ Removes an array of annotations from the map view, deselecting any selected
+ annotations in the array.
  
- Removing annotation objects disassociates them from the map view entirely, preventing them from being displayed on the map. Thus, you would typically call this method only when you want to hide or delete the specified annotations.
+ Removing annotation objects dissociates them from the map view entirely,
+ preventing them from being displayed on the map. Thus you would typically
+ call this method only when you want to hide or delete the given annotations.
  
- @param annotations The array of annotations to remove. Objects in the array must conform to the MGLAnnotation protocol.
+ @param annotations The array of annotation objects to remove. Objects in the
+    array must conform to the `MGLAnnotation` protocol.
  */
 - (void)removeAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations;
 
 /**
- Returns a reusable annotation image object located by its identifier.
+ Returns a reusable annotation image object associated with its identifier.
  
- For performance reasons, you should generally reuse MGLAnnotationImage objects for annotations in your map views. Dequeueing saves time and memory during performance-critical operations such as scrolling.
+ For performance reasons, you should generally reuse `MGLAnnotationImage`
+ objects for identical-looking annotations in your map views. Dequeueing
+ saves time and memory during performance-critical operations such as
+ scrolling.
  
- @param identifier A string identifying the annotation image to be reused. This string is the same one you specify when initially returning the annotation image object using the mapView:imageForAnnotation: method.
- @return An annotation image object with the specified identifier, or `nil` if no such object exists in the reuse queue.
+ @param identifier A string identifying the annotation image to be reused.
+    This string is the same one you specify when initially returning the
+    annotation image object using the `-mapView:imageForAnnotation:` method.
+ @return An annotation image object with the given identifier, or `nil` if no
+    such object exists in the reuse queue.
  */
 - (nullable MGLAnnotationImage *)dequeueReusableAnnotationImageWithIdentifier:(NSString *)identifier;
 
 #pragma mark Managing Annotation Selections
 
 /**
- The annotations that are currently selected.
+ The currently selected annotations.
  
- Assigning a new array to this property selects only the first annotation in the array.
+ Assigning a new array to this property selects only the first annotation in
+ the array.
  */
 @property (nonatomic, copy) NS_ARRAY_OF(id <MGLAnnotation>) *selectedAnnotations;
 
 /**
- Selects the specified annotation and displays a callout view for it.
+ Selects an annotation and displays a callout view for it.
  
- If the specified annotation is not onscreen, this method has no effect.
+ If the given annotation is not visible within the current viewport, this
+ method has no effect.
  
  @param annotation The annotation object to select.
  @param animated If `YES`, the callout view is animated into position.
@@ -457,21 +697,22 @@ IB_DESIGNABLE
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
 
 /**
- Deselects the specified annotation and hides its callout view.
+ Deselects an annotation and hides its callout view.
  
  @param annotation The annotation object to deselect.
  @param animated If `YES`, the callout view is animated offscreen.
  */
 - (void)deselectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
 
-#pragma mark Adding Overlays
+#pragma mark Overlaying the Map
 
 /**
  Adds a single overlay object to the map.
  
  To remove an overlay from a map, use the `-removeOverlay:` method.
  
- @param overlay The overlay object to add. This object must conform to the MGLOverlay protocol. */
+ @param overlay The overlay object to add. This object must conform to the
+    `MGLOverlay` protocol. */
 - (void)addOverlay:(id <MGLOverlay>)overlay;
 
 /**
@@ -479,16 +720,16 @@ IB_DESIGNABLE
  
  To remove multiple overlays from a map, use the `-removeOverlays:` method.
  
- @param overlays An array of objects, each of which must conform to the MGLOverlay protocol.
+ @param overlays An array of objects, each of which must conform to the
+    `MGLOverlay` protocol.
  */
 - (void)addOverlays:(NS_ARRAY_OF(id <MGLOverlay>) *)overlays;
 
-#pragma mark Removing Overlays
-
 /**
  Removes a single overlay object from the map.
  
- If the specified overlay is not currently associated with the map view, this method does nothing.
+ If the specified overlay is not currently associated with the map view, this
+ method does nothing.
  
  @param overlay The overlay object to remove.
  */
@@ -499,35 +740,11 @@ IB_DESIGNABLE
  
  If a given overlay object is not associated with the map view, it is ignored.
  
- @param overlays An array of objects, each of which conforms to the MGLOverlay protocol.
+ @param overlays An array of objects, each of which conforms to the `MGLOverlay`
+    protocol.
  */
 - (void)removeOverlays:(NS_ARRAY_OF(id <MGLOverlay>) *)overlays;
 
-#pragma mark Displaying the User's Location
-
-/**
- A Boolean value indicating whether the map may display the user location.
- 
- This property does not indicate whether the user’s position is actually visible on the map, only whether the map view is allowed to display it. To determine whether the user’s position is visible, use the userLocationVisible property. The default value of this property is `NO`.
- 
- Setting this property to `YES` causes the map view to use the Core Location framework to find the current location. As long as this property is `YES`, the map view continues to track the user’s location and update it periodically.
- 
- On iOS 8 and above, your app must specify a value for `NSLocationWhenInUseUsageDescription` or `NSLocationAlwaysUsageDescription` in its `Info.plist` to satisfy the requirements of the underlying Core Location framework when enabling this property.
- */
-@property (nonatomic, assign) BOOL showsUserLocation;
-
-/** A Boolean value indicating whether the device’s current location is visible in the map view. (read-only) */
-@property (nonatomic, assign, readonly, getter=isUserLocationVisible) BOOL userLocationVisible;
-
-/** Returns the annotation object indicating the user’s current location. */
-@property (nonatomic, readonly, nullable) MGLUserLocation *userLocation;
-
-/** The mode used to track the user location. */
-@property (nonatomic, assign) MGLUserTrackingMode userTrackingMode;
-
-/** Whether the map view should display a heading calibration alert when necessary. The default value is `YES`. */
-@property (nonatomic, assign) BOOL displayHeadingCalibration;
-
 #pragma mark Debugging
 
 /**
@@ -537,13 +754,24 @@ IB_DESIGNABLE
  */
 @property (nonatomic, getter=isDebugActive) BOOL debugActive;
 
-/** Cycle map debug options. */
+/**
+ Cycle through the options that determine which debugging aids are shown on the
+ map.
+ 
+ These options are all disabled by default and should remain disabled in
+ released software.
+ */
 - (void)cycleDebugOptions;
 
-/** Empties the in-memory tile cache. */
+/**
+    Empties the in-memory tile cache.
+ */
 - (void)emptyMemoryCache;
 
-/** Resets the map to the minimum zoom level, a center coordinate of (0, 0), and a northern heading. */
+/**
+    Resets the map to the minimum zoom level, a center coordinate of (0, 0), and
+    a northern heading.
+ */
 - (void)resetPosition;
 
 @end
@@ -624,45 +852,45 @@ IB_DESIGNABLE
 #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`.
  
- @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`.
  
- @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.
  
- @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 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.
  
@@ -674,8 +902,6 @@ IB_DESIGNABLE
 
 #pragma mark Managing the Display of Annotations
 
-- (nullable NSString *)mapView:(MGLMapView *)mapView symbolNameForAnnotation:(id <MGLAnnotation>)annotation __attribute__((unavailable("Use -mapView:imageForAnnotation:.")));
-
 /**
  Returns an image object to use for the marker for the specified point annotation object.
  
@@ -739,7 +965,7 @@ IB_DESIGNABLE
  
  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.
  
- 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.
+ 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.
@@ -752,7 +978,7 @@ IB_DESIGNABLE
  
  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`.
  
- 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.
+ 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.