Merge branch 'master' into ls-android-readme-tweaksupstream/ls-android-readme-tweaks

1 files changed, 135 insertions, 18 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..79023e2fd9 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,9 +3,10 @@ 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.mapboxsdk.constants.GeometryConstants;
 
-import com.mapbox.services.android.telemetry.constants.GeoConstants;
-import com.mapbox.services.android.telemetry.utils.MathUtils;
 
 /**
  * A geographical location which contains a single latitude, longitude pair, with
@@ -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,38 +81,78 @@ 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 [-90, 90], see {@link GeometryConstants#MIN_LATITUDE} and
+   * {@link GeometryConstants#MAX_LATITUDE}
+   * </p>
+   *
+   * @param latitude the latitude value in degrees
+   * @see GeometryConstants#MIN_LATITUDE
+   * @see GeometryConstants#MAX_LATITUDE
+   */
+  public void setLatitude(
+    @FloatRange(from = GeometryConstants.MIN_LATITUDE, to = GeometryConstants.MAX_LATITUDE) double latitude) {
     if (Double.isNaN(latitude)) {
       throw new IllegalArgumentException("latitude must not be NaN");
     }
-    if (Math.abs(latitude) > 90.0) {
+    if (Math.abs(latitude) > GeometryConstants.MAX_LATITUDE) {
       throw new IllegalArgumentException("latitude must be between -90 and 90");
     }
     this.latitude = latitude;
   }
 
+  /**
+   * Get the latitude, in degrees.
+   * <p>
+   * This value is in the range of [-90, 90], see {@link GeometryConstants#MIN_LATITUDE} and
+   * {@link GeometryConstants#MAX_LATITUDE}
+   * </p>
+   *
+   * @return the latitude value in degrees
+   * @see GeometryConstants#MIN_LATITUDE
+   * @see GeometryConstants#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 GeometryConstants#MIN_LONGITUDE} and
+   * {@link GeometryConstants#MAX_LONGITUDE}
+   * </p>
+   *
+   * @param longitude the longitude value in degrees
+   * @see GeometryConstants#MIN_LONGITUDE
+   * @see GeometryConstants#MAX_LONGITUDE
+   */
+  public void setLongitude(@FloatRange(from = GeometryConstants.MIN_LONGITUDE, to = GeometryConstants.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 GeometryConstants#MIN_LONGITUDE} and
+   * {@link GeometryConstants#MAX_LONGITUDE}
+   * </p>
+   *
+   * @return the longitude value in degrees
+   * @see GeometryConstants#MIN_LONGITUDE
+   * @see GeometryConstants#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,44 @@ 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;
+    return new LatLng(latitude, wrap(longitude, GeometryConstants.MIN_LONGITUDE, GeometryConstants.MAX_LONGITUDE));
   }
 
+
+  /**
+   * Constrains value to the given range (including min & max) via modular arithmetic.
+   * <p>
+   * Same formula as used in Core GL (wrap.hpp)
+   * std::fmod((std::fmod((value - min), d) + d), d) + min;
+   *
+   * Multiples of max value will be wrapped to max.
+   *
+   * @param value Value to wrap
+   * @param min   Minimum value
+   * @param max   Maximum value
+   * @return Wrapped value
+   */
+  static double wrap(double value, double min, double max) {
+    double delta = max - min;
+
+    double firstMod = (value - min) % delta;
+    double secondMod = (firstMod + delta) % delta;
+
+    if (value >= max && secondMod == 0) {
+      return max;
+    }
+    return secondMod + min;
+  }
+
+  /**
+   * 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 +254,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 +272,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);
@@ -213,6 +330,6 @@ public class LatLng implements ILatLng, Parcelable {
     final double t3 = Math.sin(a1) * Math.sin(b1);
     final double tt = Math.acos(t1 + t2 + t3);
 
-    return GeoConstants.RADIUS_EARTH_METERS * tt;
+    return GeometryConstants.RADIUS_EARTH_METERS * tt;
   }
 }