Eslint-plugin-jsdoc: `check-examples` and whitespace-based rules (like `indent`)

Created on 8 May 2019 · 9Comments · Source: gajus/eslint-plugin-jsdoc

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.

enhancement

Source

brettz9

Most helpful comment

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

But I'd suggest doing this instead:

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

This has three benefits:

You can continue using indent with your other code JavaScript.
You can continue using non-indent rules for your examples.
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 .).

brettz9 on 24 May 2019

🎉1 👍1

All 9 comments

Can confirm. Having the same issue.

slieker-d on 24 May 2019

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.

brettz9 on 24 May 2019

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

slieker-d on 24 May 2019

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"
        }
    }]
}

slieker-d on 24 May 2019

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

But I'd suggest doing this instead:

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

This has three benefits:

You can continue using indent with your other code JavaScript.
You can continue using non-indent rules for your examples.
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 .).