Checkstyle tweaks to DateField widgets. (#12400)

- Added and updated JavaDocs.
- Updated comments.
- Updated to use non-deprecated method calls.
- Removed unnecessary warning suppressions.
- Suppressed warnings for unavoidable deprecation.

10 files changed, 316 insertions, 23 deletions

diff --git a/client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java b/client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java
index fa05cc9b1f..e4fafcc43b 100644
--- a/client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java
+++ b/client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java
@@ -72,12 +72,17 @@ import com.vaadin.shared.util.SharedUtil;
  *            the resolution type which this field is based on (day, month, ...)
  * @since 8.0
  */
-@SuppressWarnings("deprecation")
 public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         extends FocusableFlexTable implements KeyDownHandler, KeyPressHandler,
         MouseOutHandler, MouseDownHandler, MouseUpHandler, BlurHandler,
         FocusHandler, SubPartAware {
 
+    /**
+     * Interface for updating date field value based on the current calendar
+     * panel data or canceling the update.
+     *
+     * @author Vaadin Ltd
+     */
     public interface SubmitListener {
 
         /**
@@ -109,6 +114,12 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
      * {@code focused} value.
      */
     public interface FocusChangeListener {
+        /**
+         * Called when focused date has changed in the calendar panel.
+         *
+         * @param focusedDate
+         *            the currently focused date in the panel
+         */
         void focusChanged(Date focusedDate);
     }
 
@@ -185,7 +196,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
      * Represents a click handler for when a user selects a value by using the
      * mouse
      */
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings({ "unchecked", "deprecation" })
     private ClickHandler dayClickHandler = event -> {
         if (!isEnabled() || isReadonly()) {
             return;
@@ -212,6 +223,9 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
     private Map<String, String> dateStyles = new HashMap<String, String>();
     private DateTimeFormat df = DateTimeFormat.getFormat("yyyy-MM-dd");
 
+    /**
+     * Constructs a calendar panel widget for displaying and selecting a date.
+     */
     public VAbstractCalendarPanel() {
         getElement().setId(DOM.createUniqueId());
         setStyleName(VDateField.CLASSNAME + "-calendarpanel");
@@ -222,6 +236,12 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         addBlurHandler(this);
     }
 
+    /**
+     * Sets the parent date field widget.
+     *
+     * @param parent
+     *            the parent widget
+     */
     public void setParentField(VDateField<R> parent) {
         this.parent = parent;
     }
@@ -384,6 +404,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
     /**
      * Updates year, month, day from focusedDate to value
      */
+    @SuppressWarnings("deprecation")
     private void selectFocused() {
         if (focusedDate != null
                 && isDateInsideRange(focusedDate, getResolution())) {
@@ -418,14 +439,30 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         }
     }
 
+    /**
+     * @deprecated This method is not used by the framework code anymore.
+     * @return {@code false}
+     */
+    @Deprecated
     protected boolean onValueChange() {
         return false;
     }
 
+    /**
+     * Returns the current date resolution.
+     *
+     * @return the resolution
+     */
     public R getResolution() {
         return resolution;
     }
 
+    /**
+     * Sets the current date resolution.
+     *
+     * @param resolution
+     *            the new resolution
+     */
     public void setResolution(R resolution) {
         this.resolution = resolution;
     }
@@ -566,9 +603,11 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
 
         updateAssistiveLabels();
 
+        @SuppressWarnings("deprecation")
         final String monthName = needsMonth
                 ? getDateTimeService().getMonth(displayedMonth.getMonth())
                 : "";
+        @SuppressWarnings("deprecation")
         final int year = displayedMonth.getYear() + 1900;
 
         getFlexCellFormatter().setStyleName(0, 2,
@@ -610,6 +649,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         }
     }
 
+    @SuppressWarnings("deprecation")
     private void updateControlButtonRangeStyles(boolean needsMonth) {
 
         if (focusedDate == null) {
@@ -674,6 +714,12 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         return parent;
     }
 
+    /**
+     * Sets date time service for the widget.
+     *
+     * @param dateTimeService
+     *            date time service
+     */
     public void setDateTimeService(DateTimeService dateTimeService) {
         this.dateTimeService = dateTimeService;
     }
@@ -683,12 +729,22 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
      * selector or not. ISO 8601 defines that a week always starts with a Monday
      * so the week numbers are only shown if this is the case.
      *
-     * @return true if week number should be shown, false otherwise
+     * @return {@code true} if week number should be shown, {@code false}
+     *         otherwise
      */
     public boolean isShowISOWeekNumbers() {
         return showISOWeekNumbers;
     }
 
+    /**
+     * Sets whether ISO 8601 week numbers should be shown in the value selector
+     * or not. ISO 8601 defines that a week always starts with a Monday so the
+     * week numbers are only shown if this is the case.
+     *
+     * @param showISOWeekNumbers
+     *            {@code true} if week number should be shown, {@code false}
+     *            otherwise
+     */
     public void setShowISOWeekNumbers(boolean showISOWeekNumbers) {
         this.showISOWeekNumbers = showISOWeekNumbers;
         if (initialRenderDone && isBelowMonth(resolution)) {
@@ -734,6 +790,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
                 .compareTo(dateStrResolution) <= 0;
     }
 
+    @SuppressWarnings("deprecation")
     private String dateStrResolution(Date date, R minResolution) {
         String dateStrResolution = (1900 + date.getYear()) + "";
         while (dateStrResolution.length() < 4) {
@@ -785,6 +842,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
     /**
      * Builds the day and time selectors of the calendar.
      */
+    @SuppressWarnings("deprecation")
     private void buildCalendarBody() {
 
         final int weekColumn = 0;
@@ -988,6 +1046,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
      *            resolution of the calendar is changed and no date has been
      *            selected.
      */
+    @SuppressWarnings("deprecation")
     protected void doRenderCalendar(boolean updateDate) {
         super.setStylePrimaryName(
                 getDateField().getStylePrimaryName() + "-calendarpanel");
@@ -1021,6 +1080,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
     /**
      * Moves the focus forward the given number of days.
      */
+    @SuppressWarnings("deprecation")
     private void focusNextDay(int days) {
         if (focusedDate == null) {
             return;
@@ -1060,6 +1120,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
     /**
      * Selects the next month
      */
+    @SuppressWarnings("deprecation")
     private void focusNextMonth() {
 
         if (focusedDate == null) {
@@ -1075,8 +1136,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         }
 
         // Now also checking whether the day is inside the range or not. If not
-        // inside,
-        // correct it
+        // inside, correct it
         if (!isDateInsideRange(requestedNextMonthDate,
                 getResolution(this::isDay))) {
             requestedNextMonthDate = adjustDateToFitInsideRange(
@@ -1089,6 +1149,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         renderCalendar();
     }
 
+    @SuppressWarnings("deprecation")
     private static void addOneMonth(Date date) {
         int currentMonth = date.getMonth();
         int requestedMonth = (currentMonth + 1) % 12;
@@ -1105,6 +1166,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         }
     }
 
+    @SuppressWarnings("deprecation")
     private static void removeOneMonth(Date date) {
         int currentMonth = date.getMonth();
 
@@ -1123,6 +1185,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
     /**
      * Selects the previous month
      */
+    @SuppressWarnings("deprecation")
     private void focusPreviousMonth() {
 
         if (focusedDate == null) {
@@ -1150,6 +1213,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
     /**
      * Selects the previous year
      */
+    @SuppressWarnings("deprecation")
     private void focusPreviousYear(int years) {
 
         if (focusedDate == null) {
@@ -1192,6 +1256,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
     /**
      * Selects the next year
      */
+    @SuppressWarnings("deprecation")
     private void focusNextYear(int years) {
 
         if (focusedDate == null) {
@@ -1439,6 +1504,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
      * @return Return true if the key press was handled by the method, else
      *         return false.
      */
+    @SuppressWarnings("deprecation")
     protected boolean handleNavigationDayMode(int keycode, boolean ctrl,
             boolean shift) {
 
@@ -1715,6 +1781,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         return date;
     }
 
+    @SuppressWarnings("deprecation")
     private Date parseRangeString(String dateStr) {
         if (dateStr == null || "".equals(dateStr)) {
             return null;
@@ -1764,6 +1831,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
      *            an additional action which will be executed in case
      *            rerendering is not required
      */
+    @SuppressWarnings("deprecation")
     protected void doSetDate(Date currentDate, boolean needRerender,
             Runnable focusAction) {
         // Check that we are not re-rendering an already active date
@@ -1798,8 +1866,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
                         dateThatFitsInsideRange.getMonth(), 1);
                 // value was adjusted. Set selected to null to not cause
                 // confusion, but this is only needed (and allowed) when we have
-                // a day
-                // resolution
+                // a day resolution
                 if (isDay(getResolution())) {
                     value = null;
                 }
@@ -1836,6 +1903,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
     private class Day extends InlineHTML {
         private final Date date;
 
+        @SuppressWarnings("deprecation")
         Day(Date date) {
             super("" + date.getDate());
             this.date = date;
@@ -1847,6 +1915,11 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         }
     }
 
+    /**
+     * Returns the current date value.
+     *
+     * @return current date value
+     */
     public Date getDate() {
         return value;
     }
@@ -1955,6 +2028,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
 
     private String rangeEnd;
 
+    @SuppressWarnings("deprecation")
     @Override
     public String getSubPartName(
             com.google.gwt.user.client.Element subElement) {
@@ -2008,7 +2082,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
         return w.getElement().isOrHasChild(subElement);
     }
 
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings({ "unchecked", "deprecation" })
     @Override
     public com.google.gwt.user.client.Element getSubPartElement(
             String subPart) {
@@ -2064,6 +2138,20 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
      */
     public class FocusedDate extends Date {
 
+        /**
+         * Constructs a date instance that keeps track of the currently selected
+         * date within the calendar panel and updates the related text field
+         * accordingly if there is one.
+         *
+         * @param year
+         *            the year value
+         * @param month
+         *            the month value between 0-11
+         * @param date
+         *            the day of the month value between 1-31
+         * @see FocusedDate
+         */
+        @SuppressWarnings("deprecation")
         public FocusedDate(int year, int month, int date) {
             super(year, month, date);
         }
diff --git a/client/src/main/java/com/vaadin/client/ui/VAbstractDateFieldCalendar.java b/client/src/main/java/com/vaadin/client/ui/VAbstractDateFieldCalendar.java
index 7ae639d0b5..56adf9e3f4 100644
--- a/client/src/main/java/com/vaadin/client/ui/VAbstractDateFieldCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VAbstractDateFieldCalendar.java
@@ -20,6 +20,12 @@ import com.vaadin.client.ui.VAbstractCalendarPanel.SubmitListener;
 
 /**
  * A client side implementation for inline date field.
+ *
+ * @param <PANEL>
+ *            the calendar panel type this field uses
+ * @param <R>
+ *            the resolution type which this field is based on (day, month, ...)
+ * @author Vaadin Ltd
  */
 public abstract class VAbstractDateFieldCalendar<PANEL extends VAbstractCalendarPanel<R>, R extends Enum<R>>
         extends VDateField<R> {
@@ -27,6 +33,14 @@ public abstract class VAbstractDateFieldCalendar<PANEL extends VAbstractCalendar
     /** For internal use only. May be removed or replaced in the future. */
     public final PANEL calendarPanel;
 
+    /**
+     * Constructs a date selection widget with an inline date/time selector.
+     *
+     * @param panel
+     *            the calendar panel instance that should be displayed
+     * @param resolution
+     *            the resolution this widget should display (day, month, ...)
+     */
     public VAbstractDateFieldCalendar(PANEL panel, R resolution) {
         super(resolution);
         calendarPanel = panel;
@@ -40,8 +54,7 @@ public abstract class VAbstractDateFieldCalendar<PANEL extends VAbstractCalendar
 
             @Override
             public void onCancel() {
-                // TODO Auto-generated method stub
-
+                // NOP
             }
         });
         calendarPanel.setFocusOutListener(event -> {
@@ -50,13 +63,28 @@ public abstract class VAbstractDateFieldCalendar<PANEL extends VAbstractCalendar
         });
     }
 
-    @SuppressWarnings("deprecation")
+    /**
+     * Update buffered values and send them (if any) to the server.
+     */
     public abstract void updateValueFromPanel();
 
+    /**
+     * Sets the tabulator index for the calendar panel element that represents
+     * the entire widget in the browser's focus cycle.
+     *
+     * @param tabIndex
+     *            the new tabulator index
+     */
     public void setTabIndex(int tabIndex) {
         calendarPanel.getElement().setTabIndex(tabIndex);
     }
 
+    /**
+     * Returns the tabulator index of the calendar panel element that represents
+     * the entire widget in the browser's focus cycle.
+     *
+     * @return the tabulator index
+     */
     public int getTabIndex() {
         return calendarPanel.getElement().getTabIndex();
     }
diff --git a/client/src/main/java/com/vaadin/client/ui/VAbstractPopupCalendar.java b/client/src/main/java/com/vaadin/client/ui/VAbstractPopupCalendar.java
index c268393a3e..81bcc7475a 100644
--- a/client/src/main/java/com/vaadin/client/ui/VAbstractPopupCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VAbstractPopupCalendar.java
@@ -57,7 +57,12 @@ import com.vaadin.shared.ui.datefield.TextualDateFieldState;
  * then pass set it by calling the
  * <code>setCalendarPanel(VAbstractCalendarPanel panel)</code> method.
  *
+ * @param <PANEL>
+ *            the calendar panel type this field uses
+ * @param <R>
+ *            the resolution type which this field is based on (day, month, ...)
  * @since 8.0
+ * @author Vaadin Ltd
  */
 public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPanel<R>, R extends Enum<R>>
         extends VAbstractTextualDate<R>
@@ -70,6 +75,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
     public PANEL calendar;
 
     /** For internal use only. May be removed or replaced in the future. */
+    @SuppressWarnings("deprecation")
     public final VOverlay popup;
 
     /** For internal use only. May be removed or replaced in the future. */
@@ -96,6 +102,17 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
 
     private static final String CALENDAR_TOGGLE_ID = "popupButton";
 
+    /**
+     * Constructs a date selection widget with a text field and a pop-up
+     * date/time selector.
+     *
+     * @param calendarPanel
+     *            the calendar panel instance that should be displayed in the
+     *            pop-up
+     * @param resolution
+     *            the resolution this widget should display (day, month, ...)
+     */
+    @SuppressWarnings("deprecation")
     public VAbstractPopupCalendar(PANEL calendarPanel, R resolution) {
         super(resolution);
 
@@ -139,7 +156,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
 
         // FIXME: Problem is, that the element with the provided id does not
         // exist yet in html. This is the same problem as with the context menu.
-        // Apply here the same fix (#11795)
+        // Apply here the same fix (#3901)
         Roles.getTextboxRole().setAriaControlsProperty(text.getElement(),
                 Id.of(calendar.getElement()));
         Roles.getButtonRole().setAriaControlsProperty(
@@ -182,8 +199,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
         popup.setWidget(wrapper);
         popup.addCloseHandler(this);
 
-        DOM.setElementProperty(calendar.getElement(), "id",
-                "PID_VAADIN_POPUPCAL");
+        calendar.getElement().setPropertyString("id", "PID_VAADIN_POPUPCAL");
 
         sinkEvents(Event.ONKEYDOWN);
 
@@ -207,7 +223,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
     /**
      * Changes the current date, and updates the
      * {@link VDateField#bufferedResolutions}, possibly
-     * {@link VDateField#sendBufferedValues()} to the server if needed
+     * {@link VDateField#sendBufferedValues()} to the server if needed.
      *
      * @param newDate
      *            the new {@code Date} to update
@@ -247,15 +263,29 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
      * Sets the state of the text field of this component. By default the text
      * field is enabled. Disabling it causes only the button for date selection
      * to be active, thus preventing the user from entering invalid dates. See
-     * <a href="http://dev.vaadin.com/ticket/6790>#6790</a>.
+     * <a href="http://dev.vaadin.com/ticket/6790">#6790</a>.
+     * <p>
+     * If the text field is enabled, it represents this widget within the
+     * browser's tabulator focus cycle. When the text field is disabled, that
+     * role is instead given to the date selection button. If the entire
+     * component is disabled, the focus cycle skips this widget altogether.
      *
      * @param textFieldEnabled
+     *            {@code true} if the text field should be enabled,
+     *            {@code false} if disabled
      */
     public void setTextFieldEnabled(boolean textFieldEnabled) {
         this.textFieldEnabled = textFieldEnabled;
         updateTextFieldEnabled();
     }
 
+    /**
+     * Updates the text field's enabled status to correspond with the latest
+     * value set through {@link #setTextFieldEnabled(boolean)} and this
+     * component's general {@link #setEnabled(boolean)}.
+     *
+     * @see #setTextFieldEnabled(boolean)
+     */
     protected void updateTextFieldEnabled() {
         boolean reallyEnabled = isEnabled() && isTextFieldEnabled();
         // IE has a non input disabled themeing that can not be overridden so we
@@ -302,6 +332,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
         }
     }
 
+    @SuppressWarnings("deprecation")
     @Override
     public void bindAriaCaption(
             com.google.gwt.user.client.Element captionElement) {
@@ -536,7 +567,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
      * Get the key code that opens the calendar panel. By default it is the down
      * key but you can override this to be whatever you like
      *
-     * @return
+     * @return the key code that opens the calendar panel
      */
     protected int getOpenCalenderPanelKey() {
         return KeyCodes.KEY_DOWN;
@@ -552,6 +583,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
         }
     }
 
+    @SuppressWarnings("deprecation")
     @Override
     public com.google.gwt.user.client.Element getSubPartElement(
             String subPart) {
@@ -562,6 +594,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
         return super.getSubPartElement(subPart);
     }
 
+    @SuppressWarnings("deprecation")
     @Override
     public String getSubPartName(
             com.google.gwt.user.client.Element subElement) {
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateCalendarPanel.java b/client/src/main/java/com/vaadin/client/ui/VDateCalendarPanel.java
index 6970d7d26f..d03f46e648 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateCalendarPanel.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateCalendarPanel.java
@@ -18,6 +18,8 @@ package com.vaadin.client.ui;
 import com.vaadin.shared.ui.datefield.DateResolution;
 
 /**
+ * A calendar panel widget to show and select a date.
+ *
  * @author Vaadin Ltd
  * @since 8.0
  */
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateField.java b/client/src/main/java/com/vaadin/client/ui/VDateField.java
index 07389617a0..a4f97a1342 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateField.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateField.java
@@ -41,6 +41,7 @@ import com.vaadin.shared.ui.datefield.AbstractDateFieldServerRpc;
 public abstract class VDateField<R extends Enum<R>> extends FlowPanel
         implements Field, HasEnabled {
 
+    /** Default classname for this widget. */
     public static final String CLASSNAME = "v-datefield";
 
     /** For internal use only. May be removed or replaced in the future. */
@@ -51,10 +52,13 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
 
     private R currentResolution;
 
+    /** Currently used locale string, e.g. {@code en_US}. */
     protected String currentLocale;
 
+    /** Is the widget read-only or not. */
     protected boolean readonly;
 
+    /** Is the widget enabled or not. */
     protected boolean enabled;
 
     /**
@@ -99,34 +103,74 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
     /** For internal use only. May be removed or replaced in the future. */
     public DateTimeService dts;
 
+    /** Should ISO 8601 week numbers be shown in the date selector or not. */
     protected boolean showISOWeekNumbers;
 
+    /**
+     * Constructs a widget for a date field.
+     *
+     * @param resolution
+     *            the resolution for this widget (day, month, ...)
+     */
     public VDateField(R resolution) {
         setStyleName(CLASSNAME);
         dts = new DateTimeService();
         currentResolution = resolution;
     }
 
+    /**
+     * Returns the current resolution.
+     *
+     * @return the resolution
+     */
     public R getCurrentResolution() {
         return currentResolution;
     }
 
+    /**
+     * Sets the resolution.
+     *
+     * @param currentResolution
+     *            the new resolution
+     */
     public void setCurrentResolution(R currentResolution) {
         this.currentResolution = currentResolution;
     }
 
+    /**
+     * Returns the current locale String.
+     *
+     * @return the locale String
+     */
     public String getCurrentLocale() {
         return currentLocale;
     }
 
+    /**
+     * Sets the locale String.
+     *
+     * @param currentLocale
+     *            the new locale String.
+     */
     public void setCurrentLocale(String currentLocale) {
         this.currentLocale = currentLocale;
     }
 
+    /**
+     * Returns the current date value.
+     *
+     * @return the date value
+     */
     public Date getCurrentDate() {
         return date;
     }
 
+    /**
+     * Sets the date value.
+     *
+     * @param date
+     *            the new date value
+     */
     public void setCurrentDate(Date date) {
         this.date = date;
     }
@@ -162,6 +206,7 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
      *
      * @see #setCurrentDate(Map)
      * @param defaultValues
+     *            a map from resolutions to date values
      * @since 8.1.2
      */
     public void setDefaultDate(Map<R, Integer> defaultValues) {
@@ -178,10 +223,21 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
         return defaultDate;
     }
 
+    /**
+     * Returns whether this widget is read-only or not.
+     *
+     * @return {@code true} if read-only, {@code false} otherwise
+     */
     public boolean isReadonly() {
         return readonly;
     }
 
+    /**
+     * Sets whether this widget should be read-only or not.
+     *
+     * @param readonly
+     *            {@code true} if read-only, {@code false} otherwise
+     */
     public void setReadonly(boolean readonly) {
         this.readonly = readonly;
     }
@@ -196,14 +252,31 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
         this.enabled = enabled;
     }
 
+    /**
+     * Returns the date time service for this widget.
+     *
+     * @return the date time service
+     */
     public DateTimeService getDateTimeService() {
         return dts;
     }
 
+    /**
+     * Returns the connector id that corresponds with this widget.
+     *
+     * @return the connector id
+     * @deprecated This method is not used by the framework code anymore.
+     */
+    @Deprecated
     public String getId() {
         return connector.getConnectorId();
     }
 
+    /**
+     * Returns the current application connection.
+     *
+     * @return the application connection
+     */
     public ApplicationConnection getClient() {
         return client;
     }
@@ -213,12 +286,22 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
      * selector or not. ISO 8601 defines that a week always starts with a Monday
      * so the week numbers are only shown if this is the case.
      *
-     * @return true if week number should be shown, false otherwise
+     * @return {@code true} if week number should be shown, {@code false}
+     *         otherwise
      */
     public boolean isShowISOWeekNumbers() {
         return showISOWeekNumbers;
     }
 
+    /**
+     * Sets whether ISO 8601 week numbers should be shown in the date selector
+     * or not. ISO 8601 defines that a week always starts with a Monday so the
+     * week numbers are only shown if this is the case.
+     *
+     * @param showISOWeekNumbers
+     *            {@code true} if week number should be shown, {@code false}
+     *            otherwise
+     */
     public void setShowISOWeekNumbers(boolean showISOWeekNumbers) {
         this.showISOWeekNumbers = showISOWeekNumbers;
     }
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateFieldCalendar.java b/client/src/main/java/com/vaadin/client/ui/VDateFieldCalendar.java
index dbe7162d36..5c249c2f6f 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateFieldCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateFieldCalendar.java
@@ -34,11 +34,15 @@ import com.vaadin.shared.ui.datefield.DateResolution;
 public class VDateFieldCalendar
         extends VAbstractDateFieldCalendar<VDateCalendarPanel, DateResolution> {
 
+    /**
+     * Constructs a widget for the InlineDateField component.
+     */
     public VDateFieldCalendar() {
         super(GWT.create(VDateCalendarPanel.class), YEAR);
     }
 
     @Override
+    @SuppressWarnings("deprecation")
     public void updateBufferedValues() {
         // If field is invisible at the beginning, client can still be null when
         // this function is called.
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateTimeCalendarPanel.java b/client/src/main/java/com/vaadin/client/ui/VDateTimeCalendarPanel.java
index e9290a741f..a7d6f63e48 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateTimeCalendarPanel.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateTimeCalendarPanel.java
@@ -20,7 +20,6 @@ import java.util.Date;
 import com.google.gwt.event.dom.client.ChangeEvent;
 import com.google.gwt.event.dom.client.ChangeHandler;
 import com.google.gwt.event.dom.client.KeyCodes;
-import com.google.gwt.user.client.Element;
 import com.google.gwt.user.client.ui.FlowPanel;
 import com.google.gwt.user.client.ui.ListBox;
 import com.google.gwt.user.client.ui.Widget;
@@ -28,6 +27,8 @@ import com.vaadin.client.DateTimeService;
 import com.vaadin.shared.ui.datefield.DateTimeResolution;
 
 /**
+ * A calendar panel widget to show and select a date and a time.
+ *
  * @author Vaadin Ltd
  * @since 8.0
  */
@@ -80,6 +81,7 @@ public class VDateTimeCalendarPanel
          * Constructs the ListBoxes and updates their value
          *
          */
+        @SuppressWarnings("deprecation")
         private void buildTime() {
             clear();
 
@@ -201,6 +203,7 @@ public class VDateTimeCalendarPanel
         /**
          * Updates the value to correspond to the values in value.
          */
+        @SuppressWarnings("deprecation")
         public void updateTimes() {
             if (getDate() == null) {
                 setDate(new Date());
@@ -253,6 +256,7 @@ public class VDateTimeCalendarPanel
          * .event.dom.client.ChangeEvent)
          */
         @Override
+        @SuppressWarnings("deprecation")
         public void onChange(ChangeEvent event) {
             /*
              * Value from dropdowns gets always set for the value. Like year and
@@ -311,6 +315,18 @@ public class VDateTimeCalendarPanel
      */
     public interface TimeChangeListener {
 
+        /**
+         * Handle time change.
+         *
+         * @param hour
+         *            the new hour value
+         * @param min
+         *            the new minute value
+         * @param sec
+         *            the new second value
+         * @param msec
+         *            the new millisecond value
+         */
         void changed(int hour, int min, int sec, int msec);
     }
 
@@ -318,6 +334,7 @@ public class VDateTimeCalendarPanel
      * The time change listener is triggered when the user changes the time.
      *
      * @param listener
+     *            the listener to use
      */
     public void setTimeChangeListener(TimeChangeListener listener) {
         timeChangeListener = listener;
@@ -378,7 +395,9 @@ public class VDateTimeCalendarPanel
     }
 
     @Override
-    public String getSubPartName(Element subElement) {
+    @SuppressWarnings("deprecation")
+    public String getSubPartName(
+            com.google.gwt.user.client.Element subElement) {
         if (time != null) {
             if (contains(time.hours, subElement)) {
                 return SUBPART_HOUR_SELECT;
@@ -395,7 +414,9 @@ public class VDateTimeCalendarPanel
     }
 
     @Override
-    public Element getSubPartElement(String subPart) {
+    @SuppressWarnings("deprecation")
+    public com.google.gwt.user.client.Element getSubPartElement(
+            String subPart) {
         if (SUBPART_HOUR_SELECT.equals(subPart)) {
             return time.hours.getElement();
         }
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateTimeFieldCalendar.java b/client/src/main/java/com/vaadin/client/ui/VDateTimeFieldCalendar.java
index 55aa900feb..41c89cc590 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateTimeFieldCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateTimeFieldCalendar.java
@@ -38,11 +38,15 @@ import com.vaadin.shared.ui.datefield.DateTimeResolution;
 public class VDateTimeFieldCalendar extends
         VAbstractDateFieldCalendar<VDateTimeCalendarPanel, DateTimeResolution> {
 
+    /**
+     * Constructs a widget for the InlineDateTimeField component.
+     */
     public VDateTimeFieldCalendar() {
         super(GWT.create(VDateTimeCalendarPanel.class), MINUTE);
     }
 
     @Override
+    @SuppressWarnings("deprecation")
     public void updateBufferedValues() {
         // If field is invisible at the beginning, client can still be null when
         // this function is called.
diff --git a/client/src/main/java/com/vaadin/client/ui/VPopupCalendar.java b/client/src/main/java/com/vaadin/client/ui/VPopupCalendar.java
index 9f38f14201..af2160d5c1 100644
--- a/client/src/main/java/com/vaadin/client/ui/VPopupCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VPopupCalendar.java
@@ -24,6 +24,7 @@ import java.util.Map;
 
 import com.google.gwt.core.client.GWT;
 import com.vaadin.shared.ui.datefield.DateResolution;
+import com.vaadin.shared.ui.datefield.DateTimeResolution;
 
 /**
  * Represents a date selection component with a text field and a popup date
@@ -35,6 +36,11 @@ import com.vaadin.shared.ui.datefield.DateResolution;
 public class VPopupCalendar
         extends VAbstractPopupCalendar<VDateCalendarPanel, DateResolution> {
 
+    /**
+     * Constructs a date selection component with a text field and a pop-up date
+     * selector. Uses a {@link VDateCalendarPanel} as the pop-up content.
+     * Default resolution is {@link DateTimeResolution#YEAR}.
+     */
     public VPopupCalendar() {
         super(GWT.create(VDateCalendarPanel.class), YEAR);
     }
@@ -54,6 +60,15 @@ public class VPopupCalendar
         super.setCurrentResolution(resolution == null ? YEAR : resolution);
     }
 
+    /**
+     * Creates a date based on the provided date values map. Any values of a
+     * more precise resolution than day are ignored.
+     *
+     * @param dateValues
+     *            a map with date values to convert into a date
+     * @return the date based on the dateValues map
+     */
+    @SuppressWarnings("deprecation")
     public static Date makeDate(Map<DateResolution, Integer> dateValues) {
         if (dateValues.get(YEAR) == null) {
             return null;
@@ -85,6 +100,7 @@ public class VPopupCalendar
     }
 
     @Override
+    @SuppressWarnings("deprecation")
     protected void updateBufferedResolutions() {
         super.updateBufferedResolutions();
         Date currentDate = getDate();
diff --git a/client/src/main/java/com/vaadin/client/ui/VPopupTimeCalendar.java b/client/src/main/java/com/vaadin/client/ui/VPopupTimeCalendar.java
index bbd6827400..7a01228875 100644
--- a/client/src/main/java/com/vaadin/client/ui/VPopupTimeCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VPopupTimeCalendar.java
@@ -33,8 +33,8 @@ import com.vaadin.client.LocaleService;
 import com.vaadin.shared.ui.datefield.DateTimeResolution;
 
 /**
- * Represents a date-time selection component with a text field and a popup date
- * selector.
+ * Represents a date-time selection component with a text field and a pop-up
+ * date-and-time selector.
  *
  * @author Vaadin Ltd
  *
@@ -43,6 +43,11 @@ import com.vaadin.shared.ui.datefield.DateTimeResolution;
 public class VPopupTimeCalendar extends
         VAbstractPopupCalendar<VDateTimeCalendarPanel, DateTimeResolution> {
 
+    /**
+     * Constructs a date-time selection component with a text field and a pop-up
+     * date-and-time selector. Uses a {@link VDateTimeCalendarPanel} as the
+     * pop-up content. Default resolution is {@link DateTimeResolution#MINUTE}.
+     */
     public VPopupTimeCalendar() {
         super(GWT.create(VDateTimeCalendarPanel.class), MINUTE);
     }
@@ -65,6 +70,14 @@ public class VPopupTimeCalendar extends
         super.setCurrentResolution(resolution == null ? MINUTE : resolution);
     }
 
+    /**
+     * Creates a date based on the provided date values map.
+     *
+     * @param dateValues
+     *            a map with date values to convert into a date
+     * @return the date based on the dateValues map
+     */
+    @SuppressWarnings("deprecation")
     public static Date makeDate(Map<DateTimeResolution, Integer> dateValues) {
         if (dateValues.get(YEAR) == null) {
             return null;
@@ -108,6 +121,7 @@ public class VPopupTimeCalendar extends
     }
 
     @Override
+    @SuppressWarnings("deprecation")
     protected void updateBufferedResolutions() {
         super.updateBufferedResolutions();
         Date currentDate = getDate();