[android] #4748 - add javadoc for unregistering location listeners

1 files changed, 13 insertions, 0 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationServices.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationServices.java
index e64b6378e2..c148b02a10 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationServices.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationServices.java
@@ -9,13 +9,26 @@ import android.location.LocationManager;
 import android.support.annotation.NonNull;
 import android.support.v4.content.ContextCompat;
 import android.util.Log;
+
 import com.mapbox.mapboxsdk.telemetry.TelemetryLocationReceiver;
 import com.mapzen.android.lost.api.LocationRequest;
 import com.mapzen.android.lost.api.LostApiClient;
+
 import java.util.concurrent.CopyOnWriteArrayList;
 
 /**
  * Manages locational updates. Contains methods to register and unregister location listeners.
+ * <p>
+ * <ul>
+ * <li>You can register a {@link LocationListener} with {@link #addLocationListener(LocationListener)} to receive location updates.</li>
+ * <li> You can unregister a {@link LocationListener} with {@link #removeLocationListener(LocationListener)}.</li>
+ * </ul>
+ * <p/>
+ * <p>
+ * Note: If registering a listener in your Activity.onResume() implementation, you should unregister it in Activity.onPause().
+ * (You won't receive location updates when paused, and this will cut down on unnecessary system overhead).
+ * Do not unregister in Activity.onSaveInstanceState(), because this won't be called if the user moves back in the history stack.
+ * </p>
  */
 public class LocationServices implements com.mapzen.android.lost.api.LocationListener {