2 files changed, 10 insertions, 6 deletions
diff --git a/core/java/android/content/ContentProvider.java b/core/java/android/content/ContentProvider.java
index 343841934223..0a1d3f9afc5a 100644
--- a/core/java/android/content/ContentProvider.java
+++ b/core/java/android/content/ContentProvider.java
@@ -918,8 +918,10 @@ public abstract class ContentProvider implements ComponentCallbacks2 {
      *
      * @param url The Uri to remove any canonicalization from.
      *
-     * @return Return the non-canonical representation of <var>url</var>, or return
-     * the <var>url</var> as-is if there is nothing to do.  Never return null.
+     * @return Return the non-canonical representation of <var>url</var>, return
+     * the <var>url</var> as-is if there is nothing to do, or return null if
+     * the data identified by the canonical representation can not be found in
+     * the current environment.
      */
     public Uri uncanonicalize(Uri url) {
         return url;
diff --git a/core/java/android/content/ContentResolver.java b/core/java/android/content/ContentResolver.java
index 995ca97ff1e3..f250029153f6 100644
--- a/core/java/android/content/ContentResolver.java
+++ b/core/java/android/content/ContentResolver.java
@@ -548,14 +548,16 @@ public abstract class ContentResolver {
      * it to its local non-canonical form.  This can be useful in some cases where
      * you know that you will only be using the Uri in the current environment and
      * want to avoid any possible overhead when using it with the content
-     * provider.
+     * provider or want to verify that the referenced data exists at all in the
+     * new environment.
      *
      * @param url The canonical {@link Uri} that is to be convered back to its
      * non-canonical form.
      *
-     * @return Returns the non-canonical representation of <var>url</var>.  This
-     * function never returns null; if there is no conversion to be done, it returns
-     * the same Uri that was provided.
+     * @return Returns the non-canonical representation of <var>url</var>.  This will
+     * return null if data identified by the canonical Uri can not be found in
+     * the current environment; callers must always check for null and deal with
+     * that by appropriately falling back to an alternative.
      *
      * @see #canonicalize
      */