docs: polish JSDoc comments, add language tags (#10129)

sissbruecker · web-flow · commit 4c505d82e5f8 · 2025-09-06T12:19:12.000+03:00
diff --git a/packages/app-layout/src/vaadin-app-layout-mixin.d.ts b/packages/app-layout/src/vaadin-app-layout-mixin.d.ts
@@ -21,7 +21,7 @@ export declare class AppLayoutMixinClass {
    * just the individual properties you want to change.
    *
    * The object has the following structure and default values:
-   * ```
+   * ```js
    * {
    *   drawer: 'Drawer'
    * }
diff --git a/packages/app-layout/src/vaadin-app-layout-mixin.js b/packages/app-layout/src/vaadin-app-layout-mixin.js
@@ -105,7 +105,7 @@ export const AppLayoutMixin = (superclass) =>
      * just the individual properties you want to change.
      *
      * The object has the following structure and default values:
-     * ```
+     * ```js
      * {
      *   drawer: 'Drawer'
      * }
diff --git a/packages/app-layout/src/vaadin-app-layout.d.ts b/packages/app-layout/src/vaadin-app-layout.d.ts
@@ -55,17 +55,17 @@ export type AppLayoutEventMap = AppLayoutCustomEventMap & HTMLElementEventMap;
  * For best results, the component should be added to the root level of your application (i.e., as a direct child of `<body>`).
  *
  * The page should include a viewport meta tag which contains `viewport-fit=cover`, like the following:
- * ```
+ * ```html
  * <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
  * ```
+ *
  * This causes the viewport to be scaled to fill the device display.
- * To ensure that important content is displayed, use the provided css variables.
- * ```
- * --safe-area-inset-top
- * --safe-area-inset-right
- * --safe-area-inset-bottom
- * --safe-area-inset-left
- * ```
+ * To ensure that important content is displayed, use the provided css variables:
+ *
+ * - `--safe-area-inset-top`
+ * - `--safe-area-inset-right`
+ * - `--safe-area-inset-bottom`
+ * - `--safe-area-inset-left`
  *
  * ### Styling
  *
diff --git a/packages/app-layout/src/vaadin-app-layout.js b/packages/app-layout/src/vaadin-app-layout.js
@@ -35,17 +35,17 @@ import { AppLayoutMixin } from './vaadin-app-layout-mixin.js';
  * For best results, the component should be added to the root level of your application (i.e., as a direct child of `<body>`).
  *
  * The page should include a viewport meta tag which contains `viewport-fit=cover`, like the following:
- * ```
+ * ```html
  * <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
  * ```
+ *
  * This causes the viewport to be scaled to fill the device display.
- * To ensure that important content is displayed, use the provided css variables.
- * ```
- * --safe-area-inset-top
- * --safe-area-inset-right
- * --safe-area-inset-bottom
- * --safe-area-inset-left
- * ```
+ * To ensure that important content is displayed, use the provided css variables:
+ *
+ * - `--safe-area-inset-top`
+ * - `--safe-area-inset-right`
+ * - `--safe-area-inset-bottom`
+ * - `--safe-area-inset-left`
  *
  * ### Styling
  *
diff --git a/packages/avatar-group/src/vaadin-avatar-group-mixin.d.ts b/packages/avatar-group/src/vaadin-avatar-group-mixin.d.ts
@@ -77,7 +77,7 @@ export declare class AvatarGroupMixinClass {
    * just the individual properties you want to change.
    *
    * The object has the following JSON structure and default values:
-   * ```
+   * ```js
    * {
    *   // Translation of the anonymous user avatar tooltip.
    *   anonymous: 'anonymous',
diff --git a/packages/avatar-group/src/vaadin-avatar-group-mixin.js b/packages/avatar-group/src/vaadin-avatar-group-mixin.js
@@ -107,7 +107,7 @@ export const AvatarGroupMixin = (superClass) =>
      * just the individual properties you want to change.
      *
      * The object has the following JSON structure and default values:
-     * ```
+     * ```js
      * {
      *   // Translation of the anonymous user avatar tooltip.
      *   anonymous: 'anonymous',
diff --git a/packages/avatar/src/vaadin-avatar-mixin.d.ts b/packages/avatar/src/vaadin-avatar-mixin.d.ts
@@ -48,7 +48,7 @@ export declare class AvatarMixinClass {
    * just the individual properties you want to change.
    *
    * The object has the following JSON structure and default values:
-   * ```
+   * ```js
    * {
    *   // Translation of the anonymous user avatar tooltip.
    *   anonymous: 'anonymous'
diff --git a/packages/avatar/src/vaadin-avatar-mixin.js b/packages/avatar/src/vaadin-avatar-mixin.js
@@ -96,7 +96,7 @@ export const AvatarMixin = (superClass) =>
      * just the individual properties you want to change.
      *
      * The object has the following JSON structure and default values:
-     * ```
+     * ```js
      * {
      *   // Translation of the anonymous user avatar tooltip.
      *   anonymous: 'anonymous'
diff --git a/packages/button/src/vaadin-button.d.ts b/packages/button/src/vaadin-button.d.ts
@@ -49,7 +49,7 @@ declare class Button extends ButtonMixin(ElementMixin(ThemableMixin(HTMLElement)
    * which makes disabled buttons focusable and hoverable, while still
    * preventing them from being triggered:
    *
-   * ```
+   * ```js
    * // Set before any button is attached to the DOM.
    * window.Vaadin.featureFlags.accessibleDisabledButtons = true
    * ```
diff --git a/packages/button/src/vaadin-button.js b/packages/button/src/vaadin-button.js
@@ -71,7 +71,7 @@ class Button extends ButtonMixin(ElementMixin(ThemableMixin(PolylitMixin(LumoInj
        * which makes disabled buttons focusable and hoverable, while still
        * preventing them from being triggered:
        *
-       * ```
+       * ```js
        * // Set before any button is attached to the DOM.
        * window.Vaadin.featureFlags.accessibleDisabledButtons = true
        * ```
diff --git a/packages/crud/src/vaadin-crud-mixin.d.ts b/packages/crud/src/vaadin-crud-mixin.d.ts
@@ -232,7 +232,7 @@ export declare class CrudMixinClass<Item> {
    *
    * The object has the following JSON structure and default values:
    *
-   * ```
+   * ```js
    * {
    *   newItem: 'New item',
    *   editItem: 'Edit item',
diff --git a/packages/crud/src/vaadin-crud-mixin.js b/packages/crud/src/vaadin-crud-mixin.js
@@ -307,7 +307,7 @@ export const CrudMixin = (superClass) =>
      *
      * The object has the following JSON structure and default values:
      *
-     * ```
+     * ```js
      * {
      *   newItem: 'New item',
      *   editItem: 'Edit item',
diff --git a/packages/dashboard/src/vaadin-dashboard-section.js b/packages/dashboard/src/vaadin-dashboard-section.js
@@ -96,7 +96,7 @@ class DashboardSection extends DashboardItemMixin(
        * `i18n` object with a custom one.
        *
        * The object has the following structure and default values:
-       * ```
+       * ```js
        * {
        *   selectSection: 'Select section for editing',
        *   remove: 'Remove',
diff --git a/packages/dashboard/src/vaadin-dashboard-widget.js b/packages/dashboard/src/vaadin-dashboard-widget.js
@@ -130,7 +130,7 @@ class DashboardWidget extends DashboardItemMixin(
        * `i18n` object with a custom one.
        *
        * The object has the following structure and default values:
-       * ```
+       * ```js
        * {
        *   selectWidget: 'Select widget for editing',
        *   remove: 'Remove',
diff --git a/packages/dashboard/src/vaadin-dashboard.d.ts b/packages/dashboard/src/vaadin-dashboard.d.ts
@@ -259,7 +259,7 @@ declare class Dashboard<TItem extends DashboardItem = DashboardItem> extends Das
    * just the individual properties you want to change.
    *
    * The object has the following structure and default values:
-   * ```
+   * ```js
    * {
    *   selectSection: 'Select section for editing',
    *   selectWidget: 'Select widget for editing',
diff --git a/packages/dashboard/src/vaadin-dashboard.js b/packages/dashboard/src/vaadin-dashboard.js
@@ -192,7 +192,7 @@ class Dashboard extends DashboardLayoutMixin(
    * just the individual properties you want to change.
    *
    * The object has the following structure and default values:
-   * ```
+   * ```js
    * {
    *   selectSection: 'Select section for editing',
    *   selectWidget: 'Select widget for editing',
diff --git a/packages/date-picker/src/vaadin-date-picker-mixin.d.ts b/packages/date-picker/src/vaadin-date-picker-mixin.d.ts
@@ -141,7 +141,7 @@ export declare class DatePickerMixinClass {
    *
    * The object has the following JSON structure and default values:
    *
-   * ```
+   * ```js
    * {
    *   // An array with the full names of months starting
    *   // with January.
diff --git a/packages/date-picker/src/vaadin-date-picker-mixin.js b/packages/date-picker/src/vaadin-date-picker-mixin.js
@@ -302,7 +302,7 @@ export const DatePickerMixin = (subclass) =>
      *
      * The object has the following JSON structure and default values:
      *
-     * ```
+     * ```js
      * {
      *   // An array with the full names of months starting
      *   // with January.
diff --git a/packages/date-time-picker/src/vaadin-date-time-picker-mixin.d.ts b/packages/date-time-picker/src/vaadin-date-time-picker-mixin.d.ts
@@ -150,7 +150,7 @@ export declare class DateTimePickerMixinClass {
    *
    * The object has the following structure and default values:
    *
-   * ```
+   * ```js
    * {
    *   // Accessible label to the date picker.
    *   // The property works in conjunction with label and accessibleName defined on the field.
diff --git a/packages/date-time-picker/src/vaadin-date-time-picker-mixin.js b/packages/date-time-picker/src/vaadin-date-time-picker-mixin.js
@@ -291,7 +291,7 @@ export const DateTimePickerMixin = (superClass) =>
      *
      * The object has the following structure and default values:
      *
-     * ```
+     * ```js
      * {
      *   // Accessible label to the date picker.
      *   // The property works in conjunction with label and accessibleName defined on the field.
diff --git a/packages/form-layout/src/vaadin-form-item.d.ts b/packages/form-layout/src/vaadin-form-item.d.ts
@@ -64,7 +64,7 @@ import { FormItemMixin } from './vaadin-form-item-mixin.js';
  *
  * The `label-position` host attribute can be used to target the label on top state:
  *
- * ```
+ * ```css
  * :host([label-position="top"]) {
  *   padding-top: 0.5rem;
  * }
diff --git a/packages/form-layout/src/vaadin-form-item.js b/packages/form-layout/src/vaadin-form-item.js
@@ -69,7 +69,7 @@ import { FormItemMixin } from './vaadin-form-item-mixin.js';
  *
  * The `label-position` host attribute can be used to target the label on top state:
  *
- * ```
+ * ```css
  * :host([label-position="top"]) {
  *   padding-top: 0.5rem;
  * }
diff --git a/packages/form-layout/src/vaadin-form-layout-mixin.d.ts b/packages/form-layout/src/vaadin-form-layout-mixin.d.ts
@@ -34,7 +34,7 @@ export declare class FormLayoutMixinClass {
    * enabled explicitly via the `autoResponsive` property or implicitly
    * if the following feature flag is set:
    *
-   * ```
+   * ```js
    * window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true
    * ```
    *
diff --git a/packages/form-layout/src/vaadin-form-layout-mixin.js b/packages/form-layout/src/vaadin-form-layout-mixin.js
@@ -36,7 +36,7 @@ export const FormLayoutMixin = (superClass) =>
          * enabled explicitly via the `autoResponsive` property or implicitly
          * if the following feature flag is set:
          *
-         * ```
+         * ```js
          * window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true
          * ```
          *
diff --git a/packages/icon/src/vaadin-icon-mixin.d.ts b/packages/icon/src/vaadin-icon-mixin.d.ts
@@ -37,9 +37,9 @@ export declare class IconMixinClass {
   /**
    * The SVG source to be loaded as the icon. It can be:
    * - an URL to a file containing the icon
-   * - an URL in the format "/path/to/file.svg#objectID", where the "objectID" refers to an ID attribute contained
+   * - an URL in the format `/path/to/file.svg#objectID`, where the `objectID` refers to an ID attribute contained
    *   inside the SVG referenced by the path. Note that the file needs to follow the same-origin policy.
-   * - a string in the format "data:image/svg+xml,<svg>...</svg>". You may need to use the "encodeURIComponent"
+   * - a string in the format `data:image/svg+xml,<svg>...</svg>`. You may need to use the `encodeURIComponent`
    *   function for the SVG content passed
    */
   src: string | null;
diff --git a/packages/icon/src/vaadin-icon-mixin.js b/packages/icon/src/vaadin-icon-mixin.js
@@ -50,9 +50,9 @@ export const IconMixin = (superClass) =>
         /**
          * The SVG source to be loaded as the icon. It can be:
          * - an URL to a file containing the icon
-         * - an URL in the format "/path/to/file.svg#objectID", where the "objectID" refers to an ID attribute contained
+         * - an URL in the format `/path/to/file.svg#objectID`, where the `objectID` refers to an ID attribute contained
          *   inside the SVG referenced by the path. Note that the file needs to follow the same-origin policy.
-         * - a string in the format "data:image/svg+xml,<svg>...</svg>". You may need to use the "encodeURIComponent"
+         * - a string in the format `data:image/svg+xml,<svg>...</svg>`. You may need to use the `encodeURIComponent`
          *   function for the SVG content passed
          *
          * @type {string}
diff --git a/packages/login/src/vaadin-login-mixin.d.ts b/packages/login/src/vaadin-login-mixin.d.ts
@@ -69,7 +69,7 @@ export declare class LoginMixinClass {
    * and `header` sections, `header` can be added to override `title` and `description` properties
    * in `vaadin-login-overlay`):
    *
-   * ```
+   * ```js
    * {
    *   header: {
    *     title: 'App name',
diff --git a/packages/login/src/vaadin-login-mixin.js b/packages/login/src/vaadin-login-mixin.js
@@ -129,7 +129,7 @@ export const LoginMixin = (superClass) =>
      * and `header` sections, `header` can be added to override `title` and `description` properties
      * in `vaadin-login-overlay`):
      *
-     * ```
+     * ```js
      * {
      *   header: {
      *     title: 'App name',
diff --git a/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts b/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts
@@ -114,7 +114,7 @@ export declare class MenuBarMixinClass<TItem extends MenuBarItem = MenuBarItem>
    * which makes disabled buttons focusable and hoverable, while still
    * preventing them from being triggered:
    *
-   * ```
+   * ```js
    * // Set before any menu bar is attached to the DOM.
    * window.Vaadin.featureFlags.accessibleDisabledButtons = true;
    * ```
@@ -127,7 +127,7 @@ export declare class MenuBarMixinClass<TItem extends MenuBarItem = MenuBarItem>
    * just the individual properties you want to change.
    *
    * The object has the following JSON structure and default values:
-   * ```
+   * ```js
    * {
    *   moreOptions: 'More options'
    * }
diff --git a/packages/menu-bar/src/vaadin-menu-bar-mixin.js b/packages/menu-bar/src/vaadin-menu-bar-mixin.js
@@ -136,12 +136,7 @@ export const MenuBarMixin = (superClass) =>
          * which makes disabled buttons focusable and hoverable, while still
          * preventing them from being triggered:
          *
-         * ```
-         * // Set before any menu bar is attached to the DOM.
-         * window.Vaadin.featureFlags.accessibleDisabledButtons = true;
-         * ```
-         *
-         * ```
+         * ```js
          * // Set before any menu bar is attached to the DOM.
          * window.Vaadin.featureFlags.accessibleDisabledButtons = true;
          * ```
@@ -190,7 +185,7 @@ export const MenuBarMixin = (superClass) =>
      * just the individual properties you want to change.
      *
      * The object has the following JSON structure and default values:
-     * ```
+     * ```js
      * {
      *   moreOptions: 'More options'
      * }
diff --git a/packages/message-input/src/vaadin-message-input-mixin.d.ts b/packages/message-input/src/vaadin-message-input-mixin.d.ts
@@ -27,7 +27,7 @@ export declare class MessageInputMixinClass {
    * just the individual properties you want to change.
    *
    * The object has the following JSON structure and default values:
-   * ```
+   * ```js
    * {
    *   // Used as the button label
    *   send: 'Send',
diff --git a/packages/message-input/src/vaadin-message-input-mixin.js b/packages/message-input/src/vaadin-message-input-mixin.js
@@ -67,7 +67,7 @@ export const MessageInputMixin = (superClass) =>
      * just the individual properties you want to change.
      *
      * The object has the following JSON structure and default values:
-     * ```
+     * ```js
      * {
      *   // Used as the button label
      *   send: 'Send',
diff --git a/packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.d.ts b/packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.d.ts
@@ -102,7 +102,7 @@ export declare class MultiSelectComboBoxMixinClass<TItem> {
    * _i18n_ object or just the property you want to modify.
    *
    * The object has the following JSON structure and default values:
-   * ```
+   * ```js
    * {
    *   // Screen reader announcement on clear button click.
    *   cleared: 'Selection cleared',
diff --git a/packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.js b/packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.js
@@ -78,7 +78,7 @@ export const MultiSelectComboBoxMixin = (superClass) =>
          * _i18n_ object or just the property you want to modify.
          *
          * The object has the following JSON structure and default values:
-         * ```
+         * ```js
          * {
          *   // Screen reader announcement on clear button click.
          *   cleared: 'Selection cleared',
diff --git a/packages/notification/src/vaadin-notification-mixin.js b/packages/notification/src/vaadin-notification-mixin.js
@@ -185,7 +185,7 @@ export const NotificationMixin = (superClass) =>
      * An options object can be passed to configure the notification.
      * The options object has the following structure:
      *
-     * ```
+     * ```ts
      * {
      *   assertive?: boolean
      *   position?: string
diff --git a/packages/notification/src/vaadin-notification.d.ts b/packages/notification/src/vaadin-notification.d.ts
@@ -102,7 +102,7 @@ declare class Notification extends NotificationMixin(ElementMixin(HTMLElement))
    * An options object can be passed to configure the notification.
    * The options object has the following structure:
    *
-   * ```
+   * ```ts
    * {
    *   assertive?: boolean
    *   position?: string
diff --git a/packages/password-field/src/vaadin-password-field-mixin.d.ts b/packages/password-field/src/vaadin-password-field-mixin.d.ts
@@ -35,7 +35,7 @@ export declare class PasswordFieldMixinClass {
    * An object with translated strings used for localization.
    * It has the following structure and default values:
    *
-   * ```
+   * ```js
    * {
    *   // Translation of the reveal icon button accessible label
    *   reveal: 'Show password'
diff --git a/packages/password-field/src/vaadin-password-field-mixin.js b/packages/password-field/src/vaadin-password-field-mixin.js
diff --git a/packages/rich-text-editor/src/vaadin-rich-text-editor.d.ts b/packages/rich-text-editor/src/vaadin-rich-text-editor.d.ts
diff --git a/packages/rich-text-editor/src/vaadin-rich-text-editor.js b/packages/rich-text-editor/src/vaadin-rich-text-editor.js
diff --git a/packages/scroller/src/vaadin-scroller.d.ts b/packages/scroller/src/vaadin-scroller.d.ts
diff --git a/packages/scroller/src/vaadin-scroller.js b/packages/scroller/src/vaadin-scroller.js
diff --git a/packages/side-nav/src/vaadin-side-nav-children-mixin.d.ts b/packages/side-nav/src/vaadin-side-nav-children-mixin.d.ts
diff --git a/packages/side-nav/src/vaadin-side-nav-children-mixin.js b/packages/side-nav/src/vaadin-side-nav-children-mixin.js
diff --git a/packages/time-picker/src/vaadin-time-picker-mixin.d.ts b/packages/time-picker/src/vaadin-time-picker-mixin.d.ts
diff --git a/packages/time-picker/src/vaadin-time-picker-mixin.js b/packages/time-picker/src/vaadin-time-picker-mixin.js
diff --git a/packages/upload/src/vaadin-upload-mixin.d.ts b/packages/upload/src/vaadin-upload-mixin.d.ts
diff --git a/packages/upload/src/vaadin-upload-mixin.js b/packages/upload/src/vaadin-upload-mixin.js
