improve JSDoc

vaadin · Oct 11, 2023 · 375df5a · 375df5a
1 parent 4defa9d
commit 375df5a
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 15 deletions.
diff --git a/packages/date-picker/src/vaadin-date-picker-mixin.js b/packages/date-picker/src/vaadin-date-picker-mixin.js
@@ -660,23 +660,19 @@ export const DatePickerMixin = (subclass) =>
     }
 
     /**
-     * Depending on the type of value change that has occurred since
+     * Depending on the nature of value change that has occurred since
      * the last commit attempt, triggers validation and fires an event:
      *
-     * ```text
-     * +--------------------------+-------------------+
-     * | Type of value change     | Event             |
-     * +--------------------------+-------------------+
-     * | empty => parsable        | change            |
-     * | empty => unparsable      | unparsable-change |
-     * | parsable => empty        | change            |
-     * | parsable => parsable     | change            |
-     * | parsable => unparsable   | change            |
-     * | unparsable => empty      | unparsable-change |
-     * | unparsable => parsable   | change            |
-     * | unparsable => unparsable | unparsable-change |
-     * +--------------------------+-------------------+
-     * ```
+     * Value change             | Event
+     * :------------------------|:------------------
+     * empty => parsable        | change
+     * empty => unparsable      | unparsable-change
+     * parsable => empty        | change
+     * parsable => parsable     | change
+     * parsable => unparsable   | change
+     * unparsable => empty      | unparsable-change
+     * unparsable => parsable   | change
+     * unparsable => unparsable | unparsable-change
      *
      * @private
      */

diff --git a/packages/date-picker/src/vaadin-date-picker.d.ts b/packages/date-picker/src/vaadin-date-picker.d.ts
@@ -155,6 +155,22 @@ export interface DatePickerEventMap extends HTMLElementEventMap, DatePickerCusto
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
+ * ### Change events
+ *
+ * Depending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,
+ * the component can fire either a `change` event or an `unparsable-change` event:
+ *
+ * Value change             | Event
+ * :------------------------|:------------------
+ * empty => parsable        | change
+ * empty => unparsable      | unparsable-change
+ * parsable => empty        | change
+ * parsable => parsable     | change
+ * parsable => unparsable   | change
+ * unparsable => empty      | unparsable-change
+ * unparsable => parsable   | change
+ * unparsable => unparsable | unparsable-change
+ *
  * @fires {Event} change - Fired when the user commits a value change.
  * @fires {Event} unparsable-change Fired when the user commits an unparsable value change and there is no change event.
  * @fires {CustomEvent} invalid-changed - Fired when the `invalid` property changes.

diff --git a/packages/date-picker/src/vaadin-date-picker.js b/packages/date-picker/src/vaadin-date-picker.js
@@ -118,6 +118,22 @@ registerStyles('vaadin-date-picker', [inputFieldShared, datePickerStyles], { mod
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
+ * ### Change events
+ *
+ * Depending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,
+ * the component can fire either a `change` event or an `unparsable-change` event:
+ *
+ * Value change             | Event
+ * :------------------------|:------------------
+ * empty => parsable        | change
+ * empty => unparsable      | unparsable-change
+ * parsable => empty        | change
+ * parsable => parsable     | change
+ * parsable => unparsable   | change
+ * unparsable => empty      | unparsable-change
+ * unparsable => parsable   | change
+ * unparsable => unparsable | unparsable-change
+ *
  * @fires {Event} change - Fired when the user commits a value change.
  * @fires {Event} unparsable-change Fired when the user commits an unparsable value change and there is no change event.
  * @fires {CustomEvent} invalid-changed - Fired when the `invalid` property changes.