Skip to content

Matching between @param definition and function parameters no longer works #1303

@pasha-zayko

Description

@pasha-zayko

Upgrading from version 48.4.0 to anything later no longer matches @param value with variable in the function definition when trying to use 'ExportNamedDeclaration' to define exclusions in global context. The function affected by this is being exported, and the message indicates "@param "xxx" does not match an existing function parameter jsdoc/check-param-names". This issue appears to be related to the change that introduced "contextDetaults" in checkParamNames for version 48.5.0:

adding these defaults

contextDefaults: [
    'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction',
    // Add this to above defaults
    'TSMethodSignature'
  ],

as the list of variables from function definition is not getting generated. Removing these lines restores the expected behavior.

/**
 * Description of the function.
 * @param inputId Planned value as integer to be evaluated.
 */
export function validateId(inputIds: number): boolean {

Expected behavior

When there is mismatch on the variable name between @param definition and function definition, the following message would be provided:
Expected @param names to be "inputIds". Got "inputId" jsdoc/check-param-names

Actual behavior

Without any change in configuration but using version 48.5.0 or higher results in this message instead:
@param "inputId" does not match an existing function parameter jsdoc/check-param-names

As mentioned earlier, the change in behavior can be traced to the addition of the contextDefaults that interfere with calculation of function variables

ESLint Config

What is the minimal config that reproduces the issue?
As long as 'ExportNamedDeclaration' present the incorrect error message is returned.

import eslint from '@eslint/js';
import globals from 'globals';
import jsdoc from 'eslint-plugin-jsdoc';
import tseslint from 'typescript-eslint';

export default tseslint.config(
    eslint.configs.recommended,
    jsdoc.configs['flat/recommended-typescript'],
    ...tseslint.configs.strictTypeChecked,
    ...tseslint.configs.stylisticTypeChecked,
    {
        'ignores': [
            'eslint.config.mjs'
        ]
    },
    {
        'plugins': { jsdoc },
        'languageOptions': {
            'globals': {
                ...globals.node,
                ...globals.es2021
            },
            'parserOptions': { 'project': true }
        },
        'settings': {
            'jsdoc': {
                'contexts': [
                    'ExportNamedDeclaration:not(:has(VariableDeclarator[id.type=\'ArrayPattern\'])):not(:has(VariableDeclarator[id.type=\'ObjectPattern\']))'
                ]
            }
        }
    }
);

Not using context for 'ExportNamedDeclaration' would provide expected message about the name mismatch.

Environment

  • Node version: 20.16.0
  • ESLint version 9.8.0
  • eslint-plugin-jsdoc version: 48.5.0+

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions