1 files changed, 82 insertions, 5 deletions
diff --git a/platform/darwin/include/MGLOfflineStorage.h b/platform/darwin/include/MGLOfflineStorage.h
index 2d33f3ba69..459371d9f7 100644
--- a/platform/darwin/include/MGLOfflineStorage.h
+++ b/platform/darwin/include/MGLOfflineStorage.h
@@ -7,22 +7,99 @@ NS_ASSUME_NONNULL_BEGIN
 @class MGLOfflineTask;
 @protocol MGLOfflineRegion;
 
-typedef void (^MGLOfflineTaskRegistrationCompletionHandler)(MGLOfflineTask *task, NSError *error);
-typedef void (^MGLOfflineTaskRemovalCompletionHandler)(NSError *error);
-typedef void (^MGLOfflineTasksRetrievalCompletionHandler)(NS_ARRAY_OF(MGLOfflineTask *) *tasks, NSError *error);
+/**
+ A block to be called once an offline task has been completely created and
+ added.
+ 
+ @param task Contains a pointer to the newly added task, or `nil` if there was
+    an error creating or adding the task.
+ @param error Contains a pointer to an error object (if any) indicating why the
+    task could not be created or added. For a list of possible error codes, see
+    `MGLErrorCode`.
+ */
+typedef void (^MGLOfflineTaskAdditionCompletionHandler)(MGLOfflineTask * _Nullable task, NSError * _Nullable error);
 
+/**
+ A block to be called once an offline task has been completely invalidated and
+ removed.
+ 
+ @param error Contains a pointer to an error object (if any) indicating why the
+    task could not be invalidated or removed.
+ */
+typedef void (^MGLOfflineTaskRemovalCompletionHandler)(NSError * _Nullable error);
+
+/**
+ A block to be called with a complete list of offline tasks.
+ 
+ @param task Contains a pointer an array of tasks, or `nil` if there was an
+    error obtaining the tasks.
+ @param error Contains a pointer to an error object (if any) indicating why the
+    list of tasks could not be obtained.
+ */
+typedef void (^MGLOfflineTaskListingCompletionHandler)(NS_ARRAY_OF(MGLOfflineTask *) *tasks, NSError * _Nullable error);
+
+/**
+ MGLOfflineStorage implements a singleton (shared object) that manages offline
+ tasks. All of this class’s instance methods are asynchronous, reflecting the
+ fact that offline resources are stored in a database.
+ */
 @interface MGLOfflineStorage : NSObject
 
+/**
+ Returns the shared offline storage object.
+ */
 + (instancetype)sharedOfflineStorage;
 
 - (instancetype)init NS_UNAVAILABLE;
 
-- (void)addTaskForRegion:(id <MGLOfflineRegion>)region withContext:(NSData *)context completionHandler:(MGLOfflineTaskRegistrationCompletionHandler)completion;
+/**
+ Creates and registers an offline task that downloads the resources needed to
+ use the given region offline.
+ 
+ The resulting task starts out with a state of `MGLOfflineTaskStateInactive`. To
+ begin downloading resources, call `-[MGLOfflineTask resume]`. To monitor
+ download progress, set the task’s `delegate` property to an object that
+ conforms to the `MGLOfflineTaskDelegate` protocol.
+ 
+ @param region A region to download.
+ @param context Arbitrary data to store alongside the downloaded resources.
+ @param completion The completion handler to call once the task has been added.
+    This handler is executed asynchronously on the main queue.
+ */
+- (void)addTaskForRegion:(id <MGLOfflineRegion>)region withContext:(NSData *)context completionHandler:(MGLOfflineTaskAdditionCompletionHandler)completion;
 
+/**
+ Unregisters the given offline task and frees any resources that are no longer
+ required by any remaining tasks. After this task is removed, it is invalid; any
+ attempt to interact with it will result in an exception being thrown.
+ 
+ @param task The offline task to remove.
+ @param completion The completion handler to call once the task has been
+    removed. This handler is executed asynchronously on the main queue.
+ */
 - (void)removeTask:(MGLOfflineTask *)task withCompletionHandler:(MGLOfflineTaskRemovalCompletionHandler)completion;
 
-- (void)getTasksWithCompletionHandler:(MGLOfflineTasksRetrievalCompletionHandler)completion;
+/**
+ Asynchronously calls a completion callback with all existing offline tasks.
+ 
+ @param completion The completion handler to call with the list of tasks. This
+     handler is executed asynchronously on the main queue.
+ */
+- (void)getTasksWithCompletionHandler:(MGLOfflineTaskListingCompletionHandler)completion;
 
+/**
+ Sets the maximum number of Mapbox-hosted tiles that may be downloaded and
+ stored on the current device.
+ 
+ Once this limit is reached,
+ `-[MGLOfflineTaskDelegate offlineTask:didReceiveMaximumAllowedMapboxTiles:]` is
+ called on every delegate of `MGLOfflineTask` until already downloaded tiles are
+ removed by calling the `-removeTask:withCompletionHandler:` method.
+ 
+ @note The [Mapbox Terms of Service](https://www.mapbox.com/tos/) prohibits
+    changing or bypassing this limit without permission from Mapbox. Contact
+    your Mapbox sales representative to have the limit raised.
+ */
 - (void)setMaximumAllowedMapboxTiles:(uint64_t)maximumCount;
 
 @end