WebView: clean up onReceivedSslError docs

No change to logic, only docs.

This adds {@link}'s for references to SslErrorHandler methods, improving
readability. This also clarifies this API is only called for recoverable
errors.

Fixes: 123042566
Test: m offline-sdk-docs
Change-Id: I0e94c9903e638e2fce59f35ec76eb5566e7ad875

diff --git a/core/java/android/webkit/WebViewClient.java b/core/java/android/webkit/WebViewClient.java
index bdd7a09..a29d449 100644 (file)
--- a/core/java/android/webkit/WebViewClient.java
+++ b/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.
      */