Documentation for padded-blocks rule is out of date.

[jseminck]

Yesterday we spent quite some time figuring out how to correctly configure the padded-blocks rule. The problem we faced was that we wanted to disable padding (use option never) for all switches, classes and blocks.

But the documentation doesn't mention the option {blocks: never}. It only mentions:

• String"never" (which applies to blocks only)
• {switches: "never"}
• {classes: "never"}

See docs: https://github.com/eslint/eslint/blob/master/docs/rules/padded-blocks.md

As it's not possible to supply both a String and an object, as parameter, this basically got us confused. :)

Edit: If needed I could make a PR and try to clarify the documentation part.

Additionally, I would have expected that passing in never as a String would actually set blocks, classes and switches, and then the object option should only be used when you want to mix/match the different options... but I assume it's the way it is because the additional options were added after the initial rule was already created?

[jseminck]

Looks like my comment was incorrect. "never" according to code should still work as I interpreted the following line incorrectly initially. Will try to find out why it didn't not work for us.
https://github.com/eslint/eslint/blob/master/lib/rules/padded-blocks.js#L53

[alberto]

Hi @jseminck thanks for commenting.

There is a mention in the docs about blocks as an object key:

If you want to enforce padding within switches and classes, a configuration object can be passed as the rule argument to configure the cases separately ( e.g. { "blocks": "always", "switches": "always", "classes": "always" } ).

We could add some examples there, though.

Your original assumption is correct, the string option only affects blocks, for backwards compatibility reasons. It's also mentioned in the docs

By default, this rule ignores padding in switch statements and classes.

[platinumazure]

@pedrottimark Wondering if you could take a look at this issue and see if you think we could improve the information architecture in the padded-blocks documentation.