Merge "WebView: update SafeBrowsing documentation" into oc-mr1-dev

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

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();