Update Location docs for isMock()

Add javadocs mentioning isMock() and why it exists to the top level
Location docs.

Bug: 240004850
Test: n/a
Change-Id: I208cb1fb4d213de33822d5109a4e822b470fd74d

1 files changed, 9 insertions, 0 deletions

diff --git a/location/java/android/location/Location.java b/location/java/android/location/Location.java
index 55ee3aaaaf77..f5a9850b31dd 100644
--- a/location/java/android/location/Location.java
+++ b/location/java/android/location/Location.java
@@ -47,6 +47,15 @@ import java.util.StringTokenizer;
  * <p>All locations generated through {@link LocationManager} are guaranteed to have a valid
  * latitude, longitude, timestamp (both Unix epoch time and elapsed realtime since boot), and
  * accuracy. All other parameters are optional.
+ *
+ * <p class="note">Note that Android provides the ability for applications to submit "mock" or faked
+ * locations through {@link LocationManager}, and that these locations can then be received by
+ * applications using LocationManager to obtain location information. These locations can be
+ * identified via the {@link #isMock()} API. Applications that wish to determine if a given location
+ * represents the best estimate of the real position of the device as opposed to a fake location
+ * coming from another application or the user should use this API. Keep in mind that the user may
+ * have a good reason for mocking their location, and thus apps should generally reject mock
+ * locations only when it is essential to their use case that only real locations are accepted.
  */
 public class Location implements Parcelable {