Merge "Unhide findPath() API. Add JavaDoc to related features."

3 files changed, 21 insertions, 12 deletions

diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index e0312757a9a2..4eecd48df646 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -3120,6 +3120,11 @@ public class Intent implements Parcelable, Cloneable {
      * URIs that can be opened with
      * {@link ContentResolver#openFileDescriptor(Uri, String)}.
      * <p>
+     * Callers can set a document URI through {@link #setData(Uri)} to indicate
+     * the initial location of documents navigator. System will do its best to
+     * launch the navigator in the specified document if it's a folder, or the
+     * folder that contains the specified document if not.
+     * <p>
      * Output: The URI of the item that was picked, returned in
      * {@link #getData()}. This must be a {@code content://} URI so that any
      * receiver can access it. If multiple documents were selected, they are
@@ -3156,6 +3161,11 @@ public class Intent implements Parcelable, Cloneable {
      * URIs that can be opened with
      * {@link ContentResolver#openFileDescriptor(Uri, String)}.
      * <p>
+     * Callers can set a document URI through {@link #setData(Uri)} to indicate
+     * the initial location of documents navigator. System will do its best to
+     * launch the navigator in the specified document if it's a folder, or the
+     * folder that contains the specified document if not.
+     * <p>
      * Output: The URI of the item that was created. This must be a
      * {@code content://} URI so that any receiver can access it.
      *
@@ -3178,6 +3188,11 @@ public class Intent implements Parcelable, Cloneable {
      * {@link DocumentsContract#buildChildDocumentsUriUsingTree(Uri, String)}
      * with the returned URI.
      * <p>
+     * Callers can set a document URI through {@link #setData(Uri)} to indicate
+     * the initial location of documents navigator. System will do its best to
+     * initiate the navigator in the specified document if it's a folder, or
+     * the folder that contains the specified document if not.
+     * <p>
      * Output: The URI representing the selected directory tree.
      *
      * @see DocumentsContract
diff --git a/core/java/android/provider/DocumentsContract.java b/core/java/android/provider/DocumentsContract.java
index 59a8fdab043b..2dcf220b8ac4 100644
--- a/core/java/android/provider/DocumentsContract.java
+++ b/core/java/android/provider/DocumentsContract.java
@@ -1310,8 +1310,6 @@ public final class DocumentsContract {
      * @return a list of documents ID starting from the top of the tree to the
      *      requested document, or {@code null} if failed.
      * @see DocumentsProvider#findDocumentPath(String, String)
-     *
-     * {@hide}
      */
     public static List<String> findDocumentPath(ContentResolver resolver, Uri treeUri) {
         checkArgument(isTreeUri(treeUri), treeUri + " is not a tree uri.");
@@ -1343,7 +1341,9 @@ public final class DocumentsContract {
      *
      * {@hide}
      */
-    public static Path findDocumentPath(ContentProviderClient client, Uri uri) throws RemoteException {
+    public static Path findDocumentPath(ContentProviderClient client, Uri uri)
+            throws RemoteException {
+
         final Bundle in = new Bundle();
         in.putParcelable(DocumentsContract.EXTRA_URI, uri);
 
@@ -1393,9 +1393,8 @@ public final class DocumentsContract {
     }
 
     /**
-     * Holds a path from a root to a particular document under it.
-     *
-     * @hide
+     * Holds a path from a document to a particular document under it. It
+     * may also contains the root ID where the path resides.
      */
     public static final class Path implements Parcelable {
 
@@ -1406,7 +1405,7 @@ public final class DocumentsContract {
          * Creates a Path.
          *
          * @param rootId the ID of the root. May be null.
-         * @param path the list of document ids from the parent document at
+         * @param path the list of document ID from the parent document at
          *          position 0 to the child document.
          */
         public Path(@Nullable String rootId, List<String> path) {
diff --git a/core/java/android/provider/DocumentsProvider.java b/core/java/android/provider/DocumentsProvider.java
index 1df4dbd7c4c5..96c2556428b8 100644
--- a/core/java/android/provider/DocumentsProvider.java
+++ b/core/java/android/provider/DocumentsProvider.java
@@ -355,8 +355,6 @@ public abstract class DocumentsProvider extends ContentProvider {
      * @return the path of the requested document. If parentDocumentId is null
      *     returned root ID must not be null. If parentDocumentId is not null
      *     returned root ID must be null.
-     *
-     * @hide
      */
     public Path findDocumentPath(String childDocumentId, @Nullable String parentDocumentId)
             throws FileNotFoundException {
@@ -468,9 +466,6 @@ public abstract class DocumentsProvider extends ContentProvider {
      * least {@link Document#COLUMN_DISPLAY_NAME} be matched in a
      * case-insensitive fashion.
      * <p>
-     * Only documents may be returned; directories are not supported in search
-     * results.
-     * <p>
      * If your provider is cloud-based, and you have some data cached or pinned
      * locally, you may return the local data immediately, setting
      * {@link DocumentsContract#EXTRA_LOADING} on the Cursor to indicate that