Clean up JavaDoc for WebView.getZoomControls()

Bug: 5461416
Change-Id: I4f2b5c9e4b4c2b1a38d678cb6756f128670ee490

Author: Steve Block

core/java/android/webkit/WebSettings.java

@@ -190,15 +190,19 @@ public boolean supportZoom() {
     }
 
     /**
-     * Sets whether the WebView should use its built-in zoom mechanisms, as
-     * opposed to separate zoom controls. The built-in zoom mechanisms comprise
-     * on-screen zoom controls, which are displayed over the WebView's content,
-     * and the use of a pinch gesture to control zooming. Whether or not these
-     * on-screen controls are displayed can be set with {@link #setDisplayZoomControls}.
-     * The separate zoom controls are no longer supported, so it is recommended
-     * that this setting is always enabled.
-     * @param enabled Whether the WebView should use the built-in zoom mechanism.
-     */
+     * Sets whether the WebView should use its built-in zoom mechanisms. The
+     * built-in zoom mechanisms comprise on-screen zoom controls, which are
+     * displayed over the WebView's content, and the use of a pinch gesture to
+     * control zooming. Whether or not these on-screen controls are displayed
+     * can be set with {@link #setDisplayZoomControls}.
+     * <p>
+     * The built-in mechanisms are the only currently supported zoom
+     * mechanisms, so it is recommended that this setting is always enabled.
+     * @param enabled Whether the WebView should use its built-in zoom mechanisms.
+     */
+    // This method was intended to select between the built-in zoom mechanisms
+    // and the separate zoom controls. The latter were obtained using
+    // {@link WebView#getZoomControls}, which is now hidden.
     public void setBuiltInZoomControls(boolean enabled) {
         throw new MustOverrideException();
     }

core/java/android/webkit/WebView.java

@@ -1530,17 +1530,15 @@ public void flingScroll(int vx, int vy) {
     }
 
     /**
-     * Returns a view containing zoom controls i.e. +/- buttons. The caller is
-     * in charge of installing this view to the view hierarchy. This view will
-     * become visible when the user starts scrolling via touch and fade away if
-     * the user does not interact with it.
+     * Gets the zoom controls for the WebView, as a separate View. The caller is
+     * responsible for inserting this View into the layout hierarchy.
      * <p/>
-     * API version 3 introduces a built-in zoom mechanism that is shown
-     * automatically by the MapView. This is the preferred approach for
-     * showing the zoom UI.
+     * API Level 3 introduced built-in zoom mechanisms for the WebView, as
+     * opposed to these separate zoom controls. The built-in mechanisms are
+     * preferred and can be enabled using
+     * {@link WebSettings#setBuiltInZoomControls}.
      *
-     * @deprecated The built-in zoom mechanism is preferred, see
-     *             {@link WebSettings#setBuiltInZoomControls(boolean)}.
+     * @deprecated The built-in zoom mechanisms are preferred.
      * @hide since API version 16.
      */
     @Deprecated