WebView: clean up onReceivedSslError docs

am: 9f726cd280

Change-Id: Id927f42978e86296710995c9d445ac7ce168e265

core/java/android/webkit/WebViewClient.java

@@ -370,11 +370,16 @@ public class WebViewClient {
 
     /**
      * Notify the host application that an SSL error occurred while loading a
-     * resource. The host application must call either handler.cancel() or
-     * handler.proceed(). Note that the decision may be retained for use in
+     * resource. The host application must call either {@link SslErrorHandler#cancel} or
+     * {@link SslErrorHandler#proceed}. Note that the decision may be retained for use in
      * response to future SSL errors. The default behavior is to cancel the
      * load.
      * <p>
+     * This API is only called for recoverable SSL certificate errors. In the case of
+     * non-recoverable errors (such as when the server fails the client), WebView will call {@link
+     * #onReceivedError(WebView, WebResourceRequest, WebResourceError)} with {@link
+     * #ERROR_FAILED_SSL_HANDSHAKE}.
+     * <p>
      * Applications are advised not to prompt the user about SSL errors, as
      * the user is unlikely to be able to make an informed security decision
      * and WebView does not provide any UI for showing the details of the
@@ -382,10 +387,10 @@ public class WebViewClient {
      * <p>
      * Application overrides of this method may display custom error pages or
      * silently log issues, but it is strongly recommended to always call
-     * handler.cancel() and never allow proceeding past errors.
+     * {@link SslErrorHandler#cancel} and never allow proceeding past errors.
      *
      * @param view The WebView that is initiating the callback.
-     * @param handler An SslErrorHandler object that will handle the user's
+     * @param handler An {@link SslErrorHandler} that will handle the user's
      *            response.
      * @param error The SSL error object.
      */