From 531f337ee2f8dd46077525043c8c3ca13efc5570 Mon Sep 17 00:00:00 2001
From: Tom MacWright <tom@macwright.org>
Date: Tue, 15 Dec 2015 10:45:15 -0500
Subject: [PATCH] [android] Add more documentation to Android bindings. Refs
 #2650

---
 .../com/mapbox/mapboxsdk/constants/GeoConstants.java | 12 ++++++++----
 .../java/com/mapbox/mapboxsdk/geometry/LatLng.java   | 11 +++++++++++
 .../mapbox/mapboxsdk/geometry/ProjectedMeters.java   |  6 ++++++
 .../java/com/mapbox/mapboxsdk/views/CompassView.java |  5 +++++
 .../com/mapbox/mapboxsdk/views/UserLocationView.java |  4 ++++
 5 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/GeoConstants.java b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/GeoConstants.java
index 41ff1802d..ed6f77f41 100644
--- a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/GeoConstants.java
+++ b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/GeoConstants.java
@@ -6,18 +6,22 @@ package com.mapbox.mapboxsdk.constants;
 public class GeoConstants {
 
     /**
-     * The equatorial radius value in meters
+     * The <a href='http://en.wikipedia.org/wiki/Earth_radius#Equatorial_radius'>equatorial radius</a>
+     * value in meters
      */
-    // http://en.wikipedia.org/wiki/Earth_radius#Equatorial_radius
     public static final int RADIUS_EARTH_METERS = 6378137;
 
     /**
-     * The minimum latitude on Earth
+     * The minimum latitude on Earth. This is the minimum latitude representable
+     * by Mapbox GL's Mercator projection, because the projection distorts latitude
+     * near the poles towards infinity.
      */
     public static final double MIN_LATITUDE = -85.05112878;
 
     /**
-     * The maximum latitude on Earth
+     * The maximum latitude on Earth. This is the maximum latitude representable
+     * by Mapbox GL's Mercator projection, because the projection distorts latitude
+     * near the poles towards infinity.
      */
     public static final double MAX_LATITUDE = 85.05112878;
 
diff --git a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java
index b2a0a02b1..c340b09e0 100644
--- a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java
+++ b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java
@@ -9,6 +9,17 @@ import com.mapbox.mapboxsdk.constants.MathConstants;
 
 import java.io.Serializable;
 
+/**
+ * <p>
+ * This class is container for a single latitude, longitude pair, with
+ * optional altitude. Latitude and longitude are expressed as decimal degrees
+ * in the WGS84 datum. By default, altitude is 0.0, or sea level.
+ * </p>
+ * <p>
+ * Mapbox GL displays maps in the Mercator Projection and projects geographical
+ * data automatically, so all data enters in the WGS84 datum.
+ * </p>
+ */
 public class LatLng implements ILatLng, Parcelable, Serializable {
 
     public static final Parcelable.Creator<LatLng> CREATOR = new Parcelable.Creator<LatLng>() {
diff --git a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java
index be4819a74..fc821e887 100644
--- a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java
+++ b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java
@@ -5,6 +5,12 @@ import android.os.Parcelable;
 
 import java.io.Serializable;
 
+/**
+ * ProjectedMeters is an internal representation of longitude, latitude points that
+ * have been projected into Mapbox GL's Mercator projection. Instead of decimal
+ * degrees, it uses Mercator meters (which are notably not equivalent to SI meters)
+ * except at the equator.
+ */
 public class ProjectedMeters implements IProjectedMeters, Parcelable, Serializable {
 
     public static final Creator<ProjectedMeters> CREATOR = new Creator<ProjectedMeters>() {
diff --git a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/CompassView.java b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/CompassView.java
index 174f94991..7bd07d093 100644
--- a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/CompassView.java
+++ b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/CompassView.java
@@ -16,6 +16,11 @@ import java.lang.ref.WeakReference;
 import java.util.Timer;
 import java.util.TimerTask;
 
+/**
+ * CompassView is a UI element overlaid on a map that shows the map's bearing
+ * when it isn't true north (0.0). Tapping the compass resets the bearing to true
+ * north and hides the compass.
+ */
 final class CompassView extends ImageView {
 
     private Timer mNorthTimer;
diff --git a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/UserLocationView.java b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/UserLocationView.java
index f120915c5..ba48eb574 100644
--- a/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/UserLocationView.java
+++ b/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/UserLocationView.java
@@ -32,6 +32,10 @@ import com.mapbox.mapboxsdk.geometry.LatLng;
 import com.mapbox.mapboxsdk.location.LocationListener;
 import com.mapbox.mapboxsdk.location.LocationServices;
 
+/**
+ * This view shows the user's location, as determined from GPS, on the map
+ * as a dot annotation.
+ */
 final class UserLocationView extends View implements LocationListener {
 
     private MapView mMapView;