docs: Updating Scoped Directory Access preview docs for DP2

Small updates to Scoped Directory Access preview docs, which include
the ability to ask for full volume access on secondary volumes,
and the "Don't ask again" checkbox in the UI for repeated access
requests.

Also, adding Scoped Directory Access to preview docs TOC.
I also updated preview/_book.yaml, even though I don't think
it is being used yet, to ensure it stays in synch with this TOC
change.

Bug: 27931961 27931982
Change-Id: Ib7d20519d580e9c7c467fdc6b2f88b699b1ff1c1

docs/html/preview/_book.yaml

@@ -70,6 +70,8 @@ toc:
     path: /preview/j8-jack.html
   - title: Android for Work Updates
     path: /preview/features/afw.html
+  - title: Scoped Directory Access
+    path: /preview/features/scoped-folder-access.html
 
 - title: Samples
   path: /preview/samples.html

docs/html/preview/features/scoped-folder-access.jd

@@ -44,6 +44,14 @@ Use this intent to access external storage directories. To get a list of
 all available volumes, including removable media volumes, use
 <code>StorageManager.getVolumesList()</code>.</p>
 
+<p>
+On secondary volumes, such as external SD cards, pass in null when calling
+<code>StorageVolume.createAccessIntent()</code> to request access to the entire
+volume, instead of a specific directory.
+<code>StorageVolume.createAccessIntent()</code> returns null if you pass in
+null to the primary volume, or if you pass in an invalid directory name.
+</p>
+
 <p>The following code snippet is an example of how to open the
 <code>Pictures</code> directory in the primary shared storage:</p>
 
@@ -122,4 +130,15 @@ user.</p>
 
 <p>If the user denies access to an external directory, do not immediately
 request access again. Repeatedly insisting on access results in a poor user
-experience.</p>
+experience. If a request is denied by the user, and the app requests access
+again, the UI displays a <b>Don't ask again</b> checkbox:</p>
+
+<img src="{@docRoot}preview/images/scoped-folder-access-dont-ask.png"
+srcset="{@docRoot}preview/images/scoped-folder-access-dont-ask.png 1x,
+{@docRoot}preview/images/scoped-folder-access-dont-ask_2x.png 2x" />
+<p class="img-caption"><strong>Figure 1.</strong> An application making a
+second request for access to removable media.</p>
+
+<p>If the user selects <b>Don't ask again</b> and denies the request, all
+future requests for the given directory from your app will be automatically
+denied, and no request UI will be presented to the user.</p>

docs/html/preview/preview_toc.cs

@@ -17,7 +17,7 @@
     <div class="nav-section-header empty"><a href="<?cs var:toroot ?>preview/support.html">
       Support and Release Notes</a></div>
   </li>
-  
+
   <li class="nav-section">
     <div class="nav-section-header empty"><a href="<?cs var:toroot ?>preview/setup-sdk.html"
       es-lang="Configurar el SDK de la versión preliminar"
@@ -82,12 +82,15 @@
 
         <li><a href="<?cs var:toroot ?>preview/features/icu4j-framework.html"
         >ICU4J Support</a></li>
-        
+
         <li><a href="<?cs var:toroot ?>preview/j8-jack.html"
         >Java 8 Language Features</a></li>
 
         <li><a href="<?cs var:toroot ?>preview/features/afw.html"
         >Android for Work Updates</a></li>
+
+        <li><a href="<?cs var:toroot ?>preview/features/scoped-folder-access.html"
+        >Scoped Directory Access</a></li>
       </ul>
   </li>