From 51c37b118aed9c0d7a0efd40c491efca04c82ef9 Mon Sep 17 00:00:00 2001 From: Bas Bosman Date: Tue, 28 Dec 2021 01:53:03 +0100 Subject: [PATCH] docs: consistency changes (#15404) * docs: consistency changes * chore: review comments * chore: update marked * chore: more review comments --- .github/ISSUE_TEMPLATE/NEW_SYNTAX.md | 4 +- .github/PULL_REQUEST_TEMPLATE.md | 3 +- .markdownlint.yml | 2 + Makefile.js | 39 +++++- .../working-with-custom-formatters.md | 24 ++-- docs/rules/accessor-pairs.md | 5 + docs/rules/array-bracket-newline.md | 8 +- docs/rules/array-element-newline.md | 8 +- docs/rules/callback-return.md | 8 +- docs/rules/camelcase.md | 2 +- docs/rules/comma-spacing.md | 10 +- docs/rules/comma-style.md | 8 +- docs/rules/complexity.md | 16 +-- docs/rules/default-case-last.md | 8 +- docs/rules/func-call-spacing.md | 12 +- docs/rules/func-names.md | 10 +- docs/rules/grouped-accessor-pairs.md | 12 +- docs/rules/id-denylist.md | 14 +- docs/rules/implicit-arrow-linebreak.md | 14 +- docs/rules/linebreak-style.md | 2 +- docs/rules/max-classes-per-file.md | 4 +- docs/rules/max-lines-per-function.md | 2 +- docs/rules/max-lines.md | 8 +- docs/rules/max-nested-callbacks.md | 12 +- docs/rules/new-parens.md | 4 +- docs/rules/no-debugger.md | 8 +- docs/rules/no-eq-null.md | 8 +- docs/rules/no-eval.md | 8 +- docs/rules/no-extra-parens.md | 8 +- docs/rules/no-implicit-coercion.md | 10 +- docs/rules/no-implicit-globals.md | 10 +- docs/rules/no-multiple-empty-lines.md | 6 +- docs/rules/no-negated-in-lhs.md | 2 - docs/rules/no-new-wrappers.md | 8 +- docs/rules/no-nonoctal-decimal-escape.md | 8 +- docs/rules/no-promise-executor-return.md | 8 +- docs/rules/no-return-await.md | 6 +- docs/rules/no-self-assign.md | 2 +- docs/rules/no-setter-return.md | 8 +- docs/rules/no-shadow-restricted-names.md | 8 +- docs/rules/no-shadow.md | 8 +- docs/rules/no-undef.md | 8 +- docs/rules/no-undefined.md | 12 +- docs/rules/no-underscore-dangle.md | 12 +- docs/rules/no-unreachable-loop.md | 2 +- docs/rules/no-unsafe-negation.md | 16 +-- docs/rules/no-unsafe-optional-chaining.md | 8 +- docs/rules/no-useless-backreference.md | 8 +- docs/rules/no-useless-rename.md | 16 +-- docs/rules/no-void.md | 10 +- docs/rules/object-curly-newline.md | 10 +- docs/rules/object-property-newline.md | 20 +-- docs/rules/object-shorthand.md | 26 ++-- docs/rules/padding-line-between-statements.md | 129 ++++++++---------- docs/rules/prefer-arrow-callback.md | 10 +- docs/rules/prefer-destructuring.md | 8 +- docs/rules/prefer-promise-reject-errors.md | 7 +- docs/rules/quotes.md | 2 +- docs/rules/semi-style.md | 12 +- docs/rules/semi.md | 10 +- docs/rules/switch-colon-spacing.md | 8 +- docs/rules/valid-jsdoc.md | 8 +- docs/user-guide/README.md | 14 +- docs/user-guide/migrating-to-2.0.0.md | 2 +- docs/user-guide/migrating-to-7.0.0.md | 96 ++++++------- docs/user-guide/migrating-to-8.0.0.md | 48 +++---- package.json | 1 + 67 files changed, 447 insertions(+), 411 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/NEW_SYNTAX.md b/.github/ISSUE_TEMPLATE/NEW_SYNTAX.md index e03cb6e11bd..f3ac551f6ba 100644 --- a/.github/ISSUE_TEMPLATE/NEW_SYNTAX.md +++ b/.github/ISSUE_TEMPLATE/NEW_SYNTAX.md @@ -20,7 +20,7 @@ assignees: '' **Please provide the TC39 URL for the syntax proposal:** - + **Please provide some example code for the new syntax:** @@ -41,3 +41,5 @@ Please check off all items that have already been completed. Be sure to paste th - [ ] `eslint` update: **Are you willing to submit a pull request to implement this syntax?** + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e2d756628cb..593e8f78421 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -42,5 +42,6 @@ #### What changes did you make? (Give an overview) - #### Is there anything you'd like reviewers to focus on? + + diff --git a/.markdownlint.yml b/.markdownlint.yml index c37cf77fbbc..a8478b2ae94 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -2,6 +2,8 @@ default: true # Exclusions for deliberate/widespread violations MD002: false # First header should be a h1 header +MD004: # Unordered list style + style: asterisk MD007: # Unordered list indentation indent: 4 MD013: false # Line length diff --git a/Makefile.js b/Makefile.js index 3730e9b8db2..10203f5ed4a 100644 --- a/Makefile.js +++ b/Makefile.js @@ -15,6 +15,7 @@ const checker = require("npm-license"), dateformat = require("dateformat"), fs = require("fs"), glob = require("glob"), + marked = require("marked"), markdownlint = require("markdownlint"), os = require("os"), path = require("path"), @@ -790,7 +791,9 @@ target.checkRuleFiles = function() { const basename = path.basename(filename, ".js"); const docFilename = `docs/rules/${basename}.md`; const docText = cat(docFilename); + const docMarkdown = marked.lexer(docText, { gfm: true, silent: false }); const ruleCode = cat(filename); + const knownHeaders = ["Rule Details", "Options", "Environments", "Examples", "Known Limitations", "When Not To Use It", "Related Rules", "Compatibility", "Further Reading"]; /** * Check if basename is present in rule-types.json file. @@ -820,7 +823,35 @@ target.checkRuleFiles = function() { } /** - * Check if deprecated information is in rule code and READNE.md. + * Check if all H2 headers are known and in the expected order + * Only H2 headers are checked as H1 and H3 are variable and/or rule specific. + * @returns {boolean} true if all headers are known and in the right order + */ + function hasKnownHeaders() { + const headers = docMarkdown.filter(token => token.type === "heading" && token.depth === 2).map(header => header.text); + + for (const header of headers) { + if (!knownHeaders.includes(header)) { + return false; + } + } + + /* + * Check only the subset of used headers for the correct order + */ + const presentHeaders = knownHeaders.filter(header => headers.includes(header)); + + for (let i = 0; i < presentHeaders.length; ++i) { + if (presentHeaders[i] !== headers[i]) { + return false; + } + } + + return true; + } + + /** + * Check if deprecated information is in rule code and README.md. * @returns {boolean} true if present * @private */ @@ -853,6 +884,12 @@ target.checkRuleFiles = function() { console.error("Missing id in the doc page's title of rule %s", basename); errors++; } + + // check for proper doc headers + if (!hasKnownHeaders()) { + console.error("Unknown or misplaced header in the doc page of rule %s, allowed headers (and their order) are: '%s'", basename, knownHeaders.join("', '")); + errors++; + } } // check for recommended configuration diff --git a/docs/developer-guide/working-with-custom-formatters.md b/docs/developer-guide/working-with-custom-formatters.md index 54db6632847..e157bb07941 100644 --- a/docs/developer-guide/working-with-custom-formatters.md +++ b/docs/developer-guide/working-with-custom-formatters.md @@ -100,23 +100,23 @@ also be manually applied to that page. --> Each object in the `results` array is a `result` object. Each `result` object contains the path of the file that was linted and information about linting issues that were encountered. Here are the properties available on each `result` object: -* **filePath**: The absolute path to the file that was linted. -* **messages**: An array of `message` objects. See below for more info about messages. -* **errorCount**: The number of errors for the given file. -* **warningCount**: The number of warnings for the given file. -* **source**: The source code for the given file. This property is omitted if this file has no errors/warnings or if the `output` property is present. -* **output**: The source code for the given file with as many fixes applied as possible. This property is omitted if no fix is available. +* **filePath**: The absolute path to the file that was linted. +* **messages**: An array of `message` objects. See below for more info about messages. +* **errorCount**: The number of errors for the given file. +* **warningCount**: The number of warnings for the given file. +* **source**: The source code for the given file. This property is omitted if this file has no errors/warnings or if the `output` property is present. +* **output**: The source code for the given file with as many fixes applied as possible. This property is omitted if no fix is available. ### The `message` Object Each `message` object contains information about the ESLint rule that was triggered by some source code. The properties available on each `message` object are: -* **ruleId**: the ID of the rule that produced the error or warning. -* **severity**: the severity of the failure, `1` for warnings and `2` for errors. -* **message**: the human readable description of the error. -* **line**: the line where the issue is located. -* **column**: the column where the issue is located. -* **nodeType**: the type of the node in the [AST](https://github.com/estree/estree/blob/master/spec.md#node-objects) +* **ruleId**: the ID of the rule that produced the error or warning. +* **severity**: the severity of the failure, `1` for warnings and `2` for errors. +* **message**: the human readable description of the error. +* **line**: the line where the issue is located. +* **column**: the column where the issue is located. +* **nodeType**: the type of the node in the [AST](https://github.com/estree/estree/blob/master/spec.md#node-objects) ## The `context` Argument diff --git a/docs/rules/accessor-pairs.md b/docs/rules/accessor-pairs.md index 22cf28ab982..dd64562e67e 100644 --- a/docs/rules/accessor-pairs.md +++ b/docs/rules/accessor-pairs.md @@ -281,6 +281,11 @@ See [no-dupe-class-members](no-dupe-class-members.md) if you also want to disall You can turn this rule off if you are not concerned with the simultaneous presence of setters and getters on objects. +## Related Rules + +* [no-dupe-keys](no-dupe-keys.md) +* [no-dupe-class-members](no-dupe-class-members.md) + ## Further Reading * [Object Setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) diff --git a/docs/rules/array-bracket-newline.md b/docs/rules/array-bracket-newline.md index bb990c75bf8..d62b61e337f 100644 --- a/docs/rules/array-bracket-newline.md +++ b/docs/rules/array-bracket-newline.md @@ -271,10 +271,10 @@ var e = [ If you don't want to enforce line breaks after opening and before closing array brackets, don't enable this rule. -## Compatibility - -* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements) - ## Related Rules * [array-bracket-spacing](array-bracket-spacing.md) + +## Compatibility + +* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements) diff --git a/docs/rules/array-element-newline.md b/docs/rules/array-element-newline.md index 650a00892eb..dabb5542394 100644 --- a/docs/rules/array-element-newline.md +++ b/docs/rules/array-element-newline.md @@ -374,10 +374,6 @@ var [i = function foo() { If you don't want to enforce linebreaks between array elements, don't enable this rule. -## Compatibility - -* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements) - ## Related Rules * [array-bracket-spacing](array-bracket-spacing.md) @@ -388,3 +384,7 @@ If you don't want to enforce linebreaks between array elements, don't enable thi * [max-statements-per-line](max-statements-per-line.md) * [block-spacing](block-spacing.md) * [brace-style](brace-style.md) + +## Compatibility + +* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements) diff --git a/docs/rules/callback-return.md b/docs/rules/callback-return.md index c4e7277c457..b722e297562 100644 --- a/docs/rules/callback-return.md +++ b/docs/rules/callback-return.md @@ -165,11 +165,11 @@ There are some cases where you might want to call a callback function more than may lead to incorrect behavior. In those cases you may want to reserve a special name for those callbacks and not include that in the list of callbacks that trigger warnings. +## Related Rules + +* [handle-callback-err](handle-callback-err.md) + ## Further Reading * [The Art Of Node: Callbacks](https://github.com/maxogden/art-of-node#callbacks) * [Nodejitsu: What are the error conventions?](https://docs.nodejitsu.com/articles/errors/what-are-the-error-conventions/) - -## Related Rules - -* [handle-callback-err](handle-callback-err.md) diff --git a/docs/rules/camelcase.md b/docs/rules/camelcase.md index 164dfab7c46..da9dcda50e5 100644 --- a/docs/rules/camelcase.md +++ b/docs/rules/camelcase.md @@ -241,7 +241,7 @@ Examples of **correct** code for this rule with the `{ "ignoreGlobals": true }` const foo = no_camelcased; ``` -## allow +### allow Examples of **correct** code for this rule with the `allow` option: diff --git a/docs/rules/comma-spacing.md b/docs/rules/comma-spacing.md index 3160f86a8f5..d6a01563f8f 100644 --- a/docs/rules/comma-spacing.md +++ b/docs/rules/comma-spacing.md @@ -110,11 +110,6 @@ var arr = [,2 ,3] If your project will not be following a consistent comma-spacing pattern, turn this rule off. -## Further Reading - -* [JavaScript](http://javascript.crockford.com/code.html) -* [Dojo Style Guide](https://dojotoolkit.org/reference-guide/1.9/developer/styleguide.html) - ## Related Rules * [array-bracket-spacing](array-bracket-spacing.md) @@ -125,3 +120,8 @@ If your project will not be following a consistent comma-spacing pattern, turn t * [space-after-keywords](space-after-keywords.md) * [space-unary-ops](space-unary-ops.md) * [space-return-throw-case](space-return-throw-case.md) + +## Further Reading + +* [JavaScript](http://javascript.crockford.com/code.html) +* [Dojo Style Guide](https://dojotoolkit.org/reference-guide/1.9/developer/styleguide.html) diff --git a/docs/rules/comma-style.md b/docs/rules/comma-style.md index f71e3105aa8..bae9a149531 100644 --- a/docs/rules/comma-style.md +++ b/docs/rules/comma-style.md @@ -157,13 +157,13 @@ var o = {fst:1, This rule can safely be turned off if your project does not care about enforcing a consistent comma style. +## Related Rules + +* [operator-linebreak](operator-linebreak.md) + ## Further Reading For more information on the Comma First style: * [A better coding convention for lists and object literals in JavaScript by isaacs](https://gist.github.com/isaacs/357981) * [npm coding style guideline](https://docs.npmjs.com/misc/coding-style) - -## Related Rules - -* [operator-linebreak](operator-linebreak.md) diff --git a/docs/rules/complexity.md b/docs/rules/complexity.md index 7955d1a2854..5f33334a6b8 100644 --- a/docs/rules/complexity.md +++ b/docs/rules/complexity.md @@ -124,14 +124,6 @@ is equivalent to If you can't determine an appropriate complexity limit for your code, then it's best to disable this rule. -## Further Reading - -* [Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) -* [Complexity Analysis of JavaScript Code](https://ariya.io/2012/12/complexity-analysis-of-javascript-code) -* [More about Complexity in JavaScript](https://craftsmanshipforsoftware.com/2015/05/25/complexity-for-javascript/) -* [About Complexity](https://web.archive.org/web/20160808115119/http://jscomplexity.org/complexity) -* [Discussion about Complexity in ESLint and more links](https://github.com/eslint/eslint/issues/4808#issuecomment-167795140) - ## Related Rules * [max-depth](max-depth.md) @@ -141,3 +133,11 @@ If you can't determine an appropriate complexity limit for your code, then it's * [max-nested-callbacks](max-nested-callbacks.md) * [max-params](max-params.md) * [max-statements](max-statements.md) + +## Further Reading + +* [Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) +* [Complexity Analysis of JavaScript Code](https://ariya.io/2012/12/complexity-analysis-of-javascript-code) +* [More about Complexity in JavaScript](https://craftsmanshipforsoftware.com/2015/05/25/complexity-for-javascript/) +* [About Complexity](https://web.archive.org/web/20160808115119/http://jscomplexity.org/complexity) +* [Discussion about Complexity in ESLint and more links](https://github.com/eslint/eslint/issues/4808#issuecomment-167795140) diff --git a/docs/rules/default-case-last.md b/docs/rules/default-case-last.md index c9eedbeec65..a82530de1da 100644 --- a/docs/rules/default-case-last.md +++ b/docs/rules/default-case-last.md @@ -116,10 +116,10 @@ if (foo !== 0) { doSomethingAnyway(); ``` -## Further Reading - -* [MDN switch statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch) - ## Related Rules * [default-case](default-case.md) + +## Further Reading + +* [MDN switch statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch) diff --git a/docs/rules/func-call-spacing.md b/docs/rules/func-call-spacing.md index 09829151edb..45660fc444e 100644 --- a/docs/rules/func-call-spacing.md +++ b/docs/rules/func-call-spacing.md @@ -17,12 +17,12 @@ new Date (); This rule requires or disallows spaces between the function name and the opening parenthesis that calls it. -## options +## Options This rule has a string option: -- `"never"` (default) disallows space between the function name and the opening parenthesis. -- `"always"` requires space between the function name and the opening parenthesis. +* `"never"` (default) disallows space between the function name and the opening parenthesis. +* `"always"` requires space between the function name and the opening parenthesis. Further, in `"always"` mode, a second object option is available that contains a single boolean `allowNewlines` property. @@ -97,9 +97,9 @@ This rule can safely be turned off if your project does not care about enforcing ## Related Rules -- [no-spaced-func](no-spaced-func.md) (deprecated) +* [no-spaced-func](no-spaced-func.md) (deprecated) ## Compatibility -- **JSCS**: [disallowSpacesInCallExpression](https://jscs-dev.github.io/rule/disallowSpacesInCallExpression) -- **JSCS**: [requireSpacesInCallExpression](https://jscs-dev.github.io/rule/requireSpacesInCallExpression) +* **JSCS**: [disallowSpacesInCallExpression](https://jscs-dev.github.io/rule/disallowSpacesInCallExpression) +* **JSCS**: [requireSpacesInCallExpression](https://jscs-dev.github.io/rule/requireSpacesInCallExpression) diff --git a/docs/rules/func-names.md b/docs/rules/func-names.md index ea1ba617e54..829cb99dd04 100644 --- a/docs/rules/func-names.md +++ b/docs/rules/func-names.md @@ -206,12 +206,12 @@ Examples of **correct** code for this rule with the `"never", { "generators": "a var foo = bar(function *baz() {}); ``` -## Further Reading - -* [Functions Explained](http://markdaggett.com/blog/2013/02/15/functions-explained/) -* [Function Names in ES6](http://2ality.com/2015/09/function-names-es6.html) - ## Compatibility * **JSCS**: [requireAnonymousFunctions](https://jscs-dev.github.io/rule/requireAnonymousFunctions) * **JSCS**: [disallowAnonymousFunctions](https://jscs-dev.github.io/rule/disallowAnonymousFunctions) + +## Further Reading + +* [Functions Explained](http://markdaggett.com/blog/2013/02/15/functions-explained/) +* [Function Names in ES6](http://2ality.com/2015/09/function-names-es6.html) diff --git a/docs/rules/grouped-accessor-pairs.md b/docs/rules/grouped-accessor-pairs.md index 60848d1d0aa..d77c8abbfaa 100644 --- a/docs/rules/grouped-accessor-pairs.md +++ b/docs/rules/grouped-accessor-pairs.md @@ -313,14 +313,14 @@ See [no-dupe-keys](no-dupe-keys.md) if you also want to disallow duplicate keys See [no-dupe-class-members](no-dupe-class-members.md) if you also want to disallow duplicate names in class definitions. -## Further Reading - -* [Object Setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) -* [Object Getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) -* [Classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) - ## Related Rules * [accessor-pairs](accessor-pairs.md) * [no-dupe-keys](no-dupe-keys.md) * [no-dupe-class-members](no-dupe-class-members.md) + +## Further Reading + +* [Object Setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) +* [Object Getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) +* [Classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) diff --git a/docs/rules/id-denylist.md b/docs/rules/id-denylist.md index 071a34f7940..1da92bb1785 100644 --- a/docs/rules/id-denylist.md +++ b/docs/rules/id-denylist.md @@ -10,16 +10,16 @@ This rule disallows specified identifiers in assignments and `function` definiti This rule will catch disallowed identifiers that are: -- variable declarations -- function declarations -- object properties assigned to during object creation -- class fields -- class methods +* variable declarations +* function declarations +* object properties assigned to during object creation +* class fields +* class methods It will not catch disallowed identifiers that are: -- function calls (so you can still use functions you do not have control over) -- object properties (so you can still use objects you do not have control over) +* function calls (so you can still use functions you do not have control over) +* object properties (so you can still use objects you do not have control over) ## Options diff --git a/docs/rules/implicit-arrow-linebreak.md b/docs/rules/implicit-arrow-linebreak.md index a1a23553549..5558dc503ba 100644 --- a/docs/rules/implicit-arrow-linebreak.md +++ b/docs/rules/implicit-arrow-linebreak.md @@ -6,16 +6,12 @@ An arrow function body can contain an implicit return as an expression instead o This rule aims to enforce a consistent location for an arrow function containing an implicit return. -See Also: - -- [`brace-style`](https://eslint.org/docs/rules/brace-style) which enforces this behavior for arrow functions with block bodies. - ### Options This rule accepts a string option: -- `"beside"` (default) disallows a newline before an arrow function body. -- `"below"` requires a newline before an arrow function body. +* `"beside"` (default) disallows a newline before an arrow function body. +* `"below"` requires a newline before an arrow function body. Examples of **incorrect** code for this rule with the default `"beside"` option: @@ -98,4 +94,8 @@ Examples of **correct** code for this rule with the `"below"` option: If you're not concerned about consistent locations of implicitly returned arrow function expressions, you should not turn on this rule. -You can also disable this rule if you are using the `"always"` option for the [`arrow-body-style`](https://eslint.org/docs/rules/arrow-body-style), since this will disable the use of implicit returns in arrow functions. +You can also disable this rule if you are using the `"always"` option for the [`arrow-body-style`](arrow-body-style.md), since this will disable the use of implicit returns in arrow functions. + +## Related Rules + +* [`brace-style`](brace-style.md) which enforces this behavior for arrow functions with block bodies. diff --git a/docs/rules/linebreak-style.md b/docs/rules/linebreak-style.md index a4eb620acc3..5143ae49dfc 100644 --- a/docs/rules/linebreak-style.md +++ b/docs/rules/linebreak-style.md @@ -66,7 +66,7 @@ function foo(params) { // \r\n } // \r\n ``` -## Using this rule with version control systems +### Using this rule with version control systems Version control systems sometimes have special behavior for linebreaks. To make it easy for developers to contribute to your codebase from different platforms, you may want to configure your VCS to handle linebreaks appropriately. diff --git a/docs/rules/max-classes-per-file.md b/docs/rules/max-classes-per-file.md index 70f3348a0fa..dac65de9d57 100644 --- a/docs/rules/max-classes-per-file.md +++ b/docs/rules/max-classes-per-file.md @@ -32,8 +32,8 @@ This rule may be configured with either an object or a number. If the option is an object, it may contain one or both of: -- `ignoreExpressions`: a boolean option (defaulted to `false`) to ignore class expressions. -- `max`: a numeric option (defaulted to 1) to specify the maximum number of classes. +* `ignoreExpressions`: a boolean option (defaulted to `false`) to ignore class expressions. +* `max`: a numeric option (defaulted to 1) to specify the maximum number of classes. For example: diff --git a/docs/rules/max-lines-per-function.md b/docs/rules/max-lines-per-function.md index f2af93b8d48..3b01f7d24e0 100644 --- a/docs/rules/max-lines-per-function.md +++ b/docs/rules/max-lines-per-function.md @@ -6,7 +6,7 @@ Some people consider large functions a code smell. Large functions tend to do a This rule enforces a maximum number of lines per function, in order to aid in maintainability and reduce complexity. -## Why not use `max-statements` or other complexity measurement rules instead? +### Why not use `max-statements` or other complexity measurement rules instead? Nested long method chains like the below example are often broken onto separate lines for readability: diff --git a/docs/rules/max-lines.md b/docs/rules/max-lines.md index 74b9aada228..3842edc92b5 100644 --- a/docs/rules/max-lines.md +++ b/docs/rules/max-lines.md @@ -109,10 +109,6 @@ var a, You can turn this rule off if you are not concerned with the number of lines in your files. -## Further reading - -* [Software Module size and file size](https://web.archive.org/web/20160725154648/http://www.mind2b.com/component/content/article/24-software-module-size-and-file-size) - ## Related Rules * [complexity](complexity.md) @@ -125,3 +121,7 @@ You can turn this rule off if you are not concerned with the number of lines in ## Compatibility * **JSCS**: [maximumNumberOfLines](https://jscs-dev.github.io/rule/maximumNumberOfLines) + +## Further Reading + +* [Software Module size and file size](https://web.archive.org/web/20160725154648/http://www.mind2b.com/component/content/article/24-software-module-size-and-file-size) diff --git a/docs/rules/max-nested-callbacks.md b/docs/rules/max-nested-callbacks.md index 24e4b907fa5..3b4ac5ee9ff 100644 --- a/docs/rules/max-nested-callbacks.md +++ b/docs/rules/max-nested-callbacks.md @@ -68,12 +68,6 @@ function handleFoo4() { } ``` -## Further Reading - -* [Control flow in Node.js](http://book.mixu.net/node/ch7.html) -* [Control Flow in Node](https://howtonode.org/control-flow) -* [Control Flow in Node Part II](https://howtonode.org/control-flow-part-ii) - ## Related Rules * [complexity](complexity.md) @@ -83,3 +77,9 @@ function handleFoo4() { * [max-lines-per-function](max-lines-per-function.md) * [max-params](max-params.md) * [max-statements](max-statements.md) + +## Further Reading + +* [Control flow in Node.js](http://book.mixu.net/node/ch7.html) +* [Control Flow in Node](https://howtonode.org/control-flow) +* [Control Flow in Node Part II](https://howtonode.org/control-flow-part-ii) diff --git a/docs/rules/new-parens.md b/docs/rules/new-parens.md index 0b2a49b7e76..5237abdd4ec 100644 --- a/docs/rules/new-parens.md +++ b/docs/rules/new-parens.md @@ -14,8 +14,8 @@ This rule can enforce or disallow parentheses when invoking a constructor with n This rule takes one option. -- `"always"` enforces parenthesis after a new constructor with no arguments (default) -- `"never"` enforces no parenthesis after a new constructor with no arguments +* `"always"` enforces parenthesis after a new constructor with no arguments (default) +* `"never"` enforces no parenthesis after a new constructor with no arguments ### always diff --git a/docs/rules/no-debugger.md b/docs/rules/no-debugger.md index f8220bde813..5ff4da3fe9c 100644 --- a/docs/rules/no-debugger.md +++ b/docs/rules/no-debugger.md @@ -31,11 +31,11 @@ function isTruthy(x) { If your code is still very much in development and don't want to worry about stripping `debugger` statements, then turn this rule off. You'll generally want to turn it back on when testing code prior to deployment. -## Further Reading - -* [Debugger](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) - ## Related Rules * [no-alert](no-alert.md) * [no-console](no-console.md) + +## Further Reading + +* [Debugger](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) diff --git a/docs/rules/no-eq-null.md b/docs/rules/no-eq-null.md index 7b0f5df142a..c06287fd859 100644 --- a/docs/rules/no-eq-null.md +++ b/docs/rules/no-eq-null.md @@ -40,10 +40,10 @@ while (qux !== null) { } ``` -## Compatibility - -* **JSHint**: This rule corresponds to `eqnull` rule of JSHint. - ## When Not To Use It If you want to enforce type-checking operations in general, use the more powerful [eqeqeq](./eqeqeq) instead. + +## Compatibility + +* **JSHint**: This rule corresponds to `eqnull` rule of JSHint. diff --git a/docs/rules/no-eval.md b/docs/rules/no-eval.md index 4a2a3b79733..eaa628f754b 100644 --- a/docs/rules/no-eval.md +++ b/docs/rules/no-eval.md @@ -145,11 +145,11 @@ global.eval("var a = 0"); foo.eval("var a = 0"); ``` +## Related Rules + +* [no-implied-eval](no-implied-eval.md) + ## Further Reading * [Eval is Evil, Part One](https://blogs.msdn.com/b/ericlippert/archive/2003/11/01/53329.aspx) * [How evil is eval](https://javascriptweblog.wordpress.com/2010/04/19/how-evil-is-eval/) - -## Related Rules - -* [no-implied-eval](no-implied-eval.md) diff --git a/docs/rules/no-extra-parens.md b/docs/rules/no-extra-parens.md index b521dcbe268..4b703a8d3f8 100644 --- a/docs/rules/no-extra-parens.md +++ b/docs/rules/no-extra-parens.md @@ -289,12 +289,12 @@ a = (b * c); typeof (a); ``` -## Further Reading - -* [MDN: Operator Precedence](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Operator_Precedence) - ## Related Rules * [arrow-parens](arrow-parens.md) * [no-cond-assign](no-cond-assign.md) * [no-return-assign](no-return-assign.md) + +## Further Reading + +* [MDN: Operator Precedence](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Operator_Precedence) diff --git a/docs/rules/no-implicit-coercion.md b/docs/rules/no-implicit-coercion.md index 8ccee339f05..9ad0b77100e 100644 --- a/docs/rules/no-implicit-coercion.md +++ b/docs/rules/no-implicit-coercion.md @@ -33,11 +33,11 @@ This rule is aimed to flag shorter notations for the type conversion, then sugge This rule has three main options and one override option to allow some coercions as required. -- `"boolean"` (`true` by default) - When this is `true`, this rule warns shorter type conversions for `boolean` type. -- `"number"` (`true` by default) - When this is `true`, this rule warns shorter type conversions for `number` type. -- `"string"` (`true` by default) - When this is `true`, this rule warns shorter type conversions for `string` type. -- `"disallowTemplateShorthand"` (`false` by default) - When this is `true`, this rule warns `string` type conversions using `${expression}` form. -- `"allow"` (`empty` by default) - Each entry in this array can be one of `~`, `!!`, `+` or `*` that are to be allowed. +* `"boolean"` (`true` by default) - When this is `true`, this rule warns shorter type conversions for `boolean` type. +* `"number"` (`true` by default) - When this is `true`, this rule warns shorter type conversions for `number` type. +* `"string"` (`true` by default) - When this is `true`, this rule warns shorter type conversions for `string` type. +* `"disallowTemplateShorthand"` (`false` by default) - When this is `true`, this rule warns `string` type conversions using `${expression}` form. +* `"allow"` (`empty` by default) - Each entry in this array can be one of `~`, `!!`, `+` or `*` that are to be allowed. Note that operator `+` in `allow` list would allow `+foo` (number coercion) as well as `"" + foo` (string coercion). diff --git a/docs/rules/no-implicit-globals.md b/docs/rules/no-implicit-globals.md index 479d958d62c..a7c03dc3bc4 100644 --- a/docs/rules/no-implicit-globals.md +++ b/docs/rules/no-implicit-globals.md @@ -214,13 +214,13 @@ and you also don't want this rule to warn you about the read-only globals, you c In the case of an ES module, if you don't want this rule to warn you about the read-only globals you can disable this rule. +## Related Rules + +* [no-undef](no-undef.md) +* [no-global-assign](no-global-assign.md) + ## Further Reading * [Immediately-Invoked Function Expression (IIFE)](http://benalman.com/news/2010/11/immediately-invoked-function-expression/) * [ReferenceError: assignment to undeclared variable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Undeclared_var) * [Temporal Dead Zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#Temporal_dead_zone) - -## Related Rules - -* [no-undef](no-undef.md) -* [no-global-assign](no-global-assign.md) diff --git a/docs/rules/no-multiple-empty-lines.md b/docs/rules/no-multiple-empty-lines.md index 1a04841825c..2e1bd0e529c 100644 --- a/docs/rules/no-multiple-empty-lines.md +++ b/docs/rules/no-multiple-empty-lines.md @@ -10,9 +10,9 @@ This rule aims to reduce the scrolling required when reading through your code. This rule has an object option: -- `"max"` (default: `2`) enforces a maximum number of consecutive empty lines. -- `"maxEOF"` enforces a maximum number of consecutive empty lines at the end of files. -- `"maxBOF"` enforces a maximum number of consecutive empty lines at the beginning of files. +* `"max"` (default: `2`) enforces a maximum number of consecutive empty lines. +* `"maxEOF"` enforces a maximum number of consecutive empty lines at the end of files. +* `"maxBOF"` enforces a maximum number of consecutive empty lines at the beginning of files. ### max diff --git a/docs/rules/no-negated-in-lhs.md b/docs/rules/no-negated-in-lhs.md index dd3d422f9a8..8961944ab60 100644 --- a/docs/rules/no-negated-in-lhs.md +++ b/docs/rules/no-negated-in-lhs.md @@ -2,8 +2,6 @@ This rule was **deprecated** in ESLint v3.3.0 and replaced by the [no-unsafe-negation](no-unsafe-negation.md) rule. -## Rule Details - Just as developers might type `-a + b` when they mean `-(a + b)` for the negative of a sum, they might type `!key in object` by mistake when they almost certainly mean `!(key in object)` to test that a key is not in an object. ## Rule Details diff --git a/docs/rules/no-new-wrappers.md b/docs/rules/no-new-wrappers.md index 45247e5ee0d..50fdacd784b 100644 --- a/docs/rules/no-new-wrappers.md +++ b/docs/rules/no-new-wrappers.md @@ -68,11 +68,11 @@ var object = new MyString(); If you want to allow the use of primitive wrapper objects, then you can safely disable this rule. -## Further Reading - -* [Wrapper objects](https://www.inkling.com/read/javascript-definitive-guide-david-flanagan-6th/chapter-3/wrapper-objects) - ## Related Rules * [no-array-constructor](no-array-constructor.md) * [no-new-object](no-new-object.md) + +## Further Reading + +* [Wrapper objects](https://www.inkling.com/read/javascript-definitive-guide-david-flanagan-6th/chapter-3/wrapper-objects) diff --git a/docs/rules/no-nonoctal-decimal-escape.md b/docs/rules/no-nonoctal-decimal-escape.md index 930b555607a..ad210a7375b 100644 --- a/docs/rules/no-nonoctal-decimal-escape.md +++ b/docs/rules/no-nonoctal-decimal-escape.md @@ -53,10 +53,10 @@ var baz = "Don't use \\8 and \\9 escapes."; var quux = "\0\u0038"; ``` -## Further Reading - -* [NonOctalDecimalEscapeSequence](https://tc39.es/ecma262/#prod-annexB-NonOctalDecimalEscapeSequence) in ECMAScript specification - ## Related Rules * [no-octal-escape](no-octal-escape.md) + +## Further Reading + +* [NonOctalDecimalEscapeSequence](https://tc39.es/ecma262/#prod-annexB-NonOctalDecimalEscapeSequence) in ECMAScript specification diff --git a/docs/rules/no-promise-executor-return.md b/docs/rules/no-promise-executor-return.md index 1adfe37b1e4..87611c914ed 100644 --- a/docs/rules/no-promise-executor-return.md +++ b/docs/rules/no-promise-executor-return.md @@ -87,10 +87,10 @@ new Promise((resolve, reject) => { Promise.resolve(1); ``` -## Further Reading - -* [MDN Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) - ## Related Rules * [no-async-promise-executor](no-async-promise-executor.md) + +## Further Reading + +* [MDN Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) diff --git a/docs/rules/no-return-await.md b/docs/rules/no-return-await.md index e3f7be259d7..fa7c7fc8e5c 100644 --- a/docs/rules/no-return-await.md +++ b/docs/rules/no-return-await.md @@ -50,9 +50,9 @@ async function foo() { There are a few reasons you might want to turn this rule off: -- If you want to use `await` to denote a value that is a thenable -- If you do not want the performance benefit of avoiding `return await` -- If you want the functions to show up in stack traces (useful for debugging purposes) +* If you want to use `await` to denote a value that is a thenable +* If you do not want the performance benefit of avoiding `return await` +* If you want the functions to show up in stack traces (useful for debugging purposes) ## Further Reading diff --git a/docs/rules/no-self-assign.md b/docs/rules/no-self-assign.md index 2991504e838..f7132e2b166 100644 --- a/docs/rules/no-self-assign.md +++ b/docs/rules/no-self-assign.md @@ -65,7 +65,7 @@ This rule has the option to check properties as well. } ``` -- `props` - if this is `true`, `no-self-assign` rule warns self-assignments of properties. Default is `true`. +* `props` - if this is `true`, `no-self-assign` rule warns self-assignments of properties. Default is `true`. ### props diff --git a/docs/rules/no-setter-return.md b/docs/rules/no-setter-return.md index 53089746edc..7e3b1323ff1 100644 --- a/docs/rules/no-setter-return.md +++ b/docs/rules/no-setter-return.md @@ -92,10 +92,10 @@ Object.defineProperty(foo, "bar", { }); ``` -## Further Reading - -* [MDN setter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) - ## Related Rules * [getter-return](getter-return.md) + +## Further Reading + +* [MDN setter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) diff --git a/docs/rules/no-shadow-restricted-names.md b/docs/rules/no-shadow-restricted-names.md index 890353da787..f7e6530d4a3 100644 --- a/docs/rules/no-shadow-restricted-names.md +++ b/docs/rules/no-shadow-restricted-names.md @@ -37,11 +37,11 @@ function f(a, b){} var undefined; ``` +## Related Rules + +* [no-shadow](no-shadow.md) + ## Further Reading * [Annotated ES5 - §15.1.1](https://es5.github.io/#x15.1.1) * [Annotated ES5 - Annex C](https://es5.github.io/#C) - -## Related Rules - -* [no-shadow](no-shadow.md) diff --git a/docs/rules/no-shadow.md b/docs/rules/no-shadow.md index 3bf9783a942..bf8400a4239 100644 --- a/docs/rules/no-shadow.md +++ b/docs/rules/no-shadow.md @@ -164,10 +164,10 @@ foo(function (err, result) { }); ``` -## Further Reading - -* [Variable Shadowing](https://en.wikipedia.org/wiki/Variable_shadowing) - ## Related Rules * [no-shadow-restricted-names](no-shadow-restricted-names.md) + +## Further Reading + +* [Variable Shadowing](https://en.wikipedia.org/wiki/Variable_shadowing) diff --git a/docs/rules/no-undef.md b/docs/rules/no-undef.md index a7de8052357..f31f2877c23 100644 --- a/docs/rules/no-undef.md +++ b/docs/rules/no-undef.md @@ -101,11 +101,11 @@ module.exports = function() { If explicit declaration of global variables is not to your taste. -## Compatibility - -This rule provides compatibility with treatment of global variables in [JSHint](http://jshint.com/) and [JSLint](http://www.jslint.com). - ## Related Rules * [no-global-assign](no-global-assign.md) * [no-redeclare](no-redeclare.md) + +## Compatibility + +This rule provides compatibility with treatment of global variables in [JSHint](http://jshint.com/) and [JSLint](http://www.jslint.com). diff --git a/docs/rules/no-undefined.md b/docs/rules/no-undefined.md index 0e67c21fd86..3d97d5b1d24 100644 --- a/docs/rules/no-undefined.md +++ b/docs/rules/no-undefined.md @@ -64,15 +64,15 @@ global.undefined = "foo"; If you want to allow the use of `undefined` in your code, then you can safely turn this rule off. -## Further Reading - -* [undefined - JavaScript \| MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined) -* [Understanding JavaScript’s ‘undefined’ \| JavaScript, JavaScript...](https://javascriptweblog.wordpress.com/2010/08/16/understanding-undefined-and-preventing-referenceerrors/) -* [ECMA262 edition 5.1 §15.1.1.3: undefined](https://es5.github.io/#x15.1.1.3) - ## Related Rules * [no-undef-init](no-undef-init.md) * [no-void](no-void.md) * [no-shadow-restricted-names](no-shadow-restricted-names.md) * [no-global-assign](no-global-assign.md) + +## Further Reading + +* [undefined - JavaScript \| MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined) +* [Understanding JavaScript’s ‘undefined’ \| JavaScript, JavaScript...](https://javascriptweblog.wordpress.com/2010/08/16/understanding-undefined-and-preventing-referenceerrors/) +* [ECMA262 edition 5.1 §15.1.1.3: undefined](https://es5.github.io/#x15.1.1.3) diff --git a/docs/rules/no-underscore-dangle.md b/docs/rules/no-underscore-dangle.md index ded42815d2a..5e33ed5d0fd 100644 --- a/docs/rules/no-underscore-dangle.md +++ b/docs/rules/no-underscore-dangle.md @@ -42,12 +42,12 @@ const foo = (_bar) => {}; This rule has an object option: -- `"allow"` allows specified identifiers to have dangling underscores -- `"allowAfterThis": false` (default) disallows dangling underscores in members of the `this` object -- `"allowAfterSuper": false` (default) disallows dangling underscores in members of the `super` object -- `"allowAfterThisConstructor": false` (default) disallows dangling underscores in members of the `this.constructor` object -- `"enforceInMethodNames": false` (default) allows dangling underscores in method names -- `"allowFunctionParams": true` (default) allows dangling underscores in function parameter names +* `"allow"` allows specified identifiers to have dangling underscores +* `"allowAfterThis": false` (default) disallows dangling underscores in members of the `this` object +* `"allowAfterSuper": false` (default) disallows dangling underscores in members of the `super` object +* `"allowAfterThisConstructor": false` (default) disallows dangling underscores in members of the `this.constructor` object +* `"enforceInMethodNames": false` (default) allows dangling underscores in method names +* `"allowFunctionParams": true` (default) allows dangling underscores in function parameter names ### allow diff --git a/docs/rules/no-unreachable-loop.md b/docs/rules/no-unreachable-loop.md index c58b97f382d..88324df8d0d 100644 --- a/docs/rules/no-unreachable-loop.md +++ b/docs/rules/no-unreachable-loop.md @@ -146,7 +146,7 @@ This rule has an object option, with one option: * `"ignore"` - an optional array of loop types that will be ignored by this rule. -## ignore +### ignore You can specify up to 5 different elements in the `"ignore"` array: diff --git a/docs/rules/no-unsafe-negation.md b/docs/rules/no-unsafe-negation.md index 38bb9b02fd1..a8728474514 100644 --- a/docs/rules/no-unsafe-negation.md +++ b/docs/rules/no-unsafe-negation.md @@ -6,8 +6,8 @@ Just as developers might type `-a + b` when they mean `-(a + b)` for the negativ This rule disallows negating the left operand of the following relational operators: -- [`in` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/in). -- [`instanceof` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof). +* [`in` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/in). +* [`instanceof` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof). Examples of **incorrect** code for this rule: @@ -74,17 +74,17 @@ if (!(foo) in object) { This rule has an object option: -- `"enforceForOrderingRelations": false` (default) allows negation of the left-hand side of ordering relational operators (`<`, `>`, `<=`, `>=`) -- `"enforceForOrderingRelations": true` disallows negation of the left-hand side of ordering relational operators +* `"enforceForOrderingRelations": false` (default) allows negation of the left-hand side of ordering relational operators (`<`, `>`, `<=`, `>=`) +* `"enforceForOrderingRelations": true` disallows negation of the left-hand side of ordering relational operators ### enforceForOrderingRelations With this option set to `true` the rule is additionally enforced for: -- `<` operator. -- `>` operator. -- `<=` operator. -- `>=` operator. +* `<` operator. +* `>` operator. +* `<=` operator. +* `>=` operator. The purpose is to avoid expressions such as `! a < b` (which is equivalent to `(a ? 0 : 1) < b`) when what is really intended is `!(a < b)`. diff --git a/docs/rules/no-unsafe-optional-chaining.md b/docs/rules/no-unsafe-optional-chaining.md index 49fa415e0c0..28b4c40540d 100644 --- a/docs/rules/no-unsafe-optional-chaining.md +++ b/docs/rules/no-unsafe-optional-chaining.md @@ -115,15 +115,15 @@ async function foo () { This rule has an object option: -- `disallowArithmeticOperators`: Disallow arithmetic operations on optional chaining expressions (Default `false`). If this is `true`, this rule warns arithmetic operations on optional chaining expressions, which possibly result in `NaN`. +* `disallowArithmeticOperators`: Disallow arithmetic operations on optional chaining expressions (Default `false`). If this is `true`, this rule warns arithmetic operations on optional chaining expressions, which possibly result in `NaN`. ### disallowArithmeticOperators With this option set to `true` the rule is enforced for: -- Unary operators: `-`, `+` -- Arithmetic operators: `+`, `-`, `/`, `*`, `%`, `**` -- Assignment operators: `+=`, `-=`, `/=`, `*=`, `%=`, `**=` +* Unary operators: `-`, `+` +* Arithmetic operators: `+`, `-`, `/`, `*`, `%`, `**` +* Assignment operators: `+=`, `-=`, `/=`, `*=`, `%=`, `**=` Examples of additional **incorrect** code for this rule with the `{ "disallowArithmeticOperators": true }` option: diff --git a/docs/rules/no-useless-backreference.md b/docs/rules/no-useless-backreference.md index d2360b39567..e72b050d02e 100644 --- a/docs/rules/no-useless-backreference.md +++ b/docs/rules/no-useless-backreference.md @@ -119,12 +119,12 @@ Examples of additional **correct** code for this rule: /^(a)\1\2$/.test("aa\x02"); // true. In this case, \1 is a backreference, \2 is an octal escape sequence. ``` -## Further Reading - -* [MDN: Regular Expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) - ## Related Rules * [no-control-regex](no-control-regex.md) * [no-empty-character-class](no-empty-character-class.md) * [no-invalid-regexp](no-invalid-regexp.md) + +## Further Reading + +* [MDN: Regular Expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) diff --git a/docs/rules/no-useless-rename.md b/docs/rules/no-useless-rename.md index ea38e844b76..fba3123322d 100644 --- a/docs/rules/no-useless-rename.md +++ b/docs/rules/no-useless-rename.md @@ -28,17 +28,13 @@ let { foo } = bar; This rule disallows the renaming of import, export, and destructured assignments to the same name. -See Also: - -- [`object-shorthand`](https://eslint.org/docs/rules/object-shorthand) which can enforce this behavior for properties in object literals. - ## Options This rule allows for more fine-grained control with the following options: -- `ignoreImport`: When set to `true`, this rule does not check imports -- `ignoreExport`: When set to `true`, this rule does not check exports -- `ignoreDestructuring`: When set to `true`, this rule does not check destructuring assignments +* `ignoreImport`: When set to `true`, this rule does not check imports +* `ignoreExport`: When set to `true`, this rule does not check exports +* `ignoreDestructuring`: When set to `true`, this rule does not check destructuring assignments By default, all options are set to `false`: @@ -119,6 +115,10 @@ function foo({ bar: bar }) {} You can safely disable this rule if you do not care about redundantly renaming import, export, and destructuring assignments. +## Related Rules + +* [`object-shorthand`](object-shorthand.md) which can enforce this behavior for properties in object literals. + ## Compatibility -- **JSCS**: [disallowIdenticalDestructuringNames](https://jscs-dev.github.io/rule/disallowIdenticalDestructuringNames) +* **JSCS**: [disallowIdenticalDestructuringNames](https://jscs-dev.github.io/rule/disallowIdenticalDestructuringNames) diff --git a/docs/rules/no-void.md b/docs/rules/no-void.md index 3f7837622b8..4f6a976f320 100644 --- a/docs/rules/no-void.md +++ b/docs/rules/no-void.md @@ -96,12 +96,12 @@ void someFunction(); If you intentionally use the `void` operator then you can disable this rule. -## Further Reading - -* [Mozilla Developer Network](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/void) -* [Bad Parts: Appendix B - JavaScript: The Good Parts by Douglas Crockford](https://oreilly.com/javascript/excerpts/javascript-good-parts/bad-parts.html) - ## Related Rules * [no-undef-init](no-undef-init.md) * [no-undefined](no-undefined.md) + +## Further Reading + +* [Mozilla Developer Network](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/void) +* [Bad Parts: Appendix B - JavaScript: The Good Parts by Douglas Crockford](https://oreilly.com/javascript/excerpts/javascript-good-parts/bad-parts.html) diff --git a/docs/rules/object-curly-newline.md b/docs/rules/object-curly-newline.md index cc98b4293c0..e7089d291a7 100644 --- a/docs/rules/object-curly-newline.md +++ b/docs/rules/object-curly-newline.md @@ -531,11 +531,6 @@ export { foo, bar } from 'foo-bar'; export { foo as f, bar } from 'foo-bar'; ``` -## Compatibility - -* **JSCS**: [requirePaddingNewLinesInObjects](https://jscs-dev.github.io/rule/requirePaddingNewLinesInObjects) -* **JSCS**: [disallowPaddingNewLinesInObjects](https://jscs-dev.github.io/rule/disallowPaddingNewLinesInObjects) - ## When Not To Use It If you don't want to enforce consistent line breaks after opening and before closing braces, then it's safe to disable this rule. @@ -546,3 +541,8 @@ If you don't want to enforce consistent line breaks after opening and before clo * [key-spacing](key-spacing.md) * [object-curly-spacing](object-curly-spacing.md) * [object-property-newline](object-property-newline.md) + +## Compatibility + +* **JSCS**: [requirePaddingNewLinesInObjects](https://jscs-dev.github.io/rule/requirePaddingNewLinesInObjects) +* **JSCS**: [disallowPaddingNewLinesInObjects](https://jscs-dev.github.io/rule/disallowPaddingNewLinesInObjects) diff --git a/docs/rules/object-property-newline.md b/docs/rules/object-property-newline.md index 893e54f2e76..8c18decb1b6 100644 --- a/docs/rules/object-property-newline.md +++ b/docs/rules/object-property-newline.md @@ -90,9 +90,9 @@ will be prohibited, because two properties, but not all properties, appear on th This rule applies equally to all property specifications, regardless of notation, including: -- `a: 1` (ES5) -- `a` (ES2015 shorthand property) -- ``[`prop${a}`]`` (ES2015 computed property name) +* `a: 1` (ES5) +* `a` (ES2015 shorthand property) +* ``[`prop${a}`]`` (ES2015 computed property name) Thus, the rule (without the object option) prohibits both of these: @@ -258,13 +258,13 @@ const obj3 = { You can turn this rule off if you want to decide, case-by-case, whether to place property specifications on separate lines. -## Compatibility +## Related Rules -- **JSCS**: This rule provides partial compatibility with [requireObjectKeysOnNewLine](https://jscs-dev.github.io/rule/requireObjectKeysOnNewLine). +* [brace-style](brace-style.md) +* [comma-dangle](comma-dangle.md) +* [key-spacing](key-spacing.md) +* [object-curly-spacing](object-curly-spacing.md) -## Related Rules +## Compatibility -- [brace-style](brace-style.md) -- [comma-dangle](comma-dangle.md) -- [key-spacing](key-spacing.md) -- [object-curly-spacing](object-curly-spacing.md) +* **JSCS**: This rule provides partial compatibility with [requireObjectKeysOnNewLine](https://jscs-dev.github.io/rule/requireObjectKeysOnNewLine). diff --git a/docs/rules/object-shorthand.md b/docs/rules/object-shorthand.md index fee0e62f4ff..0cbf90b4ba0 100644 --- a/docs/rules/object-shorthand.md +++ b/docs/rules/object-shorthand.md @@ -81,20 +81,16 @@ var foo = { }; ``` -See Also: - -- [`no-useless-rename`](https://eslint.org/docs/rules/no-useless-rename) which disallows renaming import, export, and destructured assignments to the same name. - ## Options The rule takes an option which specifies when it should be applied. It can be set to one of the following values: -- `"always"` (default) expects that the shorthand will be used whenever possible. -- `"methods"` ensures the method shorthand is used (also applies to generators). -- `"properties"` ensures the property shorthand is used (where the key and variable name match). -- `"never"` ensures that no property or method shorthand is used in any object literal. -- `"consistent"` ensures that either all shorthand or all long-form will be used in an object literal. -- `"consistent-as-needed"` ensures that either all shorthand or all long-form will be used in an object literal, but ensures all shorthand whenever possible. +* `"always"` (default) expects that the shorthand will be used whenever possible. +* `"methods"` ensures the method shorthand is used (also applies to generators). +* `"properties"` ensures the property shorthand is used (where the key and variable name match). +* `"never"` ensures that no property or method shorthand is used in any object literal. +* `"consistent"` ensures that either all shorthand or all long-form will be used in an object literal. +* `"consistent-as-needed"` ensures that either all shorthand or all long-form will be used in an object literal, but ensures all shorthand whenever possible. You can set the option in configuration like this: @@ -106,9 +102,9 @@ You can set the option in configuration like this: Additionally, the rule takes an optional object configuration: -- `"avoidQuotes": true` indicates that long-form syntax is preferred whenever the object key is a string literal (default: `false`). Note that this option can only be enabled when the string option is set to `"always"`, `"methods"`, or `"properties"`. -- `"ignoreConstructors": true` can be used to prevent the rule from reporting errors for constructor functions. (By default, the rule treats constructors the same way as other functions.) Note that this option can only be enabled when the string option is set to `"always"` or `"methods"`. -- `"avoidExplicitReturnArrows": true` indicates that methods are preferred over explicit-return arrow functions for function properties. (By default, the rule allows either of these.) Note that this option can only be enabled when the string option is set to `"always"` or `"methods"`. +* `"avoidQuotes": true` indicates that long-form syntax is preferred whenever the object key is a string literal (default: `false`). Note that this option can only be enabled when the string option is set to `"always"`, `"methods"`, or `"properties"`. +* `"ignoreConstructors": true` can be used to prevent the rule from reporting errors for constructor functions. (By default, the rule treats constructors the same way as other functions.) Note that this option can only be enabled when the string option is set to `"always"` or `"methods"`. +* `"avoidExplicitReturnArrows": true` indicates that methods are preferred over explicit-return arrow functions for function properties. (By default, the rule allows either of these.) Note that this option can only be enabled when the string option is set to `"always"` or `"methods"`. ### `avoidQuotes` @@ -246,6 +242,10 @@ var foo = { Anyone not yet in an ES6 environment would not want to apply this rule. Others may find the terseness of the shorthand syntax harder to read and may not want to encourage it with this rule. +## Related Rules + +* [`no-useless-rename`](no-useless-rename.md) which disallows renaming import, export, and destructured assignments to the same name. + ## Further Reading [Object initializer - MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer) diff --git a/docs/rules/padding-line-between-statements.md b/docs/rules/padding-line-between-statements.md index 065c7d937c9..9cf15fc3794 100644 --- a/docs/rules/padding-line-between-statements.md +++ b/docs/rules/padding-line-between-statements.md @@ -38,54 +38,54 @@ You can supply any number of configurations. If a statement pair matches multipl } ``` -- `LINEBREAK_TYPE` is one of the following. - - `"any"` just ignores the statement pair. - - `"never"` disallows blank lines. - - `"always"` requires one or more blank lines. Note it does not count lines that comments exist as blank lines. - -- `STATEMENT_TYPE` is one of the following, or an array of the following. - - `"*"` is wildcard. This matches any statements. - - `"block"` is lonely blocks. - - `"block-like"` is block like statements. This matches statements that the last token is the closing brace of blocks; e.g. `{ }`, `if (a) { }`, and `while (a) { }`. Also matches immediately invoked function expression statements. - - `"break"` is `break` statements. - - `"case"` is `case` clauses in `switch` statements. - - `"cjs-export"` is `export` statements of CommonJS; e.g. `module.exports = 0`, `module.exports.foo = 1`, and `exports.foo = 2`. This is a special case of assignment. - - `"cjs-import"` is `import` statements of CommonJS; e.g. `const foo = require("foo")`. This is a special case of variable declarations. - - `"class"` is `class` declarations. - - `"const"` is `const` variable declarations, both single-line and multiline. - - `"continue"` is `continue` statements. - - `"debugger"` is `debugger` statements. - - `"default"` is `default` clauses in `switch` statements. - - `"directive"` is directive prologues. This matches directives; e.g. `"use strict"`. - - `"do"` is `do-while` statements. This matches all statements that the first token is `do` keyword. - - `"empty"` is empty statements. - - `"export"` is `export` declarations. - - `"expression"` is expression statements. - - `"for"` is `for` loop families. This matches all statements that the first token is `for` keyword. - - `"function"` is function declarations. - - `"if"` is `if` statements. - - `"iife"` is immediately invoked function expression statements. This matches calls on a function expression, optionally prefixed with a unary operator. - - `"import"` is `import` declarations. - - `"let"` is `let` variable declarations, both single-line and multiline. - - `"multiline-block-like"` is block like statements. This is the same as `block-like` type, but only if the block is multiline. - - `"multiline-const"` is multiline `const` variable declarations. - - `"multiline-expression"` is expression statements. This is the same as `expression` type, but only if the statement is multiline. - - `"multiline-let"` is multiline `let` variable declarations. - - `"multiline-var"` is multiline `var` variable declarations. - - `"return"` is `return` statements. - - `"singleline-const"` is single-line `const` variable declarations. - - `"singleline-let"` is single-line `let` variable declarations. - - `"singleline-var"` is single-line `var` variable declarations. - - `"switch"` is `switch` statements. - - `"throw"` is `throw` statements. - - `"try"` is `try` statements. - - `"var"` is `var` variable declarations, both single-line and multiline. - - `"while"` is `while` loop statements. - - `"with"` is `with` statements. +* `LINEBREAK_TYPE` is one of the following. + * `"any"` just ignores the statement pair. + * `"never"` disallows blank lines. + * `"always"` requires one or more blank lines. Note it does not count lines that comments exist as blank lines. + +* `STATEMENT_TYPE` is one of the following, or an array of the following. + * `"*"` is wildcard. This matches any statements. + * `"block"` is lonely blocks. + * `"block-like"` is block like statements. This matches statements that the last token is the closing brace of blocks; e.g. `{ }`, `if (a) { }`, and `while (a) { }`. Also matches immediately invoked function expression statements. + * `"break"` is `break` statements. + * `"case"` is `case` clauses in `switch` statements. + * `"cjs-export"` is `export` statements of CommonJS; e.g. `module.exports = 0`, `module.exports.foo = 1`, and `exports.foo = 2`. This is a special case of assignment. + * `"cjs-import"` is `import` statements of CommonJS; e.g. `const foo = require("foo")`. This is a special case of variable declarations. + * `"class"` is `class` declarations. + * `"const"` is `const` variable declarations, both single-line and multiline. + * `"continue"` is `continue` statements. + * `"debugger"` is `debugger` statements. + * `"default"` is `default` clauses in `switch` statements. + * `"directive"` is directive prologues. This matches directives; e.g. `"use strict"`. + * `"do"` is `do-while` statements. This matches all statements that the first token is `do` keyword. + * `"empty"` is empty statements. + * `"export"` is `export` declarations. + * `"expression"` is expression statements. + * `"for"` is `for` loop families. This matches all statements that the first token is `for` keyword. + * `"function"` is function declarations. + * `"if"` is `if` statements. + * `"iife"` is immediately invoked function expression statements. This matches calls on a function expression, optionally prefixed with a unary operator. + * `"import"` is `import` declarations. + * `"let"` is `let` variable declarations, both single-line and multiline. + * `"multiline-block-like"` is block like statements. This is the same as `block-like` type, but only if the block is multiline. + * `"multiline-const"` is multiline `const` variable declarations. + * `"multiline-expression"` is expression statements. This is the same as `expression` type, but only if the statement is multiline. + * `"multiline-let"` is multiline `let` variable declarations. + * `"multiline-var"` is multiline `var` variable declarations. + * `"return"` is `return` statements. + * `"singleline-const"` is single-line `const` variable declarations. + * `"singleline-let"` is single-line `let` variable declarations. + * `"singleline-var"` is single-line `var` variable declarations. + * `"switch"` is `switch` statements. + * `"throw"` is `throw` statements. + * `"try"` is `try` statements. + * `"var"` is `var` variable declarations, both single-line and multiline. + * `"while"` is `while` loop statements. + * `"with"` is `with` statements. ## Examples -This configuration would require blank lines before all `return` statements, like the [newline-before-return] rule. +This configuration would require blank lines before all `return` statements, like the [newline-before-return](newline-before-return.md) rule. Examples of **incorrect** code for the `[{ blankLine: "always", prev: "*", next: "return" }]` configuration: @@ -122,7 +122,7 @@ function foo() { ---- -This configuration would require blank lines after every sequence of variable declarations, like the [newline-after-var] rule. +This configuration would require blank lines after every sequence of variable declarations, like the [newline-after-var](newline-after-var.md) rule. Examples of **incorrect** code for the `[{ blankLine: "always", prev: ["const", "let", "var"], next: "*"}, { blankLine: "any", prev: ["const", "let", "var"], next: ["const", "let", "var"]}]` configuration: @@ -198,7 +198,7 @@ class C { ---- -This configuration would require blank lines after all directive prologues, like the [lines-around-directive] rule. +This configuration would require blank lines after all directive prologues, like the [lines-around-directive](lines-around-directive.md) rule. Examples of **incorrect** code for the `[{ blankLine: "always", prev: "directive", next: "*" }, { blankLine: "any", prev: "directive", next: "directive" }]` configuration: @@ -277,31 +277,18 @@ switch (foo) { } ``` -## Compatibility - -- **JSCS:** [requirePaddingNewLineAfterVariableDeclaration] -- **JSCS:** [requirePaddingNewLinesAfterBlocks] -- **JSCS:** [disallowPaddingNewLinesAfterBlocks] -- **JSCS:** [requirePaddingNewLinesAfterUseStrict] -- **JSCS:** [disallowPaddingNewLinesAfterUseStrict] -- **JSCS:** [requirePaddingNewLinesBeforeExport] -- **JSCS:** [disallowPaddingNewLinesBeforeExport] -- **JSCS:** [requirePaddingNewlinesBeforeKeywords] -- **JSCS:** [disallowPaddingNewlinesBeforeKeywords] - ## When Not To Use It If you don't want to notify warnings about linebreaks, then it's safe to disable this rule. -[lines-around-directive]: https://eslint.org/docs/rules/lines-around-directive -[newline-after-var]: https://eslint.org/docs/rules/newline-after-var -[newline-before-return]: https://eslint.org/docs/rules/newline-before-return -[requirePaddingNewLineAfterVariableDeclaration]: https://jscs-dev.github.io/rule/requirePaddingNewLineAfterVariableDeclaration -[requirePaddingNewLinesAfterBlocks]: https://jscs-dev.github.io/rule/requirePaddingNewLinesAfterBlocks -[disallowPaddingNewLinesAfterBlocks]: https://jscs-dev.github.io/rule/disallowPaddingNewLinesAfterBlocks -[requirePaddingNewLinesAfterUseStrict]: https://jscs-dev.github.io/rule/requirePaddingNewLinesAfterUseStrict -[disallowPaddingNewLinesAfterUseStrict]: https://jscs-dev.github.io/rule/disallowPaddingNewLinesAfterUseStrict -[requirePaddingNewLinesBeforeExport]: https://jscs-dev.github.io/rule/requirePaddingNewLinesBeforeExport -[disallowPaddingNewLinesBeforeExport]: https://jscs-dev.github.io/rule/disallowPaddingNewLinesBeforeExport -[requirePaddingNewlinesBeforeKeywords]: https://jscs-dev.github.io/rule/requirePaddingNewlinesBeforeKeywords -[disallowPaddingNewlinesBeforeKeywords]: https://jscs-dev.github.io/rule/disallowPaddingNewlinesBeforeKeywords +## Compatibility + +* **JSCS:** [requirePaddingNewLineAfterVariableDeclaration](https://jscs-dev.github.io/rule/requirePaddingNewLineAfterVariableDeclaration) +* **JSCS:** [requirePaddingNewLinesAfterBlocks](https://jscs-dev.github.io/rule/requirePaddingNewLinesAfterBlocks) +* **JSCS:** [disallowPaddingNewLinesAfterBlocks](https://jscs-dev.github.io/rule/disallowPaddingNewLinesAfterBlocks) +* **JSCS:** [requirePaddingNewLinesAfterUseStrict](https://jscs-dev.github.io/rule/requirePaddingNewLinesAfterUseStrict) +* **JSCS:** [disallowPaddingNewLinesAfterUseStrict](https://jscs-dev.github.io/rule/disallowPaddingNewLinesAfterUseStrict) +* **JSCS:** [requirePaddingNewLinesBeforeExport](https://jscs-dev.github.io/rule/requirePaddingNewLinesBeforeExport) +* **JSCS:** [disallowPaddingNewLinesBeforeExport](https://jscs-dev.github.io/rule/disallowPaddingNewLinesBeforeExport) +* **JSCS:** [requirePaddingNewlinesBeforeKeywords](https://jscs-dev.github.io/rule/requirePaddingNewlinesBeforeKeywords) +* **JSCS:** [disallowPaddingNewlinesBeforeKeywords](https://jscs-dev.github.io/rule/disallowPaddingNewlinesBeforeKeywords) diff --git a/docs/rules/prefer-arrow-callback.md b/docs/rules/prefer-arrow-callback.md index 7b98aa1f8f6..94020f809b7 100644 --- a/docs/rules/prefer-arrow-callback.md +++ b/docs/rules/prefer-arrow-callback.md @@ -6,9 +6,9 @@ For example, arrow functions are automatically bound to their surrounding scope/ Additionally, arrow functions are: -- less verbose, and easier to reason about. +* less verbose, and easier to reason about. -- bound lexically regardless of where or when they are invoked. +* bound lexically regardless of where or when they are invoked. ## Rule Details @@ -91,10 +91,10 @@ someArray.map(function(item) { return this.doSomething(item); }, someObject); ## When Not To Use It -- In environments that have not yet adopted ES6 language features (ES3/5). +* In environments that have not yet adopted ES6 language features (ES3/5). -- In ES6+ environments that allow the use of function expressions when describing callbacks or function arguments. +* In ES6+ environments that allow the use of function expressions when describing callbacks or function arguments. ## Further Reading -- [More on ES6 arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) +* [More on ES6 arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) diff --git a/docs/rules/prefer-destructuring.md b/docs/rules/prefer-destructuring.md index b0f887c13a9..f07c03b3170 100644 --- a/docs/rules/prefer-destructuring.md +++ b/docs/rules/prefer-destructuring.md @@ -18,8 +18,8 @@ The rule has a second object with a single key, `enforceForRenamedProperties`, w **Note**: It is not possible to determine if a variable will be referring to an object or an array at runtime. This rule therefore guesses the assignment type by checking whether the key being accessed is an integer. This can lead to the following possibly confusing situations: -- Accessing an object property whose key is an integer will fall under the category `array` destructuring. -- Accessing an array element through a computed index will fall under the category `object` destructuring. +* Accessing an object property whose key is an integer will fall under the category `array` destructuring. +* Accessing an array element through a computed index will fall under the category `object` destructuring. The `--fix` option on the command line fixes only problems reported in variable declarations, and among them only those that fall under the category `object` destructuring. Furthermore, the name of the declared variable has to be the same as the name used for non-computed member access in the initializer. For example, `var foo = object.foo` can be automatically fixed by this rule. Problems that involve computed member access (e.g., `var foo = object[foo]`) or renamed properties (e.g., `var foo = object.bar`) are not automatically fixed. @@ -183,5 +183,5 @@ var [bar] = $('body'); // fails with a TypeError If you want to learn more about destructuring, check out the links below: -- [Destructuring Assignment (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) -- [Destructuring and parameter handling in ECMAScript 6 (2ality blog)](http://2ality.com/2015/01/es6-destructuring.html) +* [Destructuring Assignment (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) +* [Destructuring and parameter handling in ECMAScript 6 (2ality blog)](http://2ality.com/2015/01/es6-destructuring.html) diff --git a/docs/rules/prefer-promise-reject-errors.md b/docs/rules/prefer-promise-reject-errors.md index 9740bc97546..0cff0ea0a46 100644 --- a/docs/rules/prefer-promise-reject-errors.md +++ b/docs/rules/prefer-promise-reject-errors.md @@ -66,13 +66,16 @@ new Promise(function(resolve, reject) { Due to the limits of static analysis, this rule cannot guarantee that you will only reject Promises with `Error` objects. While the rule will report cases where it can guarantee that the rejection reason is clearly not an `Error`, it will not report cases where there is uncertainty about whether a given reason is an `Error`. For more information on this caveat, see the [similar limitations](no-throw-literal.md#known-limitations) in the `no-throw-literal` rule. -To avoid conflicts between rules, this rule does not report non-error values used in `throw` statements in async functions, even though these lead to Promise rejections. To lint for these cases, use the [`no-throw-literal`](https://eslint.org/docs/rules/no-throw-literal) rule. +To avoid conflicts between rules, this rule does not report non-error values used in `throw` statements in async functions, even though these lead to Promise rejections. To lint for these cases, use the [`no-throw-literal`](no-throw-literal.md) rule. ## When Not To Use It If you're using custom non-error values as Promise rejection reasons, you can turn off this rule. +## Related Rules + +* [`no-throw-literal`](no-throw-literal.md) + ## Further Reading -* [`no-throw-literal`](https://eslint.org/docs/rules/no-throw-literal) * [Warning: a promise was rejected with a non-error](http://bluebirdjs.com/docs/warning-explanations.html#warning-a-promise-was-rejected-with-a-non-error) diff --git a/docs/rules/quotes.md b/docs/rules/quotes.md index 25a09fd0dbf..7c113a836b4 100644 --- a/docs/rules/quotes.md +++ b/docs/rules/quotes.md @@ -147,7 +147,7 @@ var single = 'single'; var single = `single`; ``` -`{ "allowTemplateLiterals": false }` will not disallow the usage of all template literals. If you want to forbid any instance of template literals, use [no-restricted-syntax](https://eslint.org/docs/rules/no-restricted-syntax) and target the `TemplateLiteral` selector. +`{ "allowTemplateLiterals": false }` will not disallow the usage of all template literals. If you want to forbid any instance of template literals, use [no-restricted-syntax](no-restricted-syntax.md) and target the `TemplateLiteral` selector. ## When Not To Use It diff --git a/docs/rules/semi-style.md b/docs/rules/semi-style.md index 368bb532a2d..7d08d7665d1 100644 --- a/docs/rules/semi-style.md +++ b/docs/rules/semi-style.md @@ -14,8 +14,8 @@ This rule has an option. } ``` -- `"last"` (Default) enforces that semicolons are at the end of statements. -- `"first"` enforces that semicolons are at the beginning of statements. Semicolons of `for` loop heads (`for(a;b;c){}`) should be at the end of lines even if you use this option. +* `"last"` (Default) enforces that semicolons are at the end of statements. +* `"first"` enforces that semicolons are at the beginning of statements. Semicolons of `for` loop heads (`for(a;b;c){}`) should be at the end of lines even if you use this option. Examples of **incorrect** code for this rule with `"last"` option: @@ -117,8 +117,8 @@ class C { If you don't want to notify the location of semicolons, then it's safe to disable this rule. -## Related rules +## Related Rules -- [no-extra-semi](./no-extra-semi.md) -- [semi](./semi.md) -- [semi-spacing](./semi-spacing.md) +* [no-extra-semi](./no-extra-semi.md) +* [semi](./semi.md) +* [semi-spacing](./semi-spacing.md) diff --git a/docs/rules/semi.md b/docs/rules/semi.md index cb8e6dd0dab..2e82a4509ea 100644 --- a/docs/rules/semi.md +++ b/docs/rules/semi.md @@ -210,13 +210,13 @@ import a from "a" If you do not want to enforce semicolon usage (or omission) in any particular way, then you can turn this rule off. -## Further Reading - -* [An Open Letter to JavaScript Leaders Regarding Semicolons](http://blog.izs.me/post/2353458699/an-open-letter-to-javascript-leaders-regarding) -* [JavaScript Semicolon Insertion](http://inimino.org/~inimino/blog/javascript_semicolons) - ## Related Rules * [no-extra-semi](no-extra-semi.md) * [no-unexpected-multiline](no-unexpected-multiline.md) * [semi-spacing](semi-spacing.md) + +## Further Reading + +* [An Open Letter to JavaScript Leaders Regarding Semicolons](http://blog.izs.me/post/2353458699/an-open-letter-to-javascript-leaders-regarding) +* [JavaScript Semicolon Insertion](http://inimino.org/~inimino/blog/javascript_semicolons) diff --git a/docs/rules/switch-colon-spacing.md b/docs/rules/switch-colon-spacing.md index b9872c2ad5b..094aef22cff 100644 --- a/docs/rules/switch-colon-spacing.md +++ b/docs/rules/switch-colon-spacing.md @@ -15,10 +15,10 @@ This rule has 2 options that are boolean value. } ``` -- `"after": true` (Default) requires one or more spaces after colons. -- `"after": false` disallows spaces after colons. -- `"before": true` requires one or more spaces before colons. -- `"before": false` (Default) disallows before colons. +* `"after": true` (Default) requires one or more spaces after colons. +* `"after": false` disallows spaces after colons. +* `"before": true` requires one or more spaces before colons. +* `"before": false` (Default) disallows before colons. Examples of **incorrect** code for this rule: diff --git a/docs/rules/valid-jsdoc.md b/docs/rules/valid-jsdoc.md index 2d503828f35..5741402b59d 100644 --- a/docs/rules/valid-jsdoc.md +++ b/docs/rules/valid-jsdoc.md @@ -384,10 +384,10 @@ function add(num1, num2) { If you aren't using JSDoc, then you can safely turn this rule off. -## Further Reading - -* [JSDoc](http://usejsdoc.org) - ## Related Rules * [require-jsdoc](require-jsdoc.md) + +## Further Reading + +* [JSDoc](http://usejsdoc.org) diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md index 1fcb0dfc12e..63b7533f732 100644 --- a/docs/user-guide/README.md +++ b/docs/user-guide/README.md @@ -30,10 +30,10 @@ The ESLint team is committed to making upgrading as easy and painless as possibl If you were using a prior version of ESLint, you can get help with the transition by reading: -- [migrating-to-1.0.0](migrating-to-1.0.0.md) -- [migrating-to-2.0.0](migrating-to-2.0.0.md) -- [migrating-to-3.0.0](migrating-to-3.0.0.md) -- [migrating-to-4.0.0](migrating-to-4.0.0.md) -- [migrating-to-5.0.0](migrating-to-5.0.0.md) -- [migrating-to-6.0.0](migrating-to-6.0.0.md) -- [migrating-to-7.0.0](migrating-to-7.0.0.md) +* [migrating-to-1.0.0](migrating-to-1.0.0.md) +* [migrating-to-2.0.0](migrating-to-2.0.0.md) +* [migrating-to-3.0.0](migrating-to-3.0.0.md) +* [migrating-to-4.0.0](migrating-to-4.0.0.md) +* [migrating-to-5.0.0](migrating-to-5.0.0.md) +* [migrating-to-6.0.0](migrating-to-6.0.0.md) +* [migrating-to-7.0.0](migrating-to-7.0.0.md) diff --git a/docs/user-guide/migrating-to-2.0.0.md b/docs/user-guide/migrating-to-2.0.0.md index c5f50b3a1d0..4ca97cbe8a8 100644 --- a/docs/user-guide/migrating-to-2.0.0.md +++ b/docs/user-guide/migrating-to-2.0.0.md @@ -307,7 +307,7 @@ The rule `func-style` has a default configuration of `"expression"`, but in ESLi ESLint 2.0.0 removes these conflicting defaults, and so you may begin seeing linting errors related to these rules. -**To address:** If you would like to maintain the previous behavior, update your configuration for `no-multiple-empty-lines` by adding `{"max": 2}`, and change `func-style` to `"declaration"`. For example: +**To address:** If you would like to maintain the previous behavior, update your configuration for `no-multiple-empty-lines` by adding `{"max": 2}`, and change `func-style` to `"declaration"`. For example: ```json { diff --git a/docs/user-guide/migrating-to-7.0.0.md b/docs/user-guide/migrating-to-7.0.0.md index 2a640a7ad3c..8b57df2444f 100644 --- a/docs/user-guide/migrating-to-7.0.0.md +++ b/docs/user-guide/migrating-to-7.0.0.md @@ -8,29 +8,29 @@ The lists below are ordered roughly by the number of users each change is expect ### Breaking changes for users -- [Node.js 8 is no longer supported](#drop-node-8) -- [Lint files matched by `overrides[].files` by default](#additional-lint-targets) -- [The base path of `overrides` and `ignorePatterns` is changed if the config file is given by the `--config`/`--ignore-path` options](#base-path-change) -- [The place where ESLint loads plugins from is changed](#plugin-loading-change) -- [Runtime deprecation warnings for `~/.eslintrc.*` config files](#runtime-deprecation-on-personal-config-files) -- [Default ignore patterns have changed](#default-ignore-patterns) -- [Description in directive comments](#description-in-directive-comments) -- [Node.js/CommonJS rules are deprecated](#deprecate-node-rules) -- [Several rules have been updated to cover more cases](#rules-strict) -- [`eslint:recommended` has been updated](#eslint-recommended) +* [Node.js 8 is no longer supported](#drop-node-8) +* [Lint files matched by `overrides[].files` by default](#additional-lint-targets) +* [The base path of `overrides` and `ignorePatterns` is changed if the config file is given by the `--config`/`--ignore-path` options](#base-path-change) +* [The place where ESLint loads plugins from is changed](#plugin-loading-change) +* [Runtime deprecation warnings for `~/.eslintrc.*` config files](#runtime-deprecation-on-personal-config-files) +* [Default ignore patterns have changed](#default-ignore-patterns) +* [Description in directive comments](#description-in-directive-comments) +* [Node.js/CommonJS rules are deprecated](#deprecate-node-rules) +* [Several rules have been updated to cover more cases](#rules-strict) +* [`eslint:recommended` has been updated](#eslint-recommended) ### Breaking changes for plugin developers -- [Node.js 8 is no longer supported](#drop-node-8) -- [Lint files matched by `overrides[].files` by default](#additional-lint-targets) -- [Plugin resolution has been updated](#plugin-loading-change) -- [Additional validation added to the `RuleTester` class](#rule-tester-strict) +* [Node.js 8 is no longer supported](#drop-node-8) +* [Lint files matched by `overrides[].files` by default](#additional-lint-targets) +* [Plugin resolution has been updated](#plugin-loading-change) +* [Additional validation added to the `RuleTester` class](#rule-tester-strict) ### Breaking changes for integration developers -- [Node.js 8 is no longer supported](#drop-node-8) -- [Plugin resolution has been updated](#plugin-loading-change) -- [The `CLIEngine` class has been deprecated](#deprecate-cliengine) +* [Node.js 8 is no longer supported](#drop-node-8) +* [Plugin resolution has been updated](#plugin-loading-change) +* [The `CLIEngine` class has been deprecated](#deprecate-cliengine) --- @@ -38,8 +38,8 @@ The lists below are ordered roughly by the number of users each change is expect Node.js 8 reached EOL in December 2019, and we are officially dropping support for it in this release. ESLint now supports the following versions of Node.js: -- Node.js 10 (`10.12.0` and above) -- Node.js 12 and above +* Node.js 10 (`10.12.0` and above) +* Node.js 12 and above **To address:** Make sure you upgrade to at least Node.js `10.12.0` when using ESLint v7.0.0. One important thing to double check is the Node.js version supported by your editor when using ESLint via editor integrations. If you are unable to upgrade, we recommend continuing to use ESLint 6 until you are able to upgrade Node.js. @@ -71,12 +71,12 @@ If you maintain plugins that check files with extensions other than `.js`, this Up until now, ESLint has resolved the following paths relative to the directory path of the _entry_ configuration file: -- Configuration files (`.eslintrc.*`) - - relative paths in the `overrides[].files` setting - - relative paths in the `overrides[].excludedFiles` setting - - paths which start with `/` in the `ignorePatterns` setting -- Ignore files (`.eslintignore`) - - paths which start with `/` +* Configuration files (`.eslintrc.*`) + * relative paths in the `overrides[].files` setting + * relative paths in the `overrides[].excludedFiles` setting + * paths which start with `/` in the `ignorePatterns` setting +* Ignore files (`.eslintignore`) + * paths which start with `/` Starting in ESLint v7.0.0, configuration files and ignore files passed to ESLint using the `--config path/to/a-config` and `--ignore-path path/to/a-ignore` CLI flags, respectively, will resolve from the current working directory rather than the file location. This allows for users to utilize shared plugins without having to install them directly in their project. @@ -113,14 +113,14 @@ Personal config files have been deprecated since [v6.7.0](https://eslint.org/blo Up until now, ESLint has ignored the following files by default: -- Dotfiles (`.*`) -- `node_modules` in the current working directory (`/node_modules/*`) -- `bower_components` in the current working directory (`/bower_components/*`) +* Dotfiles (`.*`) +* `node_modules` in the current working directory (`/node_modules/*`) +* `bower_components` in the current working directory (`/bower_components/*`) ESLint v7.0.0 ignores `node_modules/*` of subdirectories as well, but no longer ignores `bower_components/*` and `.eslintrc.js`. Therefore, the new default ignore patterns are: -- Dotfiles except `.eslintrc.*` (`.*` but not `.eslintrc.*`) -- `node_modules` (`/**/node_modules/*`) +* Dotfiles except `.eslintrc.*` (`.*` but not `.eslintrc.*`) +* `node_modules` (`/**/node_modules/*`) **To address:** Modify your `.eslintignore` or the `ignorePatterns` property of your config file if you don't want to lint `bower_components/*` and `.eslintrc.js`. @@ -165,16 +165,16 @@ The ten Node.js/CommonJS rules in core have been deprecated and moved to the [es Several rules have been enhanced and now report additional errors: -- [accessor-pairs](https://eslint.org/docs/rules/accessor-pairs) rule now recognizes class members by default. -- [array-callback-return](https://eslint.org/docs/rules/array-callback-return) rule now recognizes `flatMap` method. -- [computed-property-spacing](https://eslint.org/docs/rules/computed-property-spacing) rule now recognizes class members by default. -- [func-names](https://eslint.org/docs/rules/func-names) rule now recognizes function declarations in default exports. -- [no-extra-parens](https://eslint.org/docs/rules/no-extra-parens) rule now recognizes parentheses in assignment targets. -- [no-dupe-class-members](https://eslint.org/docs/rules/no-dupe-class-members) rule now recognizes computed keys for static class members. -- [no-magic-numbers](https://eslint.org/docs/rules/no-magic-numbers) rule now recognizes bigint literals. -- [radix](https://eslint.org/docs/rules/radix) rule now recognizes invalid numbers for the second parameter of `parseInt()`. -- [use-isnan](https://eslint.org/docs/rules/use-isnan) rule now recognizes class members by default. -- [yoda](https://eslint.org/docs/rules/yoda) rule now recognizes bigint literals. +* [accessor-pairs](https://eslint.org/docs/rules/accessor-pairs) rule now recognizes class members by default. +* [array-callback-return](https://eslint.org/docs/rules/array-callback-return) rule now recognizes `flatMap` method. +* [computed-property-spacing](https://eslint.org/docs/rules/computed-property-spacing) rule now recognizes class members by default. +* [func-names](https://eslint.org/docs/rules/func-names) rule now recognizes function declarations in default exports. +* [no-extra-parens](https://eslint.org/docs/rules/no-extra-parens) rule now recognizes parentheses in assignment targets. +* [no-dupe-class-members](https://eslint.org/docs/rules/no-dupe-class-members) rule now recognizes computed keys for static class members. +* [no-magic-numbers](https://eslint.org/docs/rules/no-magic-numbers) rule now recognizes bigint literals. +* [radix](https://eslint.org/docs/rules/radix) rule now recognizes invalid numbers for the second parameter of `parseInt()`. +* [use-isnan](https://eslint.org/docs/rules/use-isnan) rule now recognizes class members by default. +* [yoda](https://eslint.org/docs/rules/yoda) rule now recognizes bigint literals. **To address:** Fix errors or disable these rules. @@ -184,9 +184,9 @@ Several rules have been enhanced and now report additional errors: Three new rules have been enabled in the `eslint:recommended` preset. -- [no-dupe-else-if](https://eslint.org/docs/rules/no-dupe-else-if) -- [no-import-assign](https://eslint.org/docs/rules/no-import-assign) -- [no-setter-return](https://eslint.org/docs/rules/no-setter-return) +* [no-dupe-else-if](https://eslint.org/docs/rules/no-dupe-else-if) +* [no-import-assign](https://eslint.org/docs/rules/no-import-assign) +* [no-setter-return](https://eslint.org/docs/rules/no-setter-return) **To address:** Fix errors or disable these rules. @@ -196,9 +196,9 @@ Three new rules have been enabled in the `eslint:recommended` preset. The `RuleTester` now validates the following: -- It fails test cases if the rule under test uses the non-standard `node.start` or `node.end` properties. Rules should use `node.range` instead. -- It fails test cases if the rule under test provides an autofix but a test case doesn't have an `output` property. Add an `output` property to test cases to test the rule's autofix functionality. -- It fails test cases if any unknown properties are found in the objects in the `errors` property. +* It fails test cases if the rule under test uses the non-standard `node.start` or `node.end` properties. Rules should use `node.range` instead. +* It fails test cases if the rule under test provides an autofix but a test case doesn't have an `output` property. Add an `output` property to test cases to test the rule's autofix functionality. +* It fails test cases if any unknown properties are found in the objects in the `errors` property. **To address:** Modify your rule or test case if existing test cases fail. @@ -226,7 +226,7 @@ The `CLIEngine` class provides a synchronous API that is blocking the implementa | `getRules()` | (not implemented yet) | | `resolveFileGlobPatterns()` | (removed ※2) | -- ※1 The `engine.getFormatter()` method currently returns the object of loaded packages as-is, which made it difficult to add new features to formatters for backward compatibility reasons. The new `eslint.loadFormatter()` method returns an adapter object that wraps the object of loaded packages, to ease the process of adding new features. Additionally, the adapter object has access to the `ESLint` instance to calculate default data (using loaded plugin rules to make `rulesMeta`, for example). As a result, the `ESLint` class only implements an instance version of the `loadFormatter()` method. -- ※2 Since ESLint 6, ESLint uses different logic from the `resolveFileGlobPatterns()` method to iterate files, making this method obsolete. +* ※1 The `engine.getFormatter()` method currently returns the object of loaded packages as-is, which made it difficult to add new features to formatters for backward compatibility reasons. The new `eslint.loadFormatter()` method returns an adapter object that wraps the object of loaded packages, to ease the process of adding new features. Additionally, the adapter object has access to the `ESLint` instance to calculate default data (using loaded plugin rules to make `rulesMeta`, for example). As a result, the `ESLint` class only implements an instance version of the `loadFormatter()` method. +* ※2 Since ESLint 6, ESLint uses different logic from the `resolveFileGlobPatterns()` method to iterate files, making this method obsolete. **Related issue(s):** [RFC40](https://github.com/eslint/rfcs/blob/master/designs/2019-move-to-async-api/README.md), [#12939](https://github.com/eslint/eslint/pull/12939) diff --git a/docs/user-guide/migrating-to-8.0.0.md b/docs/user-guide/migrating-to-8.0.0.md index 444ac124c4c..86c2bc757fa 100644 --- a/docs/user-guide/migrating-to-8.0.0.md +++ b/docs/user-guide/migrating-to-8.0.0.md @@ -8,26 +8,26 @@ The lists below are ordered roughly by the number of users each change is expect ### Breaking changes for users -- [Node.js 10, 13, and 15 are no longer supported](#drop-old-node) -- [Removed `codeframe` and `table` formatters](#removed-formatters) -- [`comma-dangle` rule schema is stricter](#comma-dangle) -- [Unused disable directives are now fixable](#directives) -- [`eslint:recommended` has been updated](#eslint-recommended) +* [Node.js 10, 13, and 15 are no longer supported](#drop-old-node) +* [Removed `codeframe` and `table` formatters](#removed-formatters) +* [`comma-dangle` rule schema is stricter](#comma-dangle) +* [Unused disable directives are now fixable](#directives) +* [`eslint:recommended` has been updated](#eslint-recommended) ### Breaking changes for plugin developers -- [Node.js 10, 13, and 15 are no longer supported](#drop-old-node) -- [Rules require `meta.hasSuggestions` to provide suggestions](#suggestions) -- [Rules require `meta.fixable` to provide fixes](#fixes) -- [`SourceCode#getComments()` fails in `RuleTester`](#get-comments) -- [Changes to shorthand property AST format](#ast-format) +* [Node.js 10, 13, and 15 are no longer supported](#drop-old-node) +* [Rules require `meta.hasSuggestions` to provide suggestions](#suggestions) +* [Rules require `meta.fixable` to provide fixes](#fixes) +* [`SourceCode#getComments()` fails in `RuleTester`](#get-comments) +* [Changes to shorthand property AST format](#ast-format) ### Breaking changes for integration developers -- [Node.js 10, 13, and 15 are no longer supported](#drop-old-node) -- [The `CLIEngine` class has been removed](#remove-cliengine) -- [The `linter` object has been removed](#remove-linter) -- [The `/lib` entrypoint has been removed](#remove-lib) +* [Node.js 10, 13, and 15 are no longer supported](#drop-old-node) +* [The `CLIEngine` class has been removed](#remove-cliengine) +* [The `linter` object has been removed](#remove-linter) +* [The `/lib` entrypoint has been removed](#remove-lib) --- @@ -35,9 +35,9 @@ The lists below are ordered roughly by the number of users each change is expect Node.js 10, 13, 15 all reached end of life either in 2020 or early 2021. ESLint is officially dropping support for these versions of Node.js starting with ESLint v8.0.0. ESLint now supports the following versions of Node.js: -- Node.js 12.22 and above -- Node.js 14 and above -- Node.js 16 and above +* Node.js 12.22 and above +* Node.js 14 and above +* Node.js 16 and above **To address:** Make sure you upgrade to at least Node.js `12.22.0` when using ESLint v8.0.0. One important thing to double check is the Node.js version supported by your editor when using ESLint via editor integrations. If you are unable to upgrade, we recommend continuing to use ESLint 7 until you are able to upgrade Node.js. @@ -95,10 +95,10 @@ In ESLint v7.0.0, using both `--report-unused-disable-directives` and `--fix` on Four new rules have been enabled in the `eslint:recommended` preset. -- [`no-loss-of-precision`](https://eslint.org/docs/rules/no-loss-of-precision) -- [`no-nonoctal-decimal-escape`](https://eslint.org/docs/rules/no-nonoctal-decimal-escape) -- [`no-unsafe-optional-chaining`](https://eslint.org/docs/rules/no-unsafe-optional-chaining) -- [`no-useless-backreference`](https://eslint.org/docs/rules/no-useless-backreference) +* [`no-loss-of-precision`](https://eslint.org/docs/rules/no-loss-of-precision) +* [`no-nonoctal-decimal-escape`](https://eslint.org/docs/rules/no-nonoctal-decimal-escape) +* [`no-unsafe-optional-chaining`](https://eslint.org/docs/rules/no-unsafe-optional-chaining) +* [`no-useless-backreference`](https://eslint.org/docs/rules/no-useless-backreference) **To address:** Fix errors or disable these rules. @@ -237,9 +237,9 @@ The `CLIEngine` class has been removed and replaced by the [`ESLint` class](http | `getRules()` | (removed ※2) | | `resolveFileGlobPatterns()` | (removed ※3) | -- ※1 The `engine.getFormatter()` method currently returns the object of loaded packages as-is, which made it difficult to add new features to formatters for backward compatibility reasons. The new `eslint.loadFormatter()` method returns an adapter object that wraps the object of loaded packages, to ease the process of adding new features. Additionally, the adapter object has access to the `ESLint` instance to calculate default data (using loaded plugin rules to make `rulesMeta`, for example). As a result, the `ESLint` class only implements an instance version of the `loadFormatter()` method. -- ※2 The `CLIEngine#getRules()` method had side effects and so was removed. If you were using `CLIEngine#getRules()` to retrieve meta information about rules based on linting results, use `ESLint#getRulesMetaForResults()` instead. If you were using `CLIEngine#getRules()` to retrieve all built-in rules, import `builtinRules` from `eslint/use-at-your-own-risk` for an unsupported API that allows access to internal rules. -- ※3 Since ESLint v6.0.0, ESLint uses different logic from the `resolveFileGlobPatterns()` method to iterate files, making this method obsolete. +* ※1 The `engine.getFormatter()` method currently returns the object of loaded packages as-is, which made it difficult to add new features to formatters for backward compatibility reasons. The new `eslint.loadFormatter()` method returns an adapter object that wraps the object of loaded packages, to ease the process of adding new features. Additionally, the adapter object has access to the `ESLint` instance to calculate default data (using loaded plugin rules to make `rulesMeta`, for example). As a result, the `ESLint` class only implements an instance version of the `loadFormatter()` method. +* ※2 The `CLIEngine#getRules()` method had side effects and so was removed. If you were using `CLIEngine#getRules()` to retrieve meta information about rules based on linting results, use `ESLint#getRulesMetaForResults()` instead. If you were using `CLIEngine#getRules()` to retrieve all built-in rules, import `builtinRules` from `eslint/use-at-your-own-risk` for an unsupported API that allows access to internal rules. +* ※3 Since ESLint v6.0.0, ESLint uses different logic from the `resolveFileGlobPatterns()` method to iterate files, making this method obsolete. **Related issue(s):** [RFC80](https://github.com/eslint/rfcs/tree/main/designs/2021-package-exports), [#14716](https://github.com/eslint/eslint/pull/14716), [#13654](https://github.com/eslint/eslint/issues/13654) diff --git a/package.json b/package.json index fee3bf0f67b..974fc05cd50 100644 --- a/package.json +++ b/package.json @@ -118,6 +118,7 @@ "load-perf": "^0.2.0", "markdownlint": "^0.24.0", "markdownlint-cli": "^0.30.0", + "marked": "^4.0.8", "memfs": "^3.0.1", "mocha": "^8.3.2", "mocha-junit-reporter": "^2.0.0",