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