Merge "Update some ContentResolver docs." into rvc-dev

core/java/android/content/ContentResolver.java

@@ -1449,7 +1449,7 @@ public abstract class ContentResolver implements ContentInterface {
      * on these schemes.
      *
      * @param uri The desired URI.
-     * @return InputStream
+     * @return InputStream or {@code null} if the provider recently crashed.
      * @throws FileNotFoundException if the provided URI could not be opened.
      * @see #openAssetFileDescriptor(Uri, String)
      */
@@ -1484,6 +1484,9 @@ public abstract class ContentResolver implements ContentInterface {
     /**
      * Synonym for {@link #openOutputStream(Uri, String)
      * openOutputStream(uri, "w")}.
+     *
+     * @param uri The desired URI.
+     * @return an OutputStream or {@code null} if the provider recently crashed.
      * @throws FileNotFoundException if the provided URI could not be opened.
      */
     public final @Nullable OutputStream openOutputStream(@NonNull Uri uri)
@@ -1506,7 +1509,7 @@ public abstract class ContentResolver implements ContentInterface {
      *
      * @param uri The desired URI.
      * @param mode May be "w", "wa", "rw", or "rwt".
-     * @return OutputStream
+     * @return an OutputStream or {@code null} if the provider recently crashed.
      * @throws FileNotFoundException if the provided URI could not be opened.
      * @see #openAssetFileDescriptor(Uri, String)
      */
@@ -1563,8 +1566,9 @@ public abstract class ContentResolver implements ContentInterface {
      * @param uri The desired URI to open.
      * @param mode The file mode to use, as per {@link ContentProvider#openFile
      * ContentProvider.openFile}.
-     * @return Returns a new ParcelFileDescriptor pointing to the file.  You
+     * @return Returns a new ParcelFileDescriptor pointing to the file or {@code null} if the
-     * own this descriptor and are responsible for closing it when done.
+     * provider recently crashed. You own this descriptor and are responsible for closing it
+     * when done.
      * @throws FileNotFoundException Throws FileNotFoundException if no
      * file exists under the URI or the mode is invalid.
      * @see #openAssetFileDescriptor(Uri, String)
@@ -1608,8 +1612,9 @@ public abstract class ContentResolver implements ContentInterface {
      * @param cancellationSignal A signal to cancel the operation in progress,
      *         or null if none. If the operation is canceled, then
      *         {@link OperationCanceledException} will be thrown.
-     * @return Returns a new ParcelFileDescriptor pointing to the file.  You
+     * @return Returns a new ParcelFileDescriptor pointing to the file or {@code null} if the
-     * own this descriptor and are responsible for closing it when done.
+     * provider recently crashed. You own this descriptor and are responsible for closing it
+     * when done.
      * @throws FileNotFoundException Throws FileNotFoundException if no
      * file exists under the URI or the mode is invalid.
      * @see #openAssetFileDescriptor(Uri, String)
@@ -1698,8 +1703,9 @@ public abstract class ContentResolver implements ContentInterface {
      * @param uri The desired URI to open.
      * @param mode The file mode to use, as per {@link ContentProvider#openAssetFile
      * ContentProvider.openAssetFile}.
-     * @return Returns a new ParcelFileDescriptor pointing to the file.  You
+     * @return Returns a new ParcelFileDescriptor pointing to the file or {@code null} if the
-     * own this descriptor and are responsible for closing it when done.
+     * provider recently crashed. You own this descriptor and are responsible for closing it
+     * when done.
      * @throws FileNotFoundException Throws FileNotFoundException of no
      * file exists under the URI or the mode is invalid.
      */
@@ -1754,8 +1760,9 @@ public abstract class ContentResolver implements ContentInterface {
      * @param cancellationSignal A signal to cancel the operation in progress, or null if
      *            none. If the operation is canceled, then
      *            {@link OperationCanceledException} will be thrown.
-     * @return Returns a new ParcelFileDescriptor pointing to the file.  You
+     * @return Returns a new ParcelFileDescriptor pointing to the file or {@code null} if the
-     * own this descriptor and are responsible for closing it when done.
+     * provider recently crashed. You own this descriptor and are responsible for closing it
+     * when done.
      * @throws FileNotFoundException Throws FileNotFoundException of no
      * file exists under the URI or the mode is invalid.
      */
@@ -1902,9 +1909,9 @@ public abstract class ContentResolver implements ContentInterface {
      * it is returning.
      * @param opts Additional provider-dependent options.
      * @return Returns a new ParcelFileDescriptor from which you can read the
-     * data stream from the provider.  Note that this may be a pipe, meaning
+     * data stream from the provider or {@code null} if the provider recently crashed.
-     * you can't seek in it.  The only seek you should do is if the
+     * Note that this may be a pipe, meaning you can't seek in it.  The only seek you
-     * AssetFileDescriptor contains an offset, to move to that offset before
+     * should do is if the AssetFileDescriptor contains an offset, to move to that offset before
      * reading.  You own this descriptor and are responsible for closing it when done.
      * @throws FileNotFoundException Throws FileNotFoundException of no
      * data of the desired type exists under the URI.
@@ -1938,9 +1945,9 @@ public abstract class ContentResolver implements ContentInterface {
      *         or null if none. If the operation is canceled, then
      *         {@link OperationCanceledException} will be thrown.
      * @return Returns a new ParcelFileDescriptor from which you can read the
-     * data stream from the provider.  Note that this may be a pipe, meaning
+     * data stream from the provider or {@code null} if the provider recently crashed.
-     * you can't seek in it.  The only seek you should do is if the
+     * Note that this may be a pipe, meaning you can't seek in it.  The only seek you
-     * AssetFileDescriptor contains an offset, to move to that offset before
+     * should do is if the AssetFileDescriptor contains an offset, to move to that offset before
      * reading.  You own this descriptor and are responsible for closing it when done.
      * @throws FileNotFoundException Throws FileNotFoundException of no
      * data of the desired type exists under the URI.