Extend explanations for some rules (#2070)

fregante · web-flow · commit a9337e847e0c · 2023-04-20T17:54:11.000+08:00
diff --git a/docs/rules/explicit-length-check.md b/docs/rules/explicit-length-check.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-Enforce explicitly checking the length of an object and enforce the comparison style.
+This rule is only meant to enforce a specific style and make comparisons more clear.
 
 This rule is fixable, unless it's [unsafe to fix](#unsafe-to-fix-case).
 
diff --git a/docs/rules/no-array-callback-reference.md b/docs/rules/no-array-callback-reference.md
@@ -7,6 +7,8 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
+Passing functions to iterator methods can cause issues when the function is changed without realizing that the iterator passes 2 more parameters to it. **This also applies when using TypeScript,** albeit only if the function accepts the same parameter type used by the iterator method.
+
 Suppose you have a `unicorn` module:
 
 ```js
@@ -37,6 +39,15 @@ const unicorn = require('unicorn');
 //=> [2, 3, 5]
 ```
 
+This rule helps safely call the function with the expected number of parameters:
+
+```js
+const unicorn = require('unicorn');
+
+[1, 2, 3].map(x => unicorn(x));
+//=> [2, 3, 4]
+```
+
 ## Fail
 
 ```js
diff --git a/docs/rules/no-array-reduce.md b/docs/rules/no-array-reduce.md
@@ -9,7 +9,7 @@
 
 It's only somewhat useful in the rare case of summing up numbers, which is allowed by default.
 
-Use `eslint-disable` comment if you really need to use it.
+Use `eslint-disable` comment if you really need to use it or disable the rule entirely if you prefer functional programming.
 
 This rule is not fixable.
 
diff --git a/docs/rules/no-nested-ternary.md b/docs/rules/no-nested-ternary.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-Improved version of the [`no-nested-ternary`](https://eslint.org/docs/latest/rules/no-nested-ternary) ESLint rule, which allows cases where the nested ternary is only one level and wrapped in parens.
+Improved version of the [`no-nested-ternary`](https://eslint.org/docs/latest/rules/no-nested-ternary) ESLint rule. This rule allows cases where the nested ternary is only one level and wrapped in parens.
 
 ## Fail
 
diff --git a/docs/rules/no-null.md b/docs/rules/no-null.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-Disallow the use of the `null` literal, to encourage using `undefined` instead.
+Disallow the use of the `null` literal, to encourage using `undefined` instead. You can learn why in <https://github.com/sindresorhus/meta/discussions/7>
 
 ## Fail
 
diff --git a/docs/rules/no-useless-undefined.md b/docs/rules/no-useless-undefined.md
@@ -7,6 +7,10 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
+`undefined` is the default value for new variables, parameters, return statements, etc… so specifying it doesn't make any difference.
+
+The only case where passing `undefined` is required is due to bad TypeScript types in functions, in which case you can use `checkArguments: false` option.
+
 ## Fail
 
 ```js
diff --git a/docs/rules/no-zero-fractions.md b/docs/rules/no-zero-fractions.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-There is no difference in JavaScript between, for example, `1`, `1.0` and `1.`, so prefer the former for consistency.
+There is no difference in JavaScript between, for example, `1`, `1.0` and `1.`, so prefer the former for consistency and brevity.
 
 ## Fail
 
diff --git a/docs/rules/numeric-separators-style.md b/docs/rules/numeric-separators-style.md
@@ -10,6 +10,8 @@
 Enforces a convention of grouping digits using [numeric separators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#Numeric_separators).
 Long numbers can become really hard to read, so cutting it into groups of digits, separated with a `_`, is important to keep your code clear. This rule also enforces a proper usage of the numeric separator, by checking if the groups of digits are of the correct size.
 
+By default, this doesn't apply to numbers below `10_000`, but that can be customized.
+
 ## Fail
 
 ```js
diff --git a/docs/rules/prefer-module.md b/docs/rules/prefer-module.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-Prefer using the [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) format over the legacy CommonJS module format.
+Prefer using the [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) format over the legacy CommonJS module format. Together with other changes, this helps the ecosystem migrate to a single, native module format.
 
 1. Disallows `'use strict'` directive.
 
diff --git a/docs/rules/prefer-number-properties.md b/docs/rules/prefer-number-properties.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-Enforces the use of:
+ECMAScript 2015 moved globals onto the `Number` constructor for consistency and to slightly improve them. This rule enforces their usage to limit the usage of globals:
 
 - [`Number.parseInt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/parseInt) over [`parseInt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt) *(fixable)*
 - [`Number.parseFloat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/parseFloat) over [`parseFloat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat) *(fixable)*
diff --git a/docs/rules/prefer-object-from-entries.md b/docs/rules/prefer-object-from-entries.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-When transforming a list of key-value pairs into an object, [`Object.fromEntries(…)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries) should be preferred.
+When transforming a list of key-value pairs into an object, [`Object.fromEntries(…)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries) should be preferred. [`no-array-reduce`](no-array-reduce.md) is a related but more generic rule.
 
 This rule is fixable for simple cases.
 
diff --git a/docs/rules/prefer-prototype-methods.md b/docs/rules/prefer-prototype-methods.md
@@ -16,7 +16,7 @@ const array = [].slice.apply(bar);
 ```
 
 ```js
-const hasProperty = {}.hasOwnProperty.call(foo, 'property');
+const type = {}.toString.call(foo);
 ```
 
 ```js
@@ -30,7 +30,7 @@ const array = Array.prototype.slice.apply(bar);
 ```
 
 ```js
-const hasProperty = Object.prototype.hasOwnProperty.call(foo, 'property');
+const type = Object.prototype.toString.call(foo);
 ```
 
 ```js
diff --git a/docs/rules/prefer-query-selector.md b/docs/rules/prefer-query-selector.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-It's better to use the same method to query DOM elements.
+It's better to use the same method to query DOM elements. This helps keep consistency and it lends itself to future improvements (e.g. more specific selectors).
 
 ## Fail
 
diff --git a/docs/rules/prefer-regexp-test.md b/docs/rules/prefer-regexp-test.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-When you want to know whether a pattern is found in a string, use [`RegExp#test()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test) instead of [`String#match()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) and [`RegExp#exec()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec).
+When you want to know whether a pattern is found in a string, use [`RegExp#test()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test) instead of [`String#match()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) and [`RegExp#exec()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec), as it exclusively returns a boolean and therefore is more efficient.
 
 ## Fail
 
diff --git a/docs/rules/prefer-spread.md b/docs/rules/prefer-spread.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-Enforces the use of [the spread operator (`...`)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) over
+Enforces the use of [the spread operator (`...`)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) over outdated patterns. This also helps keep consistency by using a single flexible operator instead of:
 
 - `Array.from(…)`
 
diff --git a/docs/rules/prefer-string-trim-start-end.md b/docs/rules/prefer-string-trim-start-end.md
@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-[`String#trimLeft()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimLeft) and [`String#trimRight()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimRight) are aliases of [`String#trimStart()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimStart) and [`String#trimEnd()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimEnd)
+[`String#trimLeft()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimLeft) and [`String#trimRight()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimRight) are aliases of [`String#trimStart()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimStart) and [`String#trimEnd()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimEnd). This is to ensure consistency and use [direction](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Handling_different_text_directions)-independent wording.
 
 ## Fail
 
