webkit: Update documentation for onJsConfirm, onJsPrompt callbacks

Fix documentation to clearly indicate that the default behavior is to
show WebView's own default dialog, and also describing clearly default
dialog behavior and how to customize it.

Note that onJsBeforeUnload is not updated at the moment as I could not
find a way to reproduce it.

Bug: 154014645
Test: m -j offline-sdk-docs seems not broken

Change-Id: I5ee09ea35340eb8d17353eda1786dcebcff4a29e

1 files changed, 44 insertions, 12 deletions

diff --git a/core/java/android/webkit/WebChromeClient.java b/core/java/android/webkit/WebChromeClient.java
index f78ec7c439a1..0807f4162162 100644
--- a/core/java/android/webkit/WebChromeClient.java
+++ b/core/java/android/webkit/WebChromeClient.java
@@ -219,17 +219,34 @@ public class WebChromeClient {
     }
 
     /**
-     * Tell the client to display a confirm dialog to the user. If the client
-     * returns {@code true}, WebView will assume that the client will handle the
-     * confirm dialog and call the appropriate JsResult method. If the
-     * client returns false, a default value of {@code false} will be returned to
-     * javascript. The default behavior is to return {@code false}.
+     * Notify the host application that the web page wants to display a
+     * JavaScript {@code confirm()} dialog.
+     * <p>The default behavior if this method returns {@code false} or is not
+     * overridden is to show a dialog containing the message and suspend
+     * JavaScript execution until the dialog is dismissed. The default dialog
+     * will return {@code true} to the JavaScript {@code confirm()} code when
+     * the user presses the 'confirm' button, and will return {@code false} to
+     * the JavaScript code when the user presses the 'cancel' button or
+     * dismisses the dialog.
+     * <p>To show a custom dialog, the app should return {@code true} from this
+     * method, in which case the default dialog will not be shown and JavaScript
+     * execution will be suspended. The app should call
+     * {@code JsResult.confirm()} or {@code JsResult.cancel()} when the custom
+     * dialog is dismissed.
+     * <p>To suppress the dialog and allow JavaScript execution to continue,
+     * call {@code JsResult.confirm()} or {@code JsResult.cancel()} immediately
+     * and then return {@code true}.
+     * <p>Note that if the {@link WebChromeClient} is {@code null}, the default
+     * dialog will be suppressed and the default value of {@code false} will be
+     * returned to the JavaScript code immediately.
+     *
      * @param view The WebView that initiated the callback.
      * @param url The url of the page requesting the dialog.
      * @param message Message to be displayed in the window.
      * @param result A JsResult used to send the user's response to
      *               javascript.
-     * @return boolean Whether the client will handle the confirm dialog.
+     * @return boolean {@code true} if the request is handled or ignored.
+     * {@code false} if WebView needs to show the default dialog.
      */
     public boolean onJsConfirm(WebView view, String url, String message,
             JsResult result) {
@@ -237,18 +254,33 @@ public class WebChromeClient {
     }
 
     /**
-     * Tell the client to display a prompt dialog to the user. If the client
-     * returns {@code true}, WebView will assume that the client will handle the
-     * prompt dialog and call the appropriate JsPromptResult method. If the
-     * client returns false, a default value of {@code false} will be returned to to
-     * javascript. The default behavior is to return {@code false}.
+     * Notify the host application that the web page wants to display a
+     * JavaScript {@code prompt()} dialog.
+     * <p>The default behavior if this method returns {@code false} or is not
+     * overridden is to show a dialog containing the message and suspend
+     * JavaScript execution until the dialog is dismissed. Once the dialog is
+     * dismissed, JavaScript {@code prompt()} will return the string that the
+     * user typed in, or null if the user presses the 'cancel' button.
+     * <p>To show a custom dialog, the app should return {@code true} from this
+     * method, in which case the default dialog will not be shown and JavaScript
+     * execution will be suspended. The app should call
+     * {@code JsPromptResult.confirm(result)} when the custom dialog is
+     * dismissed.
+     * <p>To suppress the dialog and allow JavaScript execution to continue,
+     * call {@code JsPromptResult.confirm(result)} immediately and then
+     * return {@code true}.
+     * <p>Note that if the {@link WebChromeClient} is {@code null}, the default
+     * dialog will be suppressed and {@code null} will be returned to the
+     * JavaScript code immediately.
+     *
      * @param view The WebView that initiated the callback.
      * @param url The url of the page requesting the dialog.
      * @param message Message to be displayed in the window.
      * @param defaultValue The default value displayed in the prompt dialog.
      * @param result A JsPromptResult used to send the user's reponse to
      *               javascript.
-     * @return boolean Whether the client will handle the prompt dialog.
+     * @return boolean {@code true} if the request is handled or ignored.
+     * {@code false} if WebView needs to show the default dialog.
      */
     public boolean onJsPrompt(WebView view, String url, String message,
             String defaultValue, JsPromptResult result) {