From 1294dde18348975a323437316e519682f0ca24be Mon Sep 17 00:00:00 2001
From: Joe Fernandez <joefernandez@google.com>
Date: Fri, 16 Sep 2016 09:51:48 -0700
Subject: docs: Clarification for location permissions and location hardware

b/28052540

Change-Id: I54fa08a3339c1d373164a003a02adeed156fa331
---
 docs/html/guide/topics/location/strategies.jd       | 21 ++++++++++++---------
 .../guide/topics/manifest/uses-feature-element.jd   | 14 +++++++-------
 docs/html/guide/topics/media/camera.jd              |  2 +-
 3 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/docs/html/guide/topics/location/strategies.jd b/docs/html/guide/topics/location/strategies.jd
index eb436d0138a4..548ed9c99f34 100755
--- a/docs/html/guide/topics/location/strategies.jd
+++ b/docs/html/guide/topics/location/strategies.jd
@@ -160,22 +160,25 @@ android.location.LocationManager#GPS_PROVIDER}.</p>
   android.location.LocationManager#NETWORK_PROVIDER} and {@link
   android.location.LocationManager#GPS_PROVIDER}, then you need to request only
   the {@code ACCESS_FINE_LOCATION} permission, because it includes permission
-  for both providers. (Permission for {@code ACCESS_COARSE_LOCATION} includes
-  permission only for {@link
-  android.location.LocationManager#NETWORK_PROVIDER}.)
+  for both providers. Permission for {@code ACCESS_COARSE_LOCATION} allows
+  access only to {@link android.location.LocationManager#NETWORK_PROVIDER}.
 </p>
 
-<p class="note">
-  <strong>Note:</strong> If your app targets Android 5.0 (API level 21) or
-  higher, you must also declare that your app uses the
+<p id="location-feature-caution" class="caution">
+  <strong>Caution:</strong> If your app targets Android 5.0 (API level 21) or
+  higher, you <em>must</em> declare that your app uses the
   <code>android.hardware.location.network</code> or
   <code>android.hardware.location.gps</code> hardware feature in the manifest
   file, depending on whether your app receives location updates from {@link
   android.location.LocationManager#NETWORK_PROVIDER} or from {@link
   android.location.LocationManager#GPS_PROVIDER}. If your app receives location
-  information from both of these providers, you need to declare that the app
-  uses both <code>android.hardware.location.network</code> and
-  <code>android.hardware.location.gps</code>.
+  information from either of these location provider sources, you need to
+  declare that the app uses these hardware features in your app manifest.
+  On devices running verions prior to Android 5.0 (API 21), requesting the
+  {@code ACCESS_FINE_LOCATION} or {@code ACCESS_COARSE_LOCATION} permission
+  includes an implied request for location hardware features. However,
+  requesting those permissions <em>does not</em> automatically request location
+  hardware features on Android 5.0 (API level 21) and higher.
 </p>
 
 <p>
diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd
index 8478940d8f1a..e43ac6118a47 100755
--- a/docs/html/guide/topics/manifest/uses-feature-element.jd
+++ b/docs/html/guide/topics/manifest/uses-feature-element.jd
@@ -1685,13 +1685,13 @@ densities: '160'
 
 <pre>&lt;uses-feature android:name="android.hardware.camera" android:required="false" /&gt;</pre>
 
-<p class="note">
-  <strong>Note:</strong> If your app targets Android 5.0 (API level 21) or
+<p class="caution">
+  <strong>Caution:</strong> If your app targets Android 5.0 (API level 21) or
   higher and uses the <code>ACCESS_COARSE_LOCATION</code> or
   <code>ACCESS_FINE_LOCATION</code> permission in order to receive location
   updates from the network or a GPS, respectively, you must also explicitly
   declare that your app uses the <code>android.hardware.location.network</code>
-  or <code>android.hardware.location.gps</code> hardware feature, respectively.
+  or <code>android.hardware.location.gps</code> hardware features.
 </p>
 
 <p class="table-caption" id="permissions-features">
@@ -1750,8 +1750,8 @@ densities: '160'
       <code>android.hardware.location</code>
     </p>
     <p>
-      <code>android.hardware.location.network</code> (Target API level 20 or
-      lower only.)
+      <code>android.hardware.location.network</code>
+      (Only when target API level is 20 orlower.)
     </p>
   </td>
 <!--  <td></td> -->
@@ -1763,8 +1763,8 @@ densities: '160'
       <code>android.hardware.location</code>
     </p>
     <p>
-      <code>android.hardware.location.gps</code> (Target API level 20 or lower
-      only.)
+      <code>android.hardware.location.gps</code>
+      (Only when target API level is 20 orlower.)
     </p>
   </td>
 
diff --git a/docs/html/guide/topics/media/camera.jd b/docs/html/guide/topics/media/camera.jd
index fcf1ab1fc9db..383b6c1f32ca 100644
--- a/docs/html/guide/topics/media/camera.jd
+++ b/docs/html/guide/topics/media/camera.jd
@@ -156,7 +156,7 @@ application must request the audio capture permission.
   </li>
   <li>
     <p><strong>Location Permission</strong> - If your application tags images
-    with GPS location information, you must request the "fine location"
+    with GPS location information, you must request the {@code ACCESS_FINE_LOCATION}
     permission. Note that, if your app targets Android 5.0 (API level 21) or
     higher, you also need to declare that your app uses the device's GPS:</p>
 <pre>
-- 
cgit v1.2.3-59-g8ed1b