diff --git a/core/java/android/text/util/Linkify.java b/core/java/android/text/util/Linkify.java
index 50e7ec30ec3a6..df54209bc0433 100644
--- a/core/java/android/text/util/Linkify.java
+++ b/core/java/android/text/util/Linkify.java
@@ -67,6 +67,14 @@ import java.util.regex.Pattern;
  *  create <code>http://example.com</code> when the clickable URL link is
  *  created.
  *
+ *  <p class="note"><b>Note:</b> When using {@link #MAP_ADDRESSES} or {@link #ALL}
+ *  to match street addresses on API level {@link android.os.Build.VERSION_CODES#O_MR1}
+ *  and earlier, methods in this class may throw
+ *  {@link android.util.AndroidRuntimeException} or other exceptions if the
+ *  device's WebView implementation is currently being updated, because
+ *  {@link android.webkit.WebView#findAddress} is required to match street
+ *  addresses.
+ *
  * @see MatchFilter
  * @see TransformFilter
  */
@@ -95,10 +103,11 @@ public class Linkify {
 
     /**
      *  Bit field indicating that street addresses should be matched in methods that
-     *  take an options mask. Note that this uses the
-     *  {@link android.webkit.WebView#findAddress(String) findAddress()} method in
-     *  {@link android.webkit.WebView} for finding addresses, which has various
-     *  limitations and has been deprecated.
+     *  take an options mask. Note that this should be avoided, as it uses the
+     *  {@link android.webkit.WebView#findAddress(String)} method, which has various
+     *  limitations and has been deprecated: see the documentation for
+     *  {@link android.webkit.WebView#findAddress(String)} for more information.
+     *
      *  @deprecated use {@link android.view.textclassifier.TextClassifier#generateLinks(
      *  TextLinks.Request)} instead and avoid it even when targeting API levels where no alternative
      *  is available.
diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java
index 137b67c6e63e0..14be73dec41cd 100644
--- a/core/java/android/webkit/WebView.java
+++ b/core/java/android/webkit/WebView.java
@@ -1603,9 +1603,9 @@ public class WebView extends AbsoluteLayout
     }
 
     /**
-     * Gets the first substring consisting of the address of a physical
-     * location. Currently, only addresses in the United States are detected,
-     * and consist of:
+     * Gets the first substring which appears to be the address of a physical
+     * location. Only addresses in the United States can be detected, which
+     * must consist of:
      * <ul>
      *   <li>a house number</li>
      *   <li>a street name</li>
@@ -1621,9 +1621,17 @@ public class WebView extends AbsoluteLayout
      * or abbreviated using USPS standards. The house number may not exceed
      * five digits.
      *
+     * <p class="note"><b>Note:</b> This function is deprecated and should be
+     * avoided on all API levels, as it cannot detect addresses outside of the
+     * United States and has a high rate of false positives. On API level
+     * {@link android.os.Build.VERSION_CODES#O_MR1} and earlier, it also causes
+     * the entire WebView implementation to be loaded and initialized, which
+     * can throw {@link android.util.AndroidRuntimeException} or other exceptions
+     * if the WebView implementation is currently being updated.
+     *
      * @param addr the string to search for addresses
      * @return the address, or if no address is found, {@code null}
-     * @deprecated this method is superseded by {@link TextClassifier#generateLinks(
+     * @deprecated This method is superseded by {@link TextClassifier#generateLinks(
      * android.view.textclassifier.TextLinks.Request)}. Avoid using this method even when targeting
      * API levels where no alternative is available.
      */
diff --git a/core/java/android/widget/TextView.java b/core/java/android/widget/TextView.java
index a9e183ad5bf2d..073965b351013 100644
--- a/core/java/android/widget/TextView.java
+++ b/core/java/android/widget/TextView.java
@@ -4960,6 +4960,10 @@ public class TextView extends View implements ViewTreeObserver.OnPreDrawListener
      * android.text.util.Linkify#ALL Linkify.ALL} and peers for
      * possible values.
      *
+     * <p class="note"><b>Note:</b>
+     * {@link android.text.util.Linkify#MAP_ADDRESSES Linkify.MAP_ADDRESSES}
+     * is deprecated and should be avoided; see its documentation.
+     *
      * @attr ref android.R.styleable#TextView_autoLink
      */
     @android.view.RemotableViewMethod
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 81accdf82b006..2f301946402b5 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -1560,7 +1560,8 @@
         <flag name="email" value="0x02" />
         <!-- Match phone numbers. -->
         <flag name="phone" value="0x04" />
-        <!-- Match map addresses. -->
+        <!-- Match map addresses.
+             Deprecated: see {@link android.text.util.Linkify#MAP_ADDRESSES}. -->
         <flag name="map" value="0x08" />
         <!-- Match all patterns (equivalent to web|email|phone|map). -->
         <flag name="all" value="0x0f" />