Update release notes and since tags for 8.4 (#10760)

all/src/main/templates/release-notes.html

@@ -83,6 +83,12 @@ <h2 id="enhancements">Enhancements in Vaadin Framework @version-minor@</h2>
             enhancements. Below is a list of the most notable changes:</p>
 
         <ul>
+            <li><tt>ComboBox</tt> has a better new item handling implementation with <tt>NewItemProvider</tt>.</li>
+            <lli><tt>Binding</tt> APIs have been improved to allow more advanced use.</lli>
+            <li>New <tt>ReadOnlyHasValue</tt> wrapper class for easy implementation of new <tt>HasValue</tt>s for <tt>Binder</tt>.</li>
+            <li>Built-in <tt>StringTo</tt> converters now have option to use <tt>ErrorMessageProvider</tt>.</li>
+            <li><tt>Grid</tt> headers and footers now support tooltips.</li>
+            <li>Added <tt>Tree</tt> and <tt>TreeGrid</tt> recursive expand and collapse methods.</li>
         </ul>
 
         </p>
@@ -97,8 +103,9 @@ <h2 id="enhancements">Enhancements in Vaadin Framework @version-minor@</h2>
 
         <h2 id="incompatible">Incompatible or Behavior-altering Changes in @version-minor@</h2>
 
-        <li><tt>BindingBuilder</tt> will now automatically mark bound field <i>read-only</i> when bound to a read-only property or a <tt>null</tt> setter.</li>
         <li>Date range limits in <tt>AbstractDateFieldState</tt> are now <tt>String</tt>s instead of <tt>Date</tt>s, some client-side method signatures were changed</li>
+        <li><tt>BrowserResizeListener</tt> is only called once resizing ends.</li>
+        <li><tt>ItemClickEvent</tt> for <tt>Grid</tt> now takes and additional row index parameter.</li>
 
         <h2>For incompatible or behavior-altering changes in 8.3, please see <a href="https://vaadin.com/download/release/8.3/8.3.0/release-notes.html#incompatible">8.3 release notes</a></h2>
 

client/src/main/java/com/vaadin/client/BrowserInfo.java

@@ -516,7 +516,7 @@ public int getBrowserMinorVersion() {
      * other than dots and digits.
      *
      * @return the complete browser version or {@code null} if unknown
-     * @since
+     * @since 8.4
      */
     public String getBrowserVersion() {
         return browserDetails.getBrowserVersion();

client/src/main/java/com/vaadin/client/DateTimeService.java

@@ -61,11 +61,12 @@ public DateTimeService(String locale) throws LocaleNotLoadedException {
     }
 
     /**
-     * Utility method to format positive int as zero-padded two-digits number
+     * Utility method to format positive int as zero-padded two-digits number.
      *
-     * @param i the value
+     * @param i
+     *            the value
      * @return "00".."99"
-     * @since
+     * @since 8.4
      */
     public static String asTwoDigits(int i) {
         return (i < 10 ? "0" : "") + i;

client/src/main/java/com/vaadin/client/WidgetUtil.java

@@ -56,7 +56,7 @@ public class WidgetUtil {
      * 
      * @param <T>
      *            the object type to store
-     * @since
+     * @since 8.4
      */
     public static class Reference<T> {
 

client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java

@@ -2113,7 +2113,7 @@ public void setRangeEnd(String newRangeEnd) {
      *
      * @param label
      *         the label to set
-     * @since
+     * @since 8.4
      */
     public void setAssistiveLabelPreviousYear(String label) {
         prevYearAssistiveLabel = label;
@@ -2124,7 +2124,7 @@ public void setAssistiveLabelPreviousYear(String label) {
      *
      * @param label
      *         the label to set
-     * @since
+     * @since 8.4
      */
     public void setAssistiveLabelNextYear(String label) {
         nextYearAssistiveLabel = label;
@@ -2135,7 +2135,7 @@ public void setAssistiveLabelNextYear(String label) {
      *
      * @param label
      *         the label to set
-     * @since
+     * @since 8.4
      */
     public void setAssistiveLabelPreviousMonth(String label) {
         prevMonthAssistiveLabel = label;
@@ -2146,7 +2146,7 @@ public void setAssistiveLabelPreviousMonth(String label) {
      *
      * @param label
      *         the label to set
-     * @since
+     * @since 8.4
      */
     public void setAssistiveLabelNextMonth(String label) {
         nextMonthAssistiveLabel = label;
@@ -2155,7 +2155,7 @@ public void setAssistiveLabelNextMonth(String label) {
     /**
      * Updates assistive labels of the navigation elements.
      *
-     * @since
+     * @since 8.4
      */
     public void updateAssistiveLabels() {
         if (prevMonth != null) {

client/src/main/java/com/vaadin/client/ui/VDateField.java

@@ -271,7 +271,7 @@ public String getResolutionVariable(R resolution) {
      * This method can be implemented by subclasses to update buffered values
      * from component values.
      *
-     * @since
+     * @since 8.4
      */
     public abstract void updateBufferedValues();
 

client/src/main/java/com/vaadin/client/ui/VRadioButtonGroup.java

@@ -308,7 +308,7 @@ protected void updateItemSelection(RadioButton radioButton, boolean value) {
      * @param value
      *            {@code true} if enabled; {@code false} if not
      *
-     * @since
+     * @since 8.4
      */
     protected void updateItemEnabled(RadioButton radioButton, boolean value) {
         boolean enabled = value && !isReadonly() && isEnabled();

client/src/main/java/com/vaadin/client/ui/datefield/AbstractDateFieldConnector.java

@@ -151,7 +151,7 @@ private void updateAssistiveLabels() {
      *
      * @param calendar
      *         the calendar panel for which to set the assistive labels
-     * @since
+     * @since 8.4
      */
     protected void setAndUpdateAssistiveLabels(
             VAbstractCalendarPanel calendar) {

client/src/main/java/com/vaadin/client/widgets/Grid.java

@@ -445,7 +445,8 @@ void detach() {
              * The tooltip is shown in the mode returned by
              * {@link #getDescriptionContentMode()}.
              *
-             * @since
+             * @return the tooltip text for this cell
+             * @since 8.4
              */
             public String getDescription() {
                 return description;
@@ -460,7 +461,7 @@ public String getDescription() {
              *
              * @param description
              *            the tooltip to show when hovering the cell
-             * @since
+             * @since 8.4
              */
             public void setDescription(String description) {
                 this.description = description;
@@ -476,7 +477,7 @@ public void setDescription(String description) {
              * @param descriptionContentMode
              *            the content mode to use for the tooltip (HTML or plain
              *            text)
-             * @since
+             * @since 8.4
              */
             public void setDescription(String description,
                     ContentMode descriptionContentMode) {
@@ -491,7 +492,7 @@ public void setDescription(String description,
              *
              * @see ContentMode
              * @return the content mode for the tooltip
-             * @since
+             * @since 8.4
              */
             public ContentMode getDescriptionContentMode() {
                 return descriptionContentMode;
@@ -503,7 +504,7 @@ public ContentMode getDescriptionContentMode() {
              * @see ContentMode
              * @param descriptionContentMode
              *            the content mode for the tooltip
-             * @since
+             * @since 8.4
              */
             public void setDescriptionContentMode(
                     ContentMode descriptionContentMode) {
@@ -7383,7 +7384,7 @@ public void scrollToRow(int rowIndex, ScrollDestination destination)
      *            the desired scroll destination
      * @param callback
      *            the callback command to execute when row is available
-     * @since
+     * @since 8.4
      */
     public void scrollToRow(int rowIndex, ScrollDestination destination,
             Runnable callback) {
@@ -7406,7 +7407,7 @@ public void scrollToRow(int rowIndex, ScrollDestination destination,
      *            the row to look for
      * @param whenRendered
      *            the callback command to execute when row is available
-     * @since
+     * @since 8.4
      */
     public void scrollToRow(int rowIndex, Runnable whenRendered) {
         scrollToRow(rowIndex, ScrollDestination.ANY, whenRendered);

server/src/main/java/com/vaadin/data/Binder.java

@@ -188,7 +188,7 @@ public default BindingValidationStatus<TARGET> validate() {
          * @param readOnly
          *            {@code true} to set binding read-only; {@code false} to
          *            enable writes
-         * @since
+         * @since 8.4
          * @throws IllegalStateException
          *             if trying to make binding read-write and the setter is
          *             {@code null}
@@ -201,23 +201,23 @@ public default BindingValidationStatus<TARGET> validate() {
          * @see #setReadOnly(boolean)
          * 
          * @return {@code true} if read-only; {@code false} if not
-         * @since
+         * @since 8.4
          */
         public boolean isReadOnly();
 
         /**
          * Gets the getter associated with this Binding.
          *
          * @return the getter
-         * @since
+         * @since 8.4
          */
         public ValueProvider<BEAN, TARGET> getGetter();
 
         /**
          * Gets the setter associated with this Binding.
          *
          * @return the setter
-         * @since
+         * @since 8.4
          */
         public Setter<BEAN, TARGET> getSetter();
     }
@@ -730,21 +730,21 @@ public BindingBuilder<BEAN, TARGET> asRequired(
                 ErrorMessageProvider errorMessageProvider);
 
         /**
-         * Sets the field to be required and delegates the required check to a custom validator.
-         * This means two things:
+         * Sets the field to be required and delegates the required check to a
+         * custom validator. This means two things:
          * <ol>
          * <li>the required indicator will be displayed for this field</li>
-         * <li>the field value is validated by customRequiredValidator</li>
+         * <li>the field value is validated by {@code requiredValidator}</li>
          * </ol>
          *
          * @see HasValue#setRequiredIndicatorVisible(boolean)
-         * @param customRequiredValidator
+         * @param requiredValidator
          *            validator responsible for the required check
          * @return this binding, for chaining
-         * @since
+         * @since 8.4
          */
         public BindingBuilder<BEAN, TARGET> asRequired(
-                Validator<TARGET> customRequiredValidator);
+                Validator<TARGET> requiredValidator);
     }
 
     /**
@@ -902,10 +902,9 @@ public BindingBuilder<BEAN, TARGET> withValidationStatusHandler(
         @Override
         public BindingBuilder<BEAN, TARGET> asRequired(
                 ErrorMessageProvider errorMessageProvider) {
-            return asRequired(
-                    Validator.from(
-                            value -> !Objects.equals(value, field.getEmptyValue()),
-                            errorMessageProvider));
+            return asRequired(Validator.from(
+                    value -> !Objects.equals(value, field.getEmptyValue()),
+                    errorMessageProvider));
         }
 
         @Override

server/src/main/java/com/vaadin/data/ReadOnlyHasValue.java

@@ -24,17 +24,21 @@
 import java.util.Objects;
 
 /**
- * Generic {@link HasValue} to use any type of component with Vaadin data binding.
+ * Generic {@link HasValue} to use any type of component with Vaadin data
+ * binding.
  * <p>
  * Example:
+ *
  * <pre>
  * Label label = new Label();
- * ReadOnlyHasValue&lt;String&gt; hasValue = new ReadOnlyHasValue&lt;&gt;(label::setCaption);
+ * ReadOnlyHasValue&lt;String&gt; hasValue = new ReadOnlyHasValue&lt;&gt;(
+ *         label::setCaption);
  * binder.forField(hasValue).bind(SomeBean::getName);
  * </pre>
  *
- * @param <V> the value type
- * @since
+ * @param <V>
+ *            the value type
+ * @since 8.4
  */
 public class ReadOnlyHasValue<V> implements HasValue<V>, Serializable {
     private V value;
@@ -43,31 +47,35 @@ public class ReadOnlyHasValue<V> implements HasValue<V>, Serializable {
     private LinkedHashSet<ValueChangeListener<V>> listenerList;
 
     /**
-     * Creates new {@code ReadOnlyHasValue}
+     * Creates new {@code ReadOnlyHasValue}.
      *
-     * @param valueProcessor the value valueProcessor, e.g. {@link Label#setValue}
-     * @param emptyValue the value to be used as empty, {@code null} by default
+     * @param valueProcessor
+     *            the value valueProcessor, e.g. {@link Label#setValue}
+     * @param emptyValue
+     *            the value to be used as empty, {@code null} by default
      */
-    public ReadOnlyHasValue(SerializableConsumer<V> valueProcessor, V emptyValue) {
+    public ReadOnlyHasValue(SerializableConsumer<V> valueProcessor,
+            V emptyValue) {
         this.valueProcessor = valueProcessor;
         this.emptyValue = emptyValue;
     }
 
     /**
      * Creates new {@code ReadOnlyHasValue} with {@code null} as an empty value.
      *
-     * @param valueProcessor the value valueProcessor, e.g. {@link Label#setValue}
+     * @param valueProcessor
+     *            the value valueProcessor, e.g. {@link Label#setValue}
      */
     public ReadOnlyHasValue(SerializableConsumer<V> valueProcessor) {
-        this(valueProcessor,null);
+        this(valueProcessor, null);
     }
 
     @Override
     public void setValue(V value) {
         V oldValue = this.value;
         this.value = value;
         valueProcessor.accept(value);
-        if (listenerList != null && ! Objects.equals(oldValue, value)) {
+        if (listenerList != null && !Objects.equals(oldValue, value)) {
             for (ValueChangeListener<V> valueChangeListener : listenerList) {
                 valueChangeListener.valueChange(
                         new ValueChangeEvent<>(null, this, oldValue, false));
@@ -99,12 +107,14 @@ public boolean isRequiredIndicatorVisible() {
 
     @Override
     public void setRequiredIndicatorVisible(boolean requiredIndicatorVisible) {
-        if (requiredIndicatorVisible) throw new IllegalArgumentException("Not Writable");
+        if (requiredIndicatorVisible)
+            throw new IllegalArgumentException("Not Writable");
     }
 
     @Override
     public void setReadOnly(boolean readOnly) {
-        if (!readOnly) throw new IllegalArgumentException("Not Writable");
+        if (!readOnly)
+            throw new IllegalArgumentException("Not Writable");
     }
 
     @Override

server/src/main/java/com/vaadin/data/converter/AbstractStringToNumberConverter.java

@@ -53,7 +53,7 @@ public abstract class AbstractStringToNumberConverter<T extends Number>
      * @param errorMessageProvider
      *            the error message provider to use if conversion fails
      *
-     * @since
+     * @since 8.4
      */
     protected AbstractStringToNumberConverter(T emptyValue,
             ErrorMessageProvider errorMessageProvider) {

server/src/main/java/com/vaadin/data/converter/StringToBigDecimalConverter.java

@@ -74,7 +74,7 @@ public StringToBigDecimalConverter(BigDecimal emptyValue,
      * @param errorMessageProvider
      *            the error message provider to use if conversion fails
      *
-     * @since
+     * @since 8.4
      */
     public StringToBigDecimalConverter(
             ErrorMessageProvider errorMessageProvider) {
@@ -91,7 +91,7 @@ public StringToBigDecimalConverter(
      * @param errorMessageProvider
      *            the error message provider to use if conversion fails
      *
-     * @since
+     * @since 8.4
      */
     public StringToBigDecimalConverter(BigDecimal emptyValue,
             ErrorMessageProvider errorMessageProvider) {