Update docs for Lost 2.2.0 (#168)

* Update download version

* Update last-known-location.md

* Update getting-started.md

* Update location-settings.md

* Update location-updates.md

* Update mock-locations-routes.md

* Update upgrade-1x-2.md

docs/getting-started.md

@@ -4,15 +4,17 @@ When using Lost, [`GoogleApiClient`](https://developer.android.com/reference/com
 
 ## Create and connect a LostApiClient
 
+After calling `lostApiClient.connect()` you should wait for `ConnectionCallbacks#onConnected()` before performing other operations like getting the last known location or requesting location updates.
+
 ```java
 LostApiClient lostApiClient = new LostApiClient.Builder(this).addConnectionCallbacks(this).build();
 lostApiClient.connect();
 
 @Override public void onConnected() {
-  //client is ready to for use
+  // Client is connected and ready to for use
 }
 
 @Override public void onConnectionSuspended() {
-
+  // Fused location provider service has been suspended
 }
 ```

docs/installation.md

@@ -5,7 +5,7 @@
 Include dependency using Gradle.
 
 ```groovy
-compile 'com.mapzen.android:lost:2.1.2'
+compile 'com.mapzen.android:lost:2.2.0'
 ```
 
 **Maven**
@@ -16,12 +16,12 @@ Include dependency using Maven.
 <dependency>
   <groupId>com.mapzen.android</groupId>
   <artifactId>lost</artifactId>
-  <version>2.1.2</version>
+  <version>2.2.0</version>
 </dependency>
 ```
 
 **Download Jar**
 
 Download the [latest JAR][1].
 
-[1]: http://search.maven.org/remotecontent?filepath=com/mapzen/android/lost/2.1.2/lost-2.1.2.jar
+[1]: http://search.maven.org/remotecontent?filepath=com/mapzen/android/lost/2.2.0/lost-2.2.0.jar

docs/last-known-location.md

@@ -1,9 +1,11 @@
 #Getting the Last Known Location
 
-Once connected you can request the last known location. The actual logic to determine the best most recent location is based this classic [blog post by Reto Meier](http://android-developers.blogspot.com/2011/06/deep-dive-into-location.html).
+Once the `LostApiClient` is connected you can request the last known location.
+
+The actual logic to determine the best most recent location is based this classic [blog post by Reto Meier](http://android-developers.blogspot.com/2011/06/deep-dive-into-location.html).
 
 ```java
-Location location = LocationServices.FusedLocationApi.getLastLocation();
+Location location = LocationServices.FusedLocationApi.getLastLocation(lostApiClient);
 if (location != null) {
   // Do stuff
 }

docs/location-settings.md

@@ -3,9 +3,11 @@
 Location and bluetooth settings can be checked to see if the requirements are satisfied for a `LocationRequest`. In addition, a mechanism for resolving unsatisfied settings is provided.
 
 After creating a `LostApiClient`, create a `LocationSettingsRequest` specifying the location priority and whether or not the user needs BLE:
+
 ```java
 ArrayList<LocationRequest> requests = new ArrayList<>();
-LocationRequest highAccuracy = LocationRequest.create().setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
+LocationRequest highAccuracy = LocationRequest.create()
+    .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
 requests.add(highAccuracy);
 
 boolean needBle = false;
@@ -16,42 +18,49 @@ LocationSettingsRequest request = new LocationSettingsRequest.Builder()
 ```
 
 Then, use the `SettingsApi` to get a `PendingResult`:
+
 ```java
-PendingResult<LocationSettingsResult> result = LocationServices.SettingsApi.checkLocationSettings(apiClient, request);
+PendingResult<LocationSettingsResult> result =
+    LocationServices.SettingsApi.checkLocationSettings(lostApiClient, request);
 ```
 
-Once you have a `PendingResult`, invoke either `await()` or `setResultCallback(ResultCallback)` to obtain a `LocationSettingsResult`. With this object, access the `LocationSettingsStates` to determine whether or not location settings have been satisfied:
+Once you have a `PendingResult`, invoke either `await()` or `setResultCallback(ResultCallback)` to obtain a `LocationSettingsResult`.
+
+With this object, access the `LocationSettingsStates` to determine whether or not location settings have been satisfied:
+
 ```java
 private static final int REQUEST_CHECK_SETTINGS = 100;
 LocationSettingsResult locationSettingsResult = result.await();
 LocationSettingsStates states = locationSettingsResult.getLocationSettingsStates();
 Status status = locationSettingsResult.getStatus();
     switch (status.getStatusCode()) {
       case Status.SUCCESS:
-        // All location and BLE settings are satisfied. The client can initialize location
-        // requests here.
+        // All location settings are satisfied. The client can make location requests here.
         break;
       case Status.RESOLUTION_REQUIRED:
-        // Location settings are not satisfied but can be resolved by show the user the Location Settings activity
+        // Location requirements are not satisfied. Redirect user to system settings for resolution.
         status.startResolutionForResult(SettingsApiActivity.this, REQUEST_CHECK_SETTINGS);
         break;
       case Status.INTERNAL_ERROR:
       case Status.INTERRUPTED:
       case Status.TIMEOUT:
       case Status.CANCELLED:
-        // Location settings are not satisfied but cannot be resolved
+        // Location settings are not satisfied and cannot be resolved.
         break;
       default:
         break;
     }
 ```
 
-If the status code is `RESOLUTION_REQUIRED`, the client can call `startResolutionForResult(Activity, int)` to bring up an `Activity`, asking for user's permission to modify the location settings to satisfy those requests. The result of the `Activity` will be returned via `onActivityResult(int, int, Intent)`. You should not rely on the `resultCode` but instead check that the `requestCode` is that of your calling activity before resuming normal application flow
+If the status code is `RESOLUTION_REQUIRED`, the client can call `startResolutionForResult(Activity, int)` to bring up an `Activity`, asking for user's permission to modify the location settings to satisfy those requests. The result of the `Activity` will be returned via `onActivityResult(int, int, Intent)`.
+
+**You should not rely on the `resultCode` but instead check that the `requestCode` is that of your calling activity before resuming normal application flow since Lost is unable to set the result code for the system setting activity.**
+
 ```java
 @Override  protected void onActivityResult(int requestCode, int resultCode, Intent data) {
     switch (requestCode) {
       case REQUEST_CHECK_SETTINGS:
-        // Check the location settings again and continue
+        // Check the location settings again and continue.
         break;
       default:
         break;

docs/location-updates.md

@@ -3,25 +3,29 @@
 Lost provides the ability to request ongoing location updates. You can specify the update interval, minimum displacement, and priority. The priority determines which location providers will be activated.
 
 ```java
-LocationRequest request = LocationRequest.create().setInterval(5000).setSmallestDisplacement(10).setPriority(LocationRequest.PRIORITY_LOW_POWER);
+LocationRequest request = LocationRequest.create()
+    .setPriority(LocationRequest.PRIORITY_LOW_POWER)
+    .setInterval(5000)
+    .setSmallestDisplacement(10);
+
 LocationListener listener = new LocationListener() {
-    @Override
-    public void onLocationChanged(Location location) {
-      // Do stuff
-    }
+  @Override
+  public void onLocationChanged(Location location) {
+    // Do stuff
+  }
 };
 
-LocationServices.FusedLocationApi.requestLocationUpdates(request, listener);
+LocationServices.FusedLocationApi.requestLocationUpdates(lostApiClient, request, listener);
 ```
 
-For situations where you want to receive location updates in the background, you can request location updates using the `PendingIntent` API
+For situations where you want to receive location updates in the background, you can request location updates using the `PendingIntent` API.
 
 ```java
-LocationRequest request = LocationRequest.create();
-request.setPriority(LocationRequest.PRIORITY_BALANCED_POWER_ACCURACY);
-request.setInterval(100);
+LocationRequest request = LocationRequest.create()
+    .setPriority(LocationRequest.PRIORITY_BALANCED_POWER_ACCURACY);
+    .setInterval(100);
 
-Intent intent = new Intent(PendingIntentService.ACTION);
-PendingIntent pendingIntent = PendingIntent.getService(PendingIntentActivity.this, 1,intent, 0);
-LocationServices.FusedLocationApi.requestLocationUpdates(client, request, pendingIntent);
+Intent intent = new Intent(MyIntentService.ACTION);
+PendingIntent pendingIntent = PendingIntent.getService(MyActivity.this, requestCode, intent, flags);
+LocationServices.FusedLocationApi.requestLocationUpdates(lostApiClient, request, pendingIntent);
 ```

docs/mock-locations-routes.md

@@ -1,20 +1,22 @@
 # Mock Locations
 
-With Lost you can mock not just individual locations but also entire routes. By loading a [GPX trace file](http://www.topografix.com/gpx.asp) onto the device you can configure Lost to replay locations from the trace file including latitude, longitude, speed, and bearing.
+With Lost you can mock not just individual locations but also entire routes.
+
+By loading a [GPX trace file](http://www.topografix.com/gpx.asp) onto the device you can configure Lost to replay locations from the trace file including latitude, longitude, speed, and bearing.
 
 ## Mocking a single location
-To mock a single location with Lost you must first enable mock mode. Then you simply create a mock location object and pass it to the API.
+To mock a single location with Lost you must first enable mock mode. Then create a mock location object and pass it to the API.
 
 ```java
 Location mockLocation = new Location("mock");
 mockLocation.setLatitude(40.7484);
 mockLocation.setLongitude(-73.9857);
 
-LocationServices.FusedLocationApi.setMockMode(true);
-LocationServices.FusedLocationApi.setMockLocation(mockLocation);
+LocationServices.FusedLocationApi.setMockMode(lostApiClient, true);
+LocationServices.FusedLocationApi.setMockLocation(lostApiClient, mockLocation);
 ```
 
-The mock location object you set will be immediately returned to all registered listeners and will be returned the next time `getLastLocation()` is called.
+The mock location object you set will be immediately returned to all registered listeners and will be returned the next time `getLastLocation(lostApiClient)` is called.
 
 ## Mocking an entire route
 To mock an entire route you must first transfer a [GPX trace file](http://www.topografix.com/gpx.asp) to the device using [adb](http://developer.android.com/tools/help/adb.html). Sample GPX traces can be found on the [public GPS traces page](http://www.openstreetmap.org/traces) for OpenStreetMap.
@@ -25,15 +27,15 @@ To install your gpx file onto your device, run the `install-gpx-trace.sh` script
 Example:
 
 ```bash
-install-gpx-trace.sh lost.gpx com.example.myapp
+scripts/install-gpx-trace.sh lost.gpx com.example.myapp
 ```
 
 Once the trace file is loaded on the device you can tell Lost to replay the locations in the trace by issuing a `LocationRequest`. Mock locations will be emitted according to the fastest interval value.
 
 ```java
 File file = new File(context.getExternalFilesDir(null), "lost.gpx");
-LocationServices.FusedLocationApi.setMockMode(true);
-LocationServices.FusedLocationApi.setMockTrace(file);
+LocationServices.FusedLocationApi.setMockMode(lostApiClient, true);
+LocationServices.FusedLocationApi.setMockTrace(lostApiClient, file);
 LocationRequest locationRequest = LocationRequest.create()
     .setInterval(1000)
     .setFastestInterval(1000) // Mock locations will replay at this interval.

docs/upgrade-1x-2.md

@@ -1,31 +1,33 @@
 #Upgrading from Lost 1.x
 
-##Add Connection Callbacks
+###Add Connection Callbacks
 Lost 2.0 introduces an underlying `Service` in the `FusedLocationProviderApi`. Because of this, connecting a `LostApiClient` requires that developers add `ConnectionCallbacks` so that they know when the client has connected and is ready to use.
 
 1.x:
 ```java
 LostApiClient client = new LostApiClient.Builder(context).addConnectionCallbacks(callbacks).build();
-client.connect(); //Client is ready for use
+client.connect(); // Client is ready for use
 ```
 
 2.0:
 ```java
 LostApiClient.ConnectionCallbacks callbacks = new LostApiClient.ConnectionCallbacks() {
     @Override public void onConnected() {
-        //Client is ready for use
+        // Client is ready for use
     }
 
     @Override public void onConnectionSuspended() {
 
     }
 };
 LostApiClient client = new LostApiClient.Builder(context).addConnectionCallbacks(callbacks).build();
-client.connect(); //Client is NOT ready for use
+client.connect(); // Client is NOT ready for use
 ```
 
-##Explicitly Request Permissions
-We have removed permissions from Lost's manifest, allowing developers to declare only the permissions they need in their client applications. In addition, developers also need to request and check for runtime permissions.
+###Explicitly Request Permissions
+We have removed all permissions from Lost's `AndroidManifest.xml`, allowing developers to declare only the permissions they need in their client applications.
+
+In addition, developers targeting Android M (API 23) and above also need to [request runtime permissions](https://developer.android.com/training/permissions/requesting.html).
 
 The permissions that Lost requires are as follows: