WebView: update SafeBrowsing documentation

No change in logic, only docs changes:

 * Docs about Safe Browsing feature as a whole.
 * Expand the docs for initSafeBrowsing/shutdownSafeBrowsing

Bug: 63660204
Bug: 62192626
Test: make update-api and manually check javadocs
Change-Id: I6526a0f1ce1327f6eff416c27ded89866587f173

2 files changed, 42 insertions, 10 deletions

diff --git a/core/java/android/webkit/WebSettings.java b/core/java/android/webkit/WebSettings.java
index 3a6de9609b3c..82cff7c13e47 100644
--- a/core/java/android/webkit/WebSettings.java
+++ b/core/java/android/webkit/WebSettings.java
@@ -1390,17 +1390,15 @@ public abstract class WebSettings {
      * Sets whether Safe Browsing is enabled. Safe browsing allows WebView to
      * protect against malware and phishing attacks by verifying the links.
      *
-     * Safe browsing is disabled by default. The recommended way to enable
-     * Safe browsing is using a manifest tag to change the default value to
-     * enabled for all WebViews.
      * <p>
-     * <pre>
-     * &lt;meta-data android:name="android.webkit.WebView.EnableSafeBrowsing"
-     *            android:value="true" /&gt;
-     * </pre>
+     * Safe browsing is disabled by default. The recommended way to enable Safe browsing is using a
+     * manifest tag to change the default value to enabled for all WebViews (read <a
+     * href="{@docRoot}reference/android/webkit/WebView.html">general Safe Browsing info</a>).
      * </p>
      *
+     * <p>
      * This API overrides the manifest tag value for this WebView.
+     * </p>
      *
      * @param enabled Whether Safe browsing is enabled.
      */
diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java
index 333c44c5910d..b9abadbe64e1 100644
--- a/core/java/android/webkit/WebView.java
+++ b/core/java/android/webkit/WebView.java
@@ -319,6 +319,22 @@ import java.util.Map;
  * out.
  * </p>
  *
+ * <h3>Safe Browsing</h3>
+ *
+ * <p>
+ * If Safe Browsing is enabled, WebView will block malicious URLs and present a warning UI to the
+ * user to allow them to navigate back safely or proceed to the malicious page.
+ * </p>
+ * <p>
+ * The recommended way for apps to enable the feature is putting the following tag in the manifest:
+ * </p>
+ * <p>
+ * <pre>
+ * &lt;meta-data android:name="android.webkit.WebView.EnableSafeBrowsing"
+ *            android:value="true" /&gt;
+ * </pre>
+ * </p>
+ *
  */
 // Implementation notes.
 // The WebView is a thin API class that delegates its public API to a backend WebViewProvider
@@ -1622,8 +1638,24 @@ public class WebView extends AbsoluteLayout
     }
 
     /**
-     * Starts Safe Browsing initialization. This should only be called once. This does not require
-     * an Activity Context, and will always use the application Context to do its work.
+     * Starts Safe Browsing initialization. This should only be called once.
+     *
+     * <p>
+     * Because the Safe Browsing feature takes time to initialize, WebView may temporarily whitelist
+     * URLs until the feature is ready. The callback will be invoked with true once initialization
+     * is complete.
+     * </p>
+     *
+     * <p>
+     * This does not enable the Safe Browsing feature itself, and should only be used if the feature
+     * is otherwise enabled.
+     * </p>
+     *
+     * <p>
+     * This does not require an Activity Context, and will always use the application Context to do
+     * its work.
+     * </p>
+     *
      * @param context Application Context.
      * @param callback will be called with the value true if initialization is
      * successful. The callback will be run on the UI thread.
@@ -1633,7 +1665,9 @@ public class WebView extends AbsoluteLayout
     }
 
     /**
-     * Shuts down Safe Browsing. This should only be called once.
+     * Shuts down Safe Browsing. This should only be called once. This does not disable the feature,
+     * it only frees resources used by Safe Browsing code. To disable Safe Browsing on an individual
+     * WebView, see {@link WebSettings#setSafeBrowsingEnabled}
      */
     public static void shutdownSafeBrowsing() {
         getFactory().getStatics().shutdownSafeBrowsing();