chore: fix some incorrect JSDoc found by eslint-plugin-jsdoc (#10012)

web-padawan · web-flow · commit 7ff89e2406f4 · 2025-08-18T10:05:13.000+03:00
diff --git a/packages/a11y-base/src/aria-hidden.js b/packages/a11y-base/src/aria-hidden.js
@@ -115,7 +115,7 @@ const applyAttributeToOthers = (originalTarget, parentNode, markerName, controlA
   targets.forEach(keep);
 
   /**
-   * @param {?Node} el
+   * @param {?Node} parent
    */
   const deep = (parent) => {
     if (!parent || elementsToStop.has(parent)) {
diff --git a/packages/a11y-base/src/aria-id-reference.js b/packages/a11y-base/src/aria-id-reference.js
@@ -17,7 +17,7 @@ const attributeToTargets = new Map();
  *
  * @param {string} attr the attribute name used as key in the map
  *
- * @returns {WeakMap<HTMLElement, Set<string>} a weak map with the stored values for the elements being controlled by the helper
+ * @return {WeakMap<HTMLElement, Set<string>>} a weak map with the stored values for the elements being controlled by the helper
  */
 function getAttrMap(attr) {
   if (!attributeToTargets.has(attr)) {
@@ -32,8 +32,6 @@ function getAttrMap(attr) {
  *
  * @param {HTMLElement} target
  * @param {string} attr the attribute to be cleared
- * @param {boolean} storeValue whether or not the current value of the attribute should be stored on the map
- * @returns
  */
 function cleanAriaIDReference(target, attr) {
   if (!target) {
diff --git a/packages/checkbox-group/src/vaadin-checkbox-group-mixin.js b/packages/checkbox-group/src/vaadin-checkbox-group-mixin.js
@@ -16,7 +16,6 @@ import { FieldMixin } from '@vaadin/field-base/src/field-mixin.js';
  * @mixes DisabledMixin
  * @mixes FieldMixin
  * @mixes FocusMixin
- * @mixes KeyboardMixin
  */
 export const CheckboxGroupMixin = (superclass) =>
   class CheckboxGroupMixinClass extends FieldMixin(FocusMixin(DisabledMixin(superclass))) {
diff --git a/packages/component-base/src/data-provider-controller/helpers.js b/packages/component-base/src/data-provider-controller/helpers.js
@@ -18,6 +18,7 @@
  *
  * @param {Cache} cache
  * @param {number} flatIndex
+ * @param {number} level
  */
 export function getFlatIndexContext(cache, flatIndex, level = 0) {
   let levelIndex = flatIndex;
@@ -53,7 +54,6 @@ export function getFlatIndexContext(cache, flatIndex, level = 0) {
  *
  * If the item isn't found, the method returns undefined.
  *
- * @param {Cache} cache
  * @param {{ getItemId: (item: unknown) => unknown}} context
  * @param {Cache} cache
  * @param {unknown} targetItem
diff --git a/packages/component-base/src/slot-controller.js b/packages/component-base/src/slot-controller.js
@@ -15,7 +15,7 @@ export class SlotController extends EventTarget {
    * Ensure that every instance has unique ID.
    *
    * @param {HTMLElement} host
-   * @param {string} slotName
+   * @param {string} prefix
    * @return {string}
    * @protected
    */
diff --git a/packages/component-base/src/tooltip-controller.js b/packages/component-base/src/tooltip-controller.js
@@ -56,7 +56,6 @@ export class TooltipController extends SlotController {
   /**
    * Override to notify the host when the tooltip is removed.
    *
-   * @param {Node} tooltipNode
    * @protected
    * @override
    */
diff --git a/packages/component-base/src/virtualizer.js b/packages/component-base/src/virtualizer.js
@@ -78,9 +78,7 @@ export class Virtualizer {
   /**
    * Flushes active asynchronous tasks so that the component and the DOM end up in a stable state
    *
-   * @method update
-   * @param {number | undefined} startIndex The start index of the range
-   * @param {number | undefined} endIndex The end index of the range
+   * @method flush
    */
   flush() {
     this.__adapter.flush();
diff --git a/packages/context-menu/src/vaadin-contextmenu-items-mixin.js b/packages/context-menu/src/vaadin-contextmenu-items-mixin.js
@@ -16,14 +16,14 @@ export const ItemsMixin = (superClass) =>
          * @typedef ContextMenuItem
          * @type {object}
          * @property {string} text - Text to be set as the menu item component's textContent
-         * @property {union: string | object} component - The component to represent the item.
+         * @property {string | HTMLElement} component - The component to represent the item.
          * Either a tagName or an element instance. Defaults to "vaadin-context-menu-item".
          * @property {boolean} disabled - If true, the item is disabled and cannot be selected
          * @property {boolean} checked - If true, the item shows a checkmark next to it
          * @property {boolean} keepOpen - If true, the menu will not be closed on item selection
          * @property {string} className - A space-delimited list of CSS class names to be set on the menu item component.
-         * @property {union: string | string[]} theme - If set, sets the given theme(s) as an attribute to the menu item component, overriding any theme set on the context menu.
-         * @property {MenuItem[]} children - Array of child menu items
+         * @property {string | string[]} theme - If set, sets the given theme(s) as an attribute to the menu item component, overriding any theme set on the context menu.
+         * @property {ContextMenuItem[]} children - Array of child menu items
          */
 
         /**
@@ -403,7 +403,6 @@ export const ItemsMixin = (superClass) =>
     /**
      * @param {!HTMLElement} root
      * @param {!ContextMenu} menu
-     * @param {!ContextMenuRendererContext} context
      * @protected
      */
     __itemsRenderer(root, menu) {
diff --git a/packages/crud/src/vaadin-crud-edit.js b/packages/crud/src/vaadin-crud-edit.js
@@ -22,8 +22,7 @@ import { crudEditStyles } from './styles/vaadin-crud-edit-base-styles.js';
  * a `<vaadin-crud>` to enable editing.
  *
  * @customElement
- * @extends HTMLElement
- * @mixes ThemableMixin
+ * @extends Button
  */
 class CrudEdit extends Button {
   static get is() {
diff --git a/packages/date-picker/src/vaadin-date-picker-helper.js b/packages/date-picker/src/vaadin-date-picker-helper.js
@@ -7,7 +7,7 @@
 /**
  * Get ISO 8601 week number for the given date.
  *
- * @param {!Date} Date object
+ * @param {!Date} date
  * @return {number} Week number
  */
 export function getISOWeekNumber(date) {
diff --git a/packages/date-picker/src/vaadin-date-picker-mixin.js b/packages/date-picker/src/vaadin-date-picker-mixin.js
@@ -1119,7 +1119,7 @@ export const DatePickerMixin = (subclass) =>
     /**
      * Override an event listener from `KeyboardMixin`.
      *
-     * @param {!KeyboardEvent} _event
+     * @param {!KeyboardEvent} event
      * @protected
      * @override
      */
diff --git a/packages/date-picker/src/vaadin-date-picker-year.js b/packages/date-picker/src/vaadin-date-picker-year.js
@@ -16,7 +16,6 @@ import { datePickerYearStyles } from './styles/vaadin-date-picker-year-base-styl
  * @customElement
  * @extends HTMLElement
  * @mixes ThemableMixin
- * @mixes DatePickerYearMixin
  * @private
  */
 export class DatePickerYear extends ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement))) {
diff --git a/packages/field-base/src/error-controller.js b/packages/field-base/src/error-controller.js
@@ -97,7 +97,7 @@ export class ErrorController extends SlotChildObserveController {
    * Note: unlike with other controllers, this method is
    * called for both default and custom error message.
    *
-   * @param {Node | undefined} node
+   * @param {Node | undefined} errorNode
    * @protected
    * @override
    */
diff --git a/packages/field-base/src/helper-controller.js b/packages/field-base/src/helper-controller.js
@@ -38,7 +38,6 @@ export class HelperController extends SlotChildObserveController {
    * Override method inherited from `SlotChildObserveController`
    * to create the default helper element lazily as needed.
    *
-   * @param {Node | undefined} node
    * @protected
    * @override
    */
diff --git a/packages/grid/src/array-data-provider.js b/packages/grid/src/array-data-provider.js
@@ -79,7 +79,7 @@ function compare(a, b) {
  * Sorts the given array of items based on the sorting rules and returns the result.
  *
  * @param {Array<any>} items
- * @param {Array<GridSorterDefinition>} items
+ * @param {Array<GridSorterDefinition>} sortOrders
  * @return {Array<any>}
  */
 function multiSort(items, sortOrders) {
@@ -101,6 +101,7 @@ function multiSort(items, sortOrders) {
 
 /**
  * @param {!Array<!GridItem>} items
+ * @param {Array<GridFilterDefinition>} filters
  * @return {!Array<!GridItem>}
  */
 function filter(items, filters) {
@@ -120,7 +121,7 @@ function filter(items, filters) {
  * Creates a new grid compatible data provider that serves the items
  * from the given array as data when requested by the grid.
  *
- * @param {Array<any>} items
+ * @param {Array<any>} allItems
  * @return {GridDataProvider<any>}
  */
 export const createArrayDataProvider = (allItems) => {
diff --git a/packages/grid/src/vaadin-grid-a11y-mixin.js b/packages/grid/src/vaadin-grid-a11y-mixin.js
@@ -138,7 +138,7 @@ export const A11yMixin = (superClass) =>
     }
 
     /**
-     * @param {!HTMLElement} row
+     * @param {!HTMLElement} cell
      * @param {number} colspan
      * @protected
      */
diff --git a/packages/grid/src/vaadin-grid-column-auto-width-mixin.js b/packages/grid/src/vaadin-grid-column-auto-width-mixin.js
@@ -137,10 +137,7 @@ export const ColumnAutoWidthMixin = (superClass) =>
       return this.__getIntrinsicWidth(innerColumn) + shareOfInnerColumnFromNecessaryExtraSpace;
     }
 
-    /**
-     * @param {!Array<!GridColumn>} cols the columns to auto size based on their content width
-     * @private
-     */
+    /** @private */
     _recalculateColumnWidths() {
       // Flush to make sure DOM is up-to-date when measuring the column widths
       this.__virtualizer.flush();
diff --git a/packages/grid/src/vaadin-grid-row-details-mixin.js b/packages/grid/src/vaadin-grid-row-details-mixin.js
@@ -124,7 +124,7 @@ export const RowDetailsMixin = (superClass) =>
 
     /**
      * @param {!HTMLElement} row
-     * @param {!GridItem} item
+     * @param {boolean} detailsOpened
      * @protected
      */
     _toggleDetailsCell(row, detailsOpened) {
diff --git a/packages/icon/src/vaadin-icon-svg.js b/packages/icon/src/vaadin-icon-svg.js
@@ -35,7 +35,7 @@ export function isValidSvg(source) {
 /**
  * Create a valid SVG literal based on the argument.
  *
- * @param {unknown} svg
+ * @param {unknown} source
  */
 export function ensureSvgLiteral(source) {
   let result = source == null || source === '' ? nothing : source;
diff --git a/packages/integer-field/src/vaadin-integer-field.js b/packages/integer-field/src/vaadin-integer-field.js
@@ -87,7 +87,7 @@ export class IntegerField extends NumberField {
   /**
    * Override an observer from `NumberField` to reset the step
    * property when an invalid step is set.
-   * @param {number} newVal
+   * @param {number} step
    * @param {HTMLElement | undefined} inputElement
    * @protected
    * @override
diff --git a/packages/item/src/vaadin-item-mixin.js b/packages/item/src/vaadin-item-mixin.js
@@ -98,7 +98,7 @@ export const ItemMixin = (superClass) =>
     }
 
     /**
-     * @param {KeyboardEvent | MouseEvent} _event
+     * @param {KeyboardEvent | MouseEvent} event
      * @protected
      * @override
      */
diff --git a/packages/menu-bar/src/vaadin-menu-bar-mixin.js b/packages/menu-bar/src/vaadin-menu-bar-mixin.js
@@ -76,18 +76,18 @@ export const MenuBarMixin = (superClass) =>
          * @property {string} text - Text to be set as the menu button component's textContent.
          * @property {string} tooltip - Text to be set as the menu button's tooltip.
          * Requires a `<vaadin-tooltip slot="tooltip">` element to be added inside the `<vaadin-menu-bar>`.
-         * @property {union: string | object} component - The component to represent the button content.
+         * @property {string | HTMLElement} component - The component to represent the button content.
          * Either a tagName or an element instance. Defaults to "vaadin-menu-bar-item".
          * @property {boolean} disabled - If true, the button is disabled and cannot be activated.
-         * @property {union: string | string[]} theme - Theme(s) to be set as the theme attribute of the button, overriding any theme set on the menu bar.
+         * @property {string | string[]} theme - Theme(s) to be set as the theme attribute of the button, overriding any theme set on the menu bar.
          * @property {SubMenuItem[]} children - Array of submenu items.
          */
 
         /**
          * @typedef SubMenuItem
          * @type {object}
          * @property {string} text - Text to be set as the menu item component's textContent.
-         * @property {union: string | object} component - The component to represent the item.
+         * @property {string | HTMLElement} component - The component to represent the item.
          * Either a tagName or an element instance. Defaults to "vaadin-menu-bar-item".
          * @property {boolean} disabled - If true, the item is disabled and cannot be selected.
          * @property {boolean} checked - If true, the item shows a checkmark next to it.
diff --git a/packages/message-list/src/vaadin-message-list-mixin.js b/packages/message-list/src/vaadin-message-list-mixin.js
@@ -167,7 +167,7 @@ export const MessageListMixin = (superClass) =>
     }
 
     /**
-     * @param {number} idx
+     * @param {number} index
      * @protected
      */
     _setTabIndexesByIndex(index) {
diff --git a/packages/number-field/src/vaadin-number-field-mixin.js b/packages/number-field/src/vaadin-number-field-mixin.js
@@ -436,7 +436,7 @@ export const NumberFieldMixin = (superClass) =>
      * Override this method from `InputControlMixin`
      * to stop propagation of the native change event.
      *
-     * @param {Event}
+     * @param {Event} event
      * @override
      * @protected
      */
diff --git a/packages/radio-group/src/vaadin-radio-group-mixin.js b/packages/radio-group/src/vaadin-radio-group-mixin.js
@@ -209,7 +209,7 @@ export const RadioGroupMixin = (superclass) =>
     }
 
     /**
-     * @param {number} index
+     * @param {HTMLElement} radioButton
      * @private
      */
     __selectNextRadioButton(radioButton) {
@@ -219,7 +219,7 @@ export const RadioGroupMixin = (superclass) =>
     }
 
     /**
-     * @param {number} index
+     * @param {HTMLElement} radioButton
      * @private
      */
     __selectPrevRadioButton(radioButton) {
diff --git a/packages/vaadin-themable-mixin/vaadin-themable-mixin.js b/packages/vaadin-themable-mixin/vaadin-themable-mixin.js
@@ -55,7 +55,6 @@ function hasThemes(tagName) {
 /**
  * Flattens the styles into a single array of styles.
  * @param {CSSResultGroup} styles
- * @param {CSSResult[]} result
  * @returns {CSSResult[]}
  */
 function flattenStyles(styles = []) {

Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@ const attributeToTargets = new Map();`
`17`	`17`	`*`
`18`	`18`	`* @param {string} attr the attribute name used as key in the map`
`19`	`19`	`*`
`20`		`- * @returns {WeakMap<HTMLElement, Set<string>} a weak map with the stored values for the elements being controlled by the helper`
	`20`	`+ * @return {WeakMap<HTMLElement, Set<string>>} a weak map with the stored values for the elements being controlled by the helper`
`21`	`21`	`*/`
`22`	`22`	`function getAttrMap(attr) {`
`23`	`23`	`if (!attributeToTargets.has(attr)) {`
`@@ -32,8 +32,6 @@ function getAttrMap(attr) {`
`32`	`32`	`*`
`33`	`33`	`* @param {HTMLElement} target`
`34`	`34`	`* @param {string} attr the attribute to be cleared`
`35`		`- * @param {boolean} storeValue whether or not the current value of the attribute should be stored on the map`
`36`		`- * @returns`
`37`	`35`	`*/`
`38`	`36`	`function cleanAriaIDReference(target, attr) {`
`39`	`37`	`if (!target) {`
Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@`
`18`	`18`	`*`
`19`	`19`	`* @param {Cache} cache`
`20`	`20`	`* @param {number} flatIndex`
	`21`	`+ * @param {number} level`
`21`	`22`	`*/`
`22`	`23`	`export function getFlatIndexContext(cache, flatIndex, level = 0) {`
`23`	`24`	`let levelIndex = flatIndex;`
`@@ -53,7 +54,6 @@ export function getFlatIndexContext(cache, flatIndex, level = 0) {`
`53`	`54`	`*`
`54`	`55`	`* If the item isn't found, the method returns undefined.`
`55`	`56`	`*`
`56`		`- * @param {Cache} cache`
`57`	`57`	`* @param {{ getItemId: (item: unknown) => unknown}} context`
`58`	`58`	`* @param {Cache} cache`
`59`	`59`	`* @param {unknown} targetItem`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@ export class SlotController extends EventTarget {`
`15`	`15`	`* Ensure that every instance has unique ID.`
`16`	`16`	`*`
`17`	`17`	`* @param {HTMLElement} host`
`18`		`- * @param {string} slotName`
	`18`	`+ * @param {string} prefix`
`19`	`19`	`* @return {string}`
`20`	`20`	`* @protected`
`21`	`21`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,6 @@ export class TooltipController extends SlotController {`
`56`	`56`	`/**`
`57`	`57`	`* Override to notify the host when the tooltip is removed.`
`58`	`58`	`*`
`59`		`- * @param {Node} tooltipNode`
`60`	`59`	`* @protected`
`61`	`60`	`* @override`
`62`	`61`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`/**`
`8`	`8`	`* Get ISO 8601 week number for the given date.`
`9`	`9`	`*`
`10`		`- * @param {!Date} Date object`
	`10`	`+ * @param {!Date} date`
`11`	`11`	`* @return {number} Week number`
`12`	`12`	`*/`
`13`	`13`	`export function getISOWeekNumber(date) {`