From 7d6333e8245d5432dcb017d601efa4af8888374e Mon Sep 17 00:00:00 2001
From: Soonil Nagarkar <sooniln@google.com>
Date: Fri, 4 Dec 2020 09:21:54 -0800
Subject: Clarifying documentation on removeUpdates and flushing

Document how batch flushes interact with removing updates.

Test: n/a
Change-Id: Ie65f517a7bda6273739f9c59df18e290fd0d770a
---
 location/java/android/location/LocationManager.java | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

(limited to 'location/java')

diff --git a/location/java/android/location/LocationManager.java b/location/java/android/location/LocationManager.java
index 047b809bc766..604c4a1de8f9 100644
--- a/location/java/android/location/LocationManager.java
+++ b/location/java/android/location/LocationManager.java
@@ -1509,8 +1509,15 @@ public class LocationManager {
     }
 
     /**
-     * Removes location updates for the specified {@link LocationListener}. Following this call,
-     * the listener will not receive any more invocations of any kind.
+     * Removes all location updates for the specified {@link LocationListener}. The given listener
+     * is guaranteed not to receive any invocations that <b>happens-after</b> this method is
+     * invoked.
+     *
+     * <p>If the given listener has any batched requests, this method will not flush any incomplete
+     * location batches before stopping location updates. If you wish to flush any pending locations
+     * before stopping, you must first call {@link #requestFlush(String, LocationListener, int)} and
+     * then call this method once the flush is complete. If this method is invoked before the flush
+     * is complete, you may not receive the flushed locations.
      *
      * @param listener listener that no longer needs location updates
      *
@@ -1537,6 +1544,8 @@ public class LocationManager {
      * Removes location updates for the specified {@link PendingIntent}. Following this call, the
      * PendingIntent will no longer receive location updates.
      *
+     * <p>See {@link #removeUpdates(LocationListener)} for more detail on how this method works.
+     *
      * @param pendingIntent pending intent that no longer needs location updates
      *
      * @throws IllegalArgumentException if pendingIntent is null
-- 
cgit v1.2.3-59-g8ed1b