[android] - javadoc update for 5.1.0 release

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;
@@ -25,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
@@ -52,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();
@@ -72,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();
@@ -92,22 +103,22 @@ 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
  INSTANCE.connected = 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) {
@@ -119,4 +130,4 @@ public static synchronized Boolean isConnected() {
  NetworkInfo activeNetwork = cm.getActiveNetworkInfo();
  return (activeNetwork != null && activeNetwork.isConnected());
  }
-}
+}

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();

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 {
 

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 that 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;
-
 }

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;
 

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
  */

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,45 +48,77 @@ 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 LocationEngine instance
+ */
+ public static synchronized LocationEngine getLocationEngine(@NonNull Context context) {
  if (instance == null) {
  instance = new LocationSource(context.getApplicationContext());
  }
 
  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()) {
  lostApiClient.connect();
  }
  }
 
+ /**
+ * 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
  public void deactivate() {
  if (lostApiClient != null && lostApiClient.isConnected()) {
  lostApiClient.disconnect();
  }
  }
 
+ /**
+ * Check if your location provider has been activated/connected. This is mainly used internally but is also useful in
+ * 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.
+ */
  @Override
  public boolean isConnected() {
  return lostApiClient.isConnected();
  }
 
+ /**
+ * Invoked when the location provider has connected.
+ */
  @Override
  public void onConnected() {
  for (LocationEngineListener listener : locationListeners) {
  listener.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,13 +157,21 @@ public void requestLocationUpdates() {
  }
  }
 
+ /**
+ * Dismiss ongoing location update to the location provider.
+ */
  @Override
  public void removeLocationUpdates() {
  if (lostApiClient.isConnected()) {
  LocationServices.FusedLocationApi.removeLocationUpdates(lostApiClient, this);
  }
  }
 
+ /**
+ * Invoked when the Location has changed.
+ *
+ * @param location the new location
+ */
  @Override
  public void onLocationChanged(Location location) {
  for (LocationEngineListener listener : locationListeners) {

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);

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 {

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 {
  /**

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 {

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 {

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

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;