Some Checkstyle fixes. (#12379)

- Added and updated JavaDocs.
- Deprecated unused fields and methods that update them.
- Suppressed unavoidable deprecated calls.
- Switched other deprecated calls to use currently recommended calls.

5 files changed, 275 insertions, 15 deletions

diff --git a/client/src/main/java/com/vaadin/client/ui/VPopupView.java b/client/src/main/java/com/vaadin/client/ui/VPopupView.java
index d5c5ed7f9d..705a018ad7 100644
--- a/client/src/main/java/com/vaadin/client/ui/VPopupView.java
+++ b/client/src/main/java/com/vaadin/client/ui/VPopupView.java
@@ -46,9 +46,16 @@ import com.vaadin.client.ui.ShortcutActionHandler.ShortcutActionHandlerOwner;
 import com.vaadin.client.ui.popupview.VisibilityChangeEvent;
 import com.vaadin.client.ui.popupview.VisibilityChangeHandler;
 
+/**
+ * Widget class for the PopupView component.
+ *
+ * @author Vaadin Ltd
+ *
+ */
 public class VPopupView extends HTML
         implements HasEnabled, Iterable<Widget>, DeferredWorker {
 
+    /** Default classname for this widget. */
     public static final String CLASSNAME = "v-popupview";
 
     /**
@@ -113,7 +120,12 @@ public class VPopupView extends HTML
         popup.setAutoHideOnHistoryEventsEnabled(false);
     }
 
-    /** For internal use only. May be removed or replaced in the future. */
+    /**
+     * For internal use only. May be removed or replaced in the future.
+     *
+     * @param popup
+     *            the popup that should be shown
+     */
     public void preparePopup(final CustomPopup popup) {
         popup.setVisible(true);
         popup.setWidget(loading);
@@ -130,6 +142,7 @@ public class VPopupView extends HTML
      * Can be overridden to customize the popup position.
      *
      * @param popup
+     *            the popup whose position should be updated
      */
     public void showPopup(final CustomPopup popup) {
         popup.setPopupPosition(0, 0);
@@ -220,6 +233,7 @@ public class VPopupView extends HTML
      * (other than it being a VOverlay) is to be considered private and
      * potentially subject to change.
      */
+    @SuppressWarnings("deprecation")
     public class CustomPopup extends VOverlay
             implements StateChangeEvent.StateChangeHandler {
 
@@ -237,6 +251,11 @@ public class VPopupView extends HTML
 
         private ShortcutActionHandler shortcutActionHandler;
 
+        /**
+         * Constructs a popup widget for VPopupView.
+         *
+         * @see CustomPopup
+         */
         public CustomPopup() {
             super(true, false); // autoHide, not modal
             setOwner(VPopupView.this);
@@ -361,6 +380,13 @@ public class VPopupView extends HTML
             return super.remove(w);
         }
 
+        /**
+         * Sets the connector of the popup content widget. Should not be
+         * {@code null}.
+         *
+         * @param newPopupComponent
+         *            the connector to set
+         */
         public void setPopupConnector(ComponentConnector newPopupComponent) {
 
             if (newPopupComponent != popupComponentConnector) {
@@ -377,6 +403,15 @@ public class VPopupView extends HTML
 
         }
 
+        /**
+         * Should this popup automatically hide when the user takes the mouse
+         * cursor out of the popup area? If this is {@code false}, the user must
+         * click outside the popup to close it. The default is {@code true}.
+         *
+         * @param hideOnMouseOut
+         *            {@code true} if this popup should hide when mouse is moved
+         *            away, {@code false} otherwise
+         */
         public void setHideOnMouseOut(boolean hideOnMouseOut) {
             this.hideOnMouseOut = hideOnMouseOut;
         }
@@ -405,6 +440,14 @@ public class VPopupView extends HTML
         }
     }
 
+    /**
+     * Adds the given visibility change handler to this widget.
+     *
+     * @param visibilityChangeHandler
+     *            the handler that should be triggered when visibility changes
+     * @return the registration object for removing the given handler when no
+     *         longer needed
+     */
     public HandlerRegistration addVisibilityChangeHandler(
             final VisibilityChangeHandler visibilityChangeHandler) {
         return addHandler(visibilityChangeHandler,
diff --git a/client/src/main/java/com/vaadin/client/ui/VProgressBar.java b/client/src/main/java/com/vaadin/client/ui/VProgressBar.java
index 2de4288af0..31fc590ae8 100644
--- a/client/src/main/java/com/vaadin/client/ui/VProgressBar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VProgressBar.java
@@ -36,6 +36,7 @@ import com.vaadin.client.StyleConstants;
  */
 public class VProgressBar extends Widget implements HasEnabled {
 
+    /** Default classname for this widget. */
     public static final String PRIMARY_STYLE_NAME = "v-progressbar";
 
     Element wrapper = DOM.createDiv();
@@ -45,6 +46,10 @@ public class VProgressBar extends Widget implements HasEnabled {
     private float state = 0.0f;
     private boolean enabled;
 
+    /**
+     * Constructs a widget for the ProgressBar component or renderer.
+     */
+    @SuppressWarnings("deprecation")
     public VProgressBar() {
         setElement(DOM.createDiv());
         getElement().appendChild(wrapper);
@@ -68,20 +73,52 @@ public class VProgressBar extends Widget implements HasEnabled {
 
     }
 
+    /**
+     * Sets whether or not this progress indicator is indeterminate. In
+     * indeterminate mode there is an animation indicating that the task is
+     * running but without providing any information about the current progress.
+     *
+     * @param indeterminate
+     *            {@code true} to set to indeterminate mode, {@code false}
+     *            otherwise
+     */
     public void setIndeterminate(boolean indeterminate) {
         this.indeterminate = indeterminate;
         setStyleName(getStylePrimaryName() + "-indeterminate", indeterminate);
     }
 
+    /**
+     * Sets the value of this progress bar. The value is a {@code float} between
+     * 0 and 1 where 0 represents no progress at all and 1 represents fully
+     * completed.
+     *
+     * @param state
+     *            the new progress value
+     */
     public void setState(float state) {
         final int size = Math.round(100 * state);
         indicator.getStyle().setWidth(size, Unit.PCT);
     }
 
+    /**
+     * Gets whether or not this progress indicator is indeterminate. In
+     * indeterminate mode there is an animation indicating that the task is
+     * running but without providing any information about the current progress.
+     *
+     * @return {@code true} if set to indeterminate mode, {@code false}
+     *         otherwise
+     */
     public boolean isIndeterminate() {
         return indeterminate;
     }
 
+    /**
+     * Returns the current value of this progress bar. The value is a
+     * {@code float} between 0 and 1 where 0 represents no progress at all and 1
+     * represents fully completed.
+     *
+     * @return the current progress value
+     */
     public float getState() {
         return state;
     }
diff --git a/client/src/main/java/com/vaadin/client/ui/VRadioButtonGroup.java b/client/src/main/java/com/vaadin/client/ui/VRadioButtonGroup.java
index 68965da811..b0904c449c 100644
--- a/client/src/main/java/com/vaadin/client/ui/VRadioButtonGroup.java
+++ b/client/src/main/java/com/vaadin/client/ui/VRadioButtonGroup.java
@@ -53,8 +53,11 @@ import elemental.json.JsonObject;
 public class VRadioButtonGroup extends FocusableFlowPanelComposite
         implements Field, ClickHandler, HasEnabled {
 
+    /** Default classname for this widget. */
     public static final String CLASSNAME = "v-select-optiongroup";
+    /** Default classname for all radio buttons within this widget. */
     public static final String CLASSNAME_OPTION = "v-select-option";
+    /** Default classname for the selected radio button within this widget. */
     public static final String CLASSNAME_OPTION_SELECTED = "v-select-option-selected";
 
     private final Map<RadioButton, JsonObject> optionsToItems;
@@ -72,6 +75,9 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite
     private final String groupId;
     private List<Consumer<JsonObject>> selectionChangeListeners;
 
+    /**
+     * Constructs a widget for the RadioButtonGroup component.
+     */
     public VRadioButtonGroup() {
         groupId = DOM.createUniqueId();
         getWidget().setStyleName(CLASSNAME);
@@ -80,8 +86,11 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite
         selectionChangeListeners = new ArrayList<>();
     }
 
-    /*
-     * Build all the options
+    /**
+     * Build all the options.
+     *
+     * @param items
+     *            the list of options
      */
     public void buildOptions(List<JsonObject> items) {
         Roles.getRadiogroupRole().set(getElement());
@@ -194,6 +203,14 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite
         }
     }
 
+    /**
+     * Sets the tabulator index for the container element that holds the radio
+     * buttons. It represents the entire radio button group within the browser's
+     * focus cycle.
+     *
+     * @param tabIndex
+     *            tabulator index for the radio button group
+     */
     public void setTabIndex(int tabIndex) {
         for (Widget anOptionsContainer : getWidget()) {
             FocusWidget widget = (FocusWidget) anOptionsContainer;
@@ -201,9 +218,11 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite
         }
     }
 
+    /**
+     * Sets radio buttons enabled according to this widget's enabled and
+     * read-only status, as well as each option's own enabled status.
+     */
     protected void updateEnabledState() {
-        // sets options enabled according to the widget's enabled,
-        // readonly and each options own enabled
         for (Map.Entry<RadioButton, JsonObject> entry : optionsToItems
                 .entrySet()) {
             RadioButton radioButton = entry.getKey();
@@ -214,10 +233,28 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite
         }
     }
 
+    /**
+     * Returns whether HTML is allowed in the item captions.
+     *
+     * @return {@code true} if the captions are used as HTML, {@code false} if
+     *         used as plain text
+     */
     public boolean isHtmlContentAllowed() {
         return htmlContentAllowed;
     }
 
+    /**
+     * Sets whether HTML is allowed in the item captions. If set to
+     * {@code true}, the captions are displayed as HTML and the developer is
+     * responsible for ensuring no harmful HTML is used. If set to
+     * {@code false}, the content is displayed as plain text.
+     * <p>
+     * This value is delegated from the RadioButtonGroupState.
+     *
+     * @param htmlContentAllowed
+     *            {@code true} if the captions are used as HTML, {@code false}
+     *            if used as plain text
+     */
     public void setHtmlContentAllowed(boolean htmlContentAllowed) {
         this.htmlContentAllowed = htmlContentAllowed;
     }
@@ -227,10 +264,22 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite
         return enabled;
     }
 
+    /**
+     * Returns whether this radio button group is read-only or not.
+     *
+     * @return {@code true} if this widget is read-only, {@code false} otherwise
+     */
     public boolean isReadonly() {
         return readonly;
     }
 
+    /**
+     * Sets the read-only status of this radio button group.
+     *
+     * @param readonly
+     *            {@code true} if this widget should be read-only, {@code false}
+     *            otherwise
+     */
     public void setReadonly(boolean readonly) {
         if (this.readonly != readonly) {
             this.readonly = readonly;
@@ -246,6 +295,14 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite
         }
     }
 
+    /**
+     * Adds the given selection change handler to this widget.
+     *
+     * @param selectionChanged
+     *            the handler that should be triggered when selection changes
+     * @return the registration object for removing the given handler when no
+     *         longer needed
+     */
     public Registration addSelectionChangeHandler(
             Consumer<JsonObject> selectionChanged) {
         selectionChangeListeners.add(selectionChanged);
@@ -253,6 +310,12 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite
                 .remove(selectionChanged);
     }
 
+    /**
+     * Removes previous selection and adds new selection.
+     *
+     * @param selectedItemKey
+     *            the key of the selected radio button
+     */
     public void selectItemKey(String selectedItemKey) {
         // At most one item could be selected so reset all radio buttons
         // before applying current selection
diff --git a/client/src/main/java/com/vaadin/client/ui/VSlider.java b/client/src/main/java/com/vaadin/client/ui/VSlider.java
index ba639e87f3..58551cb26b 100644
--- a/client/src/main/java/com/vaadin/client/ui/VSlider.java
+++ b/client/src/main/java/com/vaadin/client/ui/VSlider.java
@@ -53,23 +53,43 @@ public class VSlider extends SimpleFocusablePanel
      */
     private static final int MIN_SIZE = 50;
 
+    /**
+     * Current client-side communication engine.
+     *
+     * @deprecated this field is no longer used by the framework
+     */
+    @Deprecated
     protected ApplicationConnection client;
 
+    /**
+     * Current connector id.
+     *
+     * @deprecated this field is no longer used by the framework
+     */
+    @Deprecated
     protected String id;
 
+    /** Is this widget disabled. */
     protected boolean disabled;
+    /** Is this widget read-only. */
     protected boolean readonly;
 
     private int acceleration = 1;
+    /** Minimum value of slider. */
     protected double min;
+    /** Maximum value of slider. */
     protected double max;
+    /** Resolution (precision level) of slider. */
     protected int resolution;
+    /** Current value of slider. */
     protected Double value;
 
     private boolean updateValueOnClick;
+    /** Current orientation (vertical/horizontal) of slider. */
     protected SliderOrientation orientation = SliderOrientation.HORIZONTAL;
 
     private final HTML feedback = new HTML("", false);
+    @SuppressWarnings("deprecation")
     private final VOverlay feedbackPopup = new VOverlay(true, false) {
         {
             setOwner(VSlider.this);
@@ -82,20 +102,20 @@ public class VSlider extends SimpleFocusablePanel
         }
     };
 
-    /* DOM element for slider's base */
+    /** DOM element for slider's base. */
     private final Element base;
     private static final int BASE_BORDER_WIDTH = 1;
 
-    /* DOM element for slider's handle */
+    /** DOM element for slider's handle. */
     private final Element handle;
 
-    /* DOM element for decrement arrow */
+    /** DOM element for decrement arrow. */
     private final Element smaller;
 
-    /* DOM element for increment arrow */
+    /** DOM element for increment arrow. */
     private final Element bigger;
 
-    /* Temporary dragging/animation variables */
+    /** Temporary dragging/animation variables. */
     private boolean dragging = false;
 
     private VLazyExecutor delayedValueUpdater = new VLazyExecutor(100, () -> {
@@ -103,6 +123,9 @@ public class VSlider extends SimpleFocusablePanel
         acceleration = 1;
     });
 
+    /**
+     * Constructs a widget for the Slider component.
+     */
     public VSlider() {
         super();
 
@@ -138,6 +161,15 @@ public class VSlider extends SimpleFocusablePanel
         updateStyleNames(style, true);
     }
 
+    /**
+     * Updates the style names for this widget and the child elements.
+     *
+     * @param styleName
+     *            the new style name
+     * @param isPrimaryStyleName
+     *            {@code true} if the new style name is primary, {@code false}
+     *            otherwise
+     */
     protected void updateStyleNames(String styleName,
             boolean isPrimaryStyleName) {
 
@@ -161,6 +193,13 @@ public class VSlider extends SimpleFocusablePanel
         }
     }
 
+    /**
+     * Updates the value shown in the feedback pop-up when the slider is moved.
+     * The value should match the current value of this widget.
+     *
+     * @param value
+     *            the new value to show
+     */
     public void setFeedbackValue(double value) {
         feedback.setText(String.valueOf(value));
     }
@@ -293,7 +332,7 @@ public class VSlider extends SimpleFocusablePanel
 
                 delayedValueUpdater.trigger();
 
-                DOM.eventPreventDefault(event);
+                event.preventDefault();
                 DOM.eventCancelBubble(event, true);
             }
         } else if (targ.equals(getElement())
@@ -321,7 +360,7 @@ public class VSlider extends SimpleFocusablePanel
     }
 
     private void processMouseWheelEvent(final Event event) {
-        final int dir = DOM.eventGetMouseWheelVelocityY(event);
+        final int dir = event.getMouseWheelVelocityY();
 
         if (dir < 0) {
             increaseValue(false);
@@ -331,7 +370,7 @@ public class VSlider extends SimpleFocusablePanel
 
         delayedValueUpdater.trigger();
 
-        DOM.eventPreventDefault(event);
+        event.preventDefault();
         DOM.eventCancelBubble(event, true);
     }
 
@@ -347,7 +386,7 @@ public class VSlider extends SimpleFocusablePanel
                 handle.addClassName(getStylePrimaryName() + "-handle-active");
 
                 DOM.setCapture(getElement());
-                DOM.eventPreventDefault(event); // prevent selecting text
+                event.preventDefault(); // prevent selecting text
                 DOM.eventCancelBubble(event, true);
                 event.stopPropagation();
             }
@@ -432,7 +471,8 @@ public class VSlider extends SimpleFocusablePanel
      * webkit (only browser that really supports touches).
      *
      * @param event
-     * @return
+     *            the event whose position to check
+     * @return the client position
      */
     protected int getEventPosition(Event event) {
         if (isVertical()) {
@@ -442,6 +482,9 @@ public class VSlider extends SimpleFocusablePanel
         }
     }
 
+    /**
+     * Run internal layouting.
+     */
     public void iLayout() {
         if (isVertical()) {
             setHeight();
@@ -555,18 +598,54 @@ public class VSlider extends SimpleFocusablePanel
         return KeyCodes.KEY_RIGHT;
     }
 
+    /**
+     * Sets the current client-side communication engine.
+     *
+     * @param client
+     *            the application connection that manages this component
+     * @deprecated the updated field is no longer used by the framework
+     */
+    @Deprecated
     public void setConnection(ApplicationConnection client) {
         this.client = client;
     }
 
+    /**
+     * Sets the id of this component's connector.
+     *
+     * @param id
+     *            the connector id
+     * @deprecated the updated field is no longer used by the framework
+     */
+    @Deprecated
     public void setId(String id) {
         this.id = id;
     }
 
+    /**
+     * Disables or enables this slider. Users cannot interact with a disabled
+     * widget, and the default styles show it as grayed out (via opacity). The
+     * slider is enabled by default.
+     *
+     * @param disabled
+     *            a boolean value specifying whether the slider should be
+     *            disabled or not
+     * @see #setReadOnly(boolean)
+     */
     public void setDisabled(boolean disabled) {
         this.disabled = disabled;
     }
 
+    /**
+     * Sets the read-only status of this slider. Users cannot interact with a
+     * read-only widget, but the default styles don't show it grayed out unless
+     * it's also disabled. The slider is not read-only by default.
+     *
+     * @param readonly
+     *            a boolean value specifying whether the slider should be in
+     *            read-only mode or not
+     * @see #setDisabled(boolean)
+     */
     public void setReadOnly(boolean readonly) {
         this.readonly = readonly;
     }
@@ -575,6 +654,13 @@ public class VSlider extends SimpleFocusablePanel
         return orientation == SliderOrientation.VERTICAL;
     }
 
+    /**
+     * Sets the slider orientation. Updates the style names if the given
+     * orientation differs from previously set orientation.
+     *
+     * @param orientation
+     *            the orientation to use
+     */
     public void setOrientation(SliderOrientation orientation) {
         if (this.orientation != orientation) {
             this.orientation = orientation;
@@ -582,14 +668,35 @@ public class VSlider extends SimpleFocusablePanel
         }
     }
 
+    /**
+     * Sets the minimum value for slider.
+     *
+     * @param value
+     *            the minimum value to use
+     */
     public void setMinValue(double value) {
         min = value;
     }
 
+    /**
+     * Sets the maximum value for slider.
+     *
+     * @param value
+     *            the maximum value to use
+     */
     public void setMaxValue(double value) {
         max = value;
     }
 
+    /**
+     * Sets the resolution (precision level) for slider as the number of
+     * fractional digits that are considered significant. Determines how big
+     * change is used when increasing or decreasing the value, and where more
+     * precise values get rounded.
+     *
+     * @param resolution
+     *            the number of digits after the decimal point
+     */
     public void setResolution(int resolution) {
         this.resolution = resolution;
     }
@@ -664,6 +771,7 @@ public class VSlider extends SimpleFocusablePanel
         }
     }
 
+    @SuppressWarnings("deprecation")
     @Override
     public com.google.gwt.user.client.Element getSubPartElement(
             String subPart) {
@@ -674,6 +782,7 @@ public class VSlider extends SimpleFocusablePanel
         return null;
     }
 
+    @SuppressWarnings("deprecation")
     @Override
     public String getSubPartName(
             com.google.gwt.user.client.Element subElement) {
@@ -687,6 +796,8 @@ public class VSlider extends SimpleFocusablePanel
      * Specifies whether or not click event should update the Slider's value.
      *
      * @param updateValueOnClick
+     *            {@code true} if a click should update slider's value,
+     *            {@code false} otherwise
      */
     public void setUpdateValueOnClick(boolean updateValueOnClick) {
         this.updateValueOnClick = updateValueOnClick;
diff --git a/client/src/main/java/com/vaadin/client/ui/slider/SliderConnector.java b/client/src/main/java/com/vaadin/client/ui/slider/SliderConnector.java
index 514b4dd360..6bdd25adfe 100644
--- a/client/src/main/java/com/vaadin/client/ui/slider/SliderConnector.java
+++ b/client/src/main/java/com/vaadin/client/ui/slider/SliderConnector.java
@@ -45,9 +45,12 @@ public class SliderConnector extends AbstractFieldConnector
     private final ElementResizeListener resizeListener = event -> getWidget()
             .iLayout();
 
+    @SuppressWarnings("deprecation")
     @Override
     public void init() {
         super.init();
+        // The widget no longer uses the connection, but the value is still set
+        // to ensure backwards compatibility.
         getWidget().setConnection(getConnection());
         getWidget().addValueChangeHandler(this);
 
@@ -78,10 +81,13 @@ public class SliderConnector extends AbstractFieldConnector
         rpc.valueChanged(event.getValue());
     }
 
+    @SuppressWarnings("deprecation")
     @Override
     public void onStateChanged(StateChangeEvent stateChangeEvent) {
         super.onStateChanged(stateChangeEvent);
 
+        // The widget no longer uses the connector id, but the value is still
+        // set to ensure backwards compatibility.
         getWidget().setId(getConnectorId());
         getWidget().setDisabled(!isEnabled());
         getWidget().setReadOnly(isReadOnly());