From b316370500d770d1286897abdacbc3bd8705d7be Mon Sep 17 00:00:00 2001
From: Tobrun Van Nuland <tobrun.van.nuland@gmail.com>
Date: Tue, 30 May 2017 09:22:42 +0200
Subject: [PATCH 1/7] [android] - javadoc update for 5.1.0 release

---
 .../java/com/mapbox/mapboxsdk/Mapbox.java     |  9 +++
 .../mapboxsdk/camera/CameraPosition.java      |  4 +-
 .../mapboxsdk/camera/CameraUpdateFactory.java |  2 +-
 .../constants/MyBearingTracking.java          |  4 +-
 .../constants/MyLocationTracking.java         |  4 +-
 .../com/mapbox/mapboxsdk/constants/Style.java |  2 +-
 .../mapboxsdk/location/LocationSource.java    | 53 +++++++++++++++--
 .../maps/FocalPointChangeListener.java        |  3 +
 .../com/mapbox/mapboxsdk/maps/MapboxMap.java  |  6 +-
 .../mapboxsdk/offline/OfflineManager.java     |  4 +-
 .../mapboxsdk/offline/OfflineRegion.java      |  2 +-
 .../mapbox/mapboxsdk/storage/Resource.java    |  6 ++
 .../style/functions/CompositeFunction.java    |  2 +-
 .../mapbox/mapboxsdk/style/layers/Filter.java |  2 +-
 .../style/layers/TransitionOptions.java       | 28 +++++++++
 .../mapboxsdk/style/light/package-info.java   |  4 ++
 .../mapbox/mapboxsdk/utils/AnimatorUtils.java | 59 +++++++++++++++++++
 .../mapbox/mapboxsdk/utils/ColorUtils.java    |  3 +
 18 files changed, 175 insertions(+), 22 deletions(-)
 create mode 100644 platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/package-info.java

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java
index 8098ee4d86e..d9da3a4d987 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java
@@ -1,5 +1,6 @@
 package com.mapbox.mapboxsdk;
 
+import android.app.Application;
 import android.content.Context;
 import android.net.ConnectivityManager;
 import android.net.NetworkInfo;
@@ -15,6 +16,14 @@
 import com.mapbox.services.android.telemetry.location.LocationEngine;
 import com.mapbox.services.android.telemetry.location.LocationEnginePriority;
 
+/**
+ * The entry point of the Mapbox Android SDK.
+ * <p>
+ * Obtain a reference by calling {@link #getInstance(Context, String)}. Usually this class is configured in
+ * {@link Application#onCreate()} and is responsible for the active access token, application context and
+ * connectivity state.
+ * </p>
+ */
 public final class Mapbox {
 
   private static Mapbox INSTANCE;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java
index 5e958ff5651..66c261f1d0b 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java
@@ -156,7 +156,7 @@ public int hashCode() {
   }
 
   /**
-   * Builder for composing {@link CameraPosition} objects.
+   * Builder for composing CameraPosition objects.
    */
   public static final class Builder {
 
@@ -190,7 +190,7 @@ public Builder(CameraPosition previous) {
     /**
      * Create Builder with an existing CameraPosition data.
      *
-     * @param typedArray TypedArray containgin attribute values
+     * @param typedArray TypedArray containing attribute values
      */
     public Builder(TypedArray typedArray) {
       super();
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java
index 64b86054a0c..8e1411e2739 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java
@@ -15,7 +15,7 @@
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * Factory for creating {@link CameraUpdate} objects.
+ * Factory for creating CameraUpdate objects.
  */
 public final class CameraUpdateFactory {
 
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java
index f53c65d055a..6d035e75fa6 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java
@@ -16,7 +16,7 @@
 public class MyBearingTracking {
 
   /**
-   * Indicates the parameter accepts one of the values from {@link MyBearingTracking}.
+   * Indicates the parameter accepts one of the values from MyBearingTracking.
    */
   @IntDef( {NONE, COMPASS, GPS, /**COMBINED**/})
   @Retention(RetentionPolicy.SOURCE)
@@ -38,6 +38,4 @@ public class MyBearingTracking {
    */
   public static final int GPS = 0x00000008;
 
-  // public static final int COMBINED = 0x00000012;
-
 }
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyLocationTracking.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyLocationTracking.java
index 39f653596f6..a1744d701f2 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyLocationTracking.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyLocationTracking.java
@@ -17,7 +17,7 @@
 public class MyLocationTracking {
 
   /**
-   * Indicates the parameter accepts one of the values from {@link MyLocationTracking}.
+   * Indicates the parameter accepts one of the values from MyLocationTracking.
    */
   @IntDef( {TRACKING_NONE, TRACKING_FOLLOW})
   @Retention(RetentionPolicy.SOURCE)
@@ -30,7 +30,7 @@ public class MyLocationTracking {
   public static final int TRACKING_NONE = 0x00000000;
 
   /**
-   * Tracking the location of the user, {@link MapView} will reposition to center of {@link MyLocationView}
+   * Tracking the location of the user. {@link MapView} will reposition to center of {@link MyLocationView}
    */
   public static final int TRACKING_FOLLOW = 0x00000004;
 
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java
index 77d0929df3e..31e6313509c 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java
@@ -19,7 +19,7 @@ public class Style {
 
 
   /**
-   * Indicates the parameter accepts one of the values from {@link Style}. Using one of these
+   * Indicates the parameter accepts one of the values from Style. Using one of these
    * constants means your map style will always use the latest version and may change as we
    * improve the style
    */
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java
index c4bdb4a17de..c3fc9ef9e87 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java
@@ -2,7 +2,7 @@
 
 import android.content.Context;
 import android.location.Location;
-import android.util.Log;
+import android.support.annotation.NonNull;
 
 import com.mapbox.services.android.telemetry.location.LocationEngine;
 import com.mapbox.services.android.telemetry.location.LocationEngineListener;
@@ -15,6 +15,8 @@
 
 import java.lang.ref.WeakReference;
 
+import timber.log.Timber;
+
 /**
  * Manages locational updates. Contains methods to register and unregister location listeners.
  * <ul>
@@ -33,8 +35,6 @@
 public class LocationSource extends LocationEngine implements
   LostApiClient.ConnectionCallbacks, LocationListener {
 
-  private static final String LOG_TAG = LocationSource.class.getSimpleName();
-
   private static LocationEngine instance;
 
   private WeakReference<Context> context;
@@ -48,7 +48,13 @@ private LocationSource(Context context) {
       .build();
   }
 
-  public static synchronized LocationEngine getLocationEngine(Context context) {
+  /**
+   * Get the LocationEngine instance.
+   *
+   * @param context a Context from which the application context is derived
+   * @return the LocationEgine instance
+   */
+  public static synchronized LocationEngine getLocationEngine(@NonNull Context context) {
     if (instance == null) {
       instance = new LocationSource(context.getApplicationContext());
     }
@@ -56,6 +62,10 @@ public static synchronized LocationEngine getLocationEngine(Context context) {
     return instance;
   }
 
+  /**
+   * Activate the location engine which will connect whichever location provider you are using. You'll need to call
+   * this before requesting user location updates using {@link LocationEngine#requestLocationUpdates()}.
+   */
   @Override
   public void activate() {
     if (lostApiClient != null && !lostApiClient.isConnected()) {
@@ -63,6 +73,11 @@ public void activate() {
     }
   }
 
+  /**
+   * Disconnect the location engine, useful when you no longer need location updates or requesting the users
+   * {@link LocationEngine#getLastLocation()}. Before deactivating you'll need to stop request user location updates
+   * using {@link LocationEngine#removeLocationUpdates()}.
+   */
   @Override
   public void deactivate() {
     if (lostApiClient != null && lostApiClient.isConnected()) {
@@ -70,11 +85,20 @@ public void deactivate() {
     }
   }
 
+  /**
+   * Check if your location provider has been activated/connected. This is mainly used internally but is also useful in
+   * the rare cases when you'd like to know if your location engine is connected or not.
+   *
+   * @return boolean true if the location engine has been activated/connected, else false.
+   */
   @Override
   public boolean isConnected() {
     return lostApiClient.isConnected();
   }
 
+  /**
+   * Invoked when the location provider has connected.
+   */
   @Override
   public void onConnected() {
     for (LocationEngineListener listener : locationListeners) {
@@ -82,11 +106,19 @@ public void onConnected() {
     }
   }
 
+  /**
+   * Invoked when the location provider connection has been suspended
+   */
   @Override
   public void onConnectionSuspended() {
-    Log.d(LOG_TAG, "Connection suspended.");
+    Timber.d("Connection suspended.");
   }
 
+  /**
+   * Returns the Last known location is the location provider is connected and location permissions are granted.
+   *
+   * @return the last known location
+   */
   @Override
   public Location getLastLocation() {
     if (lostApiClient.isConnected() && PermissionsManager.areLocationPermissionsGranted(context.get())) {
@@ -97,6 +129,9 @@ public Location getLastLocation() {
     return null;
   }
 
+  /**
+   * Request location updates to the location provider.
+   */
   @Override
   public void requestLocationUpdates() {
     // Common params
@@ -122,6 +157,9 @@ public void requestLocationUpdates() {
     }
   }
 
+  /**
+   * Dismiss ongoing location update to the location provider.
+   */
   @Override
   public void removeLocationUpdates() {
     if (lostApiClient.isConnected()) {
@@ -129,6 +167,11 @@ public void removeLocationUpdates() {
     }
   }
 
+  /**
+   * Invoked when the Location has changed.
+   *
+   * @param location the new location
+   */
   @Override
   public void onLocationChanged(Location location) {
     for (LocationEngineListener listener : locationListeners) {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/FocalPointChangeListener.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/FocalPointChangeListener.java
index 006122a4e2e..aec9a848b7e 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/FocalPointChangeListener.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/FocalPointChangeListener.java
@@ -2,6 +2,9 @@
 
 import android.graphics.PointF;
 
+/**
+ * Interface definition of a callback that is invoked when the focal point will change.
+ */
 public interface FocalPointChangeListener {
 
   void onFocalPointChanged(PointF pointF);
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
index 0bfa74d1c00..0ba6c108315 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
@@ -1972,9 +1972,9 @@ public interface OnScrollListener {
   /**
    * Interface definition for a callback to be invoked when the camera changes position.
    *
-   * @deprecated Replaced by MapboxMap.OnCameraMoveStartedListener, MapboxMap.OnCameraMoveListener and
-   * MapboxMap.OnCameraIdleListener. The order in which the deprecated onCameraChange method will be called in relation
-   * to the methods in the new camera change listeners is undefined.
+   * @deprecated Replaced by {@link MapboxMap.OnCameraMoveStartedListener}, {@link MapboxMap.OnCameraMoveListener} and
+   * {@link MapboxMap.OnCameraIdleListener}. The order in which the deprecated onCameraChange method will be called in
+   * relation to the methods in the new camera change listeners is undefined.
    */
   @Deprecated
   public interface OnCameraChangeListener {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java
index 225278b17d9..e0b4607260f 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java
@@ -46,7 +46,7 @@ public class OfflineManager {
 
   /**
    * This callback receives an asynchronous response containing a list of all
-   * {@link OfflineRegion} in the database, or an error message otherwise.
+   * OfflineRegion in the database, or an error message otherwise.
    */
   public interface ListOfflineRegionsCallback {
     /**
@@ -66,7 +66,7 @@ public interface ListOfflineRegionsCallback {
 
   /**
    * This callback receives an asynchronous response containing the newly created
-   * {@link OfflineRegion} in the database, or an error message otherwise.
+   * OfflineRegion in the database, or an error message otherwise.
    */
   public interface CreateOfflineRegionCallback {
     /**
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegion.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegion.java
index 44bb2a05ee9..baa815491fa 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegion.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegion.java
@@ -98,7 +98,7 @@ public interface OfflineRegionObserver {
   }
 
   /**
-   * This callback receives an asynchronous response containing the {@link OfflineRegionStatus}
+   * This callback receives an asynchronous response containing the OfflineRegionStatus
    * of the offline region, or a {@link String} error message otherwise.
    */
   public interface OfflineRegionStatusCallback {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/Resource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/Resource.java
index af98a46a9b3..eae83e8c1f7 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/Resource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/Resource.java
@@ -5,9 +5,15 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * Resource provides access to resource types.
+ */
 public final class Resource {
   // Note: Keep this in sync with include/mbgl/storage/resource.hpp
 
+  /**
+   * Resource type variants.
+   */
   @IntDef( {UNKNOWN, STYLE, SOURCE, TILE, GLYPHS, SPRITE_IMAGE, SPRITE_JSON})
   @Retention(RetentionPolicy.SOURCE)
   public @interface Kind {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/functions/CompositeFunction.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/functions/CompositeFunction.java
index 8ded7ecd346..15e44741057 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/functions/CompositeFunction.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/functions/CompositeFunction.java
@@ -13,7 +13,7 @@
 import java.util.Map;
 
 /**
- * Composite functions combine {@link android.graphics.Camera} and {@link SourceFunction}s.
+ * Composite functions combine Camera and SourceFunctions.
  * <p>
  * Composite functions allow the appearance of a map feature to change with both its
  * properties and zoom. Each stop is an array with two elements, the first is an object
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/Filter.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/Filter.java
index 643a126388b..4dbb461e4ca 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/Filter.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/Filter.java
@@ -11,7 +11,7 @@
 public class Filter {
 
   /**
-   * Base {@link Filter} statement. Subclassed to provide concrete statements.
+   * Base Filter statement. Subclassed to provide concrete statements.
    */
   public abstract static class Statement {
     protected final String operator;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/TransitionOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/TransitionOptions.java
index a46c11b35cd..6e6e4ca6138 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/TransitionOptions.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/TransitionOptions.java
@@ -1,23 +1,51 @@
 package com.mapbox.mapboxsdk.style.layers;
 
+/**
+ * Resembles transition property from the style specification.
+ *
+ * @see <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#transition">Transition documentation</a>
+ */
 public class TransitionOptions {
 
   private long duration;
   private long delay;
 
+  /**
+   * Create a transition property based on duration and a delay.
+   *
+   * @param duration the duration of the transition
+   * @param delay    the delay to start the transition
+   */
   public TransitionOptions(long duration, long delay) {
     this.duration = duration;
     this.delay = delay;
   }
 
+  /**
+   * Create a transition property based on duration and a delay.
+   *
+   * @param duration the duration of the transition
+   * @param delay    the delay to start the transition
+   * @return a new transition property object
+   */
   public static TransitionOptions fromTransitionOptions(long duration, long delay) {
     return new TransitionOptions(duration, delay);
   }
 
+  /**
+   * Get the transition duration.
+   *
+   * @return the transition duration
+   */
   public long getDuration() {
     return duration;
   }
 
+  /**
+   * Get the transition delay.
+   *
+   * @return the transition delay
+   */
   public long getDelay() {
     return delay;
   }
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/package-info.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/package-info.java
new file mode 100644
index 00000000000..a613bf9587b
--- /dev/null
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Contains the Mapbox Maps Android Style Light API classes.
+ */
+package com.mapbox.mapboxsdk.style.light;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/AnimatorUtils.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/AnimatorUtils.java
index 7694604d9fd..34c52c829bc 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/AnimatorUtils.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/AnimatorUtils.java
@@ -10,13 +10,31 @@
 import android.support.v4.view.animation.FastOutSlowInInterpolator;
 import android.view.View;
 
+/**
+ * Animator utility class.
+ */
 public class AnimatorUtils {
 
+  /**
+   * Animate a view from an animator resource.
+   *
+   * @param view        the view to be animated
+   * @param animatorRes the animator resource to be loaded
+   * @param listener    the animator end listener
+   */
   public static void animate(@NonNull final View view, @AnimatorRes int animatorRes,
                              @Nullable OnAnimationEndListener listener) {
     animate(view, animatorRes, -1, listener);
   }
 
+  /**
+   * Animate a view from an animator resource.
+   *
+   * @param view        the view to be animated
+   * @param animatorRes the animator resource to be loaded
+   * @param duration    the duration of the animator
+   * @param listener    the animator end listener
+   */
   public static void animate(final View view, @AnimatorRes int animatorRes, int duration,
                              @Nullable final OnAnimationEndListener listener) {
     if (view == null) {
@@ -43,14 +61,33 @@ public void onAnimationEnd(Animator animation) {
     animator.start();
   }
 
+  /**
+   * Animate a view from an animator resource.
+   *
+   * @param view        the view to be animated
+   * @param animatorRes the animator resource to be loaded
+   */
   public static void animate(@NonNull final View view, @AnimatorRes int animatorRes) {
     animate(view, animatorRes, -1);
   }
 
+  /**
+   * Animate a view from an animator resource.
+   *
+   * @param view        the view to be animated
+   * @param animatorRes the animator resource to be loaded
+   * @param duration    the duration of the animator
+   */
   public static void animate(@NonNull final View view, @AnimatorRes int animatorRes, int duration) {
     animate(view, animatorRes, duration, null);
   }
 
+  /**
+   * Animate a view rotation property to a value.
+   *
+   * @param view     the view to be rotated
+   * @param rotation the value to animate to
+   */
   public static void rotate(@NonNull final View view, float rotation) {
     view.setLayerType(View.LAYER_TYPE_HARDWARE, null);
     ObjectAnimator rotateAnimator = ObjectAnimator.ofFloat(view, View.ROTATION, view.getRotation(), rotation);
@@ -64,6 +101,12 @@ public void onAnimationEnd(Animator animation) {
     rotateAnimator.start();
   }
 
+  /**
+   * Animate a view rotation property by a value.
+   *
+   * @param view       the view to be rotated
+   * @param rotationBy the value to animate by
+   */
   public static void rotateBy(@NonNull final View view, float rotationBy) {
     view.setLayerType(View.LAYER_TYPE_HARDWARE, null);
     view.animate().rotationBy(rotationBy).setInterpolator(new FastOutSlowInInterpolator()).setListener(
@@ -76,6 +119,13 @@ public void onAnimationEnd(Animator animation) {
       });
   }
 
+  /**
+   * Animate a view alpha property to a value.
+   *
+   * @param convertView the view to be animated
+   * @param alpha       the value to animate to
+   * @param listener    the animator end listener
+   */
   public static void alpha(@NonNull final View convertView, float alpha,
                            @Nullable final OnAnimationEndListener listener) {
     convertView.setLayerType(View.LAYER_TYPE_HARDWARE, null);
@@ -99,10 +149,19 @@ public void onAnimationEnd(Animator animation) {
     rotateAnimator.start();
   }
 
+  /**
+   * Animate a view alpha property to a value.
+   *
+   * @param convertView the view to be animated
+   * @param alpha       the value to animate to
+   */
   public static void alpha(@NonNull final View convertView, float alpha) {
     alpha(convertView, alpha, null);
   }
 
+  /**
+   * An interface definition that is invoked when an animation ends.
+   */
   public interface OnAnimationEndListener {
     void onAnimationEnd();
   }
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ColorUtils.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ColorUtils.java
index 2da2472d69a..24c76243d96 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ColorUtils.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ColorUtils.java
@@ -17,6 +17,9 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Color utility class.
+ */
 public class ColorUtils {
 
   /**

From 308d781c43cea8921038fd7c2d59bc5ee79cdc94 Mon Sep 17 00:00:00 2001
From: Langston Smith <langston.smith@mapbox.com>
Date: Tue, 30 May 2017 09:12:51 -0700
Subject: [PATCH 2/7] oxford comma

---
 .../src/main/java/com/mapbox/mapboxsdk/Mapbox.java            | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java
index d9da3a4d987..41f484f1029 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java
@@ -20,7 +20,7 @@
  * The entry point of the Mapbox Android SDK.
  * <p>
  * Obtain a reference by calling {@link #getInstance(Context, String)}. Usually this class is configured in
- * {@link Application#onCreate()} and is responsible for the active access token, application context and
+ * {@link Application#onCreate()} and is responsible for the active access token, application context, and
  * connectivity state.
  * </p>
  */
@@ -128,4 +128,4 @@ public static synchronized Boolean isConnected() {
     NetworkInfo activeNetwork = cm.getActiveNetworkInfo();
     return (activeNetwork != null && activeNetwork.isConnected());
   }
-}
\ No newline at end of file
+}

From 5e9a02fe9a05493f324f76ce3a48f526624c3c68 Mon Sep 17 00:00:00 2001
From: Langston Smith <langston.smith@mapbox.com>
Date: Tue, 30 May 2017 09:15:24 -0700
Subject: [PATCH 3/7] Grammar/spelling tweaks

---
 .../java/com/mapbox/mapboxsdk/Mapbox.java     | 22 ++++++++++---------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java
index 41f484f1029..f75d7ed90d6 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java
@@ -34,7 +34,7 @@ public final class Mapbox {
   /**
    * Get an instance of Mapbox.
    * <p>
-   * This class manages the active access token, application context and connectivity state.
+   * This class manages the active access token, application context, and connectivity state.
    * </p>
    *
    * @param context     Android context which holds or is an application context
@@ -61,9 +61,9 @@ public static synchronized Mapbox getInstance(@NonNull Context context, @NonNull
   }
 
   /**
-   * Access Token for this application.
+   * Access token for this application.
    *
-   * @return Mapbox Access Token
+   * @return Mapbox access token
    */
   public static String getAccessToken() {
     validateMapbox();
@@ -81,12 +81,14 @@ private static void validateMapbox() throws MapboxConfigurationException {
   }
 
   /**
-   * Runtime validation of Access Token.
+   * Runtime validation of access token.
    *
    * @throws MapboxConfigurationException exception thrown when not using a valid accessToken
    */
   private static void validateAccessToken() throws MapboxConfigurationException {
-    String accessToken = INSTANCE.accessToken;
+    String 
+      
+      = INSTANCE.accessToken;
     if (TextUtils.isEmpty(accessToken) || (!accessToken.toLowerCase(MapboxConstants.MAPBOX_LOCALE).startsWith("pk.")
       && !accessToken.toLowerCase(MapboxConstants.MAPBOX_LOCALE).startsWith("sk."))) {
       throw new MapboxConfigurationException();
@@ -101,11 +103,11 @@ public static Context getApplicationContext() {
   }
 
   /**
-   * Manually sets the connectivity state of the app. This is useful for apps that control their
+   * Manually sets the connectivity state of the app. This is useful for apps which control their
    * own connectivity state and want to bypass any checks to the ConnectivityManager.
    *
    * @param connected flag to determine the connectivity state, true for connected, false for
-   *                  disconnected, null for ConnectivityManager to determine.
+   *                  disconnected, and null for ConnectivityManager to determine.
    */
   public static synchronized void setConnected(Boolean connected) {
     // Connectivity state overridden by app
@@ -113,10 +115,10 @@ public static synchronized void setConnected(Boolean connected) {
   }
 
   /**
-   * Determines whether we have an Internet connection available. Please do not rely on this
-   * method in your apps, this method is used internally by the SDK.
+   * Determines whether we have an internet connection available. Please do not rely on this
+   * method in your apps. This method is used internally by the SDK.
    *
-   * @return true if there is an Internet connection, false otherwise
+   * @return true if there is an internet connection, false otherwise
    */
   public static synchronized Boolean isConnected() {
     if (INSTANCE.connected != null) {

From 3f94a00fcf018b462ddc0a31eb00fa81e1ea64a5 Mon Sep 17 00:00:00 2001
From: Langston Smith <langston.smith@mapbox.com>
Date: Tue, 30 May 2017 09:16:06 -0700
Subject: [PATCH 4/7] grammar tweak

---
 .../java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java
index 6d035e75fa6..88c3bef6733 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java
@@ -16,7 +16,7 @@
 public class MyBearingTracking {
 
   /**
-   * Indicates the parameter accepts one of the values from MyBearingTracking.
+   * Indicates that the parameter accepts one of the values from MyBearingTracking.
    */
   @IntDef( {NONE, COMPASS, GPS, /**COMBINED**/})
   @Retention(RetentionPolicy.SOURCE)

From db34d8d7b75d3f260910500e2243958aec7c06fc Mon Sep 17 00:00:00 2001
From: Langston Smith <langston.smith@mapbox.com>
Date: Tue, 30 May 2017 09:16:13 -0700
Subject: [PATCH 5/7] grammar tweak


From 7302cfa20a85c373f33024b0e53780aa2a67be68 Mon Sep 17 00:00:00 2001
From: Langston Smith <langston.smith@mapbox.com>
Date: Tue, 30 May 2017 09:18:01 -0700
Subject: [PATCH 6/7] Grammar tweaks

---
 .../com/mapbox/mapboxsdk/location/LocationSource.java  | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java
index c3fc9ef9e87..4e934fa3ccb 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java
@@ -52,7 +52,7 @@ private LocationSource(Context context) {
    * Get the LocationEngine instance.
    *
    * @param context a Context from which the application context is derived
-   * @return the LocationEgine instance
+   * @return the LocationEngine instance
    */
   public static synchronized LocationEngine getLocationEngine(@NonNull Context context) {
     if (instance == null) {
@@ -74,8 +74,8 @@ public void activate() {
   }
 
   /**
-   * Disconnect the location engine, useful when you no longer need location updates or requesting the users
-   * {@link LocationEngine#getLastLocation()}. Before deactivating you'll need to stop request user location updates
+   * Disconnect the location engine which is useful when you no longer need location updates or requesting the users
+   * {@link LocationEngine#getLastLocation()}. Before deactivating, you'll need to stop request user location updates
    * using {@link LocationEngine#removeLocationUpdates()}.
    */
   @Override
@@ -87,7 +87,7 @@ public void deactivate() {
 
   /**
    * Check if your location provider has been activated/connected. This is mainly used internally but is also useful in
-   * the rare cases when you'd like to know if your location engine is connected or not.
+   * the rare case when you'd like to know if your location engine is connected or not.
    *
    * @return boolean true if the location engine has been activated/connected, else false.
    */
@@ -107,7 +107,7 @@ public void onConnected() {
   }
 
   /**
-   * Invoked when the location provider connection has been suspended
+   * Invoked when the location provider connection has been suspended.
    */
   @Override
   public void onConnectionSuspended() {

From 8d90ccd53c17c67edc13ce0f8f2b1e6da2cd75d8 Mon Sep 17 00:00:00 2001
From: Langston Smith <langston.smith@mapbox.com>
Date: Tue, 30 May 2017 09:19:35 -0700
Subject: [PATCH 7/7] Grammar tweaks

---
 .../java/com/mapbox/mapboxsdk/offline/OfflineManager.java     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java
index e0b4607260f..95cb7d66c43 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java
@@ -46,7 +46,7 @@ public class OfflineManager {
 
   /**
    * This callback receives an asynchronous response containing a list of all
-   * OfflineRegion in the database, or an error message otherwise.
+   * OfflineRegion in the database or an error message otherwise.
    */
   public interface ListOfflineRegionsCallback {
     /**
@@ -66,7 +66,7 @@ public interface ListOfflineRegionsCallback {
 
   /**
    * This callback receives an asynchronous response containing the newly created
-   * OfflineRegion in the database, or an error message otherwise.
+   * OfflineRegion in the database or an error message otherwise.
    */
   public interface CreateOfflineRegionCallback {
     /**