Docs: Distinguish examples in rules under Stylistic Issues part 6 (#6567

)

docs/rules/no-trailing-spaces.md

@@ -1,50 +1,47 @@
-# Disallow trailing spaces at the end of lines (no-trailing-spaces)
+# disallow trailing whitespace at the end of lines (no-trailing-spaces)
 
 (fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
 
-Sometimes in the course of editing files, you can end up with extra whitespace at the end of lines. These whitespace differences can be picked up by source control systems and flagged as diffs, causing frustration for developers. While this extra whitespace causes no functional issues, many code conventions require that trailing spaces be removed before checkin.
+Sometimes in the course of editing files, you can end up with extra whitespace at the end of lines. These whitespace differences can be picked up by source control systems and flagged as diffs, causing frustration for developers. While this extra whitespace causes no functional issues, many code conventions require that trailing spaces be removed before check-in.
 
 ## Rule Details
 
-The following patterns are considered problems:
+This rule disallows trailing whitespace (spaces, tabs, and other Unicode whitespace characters) at the end of lines.
+
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-trailing-spaces: "error"*/
 
-// spaces, tabs and unicode whitespaces
-// are not allowed at the end of lines
 var foo = 0;//•••••
 var baz = 5;//••
+//•••••
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-trailing-spaces: "error"*/
 
 var foo = 0;
-
 var baz = 5;
 ```
 
 ## Options
 
-There is one option for this rule, `skipBlankLines`. When set to true, the rule will not flag any lines that are made up purely of whitespace. In short, if a line is zero-length after being trimmed of whitespace, then the rule will not flag that line when `skipBlankLines` is enabled.
+This rule has an object option:
 
-You can enable this option in your config like this:
+* `"skipBlankLines": false` (default) disallows trailing whitespace on empty lines
+* `"skipBlankLines": true` allows trailing whitespace on empty lines
 
-```json
-{
-    "no-trailing-spaces": ["error", { "skipBlankLines": true }]
-}
-```
+### skipBlankLines
 
-With this option enabled, The following patterns are not considered problems:
+Examples of **correct** code for this rule with the `{ "skipBlankLines": true }` option:
 
 ```js
 /*eslint no-trailing-spaces: ["error", { "skipBlankLines": true }]*/
 
 var foo = 0;
-//••••
 var baz = 5;
+//•••••
 ```

docs/rules/no-underscore-dangle.md

@@ -1,4 +1,4 @@
-# Disallow Dangling Underscores in Identifiers (no-underscore-dangle)
+# disallow dangling underscores in identifiers (no-underscore-dangle)
 
 As far as naming conventions for identifiers go, dangling underscores may be the most polarizing in JavaScript. Dangling underscores are underscores at either the beginning or end of an identifier, such as:
 
@@ -12,27 +12,9 @@ Whether or not you choose to allow dangling underscores in identifiers is purely
 
 ## Rule Details
 
-This rule aims to eliminate the use of dangling underscores in identifiers.
+This rule disallows dangling underscores in identifiers.
 
-## Options
-
-### `allow`
-
-```json
-"no-underscore-dangle": ["error", { "allow": [] }]
-```
-
-Array of variable names that are permitted to be used with underscore. If provided, it must be an `Array`.
-
-### `allowAfterThis`
-
-```json
-"no-underscore-dangle": ["error", { "allowAfterThis": true }]
-```
-
-This option allows usage of dangled variables as members of `this`.
-
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-underscore-dangle: "error"*/
@@ -42,7 +24,7 @@ var __proto__ = {};
 foo._bar();
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-underscore-dangle: "error"*/
@@ -53,6 +35,17 @@ obj.__proto__ = {};
 var file = __filename;
 ```
 
+## Options
+
+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
+* `"afterAfterThis": true` allows dangling underscores in members of the `this` object
+
+### allow
+
+Examples of additional **correct** code for this rule with the `{ "allow": ["foo_", "_bar"] }` option:
 
 ```js
 /*eslint no-underscore-dangle: ["error", { "allow": ["foo_", "_bar"] }]*/
@@ -61,6 +54,10 @@ var foo_;
 foo._bar();
 ```
 
+### allowAfterThis
+
+Examples of **correct** code for this rule with the `{ "allowAfterThis": true }` option:
+
 ```js
 /*eslint no-underscore-dangle: ["error", { "allowAfterThis": true }]*/
 

docs/rules/no-unneeded-ternary.md

@@ -1,4 +1,4 @@
-# Disallow conditional expressions that can be expressed with simpler constructs (no-unneeded-ternary)
+# disallow ternary operators when simpler alternatives exist (no-unneeded-ternary)
 
 It's a common mistake in JavaScript to use a conditional expression to select between two Boolean values instead of using ! to convert the test to a Boolean.
 Here are some examples:
@@ -18,8 +18,6 @@ var isNo = answer === 1 ? false : true;
 var isNo = answer !== 1;
 ```
 
-This rule disallows the use of 'Boolean' literals inside conditional expressions.
-
 Another common mistake is using a single variable as both the conditional test and the consequent. In such cases, the logical `OR` can be used to provide the same functionality.
 Here is an example:
 
@@ -31,13 +29,11 @@ var foo = bar ? bar : 1;
 var foo = bar || 1;
 ```
 
-This rule disallows the conditional expression as a default assignment pattern when the `defaultAssignment` option is set to `false`.
-
 ## Rule Details
 
-This rule enforces a coding style where it disallows conditional expressions that can be implemented using simpler language constructs. Specifically, this rule disallows the use of Boolean literals inside conditional expressions, and conditional expressions where a single variable is used as both the test and consequent. This rule's default options are `{"defaultAssignment": true }`.
+This rule disallow ternary operators when simpler alternatives exist.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-unneeded-ternary: "error"*/
@@ -47,13 +43,7 @@ var a = x === 2 ? true : false;
 var a = x ? true : false;
 ```
 
-The following pattern is considered a warning when `defaultAssignment` is `false`:
-
-```js
-var a = x ? x : 1;
-```
-
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-unneeded-ternary: "error"*/
@@ -65,11 +55,24 @@ var a = x !== false;
 var a = x ? "Yes" : "No";
 
 var a = x ? y : x;
+
+var a = x ? x : 1;
 ```
 
-The following pattern is not considered a warning when `defaultAssignment` is `true`:
+## Options
+
+This rule has an object option:
+
+* `"defaultAssignment": true` (default) allows the conditional expression as a default assignment pattern
+* `"defaultAssignment": false` disallows the conditional expression as a default assignment pattern
+
+### defaultAssignment
+
+Examples of additional **incorrect** code for this rule with the `{ "defaultAssignment": false }` option:
 
 ```js
+/*eslint no-unneeded-ternary: ["error", { "defaultAssignment": false }]*/
+
 var a = x ? x : 1;
 ```
 

docs/rules/no-whitespace-before-property.md

@@ -1,4 +1,4 @@
-# Disallow whitespace before properties (no-whitespace-before-property)
+# disallow whitespace before properties (no-whitespace-before-property)
 
 (fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
 
@@ -10,7 +10,7 @@ foo. bar .baz . quz
 
 ## Rule Details
 
-This rule alerts for whitespace around the dot or before the opening bracket before properties of objects if they are on the same line. It does not alert for whitespace when the object and property are on separate lines, as it is common to add newlines to longer chains of properties:
+This rule disallows whitespace around the dot or before the opening bracket before properties of objects if they are on the same line. This rule allows whitespace when the object and property are on separate lines, as it is common to add newlines to longer chains of properties:
 
 ```js
 foo
@@ -19,7 +19,7 @@ foo
   .qux()
 ```
 
-The following patterns are considered problems when this rule is turned on:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-whitespace-before-property: "error"*/
@@ -39,7 +39,7 @@ foo
   .bar(). baz()
 ```
 
-And the following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-whitespace-before-property: "error"*/