Updates based on API council feedback.

-- Promote generally-useful PFD API to public.
-- Add @WorkerThread annotations.
-- Add docs to explain how AUTHORITY_LEGACY works, and add explicit
START/FINISH_LEGACY_MIGRATION_CALL verbs to communicate progress.
-- Expand docs for createWriteRequest() to explain broader access
that it grants.  Expand all request methods to indicate the action
is fully completed before the result is delivered.
-- Expand docs for new generation fields to explain that version
also needs to be inspected.
-- Explicitly call out why getKindSize() is deprecated, and guide
towards better alternative.

Bug: 148867182, 148403418, 148011561, 147760276
Test: none
Change-Id: I54ff072a752497b6aba153bd4013567c269e5b19

5 files changed, 8 insertions, 12 deletions

diff --git a/Android.bp b/Android.bp
index fb14f86bdae4..78d38c5c2537 100644
--- a/Android.bp
+++ b/Android.bp
@@ -701,6 +701,7 @@ filegroup {
         "core/java/android/annotation/SystemApi.java",
         "core/java/android/annotation/SystemService.java",
         "core/java/android/annotation/TestApi.java",
+        "core/java/android/annotation/WorkerThread.java",
         "core/java/com/android/internal/annotations/GuardedBy.java",
         "core/java/com/android/internal/annotations/VisibleForTesting.java",
         "core/java/com/android/internal/annotations/Immutable.java",
diff --git a/api/current.txt b/api/current.txt
index d4cbe6d93486..4a4d14bd3daf 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -36594,6 +36594,7 @@ package android.os {
     method public static android.os.ParcelFileDescriptor open(java.io.File, int) throws java.io.FileNotFoundException;
     method public static android.os.ParcelFileDescriptor open(java.io.File, int, android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener) throws java.io.IOException;
     method public static int parseMode(String);
+    method @NonNull public static android.os.ParcelFileDescriptor wrap(@NonNull android.os.ParcelFileDescriptor, @NonNull android.os.Handler, @NonNull android.os.ParcelFileDescriptor.OnCloseListener) throws java.io.IOException;
     method public void writeToParcel(android.os.Parcel, int);
     field @NonNull public static final android.os.Parcelable.Creator<android.os.ParcelFileDescriptor> CREATOR;
     field public static final int MODE_APPEND = 33554432; // 0x2000000
diff --git a/api/system-current.txt b/api/system-current.txt
index e81af5a35298..19311e310f35 100755
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -8464,10 +8464,6 @@ package android.os {
     method public boolean hasSingleFileDescriptor();
   }
 
-  public class ParcelFileDescriptor implements java.io.Closeable android.os.Parcelable {
-    method @NonNull public static android.os.ParcelFileDescriptor wrap(@NonNull android.os.ParcelFileDescriptor, @NonNull android.os.Handler, @NonNull android.os.ParcelFileDescriptor.OnCloseListener) throws java.io.IOException;
-  }
-
   public final class PowerManager {
     method @RequiresPermission(allOf={android.Manifest.permission.READ_DREAM_STATE, android.Manifest.permission.WRITE_DREAM_STATE}) public void dream(long);
     method @RequiresPermission(android.Manifest.permission.DEVICE_POWER) public boolean forceSuspend();
@@ -9200,9 +9196,9 @@ package android.provider {
 
   public final class MediaStore {
     method @NonNull public static android.net.Uri rewriteToLegacy(@NonNull android.net.Uri);
-    method @NonNull public static android.net.Uri scanFile(@NonNull android.content.ContentResolver, @NonNull java.io.File);
-    method public static void scanVolume(@NonNull android.content.ContentResolver, @NonNull String);
-    method public static void waitForIdle(@NonNull android.content.ContentResolver);
+    method @NonNull @WorkerThread public static android.net.Uri scanFile(@NonNull android.content.ContentResolver, @NonNull java.io.File);
+    method @WorkerThread public static void scanVolume(@NonNull android.content.ContentResolver, @NonNull String);
+    method @WorkerThread public static void waitForIdle(@NonNull android.content.ContentResolver);
     field public static final String AUTHORITY_LEGACY = "media_legacy";
     field @NonNull public static final android.net.Uri AUTHORITY_LEGACY_URI;
   }
diff --git a/api/test-current.txt b/api/test-current.txt
index a42710da1000..d03539c70d55 100644
--- a/api/test-current.txt
+++ b/api/test-current.txt
@@ -2916,9 +2916,9 @@ package android.provider {
   }
 
   public final class MediaStore {
-    method @NonNull public static android.net.Uri scanFile(@NonNull android.content.ContentResolver, @NonNull java.io.File);
-    method public static void scanVolume(@NonNull android.content.ContentResolver, @NonNull String);
-    method public static void waitForIdle(@NonNull android.content.ContentResolver);
+    method @NonNull @WorkerThread public static android.net.Uri scanFile(@NonNull android.content.ContentResolver, @NonNull java.io.File);
+    method @WorkerThread public static void scanVolume(@NonNull android.content.ContentResolver, @NonNull String);
+    method @WorkerThread public static void waitForIdle(@NonNull android.content.ContentResolver);
   }
 
   public final class Settings {
diff --git a/core/java/android/os/ParcelFileDescriptor.java b/core/java/android/os/ParcelFileDescriptor.java
index 89ddf8cbd96a..c0847872a45a 100644
--- a/core/java/android/os/ParcelFileDescriptor.java
+++ b/core/java/android/os/ParcelFileDescriptor.java
@@ -282,9 +282,7 @@ public class ParcelFileDescriptor implements Parcelable, Closeable {
      * @param listener to be invoked when the returned descriptor has been
      *            closed.
      * @return a new ParcelFileDescriptor pointing to the given file.
-     * @hide
      */
-    @SystemApi
     // We can't accept a generic Executor here, since we need to use
     // MessageQueue.addOnFileDescriptorEventListener()
     @SuppressLint("ExecutorRegistration")