Rewrite the library with full Objective-C support and API documentation

[1ec5]

This PR rewrites the entire library to fully bridge to Objective-C while feeling more natural in Swift, handle errors more robustly, and provide complete API documentation. This PR, which closely parallels mapbox/MapboxGeocoder.swift#41 and mapbox/MapboxStatic.swift#19, is the last major step before consolidating the three libraries into one library that can eventually connect to all of Mapbox’s server APIs.

The goal is no longer to be a (poor) drop-in replacement for MapKit’s MKDirections API but rather to be as idiomatic as possible in Swift and Objective-C simultaneously, with a preference for Swift. Symbol names generally conform to platform and language conventions, but in some cases, symbol names eschew MapKit terminology in favor of Directions API terminology, so that api-documentation makes sense in the context of this library. The MB class prefix has been removed from Swift but is kept for Objective-C.

Directions API v4 support has been reimplemented as a series of subclasses of the options and model objects. The previous approach of inserting switch statements everywhere proved less than ideal. Use RouteOptionsV4 instead of RouteOptions to connect to the v4 API.

Requests

Removed the dependency on RequestKit. Once we consolidate the three Mapbox Swift libraries, it’ll be straightforward for each of the API handlers to share the simple URL request and response code. This library chooses reasonable default networking behavior; if you need anything more sophisticated, you can access the URL request information to use with a custom NSURLSession. Directions no longer needs to be strongly held in order for the request to finish. Instead, the request is made against the shared URL session; to use a custom URL session, make the request yourself using the URL returned by the URLForCalculatingDirections(options:) method. Removed the cancel() method; instead, directly cancel the NSURLSessionDataTask returned by calculateDirections(options:completionHandler:).

Added a shared (singleton) Directions object. Use the shared object if you’ve set your Mapbox access token in the MGLMapboxAccessToken key of your application’s Info.plist file. Otherwise, create a Directions object with the access token explicitly. A single directions object can handle multiple requests concurrently (since it just passes the requests off to the shared URL session).

Eliminated the separate APIs for calculating ETAs. Instead, all the options supported by the Directions API, including flags for including steps and the overview geometry, are now exposed through a new RouteOptions class. Effectively, this change adds support for the geometries, overview, radiuses, steps, and continue_straight query parameters and allows the heading accuracy of any waypoint to be customized. However, note that steps are no longer returned by default, and the overview geometry is simplified by default. If this turns out to be a major inconvenience or surprise, we can add specialized options classes for either use case. The access_token parameter is now the last URL parameter instead of the first. Broke out MBDirectionsRequest.TransportType into three profile identifier constants. You always specify a profile identifier, not a transport type. That makes the desired mode of transportation more open-ended.

Responses

Removed the MBDirectionsResponse class in favor of passing the waypoints and routes from the response directly into the completion handler. Renamed Route.geometry to Route.coordinates. For Objective-C compatibility, there are additional methods that work with C arrays of coordinates. Also, all enums are backed by integer types instead of String, but they’re CustomStringConvertible to allow for the same expressiveness we’re used to in Swift.

Error handling is much more robust now. Various error conditions returned by the API cause the localized failure reason and recovery suggestion to be set in the NSError object that is passed into the completion handler.

Documentation and other changes

Documented every public symbol. Some of the more finicky options get lots more documentation, discussing why you would use the option, when you avoid using the option, etc. There’s little chance this voluminous documentation will head off developer error, but it along with the improved error messages will help developers find their way when things do go wrong.

Updated test fixtures and expectations for the v5 server-side API and the revamped client-side API, and updated examples.

Fixes #41, fixes #43, fixes #44.

/cc @mapbox/directions @tmcw @friedbunny

[1ec5]

Here’s the documentation corresponding to the continue_straight query parameter.

[1ec5]

This PR goes in a very different direction than #30 does. After seeing how MapboxStatic.swift gets away without much in the way of networking features, I think this library can get away with something similar. One big benefit with this approach is that there’s no object to keep a strong reference to. On the other hand, #20 becomes the developer’s responsibility.