check-examples and whitespace-based rules (like indent)

[brettz9]

As currently implemented, check-examples has issues when the rule is indent as initial spacing is stripped out during parsing. May need to tweak parsing or use jsdocNode.

[slieker-d]

Can confirm. Having the same issue.

[brettz9]

Be aware that in the meantime you can use overrides to disable the indent or other rules only for examples--using the rule in conjunction with settings.jsdoc.matchingFileName, e.g., {settings: {jsdoc: {matchingFileName: "dummy.md"}}} (in this case, to get the same rules one has for Markdown files--and possible use with eslint-plugin-markdown, but you could match against any file or file type) and then setting your .eslintrc.*'s overrrides to match the file or extension you have set up jsdoc to match against, e.g.,

overrides: [
  {
    files: ["**/*.md"],
    rules: {
      indent: 'off'
    }
  }
]

You can then have your other rules continue to apply to your non-example (or non-Markdown) code without disabling non-indent rules for your examples.

[slieker-d]

I added the overrides section to our .eslintrc.json file, but we're still getting this:

[slieker-d]

This is our entire eslintrc file:

{
    "env": {
        "es6": true,
        "node": true
    },
    "extends": ["airbnb-base", "plugin:jest/recommended"],
    "globals": {
        "Atomics": "readonly",
        "SharedArrayBuffer": "readonly",
        "jest": "readonly"
    },
    "parserOptions": {
        "ecmaVersion": 2018,
        "sourceType": "module"
    },
    "plugins": [
        "jest",
        "jsdoc"
    ],
    "rules": {
        "jest/no-disabled-tests": "warn",
        "jest/no-focused-tests": "error",
        "jest/no-identical-title": "error",
        "jest/prefer-to-have-length": "warn",
        "jest/valid-expect": "error",

        "jsdoc/check-alignment": 1,
        "jsdoc/check-examples": 1,
        "jsdoc/check-indentation": 0,
        "jsdoc/check-param-names": 1,
        "jsdoc/check-syntax": 1,
        "jsdoc/check-tag-names": 1,
        "jsdoc/check-types": 1,
        "jsdoc/implements-on-classes": 1,
        "jsdoc/match-description": 1,
        "jsdoc/newline-after-description": 1,
        "jsdoc/no-types": 0,
        "jsdoc/no-undefined-types": 1,
        "jsdoc/require-description": 1,
        "jsdoc/require-description-complete-sentence": 1,
        "jsdoc/require-example": 1,
        "jsdoc/require-hyphen-before-param-description": 0,
        "jsdoc/require-jsdoc": 1,
        "jsdoc/require-param": 1,
        "jsdoc/require-param-description": 1,
        "jsdoc/require-param-name": 1,
        "jsdoc/require-param-type": 1,
        "jsdoc/require-returns": 1,
        "jsdoc/require-returns-check": 1,
        "jsdoc/require-returns-description": 1,
        "jsdoc/require-returns-type": 1,
        "jsdoc/valid-types": 1
    },
    "overrides": [{
        "files": ["**/*.js"],
        "rules": {
            "indent": "off"
        }
    }]
}

[brettz9]

You also need in your case: {settings: {jsdoc: {matchingFileName: "dummy.js"}}}

But I'd suggest doing this instead:

1. Add {settings: {jsdoc: {matchingFileName: "dummy.md"}}}
2. Change your overrides to "files": ["**/*.md"],

This has three benefits:

1. You can continue using indent with your other code JavaScript.
2. You can continue using non-indent rules for your examples.
3. If you choose "md" as the dummy extension, there is the added benefit that linting the JavaScript in your Markdown files (like README.md) tends to need similar rules disabled, such as eol-last, so you can use eslint-plugin-markdown to lint your Markdown JS with the same rules as in your examples if you wish. But that is optional--you could have separate rules for Markdown JS and separate for your @example's. If linting Markdown JavaScript, you also need to add --ext js,md to your eslint call, e.g., eslint --report-unused-disable-directives --ext js,md .).

[slieker-d]

This worked! Thank you very much!

[gajus]

🎉 This issue has been resolved in version 15.4.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[gajus]

🎉 This issue has been resolved in version 15.9.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[brettz9]

Reopening as the original issue was not actually resolved.

[brettz9]

This should have been fixed earlier in v18.1.6. Closing but feel free to refile with any reproducible examples. v15.4.0 also made it easier to work with indents via the paddedIndent option in case one deliberately adds (a fixed amount of) padding whitespace before example code.

As an aside re: the .md extension, support has been added in ESLint for the likes of **/*.md/*.js to indicate JavaScript fenced blocks within Markdown. That may be a better current option. (See the check-examples docs.)