1 files changed, 21 insertions, 17 deletions
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) {
     }