WebView: clarify docs for onShowCustomView

No change to logic, only docs.

This clarifies the docs for onShowCustomView. This @links to
FLAG_FULLSCREEN, reminds the developer they must override both
onShowCustomView and onHideCustomView, and provides guidance for
CustomViewCallback.

Bug: 143247282
Test: make -j4 docs
Change-Id: I64de3723674da5c138438921cc8232c4bf2a3d98

core/java/android/webkit/WebChromeClient.java

@@ -71,11 +71,24 @@ public class WebChromeClient {
     }
 
     /**
-     * Notify the host application that the current page has entered full
+     * Notify the host application that the current page has entered full screen mode. After this
-     * screen mode. The host application must show the custom View which
+     * call, web content will no longer be rendered in the WebView, but will instead be rendered
-     * contains the web contents — video or other HTML content —
+     * in {@code view}. The host application should add this View to a Window which is configured
-     * in full screen mode. Also see "Full screen support" documentation on
+     * with {@link android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN} flag in order to
-     * {@link WebView}.
+     * actually display this web content full screen.
+     *
+     * <p>The application may explicitly exit fullscreen mode by invoking {@code callback} (ex. when
+     * the user presses the back button). However, this is generally not necessary as the web page
+     * will often show its own UI to close out of fullscreen. Regardless of how the WebView exits
+     * fullscreen mode, WebView will invoke {@link #onHideCustomView()}, signaling for the
+     * application to remove the custom View.
+     *
+     * <p>If this method is not overridden, WebView will report to the web page it does not support
+     * fullscreen mode and will not honor the web page's request to run in fullscreen mode.
+     *
+     * <p class="note"><b>Note:</b> if overriding this method, the application must also override
+     * {@link #onHideCustomView()}.
+     *
      * @param view is the View object to be shown.
      * @param callback invoke this callback to request the page to exit
      * full screen mode.
@@ -98,10 +111,13 @@ public class WebChromeClient {
             CustomViewCallback callback) {};
 
     /**
-     * Notify the host application that the current page has exited full
+     * Notify the host application that the current page has exited full screen mode. The host
-     * screen mode. The host application must hide the custom View, ie. the
+     * application must hide the custom View (the View which was previously passed to {@link
-     * View passed to {@link #onShowCustomView} when the content entered fullscreen.
+     * #onShowCustomView(View, CustomViewCallback) onShowCustomView()}). After this call, web
-     * Also see "Full screen support" documentation on {@link WebView}.
+     * content will render in the original WebView again.
+     *
+     * <p class="note"><b>Note:</b> if overriding this method, the application must also override
+     * {@link #onShowCustomView(View, CustomViewCallback) onShowCustomView()}.
      */
     public void onHideCustomView() {}