Docs: Distinguish examples in rules under Best Practices part 4

docs/rules/no-self-assign.md

@@ -12,7 +12,7 @@ foo = foo;
 
 This rule is aimed at eliminating self assignments.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-self-assign: 2*/
@@ -26,7 +26,7 @@ foo = foo;
 ({a, b} = {a, x});
 ```
 
-The following patterns are considered not problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-self-assign: 2*/

docs/rules/no-self-compare.md

@@ -8,6 +8,8 @@ The only time you would compare a variable against itself is when you are testin
 
 This error is raised to highlight a potentially confusing and potentially pointless piece of code. There are almost no situations in which you would need to compare something to itself.
 
+Examples of **incorrect** code for this rule:
+
 ```js
 /*eslint no-self-compare: 2*/
 

docs/rules/no-sequences.md

@@ -19,7 +19,7 @@ This rule forbids the use of the comma operator, with the following exceptions:
 * In the initialization or update portions of a `for` statement.
 * If the expression sequence is explicitly wrapped in parentheses.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-sequences: 2*/
@@ -39,7 +39,7 @@ while (val = foo(), val < 42);
 with (doSomething(), val) {}
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-sequences: 2*/

docs/rules/no-throw-literal.md

@@ -9,7 +9,7 @@ This rule restricts what can be thrown as an exception.  When it was first creat
 
 This rule is aimed at maintaining consistency when throwing exception by disallowing to throw literals and other expressions which cannot possibly be an `Error` object.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-throw-literal: 2*/
@@ -32,7 +32,7 @@ throw `${err}`
 
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-throw-literal: 2*/
@@ -53,7 +53,9 @@ try {
 
 ## Known Limitations
 
-Due to the limits of static analysis, this rule cannot guarantee that you will only throw `Error` objects.  For instance, the following cases do not throw an `Error` object, but they will not be considered problems:
+Due to the limits of static analysis, this rule cannot guarantee that you will only throw `Error` objects.
+
+Examples of **correct** code for this rule, but which do not throw an `Error` object:
 
 ```js
 /*eslint no-throw-literal: 2*/

docs/rules/no-unmodified-loop-condition.md

@@ -26,7 +26,7 @@ the expression instead.
 If a reference is inside of a dynamic expression (e.g. `CallExpression`,
 `YieldExpression`, ...), this rule ignores it.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 while (node) {
@@ -43,7 +43,7 @@ while (node !== root) {
 }
 ```
 
-The following patterns are considered not problems:
+Examples of **correct** code for this rule:
 
 ```js
 while (node) {

docs/rules/no-unused-expressions.md

@@ -1,20 +1,28 @@
 # Disallow Unused Expressions (no-unused-expressions)
 
-Unused expressions are those expressions that evaluate to a value but are never used. For example:
+An unused expression which has no effect on the state of the program indicates a logic error.
 
-```js
-n + 1;
-```
-
-This is a valid JavaScript expression, but isn't actually used. Even though it's not a syntax error it is clearly a logic error and it has no effect on the code being executed.
+For example, `n + 1;` is not a syntax error, but it might be a typing mistake where a programmer meant an assignment statement `n += 1;` instead.
 
 ## Rule Details
 
-This rule aims to eliminate unused expressions. The value of an expression should always be used, except in the case of expressions that side effect: function calls, assignments, and the `new` operator.
+This rule aims to eliminate unused expressions which have no effect on the state of the program.
 
-Note that sequence expressions (those using a comma, such as `a = 1, b = 2`) are always considered unused unless their return value is assigned or used in a condition evaluation, or a function call is made with the sequence expression value.
+This rule does not apply to function calls or constructor calls with the `new` operator, because they could have *side effects* on the state of the program.
 
-Please also note that this rule does not apply to directives (which are in the form of literal string expressions (e.g., `"use strict";`) at the beginning of a script, module, or function).
+```js
+var i = 0;
+function increment() { i += 1; }
+increment(); // return value is unused, but i changed as a side effect
+
+var nThings = 0;
+function Thing() { nThings += 1; }
+new Thing(); // constructed object is unused, but nThings changed as a side effect
+```
+
+This rule does not apply to directives (which are in the form of literal string expressions such as `"use strict";` at the beginning of a script, module, or function).
+
+Sequence expressions (those using a comma, such as `a = 1, b = 2`) are always considered unused unless their return value is assigned or used in a condition evaluation, or a function call is made with the sequence expression value.
 
 ## Options
 
@@ -23,7 +31,9 @@ This rule, in its default state, does not require any arguments. If you would li
 * `allowShortCircuit` set to `true` will allow you to use short circuit evaluations in your expressions (Default: `false`).
 * `allowTernary` set to `true` will enable you use ternary operators in your expressions similarly to short circuit evaluations (Default: `false`).
 
-By default the following patterns are considered problems:
+These options allow unused expressions *only if all* of the code paths either directly change the state (for example, assignment statement) or could have *side effects* (for example, function call).
+
+Examples of **incorrect** code for the default `{ "allowShortCircuit": false, "allowTernary": false }` options:
 
 ```js
 /*eslint no-unused-expressions: 2*/
@@ -58,7 +68,7 @@ Note that one or more string expression statements (with or without semi-colons)
 "any other strings like this in the prologue";
 ```
 
-The following patterns are not considered problems by default:
+Examples of **correct** code for the default `{ "allowShortCircuit": false, "allowTernary": false }` options:
 
 ```js
 /*eslint no-unused-expressions: 2*/
@@ -82,42 +92,51 @@ delete a.b
 void a
 ```
 
-The following patterns are not considered problems if `allowShortCircuit` is enabled:
+### allowShortCircuit
 
-```js
-/*eslint no-unused-expressions: [2, { allowShortCircuit: true }]*/
+Examples of **incorrect** code for the `{ "allowShortCircuit": true }` option:
 
-a && b()
+```js
+/*eslint no-unused-expressions: [2, { "allowShortCircuit": true }]*/
 
-a() || (b = c)
+a || b
 ```
 
-If you enable the `allowTernary` the following patterns will be allowed:
+Examples of **correct** code for the `{ "allowShortCircuit": true }` option:
 
 ```js
-/*eslint no-unused-expressions: [2, { allowTernary: true }]*/
-
-a ? b() : c()
+/*eslint no-unused-expressions: [2, { "allowShortCircuit": true }]*/
 
-a ? (b = c) : d()
+a && b()
+a() || (b = c)
 ```
 
-Enabling both options will allow a combination of both ternary and short circuit evaluation:
+### allowTernary
+
+Examples of **incorrect** code for the `{ "allowTernary": true }` option:
 
 ```js
-/*eslint no-unused-expressions: [2, { allowShortCircuit: true, allowTernary: true }]*/
+/*eslint no-unused-expressions: [2, { "allowTernary": true }]*/
 
-a ? b() || (c = d) : e()
+a ? b : 0
+a ? b : c()
 ```
 
-The above options still will not allow expressions that have code paths without side effects such as the following:
+Examples of **correct** code for the `{ "allowTernary": true }` option:
 
 ```js
-/*eslint no-unused-expressions: [2, { allowShortCircuit: true, allowTernary: true }]*/
+/*eslint no-unused-expressions: [2, { "allowTernary": true }]*/
 
-a || b
+a ? b() : c()
+a ? (b = c) : d()
+```
 
-a ? b : 0
+### allowShortCircuit and allowTernary
 
-a ? b : c()
+Examples of **correct** code for the `{ "allowShortCircuit": true, "allowTernary": true }` options:
+
+```js
+/*eslint no-unused-expressions: [2, { "allowShortCircuit": true, "allowTernary": true }]*/
+
+a ? b() || (c = d) : e()
 ```

docs/rules/no-unused-labels.md

@@ -19,7 +19,7 @@ Such labels take up space in the code and can lead to confusion by readers.
 
 This rule is aimed at eliminating unused labels.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-unused-labels: 2*/
@@ -36,7 +36,7 @@ for (let i = 0; i < 10; ++i) {
 }
 ```
 
-The following patterns are considered not problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-unused-labels: 2*/

docs/rules/no-useless-call.md

@@ -7,7 +7,7 @@ But `Function.prototype.call()` and `Function.prototype.apply()` are slower than
 
 This rule is aimed to flag usage of `Function.prototype.call()` and `Function.prototype.apply()` that can be replaced with the normal function invocation.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-useless-call: 2*/
@@ -23,7 +23,7 @@ obj.foo.call(obj, 1, 2, 3);
 obj.foo.apply(obj, [1, 2, 3]);
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-useless-call: 2*/
@@ -42,18 +42,24 @@ foo.apply(null, args);
 obj.foo.apply(obj, args);
 ```
 
-Known limitations:
+## Known Limitations
 
 This rule compares code statically to check whether or not `thisArg` is changed.
 So if the code about `thisArg` is a dynamic expression, this rule cannot judge correctly.
 
+Examples of **incorrect** code for this rule:
+
 ```js
 /*eslint no-useless-call: 2*/
 
-// This is warned.
 a[i++].foo.call(a[i++], 1, 2, 3);
+```
+
+Examples of **correct** code for this rule:
+
+```js
+/*eslint no-useless-call: 2*/
 
-// This is not warned.
 a[++i].foo.call(a[i], 1, 2, 3);
 ```
 

docs/rules/no-useless-concat.md

@@ -16,7 +16,7 @@ var foo = "ab";
 
 This rule aims to flag the concatenation of 2 literals when they could be combined into a single literal. Literals can be strings or template literals.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-useless-concat: 2*/
@@ -30,7 +30,7 @@ var a = `1` + '0';
 var a = `1` + `0`;
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-useless-concat: 2*/

docs/rules/no-void.md

@@ -48,7 +48,7 @@ Some code styles prohibit `void` operator marking it as non-obvious and hard to
 
 This rule aims to eliminate use of void operator.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-void: 2*/