Update Geocoder docs to strengthen warnings (ad53af1f) · Commits · e / os / android_frameworks_base

location/java/android/location/Geocoder.java

+37 −34

Original line number	Diff line number	Diff line
		@@ -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