Revisit Javadoc for 5.1.0 (#9266)

* [android] - revisit public API javadoc

* [android] fix javadoc minor mistakes and typos

* grammar tweak

* add missing public javadoc

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java

@@ -1,6 +1,5 @@
 package com.mapbox.mapboxsdk;
 
-import android.app.Application;
 import android.content.Context;
 import android.net.ConnectivityManager;
 import android.net.NetworkInfo;
@@ -17,10 +16,10 @@ import com.mapbox.services.android.telemetry.location.LocationEngine;
 import com.mapbox.services.android.telemetry.location.LocationEnginePriority;
 
 /**
- * The entry point of the Mapbox Android SDK.
+ * The entry point to initialize 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
+ * Application#onCreate() and is responsible for the active access token, application context, and
  * connectivity state.
  * </p>
  */
@@ -97,6 +96,8 @@ public final class Mapbox {
 
   /**
    * Application context
+   *
+   * @return the application context
    */
   public static Context getApplicationContext() {
     return INSTANCE.context;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BubbleLayout.java

@@ -27,14 +27,32 @@ public class BubbleLayout extends LinearLayout {
   private float strokeWidth;
   private int strokeColor;
 
+  /**
+   * Creates an instance of bubble layout.
+   *
+   * @param context The context used to inflate this bubble layout
+   */
   public BubbleLayout(Context context) {
     this(context, null, 0);
   }
 
+  /**
+   * Creates an instance of bubble layout.
+   *
+   * @param context The context used to inflate this bubble layout
+   * @param attrs   The attribute set to initialise this bubble layout from
+   */
   public BubbleLayout(Context context, AttributeSet attrs) {
     this(context, attrs, 0);
   }
 
+  /**
+   * Creates an instance of bubble layout.
+   *
+   * @param context      The context used to inflate this bubble layout
+   * @param attrs        The attribute set to initialise this bubble layout from
+   * @param defStyleAttr The default style to apply this bubble layout with
+   */
   public BubbleLayout(Context context, AttributeSet attrs, int defStyleAttr) {
     super(context, attrs, defStyleAttr);
 
@@ -78,10 +96,21 @@ public class BubbleLayout extends LinearLayout {
     return dp * (metrics.densityDpi / DisplayMetrics.DENSITY_DEFAULT);
   }
 
+  /**
+   * Get the arrow direction.
+   *
+   * @return the arrow direction
+   */
   public ArrowDirection getArrowDirection() {
     return arrowDirection;
   }
 
+  /**
+   * Set the arrow direction.
+   *
+   * @param arrowDirection The direction of the arrow
+   * @return this
+   */
   public BubbleLayout setArrowDirection(ArrowDirection arrowDirection) {
     resetPadding();
     this.arrowDirection = arrowDirection;
@@ -89,10 +118,21 @@ public class BubbleLayout extends LinearLayout {
     return this;
   }
 
+  /**
+   * Get the arrow width.
+   *
+   * @return the width of the arrow
+   */
   public float getArrowWidth() {
     return arrowWidth;
   }
 
+  /**
+   * Set the arrow width.
+   *
+   * @param arrowWidth The width of the arrow
+   * @return this
+   */
   public BubbleLayout setArrowWidth(float arrowWidth) {
     resetPadding();
     this.arrowWidth = arrowWidth;
@@ -100,10 +140,21 @@ public class BubbleLayout extends LinearLayout {
     return this;
   }
 
+  /**
+   * Get the arrow height
+   *
+   * @return the height of the arrow
+   */
   public float getArrowHeight() {
     return arrowHeight;
   }
 
+  /**
+   * Set the arrow height.
+   *
+   * @param arrowHeight The height of the arrow
+   * @return this
+   */
   public BubbleLayout setArrowHeight(float arrowHeight) {
     resetPadding();
     this.arrowHeight = arrowHeight;
@@ -111,10 +162,21 @@ public class BubbleLayout extends LinearLayout {
     return this;
   }
 
+  /**
+   * Get the arrow position.
+   *
+   * @return the arrow position
+   */
   public float getArrowPosition() {
     return arrowPosition;
   }
 
+  /**
+   * Get the arrow position.
+   *
+   * @param arrowPosition The arrow position
+   * @return this
+   */
   public BubbleLayout setArrowPosition(float arrowPosition) {
     resetPadding();
     this.arrowPosition = arrowPosition;
@@ -122,30 +184,63 @@ public class BubbleLayout extends LinearLayout {
     return this;
   }
 
+  /**
+   * Get the corner radius
+   *
+   * @return the corner radius
+   */
   public float getCornersRadius() {
     return cornersRadius;
   }
 
+  /**
+   * Set the corner radius
+   *
+   * @param cornersRadius The corner radius
+   * @return this
+   */
   public BubbleLayout setCornersRadius(float cornersRadius) {
     this.cornersRadius = cornersRadius;
     requestLayout();
     return this;
   }
 
+  /**
+   * Get the bubble color.
+   *
+   * @return the bubble color
+   */
   public int getBubbleColor() {
     return bubbleColor;
   }
 
+  /**
+   * Set the bubble color.
+   *
+   * @param bubbleColor The buble color
+   * @return this
+   */
   public BubbleLayout setBubbleColor(int bubbleColor) {
     this.bubbleColor = bubbleColor;
     requestLayout();
     return this;
   }
 
+  /**
+   * Get stroke width.
+   *
+   * @return the stroke width
+   */
   public float getStrokeWidth() {
     return strokeWidth;
   }
 
+  /**
+   * Set the stroke width.
+   *
+   * @param strokeWidth The stroke width
+   * @return this
+   */
   public BubbleLayout setStrokeWidth(float strokeWidth) {
     resetPadding();
     this.strokeWidth = strokeWidth;
@@ -153,10 +248,21 @@ public class BubbleLayout extends LinearLayout {
     return this;
   }
 
+  /**
+   * Get the stroke color.
+   *
+   * @return the stroke color
+   */
   public int getStrokeColor() {
     return strokeColor;
   }
 
+  /**
+   * Set the stroke color.
+   *
+   * @param strokeColor The stroke color
+   * @return this
+   */
   public BubbleLayout setStrokeColor(int strokeColor) {
     this.strokeColor = strokeColor;
     requestLayout();

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java

@@ -23,7 +23,7 @@ import java.io.InputStream;
 /**
  * Factory for creating Icons from bitmap images.
  * <p>
- * {@link Icon} is used to display bitmaps on top of the map using {@link Marker} and {@link MarkerView}.
+ * icon is used to display bitmaps on top of the map using {@link Marker} and {@link MarkerView}.
  * </p>
  *
  * @see Icon
@@ -42,6 +42,12 @@ public final class IconFactory {
 
   private int nextId = 0;
 
+  /**
+   * Get a single instance of IconFactory.
+   *
+   * @param context the context to derive the application context from
+   * @return the single instance of IconFactory
+   */
   public static synchronized IconFactory getInstance(@NonNull Context context) {
     if (instance == null) {
       instance = new IconFactory(context.getApplicationContext());
@@ -71,10 +77,10 @@ public final class IconFactory {
   }
 
   /**
-   * Creates an {@link Icon} from a given Bitmap image.
+   * Creates an icon from a given Bitmap image.
    *
    * @param bitmap image used for creating the Icon.
-   * @return The {@link Icon} using the given Bitmap image.
+   * @return The icon using the given Bitmap image.
    */
   public Icon fromBitmap(@NonNull Bitmap bitmap) {
     if (nextId < 0) {
@@ -85,10 +91,10 @@ public final class IconFactory {
   }
 
   /**
-   * Create an {@link Icon} using the resource ID of a Bitmap image.
+   * Creates an icon using the resource ID of a Bitmap image.
    *
    * @param resourceId The resource ID of a Bitmap image.
-   * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load.
+   * @return The icon that was loaded from the asset or {@code null} if failed to load.
    */
   public Icon fromResource(@DrawableRes int resourceId) {
     Drawable drawable = ContextCompat.getDrawable(context, resourceId);
@@ -101,9 +107,9 @@ public final class IconFactory {
   }
 
   /**
-   * Provides an {@link Icon} using the default marker icon used for {@link Marker}.
+   * Provides an icon using the default marker icon used for {@link Marker}.
    *
-   * @return An {@link Icon} with the default {@link Marker} icon.
+   * @return An icon with the default {@link Marker} icon.
    */
   public Icon defaultMarker() {
     if (defaultMarker == null) {
@@ -113,9 +119,9 @@ public final class IconFactory {
   }
 
   /**
-   * Provides an {@link Icon} using the default marker icon used for {@link MarkerView}.
+   * Provides an icon using the default marker icon used for {@link MarkerView}.
    *
-   * @return An {@link Icon} with the default {@link MarkerView} icon.
+   * @return An icon with the default {@link MarkerView} icon.
    */
   public Icon defaultMarkerView() {
     if (defaultMarkerView == null) {
@@ -130,10 +136,10 @@ public final class IconFactory {
   }
 
   /**
-   * Creates an {@link Icon} using the name of a Bitmap image in the assets directory.
+   * Creates an Icon using the name of a Bitmap image in the assets directory.
    *
    * @param assetName The name of a Bitmap image in the assets directory.
-   * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load.
+   * @return The Icon that was loaded from the asset or null if failed to load.
    */
   public Icon fromAsset(@NonNull String assetName) {
     InputStream is;
@@ -146,11 +152,10 @@ public final class IconFactory {
   }
 
   /**
-   * Creates an {@link Icon} using the absolute file path of a Bitmap image.
+   * Creates an Icon using the absolute file path of a Bitmap image.
    *
    * @param absolutePath The absolute path of the Bitmap image.
-   * @return The {@link Icon} that was loaded from the absolute path or {@code null} if failed to
-   * load.
+   * @return The Icon that was loaded from the absolute path or null if failed to load.
    */
   public Icon fromPath(@NonNull String absolutePath) {
     Bitmap bitmap = BitmapFactory.decodeFile(absolutePath, options);
@@ -158,11 +163,11 @@ public final class IconFactory {
   }
 
   /**
-   * Create an {@link Icon} using the name of a Bitmap image file located in the internal storage.
-   * In particular, this calls {@link Context#openFileInput(String)}.
+   * Create an Icon using the name of a Bitmap image file located in the internal storage.
+   * In particular, this calls Context#openFileInput(String).
    *
    * @param fileName The name of the Bitmap image file.
-   * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load.
+   * @return The Icon that was loaded from the asset or null if failed to load.
    * @see <a href="https://developer.android.com/guide/topics/data/data-storage.html#filesInternal">
    * Using the Internal Storage</a>
    */
@@ -177,12 +182,11 @@ public final class IconFactory {
   }
 
   /**
-   * Create an {@link Icon} using a previously created icon identifier along with a provided
-   * Bitmap.
+   * Create an Icon using a previously created icon identifier along with a provided Bitmap.
    *
-   * @param iconId The {@link Icon} identifier you'd like to recreate.
+   * @param iconId The Icon identifier you'd like to recreate.
    * @param bitmap a Bitmap used to replace the current one.
-   * @return The {@link Icon} using the new Bitmap.
+   * @return The Icon using the new Bitmap.
    */
   public static Icon recreate(@NonNull String iconId, @NonNull Bitmap bitmap) {
     return new Icon(iconId, bitmap);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java

@@ -135,6 +135,12 @@ public class MarkerViewManager implements MapView.OnMapChangedListener {
     }
   }
 
+  /**
+   * Set the rotation of a MarkerView to a given rotation value.
+   *
+   * @param marker   The MarkerView to change its rotation value
+   * @param rotation The rotation value
+   */
   public void setRotation(@NonNull MarkerView marker, float rotation) {
     View convertView = markerViewMap.get(marker);
     if (convertView != null) {
@@ -544,10 +550,11 @@ public class MarkerViewManager implements MapView.OnMapChangedListener {
   }
 
   /**
-   * When the provided {@link MarkerView} is clicked on by a user, we check if a custom click
-   * event has been created and if not, display a {@link InfoWindow}.
+   * When the provided MarkerView is clicked on by a user, we check if a custom click
+   * event has been created and if not, display a InfoWindow.
    *
-   * @param markerView that the click event occurred.
+   * @param markerView that the click event occurred
+   * @return true if the marker view click has been handled, false if not
    */
   public boolean onClickMarkerView(MarkerView markerView) {
     boolean clickHandled = false;
@@ -572,9 +579,9 @@ public class MarkerViewManager implements MapView.OnMapChangedListener {
   }
 
   /**
-   * Handles the {@link MarkerView}'s info window offset.
+   * Handles the MarkerView info window offset.
    *
-   * @param marker that we are ensuring info window offset.
+   * @param marker that we are ensuring info window offset
    */
   public void ensureInfoWindowOffset(MarkerView marker) {
     View view = null;
@@ -624,7 +631,7 @@ public class MarkerViewManager implements MapView.OnMapChangedListener {
   }
 
   /**
-   * Default MarkerViewAdapter used for base class of {@link MarkerView} to adapt a MarkerView to
+   * Default MarkerViewAdapter used for base class of MarkerView to adapt a MarkerView to
    * an ImageView.
    */
   private static class ImageMarkerViewAdapter extends MapboxMap.MarkerViewAdapter<MarkerView> {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java

@@ -3,6 +3,7 @@ package com.mapbox.mapboxsdk.camera;
 import android.content.res.TypedArray;
 import android.os.Parcel;
 import android.os.Parcelable;
+import android.support.annotation.FloatRange;
 
 import com.mapbox.mapboxsdk.R;
 import com.mapbox.mapboxsdk.constants.MapboxConstants;
@@ -166,14 +167,14 @@ public final class CameraPosition implements Parcelable {
     private double zoom = -1;
 
     /**
-     * Creates an empty builder.
+     * Create an empty builder.
      */
     public Builder() {
       super();
     }
 
     /**
-     * Create Builder with an existing CameraPosition data.
+     * Create a builder with an existing CameraPosition data.
      *
      * @param previous Existing CameraPosition values to use
      */
@@ -188,7 +189,7 @@ public final class CameraPosition implements Parcelable {
     }
 
     /**
-     * Create Builder with an existing CameraPosition data.
+     * Create a builder with an existing CameraPosition data.
      *
      * @param typedArray TypedArray containing attribute values
      */
@@ -205,7 +206,7 @@ public final class CameraPosition implements Parcelable {
     }
 
     /**
-     * Create Builder from an existing CameraPositionUpdate update.
+     * Create a builder from an existing CameraPositionUpdate update.
      *
      * @param update Update containing camera options
      */
@@ -220,7 +221,7 @@ public final class CameraPosition implements Parcelable {
     }
 
     /**
-     * Create Builder from an existing CameraPositionUpdate update.
+     * Create builder from an existing CameraPositionUpdate update.
      *
      * @param update Update containing camera options
      */
@@ -235,7 +236,7 @@ public final class CameraPosition implements Parcelable {
      * Sets the direction that the camera is pointing in, in degrees clockwise from north.
      *
      * @param bearing Bearing
-     * @return Builder
+     * @return this
      */
     public Builder bearing(double bearing) {
       double direction = bearing;
@@ -252,19 +253,10 @@ public final class CameraPosition implements Parcelable {
     }
 
     /**
-     * Builds a CameraPosition.
+     * Sets the location where the camera is pointing at.
      *
-     * @return CameraPosition
-     */
-    public CameraPosition build() {
-      return new CameraPosition(target, zoom, tilt, bearing);
-    }
-
-    /**
-     * Sets the location that the camera is pointing at.
-     *
-     * @param location Location
-     * @return Builder
+     * @param location target of the camera
+     * @return this
      */
     public Builder target(LatLng location) {
       this.target = location;
@@ -272,28 +264,42 @@ public final class CameraPosition implements Parcelable {
     }
 
     /**
-     * Set the tilt in degrees
+     * Set the tilt of the camera in degrees
      * <p>
-     * value is clamped to 0 and 60.
+     * value is clamped to {@link MapboxConstants#MINIMUM_TILT} and {@link MapboxConstants#MAXIMUM_TILT}.
      * </p>
      *
-     * @param tilt Tilt value
-     * @return Builder
+     * @param tilt Tilt value of the camera
+     * @return this
      */
-    public Builder tilt(double tilt) {
+    public Builder tilt(@FloatRange(from = MapboxConstants.MINIMUM_TILT,
+      to = MapboxConstants.MAXIMUM_TILT) double tilt) {
       this.tilt = MathUtils.clamp(tilt, MapboxConstants.MINIMUM_TILT, MapboxConstants.MAXIMUM_TILT);
       return this;
     }
 
     /**
-     * Set the zoom
+     * Set the zoom of the camera
+     * <p>
+     * Zoom ranges from {@link MapboxConstants#MINIMUM_ZOOM} to {@link MapboxConstants#MAXIMUM_ZOOM}
+     * </p>
      *
-     * @param zoom Zoom value
-     * @return Builder
+     * @param zoom Zoom value of the camera
+     * @return this
      */
-    public Builder zoom(double zoom) {
+    public Builder zoom(@FloatRange(from = MapboxConstants.MINIMUM_ZOOM,
+      to = MapboxConstants.MAXIMUM_ZOOM) double zoom) {
       this.zoom = zoom;
       return this;
     }
+
+    /**
+     * Builds the CameraPosition.
+     *
+     * @return CameraPosition
+     */
+    public CameraPosition build() {
+      return new CameraPosition(target, zoom, tilt, bearing);
+    }
   }
 }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdate.java

@@ -6,10 +6,16 @@ import android.support.annotation.Nullable;
 import com.mapbox.mapboxsdk.maps.MapboxMap;
 
 /**
- * Interface definition for camera position changes.
+ * Interface definition for camera updates.
  */
 public interface CameraUpdate {
 
+  /**
+   * Get the camera position from the camera update.
+   *
+   * @param mapboxMap Map object to build the position from
+   * @return the camera position from the implementing camera update
+   */
   @Nullable
   CameraPosition getCameraPosition(@NonNull MapboxMap mapboxMap);
 

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java

@@ -42,7 +42,7 @@ public final class CameraUpdateFactory {
   }
 
   /**
-   * Returns a {@link CameraUpdate} that transforms the camera such that the specified
+   * Returns a CameraUpdate that transforms the camera such that the specified
    * latitude/longitude bounds are centered on screen at the greatest possible zoom level.
    * You can specify padding, in order to inset the bounding box from the map view's edges.
    * The returned CameraUpdate has a bearing of 0 and a tilt of 0.
@@ -56,7 +56,7 @@ public final class CameraUpdateFactory {
   }
 
   /**
-   * Returns a {@link CameraUpdate} that transforms the camera such that the specified
+   * Returns a CameraUpdate that transforms the camera such that the specified
    * latitude/longitude bounds are centered on screen at the greatest possible zoom level.
    * You can specify padding, in order to inset the bounding box from the map view's edges.
    * The returned CameraUpdate has a bearing of 0 and a tilt of 0.

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java

@@ -2,23 +2,27 @@ package com.mapbox.mapboxsdk.constants;
 
 import android.support.annotation.IntDef;
 
+import com.mapbox.mapboxsdk.maps.MapboxMap;
 import com.mapbox.mapboxsdk.maps.widgets.MyLocationView;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * MyBearingTracking exposes different types bearing tracking modes.
+ * MyBearingTracking exposes different types of bearing tracking modes.
+ * <p>
+ * These modes visualise the user direction by extracting the direction from either sensor or location data.
+ * </p>
+ * <p>
+ * Required to enable showing the user location first through {@link MapboxMap#setMyLocationEnabled(boolean)}.
+ * </p>
  *
  * @see com.mapbox.mapboxsdk.maps.TrackingSettings#setMyBearingTrackingMode(int)
  * @see MyLocationView#setMyBearingTrackingMode(int)
  */
 public class MyBearingTracking {
 
-  /**
-   * Indicates that the parameter accepts one of the values from MyBearingTracking.
-   */
-  @IntDef( {NONE, COMPASS, GPS, /**COMBINED**/})
+  @IntDef( {NONE, COMPASS, GPS})
   @Retention(RetentionPolicy.SOURCE)
   public @interface Mode {
   }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyLocationTracking.java

@@ -3,29 +3,34 @@ package com.mapbox.mapboxsdk.constants;
 import android.support.annotation.IntDef;
 
 import com.mapbox.mapboxsdk.maps.MapView;
+import com.mapbox.mapboxsdk.maps.MapboxMap;
+import com.mapbox.mapboxsdk.maps.TrackingSettings;
 import com.mapbox.mapboxsdk.maps.widgets.MyLocationView;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * MyLocationTracking exposes different types of locational tracking modes.
+ * MyLocationTracking exposes types of location tracking modes.
+ * * <p>
+ * This allows tracking the user location on screen by updating the camera position when a location update occurs.
+ * </p>
+ * <p>
+ * Required to enable showing the user location first through {@link MapboxMap#setMyLocationEnabled(boolean)}.
+ * </p>
  *
- * @see com.mapbox.mapboxsdk.maps.TrackingSettings#setMyLocationTrackingMode(int)
- * @see MyLocationView#setMyLocationTrackingMode(int)
+ * @see MapboxMap#setMyLocationEnabled(boolean)
+ * @see TrackingSettings#setMyLocationTrackingMode(int)
  */
 public class MyLocationTracking {
 
-  /**
-   * Indicates the parameter accepts one of the values from MyLocationTracking.
-   */
   @IntDef( {TRACKING_NONE, TRACKING_FOLLOW})
   @Retention(RetentionPolicy.SOURCE)
   public @interface Mode {
   }
 
   /**
-   * Location tracking is disabled.
+   * Tracking the location of the user is disabled.
    */
   public static final int TRACKING_NONE = 0x00000000;
 

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java

@@ -17,7 +17,6 @@ import java.lang.annotation.RetentionPolicy;
  */
 public class Style {
 
-
   /**
    * 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

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/IconBitmapChangedException.java

@@ -1,15 +1,13 @@
 package com.mapbox.mapboxsdk.exceptions;
 
-import android.graphics.Bitmap;
-
 import com.mapbox.mapboxsdk.annotations.Icon;
 import com.mapbox.mapboxsdk.annotations.Marker;
 import com.mapbox.mapboxsdk.maps.MapView;
 
 /**
  * <p>
- * A {@code IconBitmapChangedException} is thrown by {@link MapView} when a {@link Marker} is added
- * that has a {@link Icon} with a {@link Bitmap} that has been modified since the creation of the Icon.
+ * An IconBitmapChangedException is thrown by MapView when a Marker is added
+ * that has an Icon with a Bitmap that has been modified since the creation of the Icon.
  * </p>
  * You cannot modify a {@code Icon} after it has been added to the map in a {@code Marker}
  *

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidLatLngBoundsException.java

@@ -1,8 +1,8 @@
 package com.mapbox.mapboxsdk.exceptions;
 
 /**
- * A InvalidLatLngBoundsException is thrown by {@link com.mapbox.mapboxsdk.geometry.LatLngBounds}
- * when there aren't enough {@link com.mapbox.mapboxsdk.geometry.LatLng} to create a bounds.
+ * An InvalidLatLngBoundsException is thrown by LatLngBounds
+ * when there aren't enough LatLng to create a bounds.
  */
 public class InvalidLatLngBoundsException extends RuntimeException {
 

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidMarkerPositionException.java

@@ -5,6 +5,9 @@ package com.mapbox.mapboxsdk.exceptions;
  */
 public class InvalidMarkerPositionException extends RuntimeException {
 
+  /**
+   * Creates a invalid marker position exception thrown when a Marker object is created with an invalid LatLng position.
+   */
   public InvalidMarkerPositionException() {
     super("Adding an invalid Marker to a Map. "
       + "Missing the required position field. "

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/MapboxConfigurationException.java

@@ -8,10 +8,14 @@ import android.content.Context;
  * This occurs either when {@link com.mapbox.mapboxsdk.Mapbox} is not correctly initialised or the provided access token
  * through {@link com.mapbox.mapboxsdk.Mapbox#getInstance(Context, String)} isn't valid.
  * </p>
+ *
  * @see com.mapbox.mapboxsdk.Mapbox#getInstance(Context, String)
  */
 public class MapboxConfigurationException extends RuntimeException {
 
+  /**
+   * Creates a Mapbox configuration exception thrown by MapboxMap when the SDK hasn't been properly initialised.
+   */
   public MapboxConfigurationException() {
     super("\nUsing MapView requires setting a valid access token. Use Mapbox.getInstance(Context context, "
       + "String accessToken) to provide one. "

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/TooManyIconsException.java

@@ -1,12 +1,11 @@
 package com.mapbox.mapboxsdk.exceptions;
 
-import com.mapbox.mapboxsdk.annotations.Icon;
 import com.mapbox.mapboxsdk.annotations.IconFactory;
 
 /**
  * <p>
- * A {@code TooManyIconsException} is thrown by {@link IconFactory} when it
- * cannot create a {@link Icon} because there are already too many icons created.
+ * A TooManyIconsException is thrown by IconFactory when it
+ * cannot create a Icon because there are already too many icons created.
  * </p>
  * You should try to reuse Icon objects whenever possible.
  *

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ILatLng.java

@@ -1,12 +1,28 @@
 package com.mapbox.mapboxsdk.geometry;
 
 /**
- * Describes a latitude, longitude point.
+ * Describes a latitude, longitude, and altitude tuple.
  */
 public interface ILatLng {
+
+  /**
+   * Get the latitude, in degrees.
+   *
+   * @return the latitude value in degrees
+   */
   double getLatitude();
 
+  /**
+   * Get the longitude, in degrees.
+   *
+   * @return the longitude value in degrees
+   */
   double getLongitude();
 
+  /**
+   * Get the altitude, in meters.
+   *
+   * @return the altitude value in meters
+   */
   double getAltitude();
 }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/IProjectedMeters.java

@@ -4,7 +4,19 @@ package com.mapbox.mapboxsdk.geometry;
  * Describes a projection in Mercator meters.
  */
 public interface IProjectedMeters {
+
+  /**
+   * Get the north projection, in meters.
+   *
+   * @return the projected meters in north direction
+   */
   double getNorthing();
 
+  /**
+   * Get the east projection, in meters.
+   *
+   * @return the projected meters in east direction
+   */
   double getEasting();
+
 }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java

@@ -3,6 +3,7 @@ package com.mapbox.mapboxsdk.geometry;
 import android.location.Location;
 import android.os.Parcel;
 import android.os.Parcelable;
+import android.support.annotation.FloatRange;
 
 import com.mapbox.services.android.telemetry.constants.GeoConstants;
 import com.mapbox.services.android.telemetry.utils.MathUtils;
@@ -21,6 +22,9 @@ import com.mapbox.services.android.telemetry.utils.MathUtils;
  */
 public class LatLng implements ILatLng, Parcelable {
 
+  /**
+   * Inner class responsible for recreating Parcels into objects.
+   */
   public static final Parcelable.Creator<LatLng> CREATOR = new Parcelable.Creator<LatLng>() {
     public LatLng createFromParcel(Parcel in) {
       return new LatLng(in);
@@ -44,7 +48,7 @@ public class LatLng implements ILatLng, Parcelable {
   }
 
   /**
-   * Construct a new latitude, longitude point given float arguments
+   * Construct a new latitude, longitude point given double arguments
    *
    * @param latitude  Latitude in degrees
    * @param longitude Longitude in degrees
@@ -55,7 +59,7 @@ public class LatLng implements ILatLng, Parcelable {
   }
 
   /**
-   * Construct a new latitude, longitude, altitude point given float arguments
+   * Construct a new latitude, longitude, altitude point given double arguments
    *
    * @param latitude  Latitude in degrees
    * @param longitude Longitude in degress
@@ -68,7 +72,7 @@ public class LatLng implements ILatLng, Parcelable {
   }
 
   /**
-   * Transform a Location into a LatLng point
+   * Construct a new latitude, longitude, altitude point given location argument
    *
    * @param location Android Location
    */
@@ -77,23 +81,40 @@ public class LatLng implements ILatLng, Parcelable {
   }
 
   /**
-   * Clone an existing latitude longitude point
+   * Construct a new latitude, longitude, altitude point given another latitude, longitude, altitude point.
    *
-   * @param aLatLng LatLng
+   * @param latLng LatLng to be cloned.
    */
-  public LatLng(LatLng aLatLng) {
-    this.latitude = aLatLng.latitude;
-    this.longitude = aLatLng.longitude;
-    this.altitude = aLatLng.altitude;
+  public LatLng(LatLng latLng) {
+    this.latitude = latLng.latitude;
+    this.longitude = latLng.longitude;
+    this.altitude = latLng.altitude;
   }
 
+  /**
+   * Constructs a new latitude, longitude, altitude tuple given a parcel.
+   *
+   * @param in the parcel containing the latitude, longitude, altitude values
+   */
   protected LatLng(Parcel in) {
     setLatitude(in.readDouble());
     setLongitude(in.readDouble());
     setAltitude(in.readDouble());
   }
 
-  public void setLatitude(double latitude) {
+  /**
+   * Set the latitude, in degrees.
+   * <p>
+   * This value is in the range of [-85.05112878, 85.05112878], see {@link GeoConstants#MIN_LATITUDE} and
+   * {@link GeoConstants#MAX_LATITUDE}
+   * </p>
+   *
+   * @param latitude the latitude value in degrees
+   * @see GeoConstants#MIN_LATITUDE
+   * @see GeoConstants#MAX_LATITUDE
+   */
+  public void setLatitude(
+    @FloatRange(from = GeoConstants.MIN_LATITUDE, to = GeoConstants.MAX_LATITUDE) double latitude) {
     if (Double.isNaN(latitude)) {
       throw new IllegalArgumentException("latitude must not be NaN");
     }
@@ -103,12 +124,35 @@ public class LatLng implements ILatLng, Parcelable {
     this.latitude = latitude;
   }
 
+  /**
+   * Get the latitude, in degrees.
+   * <p>
+   * This value is in the range of [-85.05112878, 85.05112878], see {@link GeoConstants#MIN_LATITUDE} and
+   * {@link GeoConstants#MAX_LATITUDE}
+   * </p>
+   *
+   * @return the latitude value in degrees
+   * @see GeoConstants#MIN_LATITUDE
+   * @see GeoConstants#MAX_LATITUDE
+   */
   @Override
   public double getLatitude() {
     return latitude;
   }
 
-  public void setLongitude(double longitude) {
+  /**
+   * Set the longitude, in degrees.
+   * <p>
+   * This value is in the range of [-180, 180], see {@link GeoConstants#MIN_LONGITUDE} and
+   * {@link GeoConstants#MAX_LONGITUDE}
+   * </p>
+   *
+   * @param longitude the longitude value in degrees
+   * @see GeoConstants#MIN_LONGITUDE
+   * @see GeoConstants#MAX_LONGITUDE
+   */
+  public void setLongitude(@FloatRange(from = GeoConstants.MIN_LONGITUDE, to = GeoConstants.MAX_LONGITUDE)
+                             double longitude) {
     if (Double.isNaN(longitude)) {
       throw new IllegalArgumentException("longitude must not be NaN");
     }
@@ -118,15 +162,36 @@ public class LatLng implements ILatLng, Parcelable {
     this.longitude = longitude;
   }
 
+  /**
+   * Get the longitude, in degrees.
+   * <p>
+   * This value is in the range of [-180, 180], see {@link GeoConstants#MIN_LONGITUDE} and
+   * {@link GeoConstants#MAX_LONGITUDE}
+   * </p>
+   *
+   * @return the longitude value in degrees
+   * @see GeoConstants#MIN_LONGITUDE
+   * @see GeoConstants#MAX_LONGITUDE
+   */
   @Override
   public double getLongitude() {
     return longitude;
   }
 
+  /**
+   * Set the altitude, in meters.
+   *
+   * @param altitude the altitude in meters
+   */
   public void setAltitude(double altitude) {
     this.altitude = altitude;
   }
 
+  /**
+   * Get the altitude, in meters.
+   *
+   * @return the altitude value in meters
+   */
   @Override
   public double getAltitude() {
     return altitude;
@@ -136,13 +201,19 @@ public class LatLng implements ILatLng, Parcelable {
    * Return a new LatLng object with a wrapped Longitude.  This allows original data object
    * to remain unchanged.
    *
-   * @return New LatLng object with wrapped Longitude
+   * @return new LatLng object with wrapped Longitude
    */
   public LatLng wrap() {
     longitude = MathUtils.wrap(longitude, GeoConstants.MIN_LONGITUDE, GeoConstants.MAX_LONGITUDE);
     return this;
   }
 
+  /**
+   * Indicates whether some other object is "equal to" this one.
+   *
+   * @param object The object to compare
+   * @return True if equal, false if not
+   */
   @Override
   public boolean equals(Object object) {
     if (this == object) {
@@ -158,6 +229,11 @@ public class LatLng implements ILatLng, Parcelable {
       && Double.compare(latLng.longitude, longitude) == 0;
   }
 
+  /**
+   * Returns a hash code value for the object.
+   *
+   * @return the hash code value
+   */
   @Override
   public int hashCode() {
     int result;
@@ -171,16 +247,32 @@ public class LatLng implements ILatLng, Parcelable {
     return result;
   }
 
+  /**
+   * Returns a string representation of the object.
+   *
+   * @return the string representation
+   */
   @Override
   public String toString() {
     return "LatLng [latitude=" + latitude + ", longitude=" + longitude + ", altitude=" + altitude + "]";
   }
 
+  /**
+   * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
+   *
+   * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance.
+   */
   @Override
   public int describeContents() {
     return 0;
   }
 
+  /**
+   * Flatten this object in to a Parcel.
+   *
+   * @param out   The Parcel in which the object should be written.
+   * @param flags Additional flags about how the object should be written
+   */
   @Override
   public void writeToParcel(Parcel out, int flags) {
     out.writeDouble(latitude);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngBounds.java

@@ -3,6 +3,7 @@ package com.mapbox.mapboxsdk.geometry;
 import android.os.Parcel;
 import android.os.Parcelable;
 import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 
 import com.mapbox.mapboxsdk.exceptions.InvalidLatLngBoundsException;
 import com.mapbox.services.android.telemetry.constants.GeoConstants;
@@ -18,10 +19,10 @@ import java.util.List;
  */
 public class LatLngBounds implements Parcelable {
 
-  private final double mLatNorth;
-  private final double mLatSouth;
-  private final double mLonEast;
-  private final double mLonWest;
+  private final double latitudeNorth;
+  private final double latitudeSouth;
+  private final double longitudeEast;
+  private final double longitudeWest;
 
   /**
    * Construct a new LatLngBounds based on its corners, given in NESW
@@ -34,10 +35,10 @@ public class LatLngBounds implements Parcelable {
    */
   LatLngBounds(final double northLatitude, final double eastLongitude, final double southLatitude,
                final double westLongitude) {
-    this.mLatNorth = northLatitude;
-    this.mLonEast = eastLongitude;
-    this.mLatSouth = southLatitude;
-    this.mLonWest = westLongitude;
+    this.latitudeNorth = northLatitude;
+    this.longitudeEast = eastLongitude;
+    this.latitudeSouth = southLatitude;
+    this.longitudeWest = westLongitude;
   }
 
   /**
@@ -59,8 +60,8 @@ public class LatLngBounds implements Parcelable {
    * @return LatLng center of this LatLngBounds
    */
   public LatLng getCenter() {
-    return new LatLng((this.mLatNorth + this.mLatSouth) / 2,
-      (this.mLonEast + this.mLonWest) / 2);
+    return new LatLng((this.latitudeNorth + this.latitudeSouth) / 2,
+      (this.longitudeEast + this.longitudeWest) / 2);
   }
 
   /**
@@ -69,7 +70,7 @@ public class LatLngBounds implements Parcelable {
    * @return double latitude value for north
    */
   public double getLatNorth() {
-    return this.mLatNorth;
+    return this.latitudeNorth;
   }
 
   /**
@@ -78,7 +79,7 @@ public class LatLngBounds implements Parcelable {
    * @return double latitude value for south
    */
   public double getLatSouth() {
-    return this.mLatSouth;
+    return this.latitudeSouth;
   }
 
   /**
@@ -87,7 +88,7 @@ public class LatLngBounds implements Parcelable {
    * @return double longitude value for east
    */
   public double getLonEast() {
-    return this.mLonEast;
+    return this.longitudeEast;
   }
 
   /**
@@ -96,7 +97,7 @@ public class LatLngBounds implements Parcelable {
    * @return double longitude value for west
    */
   public double getLonWest() {
-    return this.mLonWest;
+    return this.longitudeWest;
   }
 
   /**
@@ -105,7 +106,7 @@ public class LatLngBounds implements Parcelable {
    * @return LatLng of the south west corner
    */
   public LatLng getSouthWest() {
-    return new LatLng(mLatSouth, mLonWest);
+    return new LatLng(latitudeSouth, longitudeWest);
   }
 
   /**
@@ -114,7 +115,7 @@ public class LatLngBounds implements Parcelable {
    * @return LatLng of the north east corner
    */
   public LatLng getNorthEast() {
-    return new LatLng(mLatNorth, mLonEast);
+    return new LatLng(latitudeNorth, longitudeEast);
   }
 
   /**
@@ -123,7 +124,7 @@ public class LatLngBounds implements Parcelable {
    * @return LatLng of the south east corner
    */
   public LatLng getSouthEast() {
-    return new LatLng(mLatSouth, mLonEast);
+    return new LatLng(latitudeSouth, longitudeEast);
   }
 
   /**
@@ -132,7 +133,7 @@ public class LatLngBounds implements Parcelable {
    * @return LatLng of the north west corner
    */
   public LatLng getNorthWest() {
-    return new LatLng(mLatNorth, mLonWest);
+    return new LatLng(latitudeNorth, longitudeWest);
   }
 
   /**
@@ -151,7 +152,7 @@ public class LatLngBounds implements Parcelable {
    * @return Span distance
    */
   public double getLatitudeSpan() {
-    return Math.abs(this.mLatNorth - this.mLatSouth);
+    return Math.abs(this.latitudeNorth - this.latitudeSouth);
   }
 
   /**
@@ -161,7 +162,7 @@ public class LatLngBounds implements Parcelable {
    * @return Span distance
    */
   public double getLongitudeSpan() {
-    return Math.abs(this.mLonEast - this.mLonWest);
+    return Math.abs(this.longitudeEast - this.longitudeWest);
   }
 
 
@@ -174,9 +175,15 @@ public class LatLngBounds implements Parcelable {
     return getLongitudeSpan() == 0.0 || getLatitudeSpan() == 0.0;
   }
 
+  /**
+   * Returns a string representaton of the object.
+   *
+   * @return the string representation
+   */
   @Override
   public String toString() {
-    return "N:" + this.mLatNorth + "; E:" + this.mLonEast + "; S:" + this.mLatSouth + "; W:" + this.mLonWest;
+    return "N:" + this.latitudeNorth + "; E:" + this.longitudeEast + "; S:" + this.latitudeSouth
+      + "; W:" + this.longitudeWest;
   }
 
   /**
@@ -241,10 +248,10 @@ public class LatLngBounds implements Parcelable {
     }
     if (o instanceof LatLngBounds) {
       LatLngBounds other = (LatLngBounds) o;
-      return mLatNorth == other.getLatNorth()
-        && mLatSouth == other.getLatSouth()
-        && mLonEast == other.getLonEast()
-        && mLonWest == other.getLonWest();
+      return latitudeNorth == other.getLatNorth()
+        && latitudeSouth == other.getLatSouth()
+        && longitudeEast == other.getLonEast()
+        && longitudeWest == other.getLonWest();
     }
     return false;
   }
@@ -258,10 +265,10 @@ public class LatLngBounds implements Parcelable {
   public boolean contains(final ILatLng latLng) {
     final double latitude = latLng.getLatitude();
     final double longitude = latLng.getLongitude();
-    return ((latitude <= this.mLatNorth)
-      && (latitude >= this.mLatSouth))
-      && ((longitude <= this.mLonEast)
-      && (longitude >= this.mLonWest));
+    return ((latitude <= this.latitudeNorth)
+      && (latitude >= this.latitudeSouth))
+      && ((longitude <= this.longitudeEast)
+      && (longitude >= this.longitudeWest));
   }
 
   /**
@@ -295,10 +302,10 @@ public class LatLngBounds implements Parcelable {
    * @return BoundingBox
    */
   public LatLngBounds union(final double lonNorth, final double latEast, final double lonSouth, final double latWest) {
-    return new LatLngBounds((this.mLatNorth < lonNorth) ? lonNorth : this.mLatNorth,
-      (this.mLonEast < latEast) ? latEast : this.mLonEast,
-      (this.mLatSouth > lonSouth) ? lonSouth : this.mLatSouth,
-      (this.mLonWest > latWest) ? latWest : this.mLonWest);
+    return new LatLngBounds((this.latitudeNorth < lonNorth) ? lonNorth : this.latitudeNorth,
+      (this.longitudeEast < latEast) ? latEast : this.longitudeEast,
+      (this.latitudeSouth > lonSouth) ? lonSouth : this.latitudeSouth,
+      (this.longitudeWest > latWest) ? latWest : this.longitudeWest);
   }
 
   /**
@@ -307,6 +314,7 @@ public class LatLngBounds implements Parcelable {
    * @param box LatLngBounds to intersect with
    * @return LatLngBounds
    */
+  @Nullable
   public LatLngBounds intersect(LatLngBounds box) {
     double minLatWest = Math.max(getLonWest(), box.getLonWest());
     double maxLatEast = Math.min(getLonEast(), box.getLonEast());
@@ -334,6 +342,9 @@ public class LatLngBounds implements Parcelable {
     return intersect(new LatLngBounds(northLatitude, eastLongitude, southLatitude, westLongitude));
   }
 
+  /**
+   * Inner class responsible for recreating Parcels into objects.
+   */
   public static final Parcelable.Creator<LatLngBounds> CREATOR =
     new Parcelable.Creator<LatLngBounds>() {
       @Override
@@ -347,25 +358,41 @@ public class LatLngBounds implements Parcelable {
       }
     };
 
+  /**
+   * Returns a hash code value for the object.
+   *
+   * @return the hash code
+   */
   @Override
   public int hashCode() {
-    return (int) ((mLatNorth + 90)
-      + ((mLatSouth + 90) * 1000)
-      + ((mLonEast + 180) * 1000000)
-      + ((mLonEast + 180) * 1000000000));
+    return (int) ((latitudeNorth + 90)
+      + ((latitudeSouth + 90) * 1000)
+      + ((longitudeEast + 180) * 1000000)
+      + ((longitudeEast + 180) * 1000000000));
   }
 
+  /**
+   * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
+   *
+   * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance.
+   */
   @Override
   public int describeContents() {
     return 0;
   }
 
+  /**
+   * Flatten this object in to a Parcel.
+   *
+   * @param out   The Parcel in which the object should be written.
+   * @param flags Additional flags about how the object should be written
+   */
   @Override
-  public void writeToParcel(final Parcel out, final int arg1) {
-    out.writeDouble(this.mLatNorth);
-    out.writeDouble(this.mLonEast);
-    out.writeDouble(this.mLatSouth);
-    out.writeDouble(this.mLonWest);
+  public void writeToParcel(final Parcel out, final int flags) {
+    out.writeDouble(this.latitudeNorth);
+    out.writeDouble(this.longitudeEast);
+    out.writeDouble(this.latitudeSouth);
+    out.writeDouble(this.longitudeWest);
   }
 
   private static LatLngBounds readFromParcel(final Parcel in) {
@@ -381,28 +408,51 @@ public class LatLngBounds implements Parcelable {
    */
   public static final class Builder {
 
-    private List<LatLng> mLatLngList;
+    private List<LatLng> latLngList;
 
+    /**
+     * Constructs a builder to compose LatLng objects to a LatLngBounds.
+     */
     public Builder() {
-      mLatLngList = new ArrayList<>();
+      latLngList = new ArrayList<>();
     }
 
+    /**
+     * Builds a new LatLngBounds.
+     * <p>
+     * Throws an {@link InvalidLatLngBoundsException} when no LatLngBounds can be created.
+     * </p>
+     *
+     * @return the build LatLngBounds
+     */
     public LatLngBounds build() {
-      if (mLatLngList.size() < 2) {
-        throw new InvalidLatLngBoundsException(mLatLngList.size());
+      if (latLngList.size() < 2) {
+        throw new InvalidLatLngBoundsException(latLngList.size());
       }
-      return LatLngBounds.fromLatLngs(mLatLngList);
+      return LatLngBounds.fromLatLngs(latLngList);
     }
 
+    /**
+     * Adds a LatLng object to the LatLngBounds.Builder.
+     *
+     * @param latLngs the List of LatLng objects to be added
+     * @return this
+     */
     public Builder includes(List<LatLng> latLngs) {
       for (LatLng point : latLngs) {
-        mLatLngList.add(point);
+        latLngList.add(point);
       }
       return this;
     }
 
+    /**
+     * Adds a LatLng object to the LatLngBounds.Builder.
+     *
+     * @param latLng the LatLng to be added
+     * @return this
+     */
     public Builder include(@NonNull LatLng latLng) {
-      mLatLngList.add(latLng);
+      latLngList.add(latLng);
       return this;
     }
   }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngSpan.java

@@ -64,19 +64,28 @@ public class LatLngSpan implements Parcelable {
     mLongitudeSpan = longitudeSpan;
   }
 
+  /**
+   * Indicates whether some other object is "equal to" this one.
+   *
+   * @param object The object to compare
+   * @return True if equal, false if not
+   */
   @Override
-  public boolean equals(Object o) {
-    if (this == o) {
+  public boolean equals(Object object) {
+    if (this == object) {
       return true;
     }
-    if (o instanceof LatLngSpan) {
-      LatLngSpan other = (LatLngSpan) o;
+    if (object instanceof LatLngSpan) {
+      LatLngSpan other = (LatLngSpan) object;
       return mLongitudeSpan == other.getLongitudeSpan()
         && mLatitudeSpan == other.getLatitudeSpan();
     }
     return false;
   }
 
+  /**
+   * Inner class responsible for recreating Parcels into objects.
+   */
   public static final Parcelable.Creator<LatLngSpan> CREATOR =
     new Parcelable.Creator<LatLngSpan>() {
       @Override
@@ -90,14 +99,41 @@ public class LatLngSpan implements Parcelable {
       }
     };
 
+  /**
+   * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
+   *
+   * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance.
+   */
   @Override
   public int describeContents() {
     return 0;
   }
 
+  /**
+   * Flatten this object in to a Parcel.
+   *
+   * @param out   Parcel in which the object should be written
+   * @param flags Additional flags about how the object should be written
+   */
   @Override
-  public void writeToParcel(Parcel out, int arg1) {
+  public void writeToParcel(Parcel out, int flags) {
     out.writeDouble(mLatitudeSpan);
     out.writeDouble(mLongitudeSpan);
   }
+
+  /**
+   * Returns a hash code value for the object.
+   *
+   * @return hash code value of this
+   */
+  @Override
+  public int hashCode() {
+    int result;
+    long temp;
+    temp = Double.doubleToLongBits(mLatitudeSpan);
+    result = (int) (temp ^ (temp >>> 32));
+    temp = Double.doubleToLongBits(mLongitudeSpan);
+    result = 31 * result + (int) (temp ^ (temp >>> 32));
+    return result;
+  }
 }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java

@@ -13,6 +13,9 @@ import android.os.Parcelable;
  */
 public class ProjectedMeters implements IProjectedMeters, Parcelable {
 
+  /**
+   * Inner class responsible for recreating Parcels into objects.
+   */
   public static final Creator<ProjectedMeters> CREATOR = new Creator<ProjectedMeters>() {
     public ProjectedMeters createFromParcel(Parcel in) {
       return new ProjectedMeters(in);
@@ -47,6 +50,12 @@ public class ProjectedMeters implements IProjectedMeters, Parcelable {
     this.easting = projectedMeters.easting;
   }
 
+  /**
+   * Creates a ProjectedMeters from a Parcel.
+   *
+   * @param in The parcel to create from
+   * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance.
+   */
   private ProjectedMeters(Parcel in) {
     northing = in.readDouble();
     easting = in.readDouble();
@@ -72,22 +81,32 @@ public class ProjectedMeters implements IProjectedMeters, Parcelable {
     return easting;
   }
 
+  /**
+   * Indicates whether some other object is "equal to" this one.
+   *
+   * @param other The object to compare this to
+   * @return true if equal, false if not
+   */
   @Override
-  public boolean equals(Object o) {
-    if (this == o) {
+  public boolean equals(Object other) {
+    if (this == other) {
       return true;
     }
-    if (o == null || getClass() != o.getClass()) {
+    if (other == null || getClass() != other.getClass()) {
       return false;
     }
 
-    ProjectedMeters projectedMeters = (ProjectedMeters) o;
+    ProjectedMeters projectedMeters = (ProjectedMeters) other;
 
     return Double.compare(projectedMeters.easting, easting) == 0
       && Double.compare(projectedMeters.northing, northing) == 0;
-
   }
 
+  /**
+   * Returns a hash code value for the object.
+   *
+   * @return the hash code of this
+   */
   @Override
   public int hashCode() {
     int result;
@@ -99,16 +118,32 @@ public class ProjectedMeters implements IProjectedMeters, Parcelable {
     return result;
   }
 
+  /**
+   * Returns a string representation of the object.
+   *
+   * @return the string representation of this
+   */
   @Override
   public String toString() {
     return "ProjectedMeters [northing=" + northing + ", easting=" + easting + "]";
   }
 
+  /**
+   * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
+   *
+   * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance.
+   */
   @Override
   public int describeContents() {
     return 0;
   }
 
+  /**
+   * Flatten this object in to a Parcel.
+   *
+   * @param out   The Parcel in which the object should be written.
+   * @param flags Additional flags about how the object should be written
+   */
   @Override
   public void writeToParcel(Parcel out, int flags) {
     out.writeDouble(northing);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/VisibleRegion.java

@@ -37,6 +37,11 @@ public class VisibleRegion implements Parcelable {
    */
   public final LatLngBounds latLngBounds;
 
+  /**
+   * Creates a VisibleRegion from a Parcel.
+   *
+   * @param in The Parcel to create this from
+   */
   private VisibleRegion(Parcel in) {
     this.farLeft = in.readParcelable(LatLng.class.getClassLoader());
     this.farRight = in.readParcelable(LatLng.class.getClassLoader());
@@ -46,7 +51,7 @@ public class VisibleRegion implements Parcelable {
   }
 
   /**
-   * Creates a new VisibleRegion given the four corners of the camera.
+   * Creates a VisibleRegion given the four corners of the camera.
    *
    * @param farLeft      A LatLng object containing the latitude and longitude of the near left corner of the region.
    * @param farRight     A LatLng object containing the latitude and longitude of the near left corner of the region.
@@ -88,12 +93,22 @@ public class VisibleRegion implements Parcelable {
       && latLngBounds.equals(visibleRegion.latLngBounds);
   }
 
+  /**
+   * The string representation of the object.
+   *
+   * @return the string representation of this
+   */
   @Override
   public String toString() {
     return "[farLeft [" + farLeft + "], farRight [" + farRight + "], nearLeft [" + nearLeft + "], nearRight ["
       + nearRight + "], latLngBounds [" + latLngBounds + "]]";
   }
 
+  /**
+   * Returns a hash code value for the object.
+   *
+   * @return the hash code
+   */
   @Override
   public int hashCode() {
     return ((farLeft.hashCode() + 90)
@@ -102,11 +117,22 @@ public class VisibleRegion implements Parcelable {
       + ((nearRight.hashCode() + 180) * 1000000000));
   }
 
+  /**
+   * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
+   *
+   * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance.
+   */
   @Override
   public int describeContents() {
     return 0;
   }
 
+  /**
+   * Flatten this object in to a Parcel.
+   *
+   * @param out   The Parcel in which the object should be written.
+   * @param flags Additional flags about how the object should be written
+   */
   @Override
   public void writeToParcel(Parcel out, int flags) {
     out.writeParcelable(farLeft, flags);
@@ -116,6 +142,9 @@ public class VisibleRegion implements Parcelable {
     out.writeParcelable(latLngBounds, flags);
   }
 
+  /**
+   * Inner class responsible for recreating Parcels into objects.
+   */
   public static final Parcelable.Creator<VisibleRegion> CREATOR =
     new Parcelable.Creator<VisibleRegion>() {
       public VisibleRegion createFromParcel(Parcel in) {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java

@@ -28,12 +28,16 @@ import com.mapzen.android.lost.api.LostApiClient;
  * in the history stack.
  * </p>
  */
-public class LocationSource extends LocationEngine implements
-  LostApiClient.ConnectionCallbacks, LocationListener {
+public class LocationSource extends LocationEngine implements LostApiClient.ConnectionCallbacks, LocationListener {
 
   private Context context;
   private LostApiClient lostApiClient;
 
+  /**
+   * Constructs a location source instance.
+   *
+   * @param context the context from which the Application context will be derived.
+   */
   public LocationSource(Context context) {
     super();
     this.context = context.getApplicationContext();

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java

@@ -1,7 +1,5 @@
 package com.mapbox.mapboxsdk.maps;
 
-import android.app.Activity;
-import android.app.Fragment;
 import android.content.Context;
 import android.graphics.Canvas;
 import android.graphics.PointF;
@@ -27,7 +25,6 @@ import android.widget.FrameLayout;
 import android.widget.ImageView;
 import android.widget.ZoomButtonsController;
 
-import com.mapbox.mapboxsdk.Mapbox;
 import com.mapbox.mapboxsdk.R;
 import com.mapbox.mapboxsdk.annotations.MarkerViewManager;
 import com.mapbox.mapboxsdk.constants.MapboxConstants;
@@ -178,14 +175,14 @@ public class MapView extends FrameLayout {
 
   /**
    * <p>
-   * You must call this method from the parent's {@link android.app.Activity#onCreate(Bundle)} or
-   * {@link android.app.Fragment#onCreate(Bundle)}.
+   * You must call this method from the parent's Activity#onCreate(Bundle)} or
+   * Fragment#onCreate(Bundle).
    * </p>
-   * You must set a valid access token with {@link Mapbox#getInstance(Context, String)}) before you call this method
-   * or an exception will be thrown.
+   * You must set a valid access token with {@link com.mapbox.mapboxsdk.Mapbox#getInstance(Context, String)}
+   * before you call this method or an exception will be thrown.
    *
    * @param savedInstanceState Pass in the parent's savedInstanceState.
-   * @see Mapbox#getInstance(Context, String)
+   * @see com.mapbox.mapboxsdk.Mapbox#getInstance(Context, String)
    */
   @UiThread
   public void onCreate(@Nullable Bundle savedInstanceState) {
@@ -214,12 +211,11 @@ public class MapView extends FrameLayout {
   }
 
   /**
-   * You must call this method from the parent's {@link android.app.Activity#onSaveInstanceState(Bundle)}
-   * or {@link android.app.Fragment#onSaveInstanceState(Bundle)}.
+   * You must call this method from the parent's Activity#onSaveInstanceState(Bundle)
+   * or Fragment#onSaveInstanceState(Bundle).
    *
    * @param outState Pass in the parent's outState.
    */
-
   @UiThread
   public void onSaveInstanceState(@NonNull Bundle outState) {
     outState.putBoolean(MapboxConstants.STATE_HAS_SAVED_STATE, true);
@@ -227,7 +223,7 @@ public class MapView extends FrameLayout {
   }
 
   /**
-   * You must call this method from the parent's {@link Activity#onStart()} or {@link Fragment#onStart()}
+   * You must call this method from the parent's Activity#onStart() or Fragment#onStart()
    */
   @UiThread
   public void onStart() {
@@ -236,7 +232,7 @@ public class MapView extends FrameLayout {
   }
 
   /**
-   * You must call this method from the parent's {@link Activity#onResume()} or {@link Fragment#onResume()}.
+   * You must call this method from the parent's Activity#onResume() or Fragment#onResume().
    */
   @UiThread
   public void onResume() {
@@ -244,7 +240,7 @@ public class MapView extends FrameLayout {
   }
 
   /**
-   * You must call this method from the parent's {@link Activity#onPause()} or {@link Fragment#onPause()}.
+   * You must call this method from the parent's Activity#onPause() or Fragment#onPause().
    */
   @UiThread
   public void onPause() {
@@ -252,7 +248,7 @@ public class MapView extends FrameLayout {
   }
 
   /**
-   * You must call this method from the parent's {@link Activity#onStop()} or {@link Fragment#onStop()}.
+   * You must call this method from the parent's Activity#onStop() or Fragment#onStop().
    */
   @UiThread
   public void onStop() {
@@ -261,7 +257,7 @@ public class MapView extends FrameLayout {
   }
 
   /**
-   * You must call this method from the parent's {@link Activity#onDestroy()} or {@link Fragment#onDestroy()}.
+   * You must call this method from the parent's Activity#onDestroy() or Fragment#onDestroy().
    */
   @UiThread
   public void onDestroy() {
@@ -325,7 +321,7 @@ public class MapView extends FrameLayout {
   }
 
   /**
-   * You must call this method from the parent's {@link Activity#onLowMemory()} or {@link Fragment#onLowMemory()}.
+   * You must call this method from the parent's Activity#onLowMemory() or Fragment#onLowMemory().
    */
   @UiThread
   public void onLowMemory() {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java

@@ -736,8 +736,8 @@ public final class MapboxMap {
    * will return the current location of the camera in flight.
    * <p>
    * Note that this will cancel location tracking mode if enabled. You can change this behaviour by calling
-   * {@link TrackingSettings#setDismissTrackingModeForCameraPositionChange(boolean)} with false before invoking this
-   * method and calling it with true in the {@link CancelableCallback#onFinish()}.
+   * {@link com.mapbox.mapboxsdk.maps.TrackingSettings#setDismissLocationTrackingOnGesture(boolean)} with false before
+   * invoking this method and calling it with true in the {@link CancelableCallback#onFinish()}.
    * </p>
    *
    * @param update             The change that should be applied to the camera.
@@ -763,8 +763,8 @@ public final class MapboxMap {
    * will return the current location of the camera in flight.
    * <p>
    * Note that this will cancel location tracking mode if enabled. You can change this behaviour by calling
-   * {@link TrackingSettings#setDismissTrackingModeForCameraPositionChange(boolean)} with false before invoking this
-   * method and calling it with true in the {@link CancelableCallback#onFinish()}.
+   * {@link com.mapbox.mapboxsdk.maps.TrackingSettings#setDismissLocationTrackingOnGesture(boolean)} with false before
+   * invoking this method and calling it with true in the {@link CancelableCallback#onFinish()}.
    * </p>
    *
    * @param update             The change that should be applied to the camera.
@@ -887,7 +887,12 @@ public final class MapboxMap {
   }
 
   /**
-   * Set focal bearing.
+   * Transform the map bearing given a bearing, focal point coordinates, and a duration.
+   *
+   * @param bearing  The bearing of the Map to be transformed to
+   * @param focalX   The x coordinate of the focal point
+   * @param focalY   The y coordinate of the focal point
+   * @param duration The duration of the transformation
    */
   public void setFocalBearing(double bearing, float focalX, float focalY, long duration) {
     transform.setBearing(bearing, focalX, focalY, duration);
@@ -1059,7 +1064,7 @@ public final class MapboxMap {
    * An error message will be logged in the Android logcat and {@link MapView#DID_FAIL_LOADING_MAP} event will be
    * sent.
    *
-   * @param style The bundled style. Accepts one of the values from {@link Style}.
+   * @param style The bundled style.
    * @see Style
    */
   @UiThread
@@ -1075,7 +1080,8 @@ public final class MapboxMap {
    * An error message will be logged in the Android logcat and {@link MapView#DID_FAIL_LOADING_MAP} event will be
    * sent.
    *
-   * @param style The bundled style. Accepts one of the values from {@link Style}.
+   * @param style    The bundled style.
+   * @param callback The callback to be invoked when the style has finished loading
    * @see Style
    */
   @UiThread
@@ -1576,9 +1582,11 @@ public final class MapboxMap {
   }
 
   /**
-   * Gets a camera position that would fit a bounds.
+   * Get a camera position that fits a provided bounds and padding.
    *
    * @param latLngBounds the bounds to constrain the map with
+   * @param padding      the padding to apply to the bounds
+   * @return the camera position that fits the bounds and padding
    */
   public CameraPosition getCameraForLatLngBounds(@Nullable LatLngBounds latLngBounds, int[] padding) {
     // calculate and set additional bounds padding
@@ -2410,11 +2418,13 @@ public final class MapboxMap {
   }
 
   /**
-   * Interface definintion for a callback to be invoked when the style has finished loading.
+   * Interface definition for a callback to be invoked when the style has finished loading.
    */
   public interface OnStyleLoadedListener {
     /**
-     * Invoked when the style has finished loading.
+     * Invoked when the style has finished loading
+     *
+     * @param style the style that has been loaded
      */
     void onStyleLoaded(String style);
   }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMapOptions.java

@@ -378,7 +378,7 @@ public class MapboxMapOptions implements Parcelable {
   /**
    * Specifies the gravity state of mapbox_compass_icon for a map view.
    *
-   * @param gravity see {@link android.view.Gravity}
+   * @param gravity Android SDK Gravity.
    * @return This
    */
   public MapboxMapOptions compassGravity(int gravity) {
@@ -439,7 +439,7 @@ public class MapboxMapOptions implements Parcelable {
   /**
    * Specifies the gravity state of logo for a map view.
    *
-   * @param gravity see {@link android.view.Gravity}
+   * @param gravity Android SDK Gravity.
    * @return This
    */
   public MapboxMapOptions logoGravity(int gravity) {
@@ -472,7 +472,7 @@ public class MapboxMapOptions implements Parcelable {
   /**
    * Specifies the gravity state of attribution for a map view.
    *
-   * @param gravity see {@link android.view.Gravity}
+   * @param gravity Android SDK Gravity.
    * @return This
    */
   public MapboxMapOptions attributionGravity(int gravity) {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java

@@ -16,7 +16,6 @@ import android.support.annotation.Nullable;
 import android.support.annotation.UiThread;
 import android.support.v4.content.ContextCompat;
 import android.support.v4.content.res.ResourcesCompat;
-import android.view.Gravity;
 import android.view.View;
 import android.widget.FrameLayout;
 import android.widget.ImageView;
@@ -196,7 +195,7 @@ public final class UiSettings {
     setLogoMargins(resources, options.getLogoMargins());
   }
 
-  private void setLogoMargins(Resources resources, int[]logoMargins) {
+  private void setLogoMargins(Resources resources, int[] logoMargins) {
     if (logoMargins != null) {
       setLogoMargins(logoMargins[0], logoMargins[1], logoMargins[2], logoMargins[3]);
     } else {
@@ -309,8 +308,7 @@ public final class UiSettings {
    * </p>
    * By default, the compass is in the top right corner.
    *
-   * @param gravity One of the values from {@link Gravity}.
-   * @see Gravity
+   * @param gravity Android SDK Gravity.
    */
   @UiThread
   public void setCompassGravity(int gravity) {
@@ -454,8 +452,7 @@ public final class UiSettings {
    * </p>
    * By default, the logo is in the bottom left corner.
    *
-   * @param gravity One of the values from {@link Gravity}.
-   * @see Gravity
+   * @param gravity Android SDK Gravity.
    */
   public void setLogoGravity(int gravity) {
     setWidgetGravity(logoView, gravity);
@@ -546,8 +543,7 @@ public final class UiSettings {
    * </p>
    * By default, the attribution is in the bottom left corner next to the Mapbox logo.
    *
-   * @param gravity One of the values from {@link Gravity}.
-   * @see Gravity
+   * @param gravity Android SDK Gravity.
    */
   public void setAttributionGravity(int gravity) {
     setWidgetGravity(attributionsView, gravity);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationView.java

@@ -45,6 +45,9 @@ import timber.log.Timber;
 
 /**
  * UI element overlaid on a map to show the user's location.
+ * <p>
+ * Use {@link MyLocationViewSettings} to manipulate the state of this view.
+ * </p>
  */
 public class MyLocationView extends View {
 
@@ -155,6 +158,12 @@ public class MyLocationView extends View {
     this.locationSource = locationSource;
   }
 
+  /**
+   * Set the foreground drawable, for internal use only.
+   *
+   * @param defaultDrawable The drawable shown when showing this view
+   * @param bearingDrawable The drawable shown when tracking of bearing is enabled
+   */
   public final void setForegroundDrawables(Drawable defaultDrawable, Drawable bearingDrawable) {
     if (defaultDrawable == null) {
       return;
@@ -183,6 +192,11 @@ public class MyLocationView extends View {
     invalidateBounds();
   }
 
+  /**
+   * Set the foreground drawable tint, for internal use only.
+   *
+   * @param color The color to tint the drawable with
+   */
   public final void setForegroundDrawableTint(@ColorInt int color) {
     if (foregroundDrawable != null) {
       foregroundDrawable.mutate().setColorFilter(color, PorterDuff.Mode.SRC_IN);
@@ -193,10 +207,24 @@ public class MyLocationView extends View {
     invalidate();
   }
 
+  /**
+   * Set the shadow drawable, for internal use only.
+   *
+   * @param drawable The drawable shown as shadow
+   */
   public final void setShadowDrawable(Drawable drawable) {
     setShadowDrawable(drawable, 0, 0, 0, 0);
   }
 
+  /**
+   * Set the shadow drawable with some additional offset.
+   *
+   * @param drawable The drawable shown as shadow
+   * @param left     The left offset margin
+   * @param top      The top offset margin
+   * @param right    The right offset margin
+   * @param bottom   The bottom offset margin
+   */
   public final void setShadowDrawable(Drawable drawable, int left, int top, int right, int bottom) {
     if (drawable != null) {
       backgroundDrawable = drawable;
@@ -210,6 +238,11 @@ public class MyLocationView extends View {
     invalidateBounds();
   }
 
+  /**
+   * Set the shadow drawable tint color, for internal use only.
+   *
+   * @param color The tint color to apply
+   */
   public final void setShadowDrawableTint(@ColorInt int color) {
     if (backgroundDrawable == null) {
       return;
@@ -218,6 +251,11 @@ public class MyLocationView extends View {
     invalidate();
   }
 
+  /**
+   * Set the accuracy tint color, for internal use only.
+   *
+   * @param color The tint color to apply
+   */
   public final void setAccuracyTint(@ColorInt int color) {
     int alpha = accuracyPaint.getAlpha();
     accuracyPaint.setColor(color);
@@ -225,6 +263,11 @@ public class MyLocationView extends View {
     invalidate();
   }
 
+  /**
+   * Set the accuracy alpha value, for internal use only.
+   *
+   * @param alpha The alpha accuracy value to apply
+   */
   public final void setAccuracyAlpha(@IntRange(from = 0, to = 255) int alpha) {
     accuracyPaint.setAlpha(alpha);
     invalidate();
@@ -314,6 +357,11 @@ public class MyLocationView extends View {
     }
   }
 
+  /**
+   * Set the tilt value, for internal use only.
+   *
+   * @param tilt The tilt to apply
+   */
   public void setTilt(@FloatRange(from = 0, to = 60.0f) double tilt) {
     this.tilt = tilt;
     if (myLocationTrackingMode == MyLocationTracking.TRACKING_FOLLOW) {
@@ -322,6 +370,11 @@ public class MyLocationView extends View {
     invalidate();
   }
 
+  /**
+   * Set the bearing value, for internal use only.
+   *
+   * @param bearing The bearing to apply
+   */
   public void setBearing(double bearing) {
     this.bearing = bearing;
     if (myLocationTrackingMode == MyLocationTracking.TRACKING_NONE) {
@@ -335,6 +388,11 @@ public class MyLocationView extends View {
     }
   }
 
+  /**
+   * Set the bearing and tilt from a camera position, for internal use only.
+   *
+   * @param position The camera position to extract bearing and tilt from
+   */
   public void setCameraPosition(CameraPosition position) {
     if (position != null) {
       setBearing(position.bearing);
@@ -342,6 +400,9 @@ public class MyLocationView extends View {
     }
   }
 
+  /**
+   * Called when the hosting activity is starting, for internal use only.
+   */
   public void onStart() {
     if (myBearingTrackingMode == MyBearingTracking.COMPASS && compassListener.isSensorAvailable()) {
       compassListener.onResume();
@@ -351,6 +412,9 @@ public class MyLocationView extends View {
     }
   }
 
+  /**
+   * Called when the hosting activity is stopping, for internal use only.
+   */
   public void onStop() {
     compassListener.onPause();
     toggleGps(false);
@@ -382,6 +446,9 @@ public class MyLocationView extends View {
     }
   }
 
+  /**
+   * Update current locationstate.
+   */
   public void update() {
     if (isEnabled()) {
       myLocationBehavior.invalidate();
@@ -396,17 +463,33 @@ public class MyLocationView extends View {
     this.projection = mapboxMap.getProjection();
   }
 
+  /**
+   * Set the enabled state, for internal use only.
+   *
+   * @param enabled The value to set the state to
+   */
   @Override
   public void setEnabled(boolean enabled) {
     setEnabled(enabled, false);
   }
 
+  /**
+   * Set the enabled state, for internal use only.
+   *
+   * @param enabled                The value to set the state to
+   * @param isCustomLocationSource Flag handling for handling user provided custom location source
+   */
   public void setEnabled(boolean enabled, boolean isCustomLocationSource) {
     super.setEnabled(enabled);
     setVisibility(enabled ? View.VISIBLE : View.INVISIBLE);
     toggleGps(enabled, isCustomLocationSource);
   }
 
+  /**
+   * Save the view instance state, for internal use only.
+   *
+   * @return the marshaled representation of the view state
+   */
   @Override
   protected Parcelable onSaveInstanceState() {
     Bundle bundle = new Bundle();
@@ -415,6 +498,11 @@ public class MyLocationView extends View {
     return bundle;
   }
 
+  /**
+   * Restore the view instance state, for internal use only.
+   *
+   * @param state the marshalled representation of the state to restore
+   */
   @Override
   public void onRestoreInstanceState(Parcelable state) {
     if (state instanceof Bundle) {
@@ -430,7 +518,7 @@ public class MyLocationView extends View {
   }
 
   /**
-   * Enabled / Disable GPS location updates along with updating the UI
+   * Enabled / Disable GPS location updates along with updating the UI, for internal use only.
    *
    * @param enableGps true if GPS is to be enabled, false if GPS is to be disabled
    */
@@ -463,10 +551,20 @@ public class MyLocationView extends View {
     }
   }
 
+  /**
+   * Get the current location.
+   *
+   * @return the current location
+   */
   public Location getLocation() {
     return location;
   }
 
+  /**
+   * Set the current location, for internal use only.
+   *
+   * @param location The current location
+   */
   public void setLocation(Location location) {
     if (location == null) {
       this.location = null;
@@ -482,10 +580,20 @@ public class MyLocationView extends View {
     }
   }
 
+  /**
+   * Set location change animation enabled, for internal use only.
+   *
+   * @param locationChangeAnimationEnabled True if location changes are animated
+   */
   public void setLocationChangeAnimationEnabled(boolean locationChangeAnimationEnabled) {
     this.locationChangeAnimationEnabled = locationChangeAnimationEnabled;
   }
 
+  /**
+   * Set the bearing tracking mode, for internal use only.
+   *
+   * @param myBearingTrackingMode The bearing tracking mode
+   */
   public void setMyBearingTrackingMode(@MyBearingTracking.Mode int myBearingTrackingMode) {
     this.myBearingTrackingMode = myBearingTrackingMode;
     if (myBearingTrackingMode == MyBearingTracking.COMPASS && compassListener.isSensorAvailable()) {
@@ -502,6 +610,11 @@ public class MyLocationView extends View {
     invalidate();
   }
 
+  /**
+   * Set the location tracking mode, for internla use only.
+   *
+   * @param myLocationTrackingMode The location tracking mode
+   */
   public void setMyLocationTrackingMode(@MyLocationTracking.Mode int myLocationTrackingMode) {
     MyLocationBehaviorFactory factory = new MyLocationBehaviorFactory();
     myLocationBehavior = factory.getBehavioralModel(myLocationTrackingMode);
@@ -522,17 +635,32 @@ public class MyLocationView extends View {
     invalidate();
   }
 
+  /**
+   * Get the location tracking mode, for internal use only.
+   *
+   * @return The location tracking mode
+   */
   @MyLocationTracking.Mode
   public int getMyLocationTrackingMode() {
     return myLocationTrackingMode;
   }
 
 
+  /**
+   * Get the bearing tracking mode, for internal use only.
+   *
+   * @return the bearing tracking mode
+   */
   @MyBearingTracking.Mode
   public int getMyBearingTrackingMode() {
     return myBearingTrackingMode;
   }
 
+  /**
+   * Set the compass bearing value, for internal use only.
+   *
+   * @param bearing The compas bearing value
+   */
   private void setCompass(double bearing) {
     setCompass(bearing, 0 /* no animation */);
   }
@@ -560,14 +688,29 @@ public class MyLocationView extends View {
     directionAnimator.start();
   }
 
+  /**
+   * Get the center of this view in screen coordinates.
+   *
+   * @return the center of the view
+   */
   public PointF getCenter() {
     return new PointF(getCenterX(), getCenterY());
   }
 
+  /**
+   * Get the x value of the center of this view.
+   *
+   * @return the x value of the center of the view
+   */
   private float getCenterX() {
     return (getX() + getMeasuredWidth()) / 2 + contentPaddingX - projectedX;
   }
 
+  /**
+   * Get the y value of the center of this view.
+   *
+   * @return the y value of the center of the view
+   */
   private float getCenterY() {
     return (getY() + getMeasuredHeight()) / 2 + contentPaddingY - projectedY;
   }
@@ -577,6 +720,11 @@ public class MyLocationView extends View {
     contentPaddingY = (padding[1] - padding[3]) / 2;
   }
 
+  /**
+   * Set the location source from which location updates are received, for internal use only.
+   *
+   * @param locationSource The location source to receive updates from
+   */
   public void setLocationSource(LocationEngine locationSource) {
     toggleGps(false);
     this.locationSource = locationSource;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationViewSettings.java

@@ -5,9 +5,9 @@ import android.support.annotation.ColorInt;
 import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 
+import com.mapbox.mapboxsdk.camera.CameraPosition;
 import com.mapbox.mapboxsdk.constants.MyLocationTracking;
 import com.mapbox.mapboxsdk.maps.FocalPointChangeListener;
-import com.mapbox.mapboxsdk.camera.CameraPosition;
 import com.mapbox.mapboxsdk.maps.MapboxMapOptions;
 import com.mapbox.mapboxsdk.maps.Projection;
 
@@ -77,6 +77,11 @@ public class MyLocationViewSettings {
     this.focalPointChangeListener = focalPointChangedListener;
   }
 
+  /**
+   * Initialise this with MapboxMapOptions.
+   *
+   * @param options the options to initialise this class from
+   */
   public void initialise(@NonNull MapboxMapOptions options) {
     CameraPosition position = options.getCamera();
     if (position != null && !position.equals(CameraPosition.DEFAULT)) {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/net/ConnectivityReceiver.java

@@ -24,7 +24,10 @@ public class ConnectivityReceiver extends BroadcastReceiver {
   private static ConnectivityReceiver INSTANCE;
 
   /**
-   * Get or create the singleton instance
+   * Get a single instance of ConnectivityReceiver.
+   *
+   * @param context the context to extract the application context from
+   * @return single instance of ConnectivityReceiver
    */
   public static synchronized ConnectivityReceiver instance(Context context) {
     if (INSTANCE == null) {
@@ -74,7 +77,7 @@ public class ConnectivityReceiver extends BroadcastReceiver {
   }
 
   /**
-   * @see BroadcastReceiver#onReceive(Context, Intent)
+   * {@inheritDoc}
    */
   @Override
   public void onReceive(Context context, Intent intent) {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java

@@ -115,6 +115,12 @@ public class OfflineManager {
     }).start();
   }
 
+  /**
+   * Get the single instance of offline manager.
+   *
+   * @param context the context used to host the offline manager
+   * @return the single instance of offline manager
+   */
   public static synchronized OfflineManager getInstance(Context context) {
     if (instance == null) {
       instance = new OfflineManager(context);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegion.java

@@ -393,6 +393,7 @@ public class OfflineRegion {
    * After you call this method, you may not call any additional methods on this object.
    * </p>
    *
+   * @param bytes    the metadata in bytes
    * @param callback the callback to be invoked
    */
   public void updateMetadata(@NonNull final byte[] bytes, @NonNull final OfflineRegionUpdateMetadataCallback callback) {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegionStatus.java

@@ -7,6 +7,7 @@ package com.mapbox.mapboxsdk.offline;
  * <p>
  * Note that the total required size in bytes is not currently available. A
  * future API release may provide an estimate of this number.
+ * </p>
  */
 public class OfflineRegionStatus {
 
@@ -51,6 +52,7 @@ public class OfflineRegionStatus {
    * Specifically, it is false during early phases of an offline download. Once
    * style and tile sources have been downloaded, it is possible to calculate the
    * precise number of required resources, at which point it is set to true.
+   * </p>
    */
   private boolean requiredResourceCountIsPrecise = true;
 
@@ -73,37 +75,93 @@ public class OfflineRegionStatus {
   }
 
   /**
-   * Is the region complete?
+   * Validates if the region download has completed
+   *
+   * @return true if download is complete, false if not
    */
   public boolean isComplete() {
     return (completedResourceCount == requiredResourceCount);
   }
 
+  /**
+   * Returns the download state.
+   * <p>
+   * State is defined as
+   * </p>
+   * <ul>
+   * <li>{@link OfflineRegion#STATE_ACTIVE}</li>
+   * <li>{@link OfflineRegion#STATE_INACTIVE}</li>
+   * </ul>
+   *
+   * @return the download state.
+   */
   @OfflineRegion.DownloadState
   public int getDownloadState() {
     return downloadState;
   }
 
+  /**
+   * Get the number of resources (inclusive of tiles) that have been fully downloaded
+   * and are ready for offline access.
+   *
+   * @return the amount of resources that have finished downloading.
+   */
   public long getCompletedResourceCount() {
     return completedResourceCount;
   }
 
+  /**
+   * The cumulative size, in bytes, of all resources (inclusive of tiles) that have
+   * been fully downloaded.
+   *
+   * @return the size of the resources that have finished downloading
+   */
   public long getCompletedResourceSize() {
     return completedResourceSize;
   }
 
+  /**
+   * Get the number of tiles that have been fully downloaded and are ready for
+   * offline access.
+   *
+   * @return the completed tile count
+   */
   public long getCompletedTileCount() {
     return completedTileCount;
   }
 
+  /**
+   * Get the cumulative size, in bytes, of all tiles that have been fully downloaded.
+   *
+   * @return the completed tile size
+   */
   public long getCompletedTileSize() {
     return completedTileSize;
   }
 
+  /**
+   * Get the number of resources that are known to be required for this region. See the
+   * documentation for `requiredResourceCountIsPrecise` for an important caveat
+   * about this number.
+   *
+   * @return the amount of resources that are required
+   */
   public long getRequiredResourceCount() {
     return requiredResourceCount;
   }
 
+  /**
+   * Returns when the value of requiredResourceCount is a precise
+   * count of the number of required resources, and false when it is merely a lower
+   * bound.
+   * <p>
+   * Specifically, it is false during early phases of an offline download. Once
+   * style and tile sources have been downloaded, it is possible to calculate the
+   * precise number of required resources, at which point it is set to true.
+   * </p>
+   *
+   * @return True if the required resource count is precise, false if not
+   */
   public boolean isRequiredResourceCountPrecise() {
     return requiredResourceCountIsPrecise;
   }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/FileSource.java

@@ -3,9 +3,9 @@ package com.mapbox.mapboxsdk.storage;
 import android.content.Context;
 import android.content.pm.ApplicationInfo;
 import android.content.pm.PackageManager;
+import android.content.res.AssetManager;
 import android.os.Environment;
 import android.support.annotation.NonNull;
-import android.content.res.AssetManager;
 
 import com.mapbox.mapboxsdk.Mapbox;
 import com.mapbox.mapboxsdk.constants.MapboxConstants;
@@ -28,8 +28,9 @@ public class FileSource {
     /**
      * Called whenever a URL needs to be transformed.
      *
-     * @param kind The kind of URL to be transformed.
-     * @return A URL that will now be downloaded.
+     * @param kind the kind of URL to be transformed.
+     * @param url  the  URL to be transformed
+     * @return a URL that will now be downloaded.
      */
     String onURL(@Resource.Kind int kind, String url);
 
@@ -38,6 +39,12 @@ public class FileSource {
   // File source instance is kept alive after initialization
   private static FileSource INSTANCE;
 
+  /**
+   * Get the single instance of FileSource.
+   *
+   * @param context the context to derive the cache path from
+   * @return the single instance of FileSource
+   */
   public static synchronized FileSource getInstance(Context context) {
     if (INSTANCE == null) {
       String cachePath = getCachePath(context);
@@ -47,6 +54,12 @@ public class FileSource {
     return INSTANCE;
   }
 
+  /**
+   * Get the cache path for a context.
+   *
+   * @param context the context to derive the cache path from
+   * @return the cache path
+   */
   public static String getCachePath(Context context) {
     // Default value
     boolean setStorageExternal = MapboxConstants.DEFAULT_SET_STORAGE_EXTERNAL;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/PropertyValue.java

@@ -30,14 +30,29 @@ public class PropertyValue<T> {
     this.value = value;
   }
 
+  /**
+   * Returns if this is null
+   *
+   * @return true if this is null, false if not
+   */
   public boolean isNull() {
     return value == null;
   }
 
+  /**
+   * Returns if this is a function.
+   *
+   * @return true if is a function, false if not
+   */
   public boolean isFunction() {
     return !isNull() && value instanceof Function;
   }
 
+  /**
+   * Returns if this is a value.
+   *
+   * @return true if is a value, false if not
+   */
   public boolean isValue() {
     return !isNull() && !isFunction();
   }
@@ -53,6 +68,11 @@ public class PropertyValue<T> {
     }
   }
 
+  /**
+   * Get the value of the property.
+   *
+   * @return the property value
+   */
   @Nullable
   public T getValue() {
     if (isValue()) {
@@ -64,6 +84,11 @@ public class PropertyValue<T> {
     }
   }
 
+  /**
+   * Get the color int value of the property if the value is a color.
+   *
+   * @return the color int value of the property, null if not a color value
+   */
   @ColorInt
   @Nullable
   public Integer getColorInt() {
@@ -80,6 +105,11 @@ public class PropertyValue<T> {
     }
   }
 
+  /**
+   * Get the string representation of a property value.
+   *
+   * @return the string representation
+   */
   @Override
   public String toString() {
     return String.format("%s: %s", name, value);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Light.java

@@ -13,7 +13,7 @@ import com.mapbox.mapboxsdk.style.layers.TransitionOptions;
 /**
  * The global light source.
  *
- * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#light>">The online documentation</a>
+ * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#light">The online documentation</a>
  */
 @UiThread
 public class Light {
@@ -43,7 +43,8 @@ public class Light {
    *
    * @return anchor as String
    */
-  @Property.ANCHOR public String getAnchor() {
+  @Property.ANCHOR
+  public String getAnchor() {
     return nativeGetAnchor();
   }
 
@@ -106,7 +107,7 @@ public class Light {
    *
    * @return color as String
    */
-   public String getColor() {
+  public String getColor() {
     return nativeGetColor();
   }
 
@@ -142,7 +143,7 @@ public class Light {
    *
    * @return intensity as Float
    */
-   public float getIntensity() {
+  public float getIntensity() {
     return nativeGetIntensity();
   }
 
@@ -165,17 +166,30 @@ public class Light {
   }
 
   private native void nativeSetAnchor(String anchor);
+
   private native String nativeGetAnchor();
+
   private native void nativeSetPosition(Position position);
+
   private native Position nativeGetPosition();
+
   private native TransitionOptions nativeGetPositionTransition();
+
   private native void nativeSetPositionTransition(long duration, long delay);
+
   private native void nativeSetColor(String color);
+
   private native String nativeGetColor();
+
   private native TransitionOptions nativeGetColorTransition();
+
   private native void nativeSetColorTransition(long duration, long delay);
+
   private native void nativeSetIntensity(float intensity);
+
   private native float nativeGetIntensity();
+
   private native TransitionOptions nativeGetIntensityTransition();
+
   private native void nativeSetIntensityTransition(long duration, long delay);
 }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Position.java

@@ -18,7 +18,7 @@ public class Position {
   private float polarAngle;
 
   /**
-   * Creates a Position from a radial coordinate, an azimuthal angle & a polar angle.
+   * Creates a Position from a radial coordinate, an azimuthal angle and a polar angle.
    *
    * @param radialCoordinate the distance from the center of the base of an object to its light
    * @param azimuthalAngle the position of the light relative to 0°
@@ -31,7 +31,7 @@ public class Position {
   }
 
   /**
-   * Returns a Position from a radial coordinate, an azimuthal angle & a polar angle
+   * Returns a Position from a radial coordinate, an azimuthal angle and a polar angle
    *
    * @param radialCoordinate the radial coordinate
    * @param azimuthalAngle the azimuthal angle

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/light.java.ejs

@@ -17,7 +17,7 @@ import com.mapbox.mapboxsdk.style.layers.TransitionOptions;
 /**
  * The global light source.
  *
- * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#light>">The online documentation</a>
+ * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#light">The online documentation</a>
  */
 @UiThread
 public class Light {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/BitmapUtils.java

@@ -5,8 +5,17 @@ import android.graphics.Canvas;
 import android.support.annotation.NonNull;
 import android.view.View;
 
+/**
+ * Utility class for creating bitmaps
+ */
 public class BitmapUtils {
 
+  /**
+   * Convert a view to a bitmap.
+   *
+   * @param view the view to convert
+   * @return the converted bitmap
+   */
   public static Bitmap createBitmapFromView(@NonNull View view) {
     view.setDrawingCacheEnabled(true);
     view.setDrawingCacheQuality(View.DRAWING_CACHE_QUALITY_LOW);
@@ -22,6 +31,13 @@ public class BitmapUtils {
     return snapshot;
   }
 
+  /**
+   * Create a bitmap from a background and a foreground bitmap
+   *
+   * @param background The bitmap placed in the background
+   * @param foreground The bitmap placed in the foreground
+   * @return the merged bitmap
+   */
   public static Bitmap mergeBitmap(@NonNull Bitmap background, @NonNull Bitmap foreground) {
     Bitmap result = Bitmap.createBitmap(background.getWidth(), background.getHeight(), background.getConfig());
     Canvas canvas = new Canvas(result);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ColorUtils.java

@@ -23,7 +23,7 @@ import java.util.regex.Pattern;
 public class ColorUtils {
 
   /**
-   * Returns a color integer associated as primary color from a theme based on a {@link Context}.
+   * Returns a color integer associated as primary color from a theme based on a Context.
    *
    * @param context The context used to style the color attributes.
    * @return The primary color value of current theme in the form 0xAARRGGBB.
@@ -37,7 +37,7 @@ public class ColorUtils {
   }
 
   /**
-   * Returns a color integer associated as primary dark color from a theme based on a {@link Context}.
+   * Returns a color integer associated as primary dark color from a theme based on a Context.
    *
    * @param context The context used to style the color attributes.
    * @return The primary dark color value of current theme in the form 0xAARRGGBB.
@@ -51,7 +51,7 @@ public class ColorUtils {
   }
 
   /**
-   * Returns a color integer associated as accent color from a theme based on a {@link Context}.
+   * Returns a color integer associated as accent color from a theme based on a Context.
    *
    * @param context The context used to style the color attributes.
    * @return The accent color value of current theme in the form 0xAARRGGBB.
@@ -65,7 +65,7 @@ public class ColorUtils {
   }
 
   /**
-   * Returns a color state list associated with a theme based on a {@link Context}
+   * Returns a color state list associated with a theme based on a Context.
    *
    * @param color The color used for tinting.
    * @return A ColorStateList object containing the primary color of a theme
@@ -85,7 +85,7 @@ public class ColorUtils {
   }
 
   /**
-   * Set a color tint list to the {@link Drawable} of an {@link ImageView}.
+   * Set a color tint list to the Drawable of an ImageView.
    *
    * @param imageView The view to set the default tint list.
    * @param tintColor The color to tint.

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/MapFragmentUtils.java

@@ -18,12 +18,25 @@ import com.mapbox.mapboxsdk.maps.MapboxMapOptions;
  */
 public class MapFragmentUtils {
 
+  /**
+   * Convert MapboxMapOptions to a bundle of fragment arguments.
+   *
+   * @param options The MapboxMapOptions to convert
+   * @return a bundle of converted fragment arguments
+   */
   public static Bundle createFragmentArgs(MapboxMapOptions options) {
     Bundle bundle = new Bundle();
     bundle.putParcelable(MapboxConstants.FRAG_ARG_MAPBOXMAPOPTIONS, options);
     return bundle;
   }
 
+  /**
+   * Convert a bundle of fragment arguments to MapboxMapOptions.
+   *
+   * @param context The context of the activity hosting the fragment
+   * @param args    The fragment arguments
+   * @return converted MapboxMapOptions
+   */
   public static MapboxMapOptions resolveArgs(Context context, Bundle args) {
     MapboxMapOptions options;
     if (args != null && args.containsKey(MapboxConstants.FRAG_ARG_MAPBOXMAPOPTIONS)) {