From 375df5aa639c65682cc983572eeafc6fcf30495d Mon Sep 17 00:00:00 2001
From: Sergey Vinogradov <mr.vursen@gmail.com>
Date: Mon, 9 Oct 2023 16:34:05 +0300
Subject: [PATCH] improve JSDoc

---
 .../src/vaadin-date-picker-mixin.js           | 26 ++++++++-----------
 .../date-picker/src/vaadin-date-picker.d.ts   | 16 ++++++++++++
 .../date-picker/src/vaadin-date-picker.js     | 16 ++++++++++++
 3 files changed, 43 insertions(+), 15 deletions(-)

diff --git a/packages/date-picker/src/vaadin-date-picker-mixin.js b/packages/date-picker/src/vaadin-date-picker-mixin.js
index ee67854047..44e200eb11 100644
--- 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
index 9b359757b4..1812c09d38 100644
--- 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
index 5def62320e..29977849c3 100644
--- 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.