Merge "More on issue #10130785: Restore silence and vibrate settings..." into klp-dev

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;

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
      */