Update ImageDecoder docs regarding Files

Bug: 139186570
Test: make docs

As part of enforcing Scoped Storage for the next Android release, we're
encouraging app developers to steer away from using raw file path access
and, instead, use FileDescriptor or Uri to access files.

Update createSource(File)'s docs to suggest why they might want to use a
different method.

Update the top level example to use createSource(ContentResolver, Uri)
instead of createSource(File).

Change-Id: Icbccdb5183edd0b6a052ec905f999f02ac4e61d3
(cherry picked from commit 4056974583)
Merged-In: Icbccdb5183edd0b6a052ec905f999f02ac4e61d3

graphics/java/android/graphics/ImageDecoder.java

@@ -70,9 +70,9 @@ import java.util.concurrent.atomic.AtomicBoolean;
  *  {@link Bitmap} objects.
  *
  *  <p>To use it, first create a {@link Source Source} using one of the
- *  {@code createSource} overloads. For example, to decode from a {@link File}, call
- *  {@link #createSource(File)} and pass the result to {@link #decodeDrawable(Source)}
- *  or {@link #decodeBitmap(Source)}:
+ *  {@code createSource} overloads. For example, to decode from a {@link Uri}, call
+ *  {@link #createSource(ContentResolver, Uri)} and pass the result to
+ *  {@link #decodeDrawable(Source)} or {@link #decodeBitmap(Source)}:
  *
  *  <pre class="prettyprint">
  *  File file = new File(...);
@@ -1032,7 +1032,11 @@ public final class ImageDecoder implements AutoCloseable {
 
     /**
      * Create a new {@link Source Source} from a {@link java.io.File}.
-     *
+     * <p>
+     * This method should only be used for files that you have direct access to;
+     * if you'd like to work with files hosted outside your app, use an API like
+     * {@link #createSource(Callable)} or
+     * {@link #createSource(ContentResolver, Uri)}.
      * @return a new Source object, which can be passed to
      *      {@link #decodeDrawable decodeDrawable} or
      *      {@link #decodeBitmap decodeBitmap}.