Merge branch 'release-ios-v3.3.0' into master

4 files changed, 45 insertions, 15 deletions

diff --git a/platform/macos/CHANGELOG.md b/platform/macos/CHANGELOG.md
index 675cdd885a..c30dbe064b 100644
--- a/platform/macos/CHANGELOG.md
+++ b/platform/macos/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 * Right-clicking to open MGLMapView’s context menu no longer prevents the user from subsequently panning the map by clicking and dragging. ([#5593](https://github.com/mapbox/mapbox-gl-native/pull/5593))
 * Replaced the wireframe debug mask with an overdraw visualization debug mask to match Mapbox GL JS’s overdraw inspector. ([#5403](https://github.com/mapbox/mapbox-gl-native/pull/5403))
+* Improved the design of the generated API documentation. ([#5306](https://github.com/mapbox/mapbox-gl-native/pull/5306))
 
 ## 0.2.0
 
diff --git a/platform/macos/docs/doc-README.md b/platform/macos/docs/doc-README.md
index e8f7029bd6..4aba26afd9 100644
--- a/platform/macos/docs/doc-README.md
+++ b/platform/macos/docs/doc-README.md
@@ -2,7 +2,7 @@
 
 The Mapbox macOS SDK is an open-source framework for embedding interactive map views with scalable, customizable vector maps into Cocoa applications on macOS 10.10.0 and above using Objective-C, Swift, or Interface Builder. It takes stylesheets that conform to the [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/), applies them to vector tiles that conform to the [Mapbox Vector Tile Specification](https://www.mapbox.com/developers/vector-tiles/), and renders them using OpenGL.
 
-<img alt="" src="https://raw.githubusercontent.com/mapbox/mapbox-gl-native/master/platform/macos/screenshot.png" width="645">
+<img alt="Mapbox macOS SDK screenshot" src="screenshot.png" width="645">
 
 For setup information, consult the README.md that comes with this documentation. The [Mapbox iOS SDK](https://www.mapbox.com/ios-sdk/)’s [API documentation](https://www.mapbox.com/ios-sdk/api/) and [online examples](https://www.mapbox.com/ios-sdk/examples/) apply to the Mapbox macOS SDK with few differences, mostly around unimplemented features like user location tracking. A [full changelog](https://github.com/mapbox/mapbox-gl-native/blob/master/platform/macos/CHANGELOG.md) is also available.
 
diff --git a/platform/macos/scripts/document.sh b/platform/macos/scripts/document.sh
index e62a1e1668..526aecb7d1 100755
--- a/platform/macos/scripts/document.sh
+++ b/platform/macos/scripts/document.sh
@@ -32,6 +32,8 @@ sed -n -e '/^## /{' -e ':a' -e 'n' -e '/^##/q' -e 'p' -e 'ba' -e '}' platform/ma
 rm -rf ${OUTPUT}
 mkdir -p ${OUTPUT}
 
+cp platform/macos/screenshot.png "${OUTPUT}"
+
 jazzy \
     --config platform/macos/jazzy.yml \
     --sdk macosx \
@@ -39,6 +41,7 @@ jazzy \
     --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \
     --module-version ${SHORT_VERSION} \
     --readme ${README} \
+    --theme platform/darwin/docs/theme \
     --output ${OUTPUT}
 # https://github.com/realm/jazzy/issues/411
 find ${OUTPUT} -name *.html -exec \
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.