search

gajus / eslint-plugin-jsdoc

JSDoc specific linting rules for ESLint.
Other
1.07k stars 155 forks source link

parser does not recognize JSDoc blocks without initial whitespace #1217

Open stoicbuddha opened 3 months ago

stoicbuddha commented 3 months ago

Description:

When using JSDoc to define a typedef with an import statement, the linter fails with the rule jsdoc/no-undefined-types when the import statement is referencing a type defined in another file purely based on spacing.

Steps to Reproduce:

Define a JSDoc typedef with an import statement referencing a type from another file, for example: javascript

/**@typedef {import('restify').Request} Request */ // Passes linter just fine
/**@typedef {import('./types').helperError} helperError */ // Fails linter

Expected Behavior:

The linter should recognize the import statement and not raise any errors for the typedef definition; for the sake of consistency, it should either error on both or error on neither.

Actual Behavior:

The linter fails on the import for helperError with the rule jsdoc/no-undefined-types, indicating that the imported type is undefined, despite being properly recognized by VS Code.

Note that the following works properly and passes the linter:

/** @typedef {import('./types').helperError} helperError */

The behavior is inconsistent.

ESLint Config

module.exports = {
    env: {
        browser: true,
        commonjs: true,
        es2021: true,
    },
    extends: "plugin:jsdoc/recommended-typescript-flavor",
    overrides: [
        {
            env: {
                node: true,
            },
            files: [".eslintrc.{js,cjs}"],
            parserOptions: {
                sourceType: "script",
            },
        },
    ],
    plugins: ["jsdoc"],
    parserOptions: {
        ecmaVersion: "latest",
    },
    ignorePatterns: ["**/node_modules/*"],
    rules: {
        "jsdoc/check-access": 1, // Recommended
        "jsdoc/check-alignment": 1, // Recommended
        "jsdoc/check-param-names": 1, // Recommended
        "jsdoc/check-property-names": 1, // Recommended
        "jsdoc/check-syntax": 1,
        "jsdoc/check-tag-names": 1, // Recommended
        "jsdoc/check-types": 1, // Recommended
        "jsdoc/check-values": 1, // Recommended
        "jsdoc/empty-tags": 1, // Recommended
        "jsdoc/implements-on-classes": 1, // Recommended
        "jsdoc/multiline-blocks": 1, // Recommended
        "jsdoc/no-bad-blocks": 1,
        "jsdoc/no-blank-block-descriptions": 1,
        "jsdoc/no-defaults": 1,
        "jsdoc/no-multi-asterisks": 1, // Recommended
        "jsdoc/no-undefined-types": 1, // Recommended
        "jsdoc/require-asterisk-prefix": 1,
        "jsdoc/require-description": 0,
        "jsdoc/require-jsdoc": 1, // Recommended
        "jsdoc/require-param": 1, // Recommended
        "jsdoc/require-param-description": 0, // Recommended
        "jsdoc/require-param-name": 1, // Recommended
        "jsdoc/require-param-type": 1, // Recommended
        "jsdoc/require-property": 1, // Recommended
        "jsdoc/require-property-description": 1, // Recommended
        "jsdoc/require-property-name": 1, // Recommended
        "jsdoc/require-property-type": 1, // Recommended
        "jsdoc/require-returns": 1, // Recommended
        "jsdoc/require-returns-check": 1, // Recommended
        "jsdoc/require-returns-description": 0, // Recommended
        "jsdoc/require-returns-type": 1, // Recommended
        "jsdoc/require-throws": 1,
        "jsdoc/require-yields": 1, // Recommended
        "jsdoc/require-yields-check": 1, // Recommended
        "jsdoc/tag-lines": 0,
        "jsdoc/sort-tags": 0,
        "jsdoc/valid-types": 1, // Recommended
    },
    settings: {
        jsdoc: {
            mode: "typescript",
        },
    },
};

Environment

Node version: v18.19.1 ESLint Version: v8.57.0 eslint-plugin-jsdoc: 48.2.1

brettz9 commented 3 months ago

I'm almost certain that in source code if not in its docs, the original JSDoc tool called for whitespace after the initial /**. However, as you are using the TypeScript mode (now the default also), we'd ideally be using comment parsing as used by TypeScript.

It does seem though that TSDoc, a spec/tool for parsing JSDoc comments for TypeScript, allows for no whitespace. Ideally then, we'd use a tool like @microsoft/tsdoc in place of comment-parser. This might also be useful in a few other edge cases like #1116 .

However, this would most likely require a high degree of refactoring, and it is not one I am inclined to undertake myself (it'd also require changes in @es-joy/jsdoccomment). A PR would be welcome, however.