Update Geocoder docs to strengthen warnings

Bug: 177616061
Test: none
Change-Id: I81bcd4530fd7064ade8be00e0ad6d126cb9ab6f6

1 files changed, 37 insertions, 34 deletions

diff --git a/location/java/android/location/Geocoder.java b/location/java/android/location/Geocoder.java
index 307fb8783c51..51586d708018 100644
--- a/location/java/android/location/Geocoder.java
+++ b/location/java/android/location/Geocoder.java
@@ -45,6 +45,10 @@ import java.util.concurrent.TimeUnit;
  * empty list if there no backend service in the platform.  Use the
  * isPresent() method to determine whether a Geocoder implementation
  * exists.
+ *
+ * <p class="note"><strong>Warning:</strong> Geocoding services may provide no guarantees on
+ * availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful or
+ * correct. Do not use this API for any safety-critical or regulatory compliance purpose.
  */
 public final class Geocoder {
 
@@ -95,15 +99,15 @@ public final class Geocoder {
     }
 
     /**
-     * Returns an array of Addresses that are known to describe the
-     * area immediately surrounding the given latitude and longitude.
-     * The returned addresses will be localized for the locale
-     * provided to this class's constructor.
+     * Returns an array of Addresses that attempt to describe the area immediately surrounding the
+     * given latitude and longitude. The returned addresses should be localized for the locale
+     * provided to this class's constructor. Results may be obtained by means of a network lookup
+     * and this method may take some time to return, and so should not be called on the main thread.
      *
-     * <p> The returned values may be obtained by means of a network lookup.
-     * The results are a best guess and are not guaranteed to be meaningful or
-     * correct. It may be useful to call this method from a thread separate from your
-     * primary UI thread.
+     * <p class="note"><strong>Warning:</strong> Geocoding services may provide no guarantees on
+     * availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
+     * or correct. Do <b>NOT</b> use this API for any safety-critical or regulatory compliance
+     * purposes.
      *
      * @param latitude the latitude a point for the search
      * @param longitude the longitude a point for the search
@@ -134,17 +138,17 @@ public final class Geocoder {
     }
 
     /**
-     * Returns an array of Addresses that are known to describe the
-     * named location, which may be a place name such as "Dalvik,
-     * Iceland", an address such as "1600 Amphitheatre Parkway,
-     * Mountain View, CA", an airport code such as "SFO", etc..  The
-     * returned addresses will be localized for the locale provided to
-     * this class's constructor.
-     *
-     * <p> The query will block and returned values will be obtained by means of a network lookup.
-     * The results are a best guess and are not guaranteed to be meaningful or
-     * correct. It may be useful to call this method from a thread separate from your
-     * primary UI thread.
+     * Returns an array of Addresses that attempt to describe the named location, which may be a
+     * place name such as "Dalvik, Iceland", an address such as "1600 Amphitheatre Parkway, Mountain
+     * View, CA", an airport code such as "SFO", and so forth. The returned addresses should be
+     * localized for the locale provided to this class's constructor. Results may be obtained by
+     * means of a network lookup and this method may take some time to return, and so should not be
+     * called on the main thread.
+     *
+     * <p class="note"><strong>Warning:</strong> Geocoding services may provide no guarantees on
+     * availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
+     * or correct. Do <b>NOT</b> use this API for any safety-critical or regulatory compliance
+     * purposes.
      *
      * @param locationName a user-supplied description of a location
      * @param maxResults max number of results to return. Smaller numbers (1 to 5) are recommended
@@ -161,21 +165,20 @@ public final class Geocoder {
     }
 
     /**
-     * Returns an array of Addresses that are known to describe the
-     * named location, which may be a place name such as "Dalvik,
-     * Iceland", an address such as "1600 Amphitheatre Parkway,
-     * Mountain View, CA", an airport code such as "SFO", etc..  The
-     * returned addresses will be localized for the locale provided to
-     * this class's constructor.
-     *
-     * <p> You may specify a bounding box for the search results by including
-     * the Latitude and Longitude of the Lower Left point and Upper Right
-     * point of the box.
-     *
-     * <p> The query will block and returned values will be obtained by means of a network lookup.
-     * The results are a best guess and are not guaranteed to be meaningful or
-     * correct. It may be useful to call this method from a thread separate from your
-     * primary UI thread.
+     * Returns an array of Addresses that attempt to describe the named location, which may be a
+     * place name such as "Dalvik, Iceland", an address such as "1600 Amphitheatre Parkway, Mountain
+     * View, CA", an airport code such as "SFO", and so forth. The returned addresses should be
+     * localized for the locale provided to this class's constructor. Results may be obtained by
+     * means of a network lookup and this method may take some time to return, and so should not be
+     * called on the main thread.
+     *
+     * <p> You may specify a bounding box for the search results by including the latitude and
+     * longitude of the lower left point and upper right point of the box.
+     *
+     * <p class="note"><strong>Warning:</strong> Geocoding services may provide no guarantees on
+     * availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
+     * or correct. Do <b>NOT</b> use this API for any safety-critical or regulatory compliance
+     * purposes.
      *
      * @param locationName a user-supplied description of a location
      * @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are recommended