1 files changed, 64 insertions, 21 deletions
diff --git a/platform/darwin/src/MGLMapSnapshotter.h b/platform/darwin/src/MGLMapSnapshotter.h
index a2a4f1b331..615d39bee4 100644
--- a/platform/darwin/src/MGLMapSnapshotter.h
+++ b/platform/darwin/src/MGLMapSnapshotter.h
@@ -12,40 +12,52 @@ MGL_EXPORT
 @interface MGLMapSnapshotOptions : NSObject
 
 /**
- Creates a set of options with the minimum required information
- @param styleURL the style url to use
- @param camera the camera settings
- @param size the image size
+ Creates a set of options with the minimum required information.
+ 
+ @param styleURL URL of the map style to snapshot. 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.
+ @param size The image size.
  */
-- (instancetype)initWithStyleURL:(NSURL*)styleURL camera:(MGLMapCamera*)camera size:(CGSize)size;
+- (instancetype)initWithStyleURL:(nullable NSURL *)styleURL camera:(MGLMapCamera *)camera size:(CGSize)size;
 
-#pragma mark - Configuring the map
+#pragma mark - Configuring the Map
 
 /**
-  The style URL for these options.
+ URL of the map style to snapshot.
  */
-@property (nonatomic, readonly) NSURL* styleURL;
+@property (nonatomic, readonly) NSURL *styleURL;
 
 /**
- The zoom. Default is 0.
+ The zoom level.
+ 
+ The default zoom level is 0. If this property is non-zero and the camera property
+ is non-nil, the camera’s altitude is ignored in favor of this property’s value.
  */
-@property (nonatomic) double zoom;
+@property (nonatomic) double zoomLevel;
 
 /**
- The `MGLMapcamera` options to use.
+ A camera representing the viewport visible in the snapshot.
+ 
+ If this property is non-nil and the `coordinateBounds` property is set to a non-empty
+ coordinate bounds, the camera’s center coordinate and altitude are ignored in favor
+ of the `coordinateBounds` property.
  */
-@property (nonatomic) MGLMapCamera* camera;
+@property (nonatomic) MGLMapCamera *camera;
 
 /**
- A region to capture. Overrides the center coordinate
- in the mapCamera options if set
+ The cooordinate rectangle that encompasses the bounds to capture.
+ 
+ If this property is non-empty and the camera property is non-nil, the camera’s
+ center coordinate and altitude are ignored in favor of this property’s value.
  */
-@property (nonatomic) MGLCoordinateBounds region;
+@property (nonatomic) MGLCoordinateBounds coordinateBounds;
 
-#pragma mark - Configuring the image
+#pragma mark - Configuring the Image
 
 /**
- The size of the output image. Minimum is 64x64
+ The size of the output image, measured in points.
+ 
  */
 @property (nonatomic, readonly) CGSize size;
 
@@ -57,18 +69,46 @@ MGL_EXPORT
 
 @end
 
+#if TARGET_OS_IPHONE
 /**
  A block to processes the result or error of a snapshot request.
  
- The result will be either an `MGLImage` or a `NSError`
+ @param snapshot The `UIImage` that was generated or `nil` if an error occurred.
+ @param error The error that occured or `nil` when successful.
+ */
+typedef void (^MGLMapSnapshotCompletionHandler)(UIImage* _Nullable snapshot, NSError* _Nullable error);
+#else
+/**
+ A block to processes the result or error of a snapshot request.
  
- @param snapshot The image that was generated or `nil` if an error occurred.
+ @param snapshot The `NSImage` that was generated or `nil` if an error occurred.
  @param error The eror that occured or `nil` when succesful.
  */
-typedef void (^MGLMapSnapshotCompletionHandler)(MGLImage* _Nullable snapshot, NSError* _Nullable error);
+typedef void (^MGLMapSnapshotCompletionHandler)(NSImage* _Nullable snapshot, NSError* _Nullable error);
+#endif
 
 /**
- A utility object for capturing map-based images.
+ An immutable utility object for capturing map-based images.
+ 
+ ### Example
+ 
+ ```swift
+ var camera = MGLMapCamera()
+ camera.centerCoordinate = CLLocationCoordinate2D(latitude: 37.7184, longitude: -122.4365)
+ camera.pitch = 20
+ 
+ var options = MGLMapSnapshotOptions(styleURL: MGLStyle.satelliteStreetsStyleURL(), camera: camera, size: CGSize(width: 320, height: 480))
+ options.zoomLevel = 10
+ 
+ var snapshotter = MGLMapSnapshotter(options: options)
+ snapshotter.start { (image, error) in
+   if error {
+     // error handler
+   } else {
+     // image handler
+   }
+ }
+ ```
  */
 MGL_EXPORT
 @interface MGLMapSnapshotter : NSObject
@@ -92,6 +132,9 @@ MGL_EXPORT
 
 /**
  Cancels the snapshot creation request, if any.
+ 
+ Once you call this method, you cannot resume the snapshot. In order to obtain the
+ snapshot, create a new `MGLMapSnapshotter` object.
  */
 - (void)cancel;