Documentation and naming conventions

mapbox · Nov 1, 2018 · 46828bf · 46828bf
1 parent 0ee8a5b
commit 46828bf
Show file tree

Hide file tree

Showing 4 changed files with 43 additions and 27 deletions.
diff --git a/MapboxDirections.xcodeproj/project.pbxproj b/MapboxDirections.xcodeproj/project.pbxproj
@@ -22,10 +22,10 @@
 		35D92FF0218203AB000C78CB /* 2018-10-16-Liechtenstein.tar in Resources */ = {isa = PBXBuildFile; fileRef = 35D92FEF218203AA000C78CB /* 2018-10-16-Liechtenstein.tar */; };
 		35D92FF1218203AB000C78CB /* 2018-10-16-Liechtenstein.tar in Resources */ = {isa = PBXBuildFile; fileRef = 35D92FEF218203AA000C78CB /* 2018-10-16-Liechtenstein.tar */; };
 		35D92FF2218203AB000C78CB /* 2018-10-16-Liechtenstein.tar in Resources */ = {isa = PBXBuildFile; fileRef = 35D92FEF218203AA000C78CB /* 2018-10-16-Liechtenstein.tar */; };
-		35DBF005217DF0D90009D2AE /* MBBoundingBox.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF004217DF0D90009D2AE /* MBBoundingBox.swift */; };
-		35DBF006217DF0D90009D2AE /* MBBoundingBox.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF004217DF0D90009D2AE /* MBBoundingBox.swift */; };
-		35DBF007217DF0D90009D2AE /* MBBoundingBox.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF004217DF0D90009D2AE /* MBBoundingBox.swift */; };
-		35DBF008217DF0D90009D2AE /* MBBoundingBox.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF004217DF0D90009D2AE /* MBBoundingBox.swift */; };
+		35DBF005217DF0D90009D2AE /* MBCoordinateBounds.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF004217DF0D90009D2AE /* MBCoordinateBounds.swift */; };
+		35DBF006217DF0D90009D2AE /* MBCoordinateBounds.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF004217DF0D90009D2AE /* MBCoordinateBounds.swift */; };
+		35DBF007217DF0D90009D2AE /* MBCoordinateBounds.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF004217DF0D90009D2AE /* MBCoordinateBounds.swift */; };
+		35DBF008217DF0D90009D2AE /* MBCoordinateBounds.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF004217DF0D90009D2AE /* MBCoordinateBounds.swift */; };
 		35DBF00A217E172C0009D2AE /* CLLocationCoordinate2D.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF009217E172C0009D2AE /* CLLocationCoordinate2D.swift */; };
 		35DBF00B217E172C0009D2AE /* CLLocationCoordinate2D.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF009217E172C0009D2AE /* CLLocationCoordinate2D.swift */; };
 		35DBF00C217E172C0009D2AE /* CLLocationCoordinate2D.swift in Sources */ = {isa = PBXBuildFile; fileRef = 35DBF009217E172C0009D2AE /* CLLocationCoordinate2D.swift */; };
@@ -301,7 +301,7 @@
 		358D48801E2EAB2500F32A65 /* MBRouteOptions.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MBRouteOptions.h; sourceTree = "<group>"; };
 		358D48851E2EAB4500F32A65 /* MBRouteOptions.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MBRouteOptions.m; sourceTree = "<group>"; };
 		35D92FEF218203AA000C78CB /* 2018-10-16-Liechtenstein.tar */ = {isa = PBXFileReference; lastKnownFileType = archive.tar; path = "2018-10-16-Liechtenstein.tar"; sourceTree = "<group>"; };
-		35DBF004217DF0D90009D2AE /* MBBoundingBox.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MBBoundingBox.swift; sourceTree = "<group>"; };
+		35DBF004217DF0D90009D2AE /* MBCoordinateBounds.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MBCoordinateBounds.swift; sourceTree = "<group>"; };
 		35DBF009217E172C0009D2AE /* CLLocationCoordinate2D.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CLLocationCoordinate2D.swift; sourceTree = "<group>"; };
 		35DBF00E217E17A30009D2AE /* HTTPURLResponse.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = HTTPURLResponse.swift; sourceTree = "<group>"; };
 		35DBF013217E199E0009D2AE /* OfflineDirectionsTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OfflineDirectionsTests.swift; sourceTree = SOURCE_ROOT; };
@@ -604,7 +604,7 @@
 				C56516831FE1A2DD00A0AD18 /* MBVisualInstructionType.swift */,
 				35EFD00A207DFACA00BF3873 /* MBVisualInstruction.swift */,
 				35828C9D217A003F00ED546E /* OfflineDirections.swift */,
-				35DBF004217DF0D90009D2AE /* MBBoundingBox.swift */,
+				35DBF004217DF0D90009D2AE /* MBCoordinateBounds.swift */,
 			);
 			path = MapboxDirections;
 			sourceTree = "<group>";
@@ -1220,7 +1220,7 @@
 				C5DAACA220195AB2001F9261 /* MBMatchOptions.swift in Sources */,
 				358D48871E2EAB4500F32A65 /* MBRouteOptions.m in Sources */,
 				DA1A10CC1D00F969009F82FA /* MBWaypoint.swift in Sources */,
-				35DBF006217DF0D90009D2AE /* MBBoundingBox.swift in Sources */,
+				35DBF006217DF0D90009D2AE /* MBCoordinateBounds.swift in Sources */,
 				DA1A10CA1D00F969009F82FA /* MBRouteOptions.swift in Sources */,
 				DA1A10C81D00F969009F82FA /* MBRoute.swift in Sources */,
 				C5990B4D2045E74800D7DFD4 /* MBDirectionsOptions.swift in Sources */,
@@ -1277,7 +1277,7 @@
 				C5DAACA320195AB2001F9261 /* MBMatchOptions.swift in Sources */,
 				358D48881E2EAB4500F32A65 /* MBRouteOptions.m in Sources */,
 				DA1A10F21D010247009F82FA /* MBWaypoint.swift in Sources */,
-				35DBF007217DF0D90009D2AE /* MBBoundingBox.swift in Sources */,
+				35DBF007217DF0D90009D2AE /* MBCoordinateBounds.swift in Sources */,
 				DA1A10F01D010247009F82FA /* MBRouteOptions.swift in Sources */,
 				DA1A10EE1D010247009F82FA /* MBRoute.swift in Sources */,
 				C5990B4E2045E74900D7DFD4 /* MBDirectionsOptions.swift in Sources */,
@@ -1334,7 +1334,7 @@
 				C5DAACA420195AB3001F9261 /* MBMatchOptions.swift in Sources */,
 				358D48891E2EAB4500F32A65 /* MBRouteOptions.m in Sources */,
 				DA1A11091D0103A3009F82FA /* MBWaypoint.swift in Sources */,
-				35DBF008217DF0D90009D2AE /* MBBoundingBox.swift in Sources */,
+				35DBF008217DF0D90009D2AE /* MBCoordinateBounds.swift in Sources */,
 				DA1A11071D0103A3009F82FA /* MBRouteOptions.swift in Sources */,
 				DA1A11051D0103A3009F82FA /* MBRoute.swift in Sources */,
 				C5990B4F2045E74A00D7DFD4 /* MBDirectionsOptions.swift in Sources */,
@@ -1372,7 +1372,7 @@
 				C57D55081DB58C0200B94B74 /* MBLane.swift in Sources */,
 				DAC05F181CFC075300FA0071 /* MBRoute.swift in Sources */,
 				C59094BF203B800300EB2417 /* MBDirectionsOptions.swift in Sources */,
-				35DBF005217DF0D90009D2AE /* MBBoundingBox.swift in Sources */,
+				35DBF005217DF0D90009D2AE /* MBCoordinateBounds.swift in Sources */,
 				C5434B8C200695A50069E887 /* MBMatchOptions.swift in Sources */,
 				DAA76D681DD127CB0015EC78 /* MBLaneIndication.swift in Sources */,
 				C59094C1203DE6BC00EB2417 /* MBDirectionsResult.swift in Sources */,

diff --git a/MapboxDirections/MBBoundingBox.swift → MapboxDirections/MBCoordinateBounds.swift b/MapboxDirections/MBBoundingBox.swift → MapboxDirections/MBCoordinateBounds.swift
@@ -4,8 +4,8 @@ import CoreLocation
 /**
  A bounding box represents a geographic region.
  */
-@objc(MBBoundingBox)
-public class BoundingBox: NSObject, Codable {
+@objc(MBCoordinateBounds)
+public class CoordinateBounds: NSObject, Codable {
     let northWest: CLLocationCoordinate2D
     let southEast: CLLocationCoordinate2D
 

diff --git a/MapboxDirections/OfflineDirections.swift b/MapboxDirections/OfflineDirections.swift
@@ -17,7 +17,7 @@ public protocol OfflineDirectionsProtocol {
      Fetches the available versions.
      */
     @discardableResult
-    func availableOfflineVersions(completionHandler: @escaping OfflineVersionsHandler) -> URLSessionDataTask
+    func fetchAvailableOfflineVersions(completionHandler: @escaping OfflineVersionsHandler) -> URLSessionDataTask
 
     /**
      Initiates a download process of all tiles needed to provide routing within the given bounding box.
@@ -28,12 +28,13 @@ public protocol OfflineDirectionsProtocol {
      - parameter completionHandler: Informs when the download is completed or failed. The offline pack may be moved from the temporary directory and to a persistent store at this point.
      */
     @discardableResult
-    func downloadTiles(for boundingBox: BoundingBox, version: OfflineVersion, session: URLSession?, completionHandler: @escaping OfflineDownloaderCompletionHandler) -> URLSessionDownloadTask
+    func downloadTiles(in coordinateBounds: CoordinateBounds, version: OfflineVersion, session: URLSession?, completionHandler: @escaping OfflineDownloaderCompletionHandler) -> URLSessionDownloadTask
 }
 
 extension Directions: OfflineDirectionsProtocol {
 
-    func availableVersionsURL() -> URL {
+    /// URL to the endpoint listing available versions
+    public var availableVersionsURL: URL {
 
         let url = apiEndpoint.appendingPathComponent("route-tiles/v1").appendingPathComponent("versions")
         var components = URLComponents(url: url, resolvingAgainstBaseURL: true)
@@ -42,21 +43,27 @@ extension Directions: OfflineDirectionsProtocol {
         return components!.url!
     }
 
-    func tilesURL(for boundingBox: BoundingBox, version: OfflineVersion) -> URL {
+    /// URL to the endpoint for downloading a tile pack
+    public func tilesURL(for coordinateBounds: CoordinateBounds, version: OfflineVersion) -> URL {
 
-        let url = apiEndpoint.appendingPathComponent("route-tiles/v1").appendingPathComponent(boundingBox.path)
+        let url = apiEndpoint.appendingPathComponent("route-tiles/v1").appendingPathComponent(coordinateBounds.path)
         var components = URLComponents(url: url, resolvingAgainstBaseURL: true)
         components?.queryItems = [URLQueryItem(name: "version", value: version),
                                   URLQueryItem(name: "access_token", value: accessToken)]
 
         return components!.url!
     }
 
+    /**
+     Fetch the available versions. A version is represented as a String (yyyy-MM-dd or yyyy-MM-dd-x).
+     
+     - parameter completionHandler: The closure to call with the results
+     - returns: A `URLSessionDataTask`
+     */
     @discardableResult
-    @objc
-    public func availableOfflineVersions(completionHandler: @escaping OfflineVersionsHandler) -> URLSessionDataTask {
+    @objc public func fetchAvailableOfflineVersions(completionHandler: @escaping OfflineVersionsHandler) -> URLSessionDataTask {
 
-        let task = URLSession.shared.dataTask(with: availableVersionsURL()) { (data, response, error) in
+        let task = URLSession.shared.dataTask(with: availableVersionsURL) { (data, response, error) in
             if let error = error {
                 return completionHandler(nil, error)
             }
@@ -76,15 +83,24 @@ extension Directions: OfflineDirectionsProtocol {
         return task
     }
 
+    /**
+     Initializes an `URLSessionDownloadTask` used for downloading tiles within a given bounding box.
+     
+     - parameter coordinateBounds: The bounding box
+     - parameter version: The version to download. Version is represented as a String (yyyy-MM-dd-x)
+     - parameter session: Optional URLSession
+     - parameter completionHandler: The closure to call with the results
+     
+     - returns: A `URLSessionDownloadTask`
+     */
     @discardableResult
-    @objc
-    public func downloadTiles(for boundingBox: BoundingBox,
+    @objc public func downloadTiles(in coordinateBounds: CoordinateBounds,
                               version: OfflineVersion,
                               session: URLSession? = URLSession.shared,
                               completionHandler: @escaping OfflineDownloaderCompletionHandler) -> URLSessionDownloadTask {
 
         let urlSession = session ?? URLSession.shared
-        let url = tilesURL(for: boundingBox, version: version)
+        let url = tilesURL(for: coordinateBounds, version: version)
 
         return urlSession.downloadTask(with: url, completionHandler: completionHandler)
     }

diff --git a/OfflineDirectionsTests.swift b/OfflineDirectionsTests.swift
@@ -24,7 +24,7 @@ class OfflineDirectionsTests: XCTestCase {
             return OHHTTPStubsResponse(jsonObject: jsonObject, statusCode: 200, headers: ["Content-Type": "application/json"])
         }
 
-        directions.availableOfflineVersions { (versions, error) in
+        directions.fetchAvailableOfflineVersions { (versions, error) in
             XCTAssertEqual(versions!.count, 1)
             XCTAssertEqual(versions!.first!, "2018-10-16")
 
@@ -40,8 +40,8 @@ class OfflineDirectionsTests: XCTestCase {
 
         let directions = Directions(accessToken: token, host: host)
 
-        let boundingBox = BoundingBox([CLLocationCoordinate2D(latitude: 37.7890, longitude: -122.4337),
-                                       CLLocationCoordinate2D(latitude: 37.7881, longitude: -122.4318)])
+        let coordinateBounds = CoordinateBounds([CLLocationCoordinate2D(latitude: 37.7890, longitude: -122.4337),
+                                                 CLLocationCoordinate2D(latitude: 37.7881, longitude: -122.4318)])
 
         let version = "2018-10-16"
         let downloadExpectation = self.expectation(description: "Download tile expectation")
@@ -62,7 +62,7 @@ class OfflineDirectionsTests: XCTestCase {
             return OHHTTPStubsResponse(fileAtPath: path!, statusCode: 200, headers: headers)
         }
 
-        _ = directions.downloadTiles(for: boundingBox, version: version, completionHandler: { (url, response, error) in
+        _ = directions.downloadTiles(in: coordinateBounds, version: version, completionHandler: { (url, response, error) in
             XCTAssertEqual(response!.suggestedFilename, "2018-10-16.tar")
             XCTAssertNotNil(url, "url should point to the temporary local file")
             XCTAssertNil(error)