1 files changed, 104 insertions, 12 deletions
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java
index ca2d3673b2..eb57241196 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java
+++ b/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);