Improve some javadoc related to isProviderEnabled() apis

- LocationManager.isProviderEnabled() no longer throws SecurityException:
the caller could already circumvent the permission check by calling
Secure.isLocationProviderEnabled()

Change-Id: I5abd04264299671ed35ce4594b5be46d86378767

1 files changed, 12 insertions, 6 deletions

diff --git a/location/java/android/location/LocationManager.java b/location/java/android/location/LocationManager.java
index 14b812e..ccb4304 100644
--- a/location/java/android/location/LocationManager.java
+++ b/location/java/android/location/LocationManager.java
@@ -152,17 +152,18 @@ public class LocationManager {
 
     /**
      * Broadcast intent action when the configured location providers
-     * change. If you're interacting with the
-     * {@link android.provider.Settings.Secure#LOCATION_MODE} API,
-     * use {@link #MODE_CHANGED_ACTION} instead.
+     * change. For use with {@link #isProviderEnabled(String)}. If you're interacting with the
+     * {@link android.provider.Settings.Secure#LOCATION_MODE} API, use {@link #MODE_CHANGED_ACTION}
+     * instead.
      */
     public static final String PROVIDERS_CHANGED_ACTION =
         "android.location.PROVIDERS_CHANGED";
 
     /**
      * Broadcast intent action when {@link android.provider.Settings.Secure#LOCATION_MODE} changes.
-     * If you're interacting with provider-based APIs such as {@link #getProviders(boolean)}, you
-     * use {@link #PROVIDERS_CHANGED_ACTION} instead.
+     * For use with the {@link android.provider.Settings.Secure#LOCATION_MODE} API.
+     * If you're interacting with {@link #isProviderEnabled(String)}, use
+     * {@link #PROVIDERS_CHANGED_ACTION} instead.
      *
      * In the future, there may be mode changes that do not result in
      * {@link #PROVIDERS_CHANGED_ACTION} broadcasts.
@@ -1098,8 +1099,13 @@ public class LocationManager {
      * <p>If the user has enabled this provider in the Settings menu, true
      * is returned otherwise false is returned
      *
+     * <p>Callers should instead use
+     * {@link android.provider.Settings.Secure#LOCATION_MODE}
+     * unless they depend on provider-specific APIs such as
+     * {@link #requestLocationUpdates(String, long, float, LocationListener)}.
+     *
      * @param provider the name of the provider
-     * @return true if the provider is enabled
+     * @return true if the provider exists and is enabled
      *
      * @throws IllegalArgumentException if provider is null
      * @throws SecurityException if no suitable permission is present