From ad3bbd9c111f5913a9c69e642319c4a8bdb7d2ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Minh=20Nguye=CC=82=CC=83n?= <mxn@1ec5.org>
Date: Sat, 26 Mar 2016 15:07:26 -0700
Subject: [PATCH] [ios, osx] Clarified documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updated MGLTilePyramidOfflineRegion documentation to note that local files can’t be used as style URLs. Added documentation for private offline methods.
---
 .../darwin/include/MGLTilePyramidOfflineRegion.h    | 13 +++++++------
 platform/darwin/src/MGLOfflineRegion_Private.h      | 11 +++++++++++
 platform/darwin/src/MGLOfflineStorage_Private.h     |  3 +++
 3 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/platform/darwin/include/MGLTilePyramidOfflineRegion.h b/platform/darwin/include/MGLTilePyramidOfflineRegion.h
index 89920adcc..886464587 100644
--- a/platform/darwin/include/MGLTilePyramidOfflineRegion.h
+++ b/platform/darwin/include/MGLTilePyramidOfflineRegion.h
@@ -17,9 +17,8 @@ NS_ASSUME_NONNULL_BEGIN
  In addition to the JSON stylesheet, different styles may require different font
  glyphs, sprite sheets, and other resources.
  
- 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 URL may be a full HTTP or HTTPS URL or a Mapbox URL indicating the style’s
+ map ID (`mapbox://styles/{user}/{style}`).
  */
 @property (nonatomic, readonly) NSURL *styleURL;
 
@@ -52,9 +51,11 @@ NS_ASSUME_NONNULL_BEGIN
  This is the designated initializer for `MGLTilePyramidOfflineRegion`.
  
  @param styleURL URL of the map style for which to download resources. 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.
+    may be a full HTTP or HTTPS URL or a Mapbox URL indicating the style’s map
+    ID (`mapbox://styles/{user}/{style}`). Specify `nil` for the default style.
+    Relative file URLs cannot be used as offline style URLs. To download the
+    online resources required by a local style, specify a URL to an online copy
+    of the style.
  @param bounds The coordinate bounds for the geographic region to be covered by
     the downloaded tiles.
  @param minimumZoomLevel The minimum zoom level to be covered by the downloaded
diff --git a/platform/darwin/src/MGLOfflineRegion_Private.h b/platform/darwin/src/MGLOfflineRegion_Private.h
index 41cd5843f..22106987d 100644
--- a/platform/darwin/src/MGLOfflineRegion_Private.h
+++ b/platform/darwin/src/MGLOfflineRegion_Private.h
@@ -8,8 +8,19 @@ NS_ASSUME_NONNULL_BEGIN
 
 @protocol MGLOfflineRegion_Private <MGLOfflineRegion>
 
+/**
+ Initializes and returns an offline region backed by the given C++ region
+ definition object.
+ 
+ @param definition A reference to an offline region definition backing the
+    offline region.
+ */
 - (instancetype)initWithOfflineRegionDefinition:(const mbgl::OfflineRegionDefinition &)definition;
 
+/**
+ Creates and returns a C++ offline region definition corresponding to the
+ receiver.
+ */
 - (const mbgl::OfflineRegionDefinition)offlineRegionDefinition;
 
 @end
diff --git a/platform/darwin/src/MGLOfflineStorage_Private.h b/platform/darwin/src/MGLOfflineStorage_Private.h
index 05c3188bd..7c7b80dc4 100644
--- a/platform/darwin/src/MGLOfflineStorage_Private.h
+++ b/platform/darwin/src/MGLOfflineStorage_Private.h
@@ -8,6 +8,9 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface MGLOfflineStorage (Private)
 
+/**
+ The shared file source object owned by the shared offline storage object.
+ */
 @property (nonatomic) mbgl::DefaultFileSource *mbglFileSource;
 
 @end