Eslint-plugin-jsdoc: check-examples errors on @file not being in the example snippet

[bobpaw]

Expected behavior

I expected to not receive @file errors because the example is a snippet and part of a JSDoc block.

Actual behavior

It gave an error. This one is pretty clearly wrong. JSDoc blocks shouldn't be parsed for sub-blocks.

ESLint Config

module.exports = {
    env: {
        node: true,
    },
    parserOptions: {
        ecmaVersion: 11
    },
    plugins: [
        "jsdoc"
    ],
    ignorePatterns: ["out/"],
    rules: {
        "jsdoc/check-examples": "error", // It's sort of broken right now
        "jsdoc/require-file-overview": "warn",
    }
};

ESLint Sample

/**
 * @file Foo bar
 */

/**
 * Does quux
 * @example
 * // Do it!
 * quux();
 */
function quux () {
}

[brettz9]

I'm not clear on an example that is triggering the problem. The whole idea of check-examples is to check for its inner contents.

[brettz9]

Oh, I think I understand--I'll see about disabling that rule by default.

[bobpaw]

Sorry I misinterpreted the form. I'm editing it now.

[bobpaw]

I've updated my sample.

[gajus]

:tada: This issue has been resolved in version 30.3.2 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket:

[brettz9]

Btw, though it is good to fix the default behavior, you can use matchingFileName, e.g., matchingFileName: 'dummy.md' along with overrides in your eslint config, e.g., with files: ['*.md'] to apply specific rules (or disabling of rules) to your examples. (We suggest ".md" since if you are using eslint-plugin-markdown, the same kinds of rules that you want to disable there, tend to be similar to those one would also want to disable in @example. However, you should also be able to use something distinct from .md like .example, though I don't recall offhand if that would require adding the extension to eslint --ext.)