Improve documentation and rename insertVisualStateCallback to postVisualStateCallback.

Bug: 21043955
Change-Id: I077cad68fb519581387d1b474f27d43222f68e3b

2 files changed, 40 insertions, 33 deletions

diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java
index e27e253..37b59d0 100644
--- a/core/java/android/webkit/WebView.java
+++ b/core/java/android/webkit/WebView.java
@@ -366,15 +366,15 @@ public class WebView extends AbsoluteLayout
     }
 
     /**
-     * Callback interface supplied to {@link #insertVisualStateCallback} for receiving
+     * Callback interface supplied to {@link #postVisualStateCallback} for receiving
      * notifications about the visual state.
      */
     public static abstract class VisualStateCallback {
         /**
          * Invoked when the visual state is ready to be drawn in the next {@link #onDraw}.
          *
-         * @param requestId the id supplied to the corresponding {@link #insertVisualStateCallback}
-         * request
+         * @param requestId The identifier passed to {@link #postVisualStateCallback} when this
+         *                  callback was posted.
          */
         public abstract void onComplete(long requestId);
     }
@@ -1125,15 +1125,18 @@ public class WebView extends AbsoluteLayout
     }
 
     /**
-     * Inserts a {@link VisualStateCallback}.
+     * Posts a {@link VisualStateCallback}, which will be called when
+     * the current state of the WebView is ready to be drawn.
      *
-     * <p>Updates to the the DOM are reflected asynchronously such that when the DOM is updated the
-     * subsequent {@link WebView#onDraw} invocation might not reflect those updates. The
+     * <p>Because updates to the the DOM are processed asynchronously, updates to the DOM may not
+     * immediately be reflected visually by subsequent {@link WebView#onDraw} invocations. The
      * {@link VisualStateCallback} provides a mechanism to notify the caller when the contents of
-     * the DOM at the current time are ready to be drawn the next time the {@link WebView} draws.
-     * By current time we mean the time at which this API was called. The next draw after the
-     * callback completes is guaranteed to reflect all the updates to the DOM applied before the
-     * current time, but it may also contain updates applied after the current time.</p>
+     * the DOM at the current time are ready to be drawn the next time the {@link WebView}
+     * draws.</p>
+     *
+     * <p>The next draw after the callback completes is guaranteed to reflect all the updates to the
+     * DOM up to the the point at which the {@link VisualStateCallback} was posted, but it may also
+     * contain updates applied after the callback was posted.</p>
      *
      * <p>The state of the DOM covered by this API includes the following:
      * <ul>
@@ -1164,15 +1167,15 @@ public class WebView extends AbsoluteLayout
      * {@link VisualStateCallback#onComplete} method.</li>
      * </ul></p>
      *
-     * <p>When using this API it is also recommended to enable pre-rasterization if the
-     * {@link WebView} is offscreen to avoid flickering. See WebSettings#setOffscreenPreRaster for
+     * <p>When using this API it is also recommended to enable pre-rasterization if the {@link
+     * WebView} is offscreen to avoid flickering. See {@link WebSettings#setOffscreenPreRaster} for
      * more details and do consider its caveats.</p>
      *
-     * @param requestId an id that will be returned in the callback to allow callers to match
-     * requests with callbacks.
-     * @param callback the callback to be invoked.
+     * @param requestId An id that will be returned in the callback to allow callers to match
+     *                  requests with callbacks.
+     * @param callback  The callback to be invoked.
      */
-    public void insertVisualStateCallback(long requestId, VisualStateCallback callback) {
+    public void postVisualStateCallback(long requestId, VisualStateCallback callback) {
         checkThread();
         mProvider.insertVisualStateCallback(requestId, callback);
     }
diff --git a/core/java/android/webkit/WebViewClient.java b/core/java/android/webkit/WebViewClient.java
index 8a2b3fa..3a40de6 100644
--- a/core/java/android/webkit/WebViewClient.java
+++ b/core/java/android/webkit/WebViewClient.java
@@ -83,27 +83,31 @@ public class WebViewClient {
     }
 
     /**
-     * Notify the host application that the page commit is visible.
+     * Notify the host application that {@link android.webkit.WebView} content left over from
+     * previous page navigations will no longer be drawn.
      *
-     * <p>This is the earliest point at which we can guarantee that the contents of the previously
-     * loaded page will not longer be drawn in the next {@link WebView#onDraw}. The next draw will
-     * render the {@link WebView#setBackgroundColor background color} of the WebView or some of the
-     * contents from the committed page already. This callback may be useful when reusing
-     * {@link WebView}s to ensure that no stale content is shown. This method is only called for
-     * the main frame.</p>
+     * <p>This callback can be used to determine the point at which it is safe to make a recycled
+     * {@link android.webkit.WebView} visible, ensuring that no stale content is shown. It is called
+     * at the earliest point at which it can be guaranteed that {@link WebView#onDraw} will no
+     * longer draw any content from previous navigations. The next draw will display either the
+     * {@link WebView#setBackgroundColor background color} of the {@link WebView}, or some of the
+     * contents of the newly loaded page.
      *
-     * <p>This method is called when the state of the DOM at the point at which the
-     * body of the HTTP response (commonly the string of html) had started loading will be visible.
-     * If you set a background color for the page in the HTTP response body this will most likely
-     * be visible and perhaps some other elements. At that point no other resources had usually
-     * been loaded, so you can expect images for example to not be visible. If you want
-     * a finer level of granularity consider calling {@link WebView#insertVisualStateCallback}
-     * directly.</p>
+     * <p>This method is called when the body of the HTTP response has started loading, is reflected
+     * in the DOM, and will be visible in subsequent draws. This callback occurs early in the
+     * document loading process, and as such you should expect that linked resources (for example,
+     * css and images) may not be available.</p>
      *
-     * <p>Please note that all the conditions and recommendations presented in
-     * {@link WebView#insertVisualStateCallback} also apply to this API.<p>
+     * <p>For more fine-grained notification of visual state updates, see {@link
+     * WebView#postVisualStateCallback}.</p>
      *
-     * @param url the url of the committed page
+     * <p>Please note that all the conditions and recommendations applicable to
+     * {@link WebView#postVisualStateCallback} also apply to this API.<p>
+     *
+     * <p>This callback is only called for main frame navigations.</p>
+     *
+     * @param view The {@link android.webkit.WebView} for which the navigation occurred.
+     * @param url  The URL corresponding to the page navigation that triggered this callback.
      */
     public void onPageCommitVisible(WebView view, String url) {
     }