Docs: Add valid example that shows vars in a block scope

[edg2s]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofixing to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

All the current valid examples show hoisting the var to the function scope. This example makes is clear that this rule allows you to declare vars inside a block scope, just not use them out of that scope.

Is there anything you'd like reviewers to focus on?

[eslint-github-bot]

Hi @edg2s!, thanks for the Pull Request

The first commit message isn't properly formatted. We ask that you update the message to match this format, as we use it to generate changelogs and automate releases.

• The commit message tag must be one of the following:

  The Tag is one of the following:

  • Fix - for a bug fix.
  • Update - either for a backwards-compatible enhancement or for a rule change that adds reported problems.
  • New - implements a new feature.
  • Breaking - for a backwards-incompatible enhancement or feature.
  • Docs - changes to documentation only.
  • Build - changes to build process only.
  • Upgrade - for a dependency upgrade.
  • Chore - for anything that isn't user-facing (for example, refactoring, adding tests, etc.).

  You can use the labels of the issue you are working on to determine the best tag.

• There should be a space following the initial tag and colon, for example 'New: Message'.

Read more about contributing to ESLint here

[eslint-github-bot]

Hi @edg2s!, thanks for the Pull Request

The first commit message isn't properly formatted. We ask that you update the message to match this format, as we use it to generate changelogs and automate releases.

• The commit message tag must be one of the following:

  The Tag is one of the following:

  • Fix - for a bug fix.
  • Update - either for a backwards-compatible enhancement or for a rule change that adds reported problems.
  • New - implements a new feature.
  • Breaking - for a backwards-incompatible enhancement or feature.
  • Docs - changes to documentation only.
  • Build - changes to build process only.
  • Upgrade - for a dependency upgrade.
  • Chore - for anything that isn't user-facing (for example, refactoring, adding tests, etc.).

  You can use the labels of the issue you are working on to determine the best tag.

• There should be a space following the initial tag and colon, for example 'New: Message'.

Read more about contributing to ESLint here

[nzakas]

Thanks. Can you add a corresponding example in the “invalid” section, too? Note that all of the current examples in the “valid” section are rewritten versions of the code in the “invalid” section, and that is by design.

[edg2s]

I did notice that, but I don't think there is a functionally equivalent invalid example for this function. I could move the console.log down but that would be different functionality.

[nzakas]

You may want to consider a different example, then, that can show the same thing.

[edg2s]

You may want to consider a different example, then, that can show the same thing.

Any invalid case would have a variable being used outside the scope in which it was defined. In order to fix that without changing the functionality you would have to move the variable declaration further up, but the whole point of this PR is to add an example of a var in a block scope.

[edg2s]

Note that all of the current examples in the “valid” section are rewritten versions of the code in the “invalid” section, and that is by design.

And there are many other places where the examples don't (or can't) match up perfectly, e.g. https://eslint.org/docs/rules/no-compare-neg-zero, https://eslint.org/docs/rules/valid-typeof, https://eslint.org/docs/rules/dot-location, ...

[nzakas]

The goal isn’t necessarily to show a bad example and then the fixed version, it’s to show an example of what the rule will flag and then a similar example that shows what the rule won’t flag.

Despite other rules not always following this pattern, this rule’s documentation does, so I’d prefer to stick with it.

[nzakas]

LGTM. Thanks!