From 89580a40557093184b5e164b7ef284670d47090b Mon Sep 17 00:00:00 2001
From: Kenneth Williams <scriptdaemon@users.noreply.github.com>
Date: Thu, 2 Jun 2016 06:42:03 -0700
Subject: [PATCH] Docs: Distinguish examples in rules under Stylistic Issues
 part 5 (#6291)

---
 docs/rules/no-lonely-if.md             | 10 ++--
 docs/rules/no-mixed-spaces-and-tabs.md | 30 +++++-------
 docs/rules/no-multiple-empty-lines.md  | 66 +++++++-------------------
 docs/rules/no-negated-condition.md     | 41 ++++------------
 docs/rules/no-nested-ternary.md        | 12 +++--
 docs/rules/no-new-object.md            |  8 ++--
 docs/rules/no-plusplus.md              | 35 ++++++--------
 docs/rules/no-restricted-syntax.md     | 12 ++---
 docs/rules/no-spaced-func.md           | 12 ++---
 docs/rules/no-ternary.md               | 22 +++------
 10 files changed, 88 insertions(+), 160 deletions(-)

diff --git a/docs/rules/no-lonely-if.md b/docs/rules/no-lonely-if.md
index c7b84fa41d2..4dab7ef7b63 100644
--- a/docs/rules/no-lonely-if.md
+++ b/docs/rules/no-lonely-if.md
@@ -1,6 +1,6 @@
-# Disallow `if` as the Only Statement in an `else` Block (no-lonely-if)
+# disallow `if` statements as the only statement in `else` blocks (no-lonely-if)
 
-If an `if` statement is the only statement in the `else` block of a parent `if` statement, it is often clearer to combine the two to using `else if` form.
+If an `if` statement is the only statement in the `else` block, it is often clearer to use an `else if` form.
 
 ```js
 if (foo) {
@@ -24,9 +24,9 @@ if (foo) {
 
 ## Rule Details
 
-This rule warns when an `if` statement's `else` block contains only another `if` statement.
+This rule disallows `if` statements as the only statement in `else` blocks.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-lonely-if: "error"*/
@@ -50,7 +50,7 @@ if (condition) {
 }
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-lonely-if: "error"*/
diff --git a/docs/rules/no-mixed-spaces-and-tabs.md b/docs/rules/no-mixed-spaces-and-tabs.md
index c5a2df83e54..904e2fcfd83 100644
--- a/docs/rules/no-mixed-spaces-and-tabs.md
+++ b/docs/rules/no-mixed-spaces-and-tabs.md
@@ -1,24 +1,12 @@
-# Disallow mixed spaces and tabs for indentation (no-mixed-spaces-and-tabs)
+# disallow mixed spaces and tabs for indentation (no-mixed-spaces-and-tabs)
 
 Most code conventions require either tabs or spaces be used for indentation. As such, it's usually an error if a single line of code is indented with both tabs and spaces.
 
 ## Rule Details
 
-The `no-mixed-spaces-and-tabs` rule is aimed at flagging any lines of code that are indented with a mixture of tabs and spaces.
+This rule disallows mixed spaces and tabs for indentation.
 
-## Options
-
-### smart-tabs
-
-This option suppresses warnings about mixed tabs and spaces when the latter are used for alignment only. This technique is called [SmartTabs](http://www.emacswiki.org/emacs/SmartTabs). The option is turned off by default.
-
-You can enable this option by using the following configuration:
-
-```json
-"no-mixed-spaces-and-tabs": ["error", "smart-tabs"]
-```
-
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-mixed-spaces-and-tabs: "error"*/
@@ -38,7 +26,7 @@ function main() {
 }
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-mixed-spaces-and-tabs: "error"*/
@@ -49,7 +37,15 @@ function add(x, y) {
 }
 ```
 
-When the SmartTabs option is enabled the following does not produce a warning:
+## Options
+
+This rule has a string option.
+
+* `"smart-tabs"` allows mixed spaces and tabs when the latter are used for alignment.
+
+### smart-tabs
+
+Examples of **correct** code for this rule with the `"smart-tabs"` option:
 
 ```js
 /*eslint no-mixed-spaces-and-tabs: ["error", "smart-tabs"]*/
diff --git a/docs/rules/no-multiple-empty-lines.md b/docs/rules/no-multiple-empty-lines.md
index 5c3dd107cdc..87b2425e010 100644
--- a/docs/rules/no-multiple-empty-lines.md
+++ b/docs/rules/no-multiple-empty-lines.md
@@ -1,72 +1,50 @@
-# Disallows multiple blank lines (no-multiple-empty-lines)
+# disallow multiple empty lines (no-multiple-empty-lines)
 
 Some developers prefer to have multiple blank lines removed, while others feel that it helps improve readability. Whitespace is useful for separating logical sections of code, but excess whitespace takes up more of the screen.
 
-
 ## Rule Details
 
 This rule aims to reduce the scrolling required when reading through your code. It will warn when the maximum amount of empty lines has been exceeded.
 
 ## Options
 
-The second argument can be used to configure this rule:
+This rule has an object option:
 
-* `max` sets the maximum number of consecutive blank lines.
-* `maxEOF` can be used to set a different number for the end of file. The last
-  blank lines will then be treated differently. If omitted, the `max` option is
-  applied at the end of the file.
-* `maxBOF` can be used to set a different number for the beginning of the file.
-  If omitted, the 'max' option is applied at the beginning of the file.
+* `"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
 
-In the following example, the `error` is the severity of the rule, and the
-`max` property is the maximum number of empty lines (2 in this example).
-
-```json
-"no-multiple-empty-lines": ["error", {"max": 2}]
-```
-
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule with the default `{ "max": 2 }` option:
 
 ```js
-/*eslint no-multiple-empty-lines: ["error", {max: 2}]*/
-
+/*eslint no-multiple-empty-lines: "error"*/
 
 var foo = 5;
 
 
 
 var bar = 3;
-
-
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule with the default `{ "max": 2 }` option:
 
 ```js
-/*eslint no-multiple-empty-lines: ["error", {max: 2}]*/
-
+/*eslint no-multiple-empty-lines: "error"*/
 
 var foo = 5;
 
 
 var bar = 3;
-
-
 ```
 
 ### maxEOF
 
-```json
-"no-multiple-empty-lines": ["error", {"max": 2, "maxEOF": 1}]
-```
-
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule with the `{ max: 2, maxEOF: 1 }` options:
 
 ```js
-/*eslint no-multiple-empty-lines: ["error", {max: 2, maxEOF: 1}]*/
-
+/*eslint no-multiple-empty-lines: ["error", { "max": 2, "maxEOF": 1 }]*/
 
 var foo = 5;
 
@@ -76,11 +54,10 @@ var bar = 3;
 
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule with the `{ max: 2, maxEOF: 1 }` options:
 
 ```js
-/*eslint no-multiple-empty-lines: ["error", {max: 2, maxEOF: 1}]*/
-
+/*eslint no-multiple-empty-lines: ["error", { "max": 2, "maxEOF": 1 }]*/
 
 var foo = 5;
 
@@ -91,34 +68,27 @@ var bar = 3;
 
 ### maxBOF
 
-```json
-"no-multiple-empty-lines": ["error", {"max": 2, "maxBOF": 0}]
-```
-
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule with the `{ max: 2, maxBOF: 1 }` options:
 
 ```js
-/*eslint no-multiple-empty-lines: ["error", {max: 2, maxBOF: 0}]*/
+/*eslint no-multiple-empty-lines: ["error", { "max": 2, "maxBOF": 1 }]*/
 
 
 var foo = 5;
 
 
 var bar = 3;
-
-
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule with the `{ max: 2, maxBOF: 1 }` options:
 
 ```js
-/*eslint no-multiple-empty-lines: ["error", {max: 2, maxBOF: 0}]*/
+/*eslint no-multiple-empty-lines: ["error", { "max": 2, "maxBOF": 1}]*/
+
 var foo = 5;
 
 
 var bar = 3;
-
-
 ```
 
 ## When Not To Use It
diff --git a/docs/rules/no-negated-condition.md b/docs/rules/no-negated-condition.md
index a73b4d651de..58addae69b3 100644
--- a/docs/rules/no-negated-condition.md
+++ b/docs/rules/no-negated-condition.md
@@ -1,34 +1,15 @@
-# Disallow use of negated expressions in conditions (no-negated-condition)
+# disallow negated conditions (no-negated-condition)
 
-Checks against the use of a negated expression in an if condition when the else branch is not empty or in a ternary operator. Negated conditions are more difficult to understand. Code can be made more readable by inverting the condition instead.
-
-For example:
-
-```js
-if (!a) {
-    doSomething();
-}
-else {
-    doSomethingElse();
-}
-```
-
-should instead be written as:
-
-```js
-if (a) {
-    doSomethingElse();
-}
-else {
-    doSomething();
-}
-```
+Negated conditions are more difficult to understand. Code can be made more readable by inverting the condition instead.
 
 ## Rule Details
 
-The rule is aimed at preventing the use of a negated expression in a condition.
+This rule disallows negated conditions in either of the following:
 
-The following patterns are considered warnings:
+* `if` statements which have an `else` branch
+* ternary expressions
+
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-negated-condition: "error"*/
@@ -51,13 +32,10 @@ if (a !== b) {
     doSomethingElse();
 }
 
-
-!a ? b : c
-
+!a ? c : b
 ```
 
-The following patterns are not warnings:
-
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-negated-condition: "error"*/
@@ -77,5 +55,4 @@ if (a != b) {
 }
 
 a ? b : c
-
 ```
diff --git a/docs/rules/no-nested-ternary.md b/docs/rules/no-nested-ternary.md
index c9845c67d78..8c9cb0dbf07 100644
--- a/docs/rules/no-nested-ternary.md
+++ b/docs/rules/no-nested-ternary.md
@@ -1,6 +1,6 @@
-# Disallow Nested Ternaries (no-nested-ternary)
+# disallow nested ternary expressions (no-nested-ternary)
 
-Nesting ternary expressions makes code unclear. The `no-nested-ternary` rule disallows the use of nested ternary expressions.
+Nesting ternary expressions can make code more difficult to understand.
 
 ```js
 var foo = bar ? baz : qux === quxx ? bing : bam;
@@ -8,9 +8,9 @@ var foo = bar ? baz : qux === quxx ? bing : bam;
 
 ## Rule Details
 
-The `no-nested-ternary` rule aims to increase the clarity and readability of code by disallowing the use of nested ternary expressions.
+The `no-nested-ternary` rule disallows nested ternary expressions.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-nested-ternary: "error"*/
@@ -20,11 +20,13 @@ var thing = foo ? bar : baz === qux ? quxx : foobar;
 foo ? baz === qux ? quxx() : foobar() : bar();
 ```
 
-The following patterns are considered okay and could be used alternatively:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-nested-ternary: "error"*/
 
+var thing = foo ? bar : foobar;
+
 var thing;
 
 if (foo) {
diff --git a/docs/rules/no-new-object.md b/docs/rules/no-new-object.md
index acedb0d225a..5186682fc05 100644
--- a/docs/rules/no-new-object.md
+++ b/docs/rules/no-new-object.md
@@ -1,4 +1,4 @@
-# Disallow the use of the Object constructor (no-new-object)
+# disallow `Object` constructors (no-new-object)
 
 The `Object` constructor is used to create new generic objects in JavaScript, such as:
 
@@ -18,9 +18,9 @@ While there are no performance differences between the two approaches, the byte
 
 ## Rule Details
 
-This rule aims to eliminate use of the `Object` constructor. As such, it warns whenever `new Object` is found in code.
+This rule disallows `Object` constructors.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-new-object: "error"*/
@@ -30,7 +30,7 @@ var myObject = new Object();
 var myObject = new Object;
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-new-object: "error"*/
diff --git a/docs/rules/no-plusplus.md b/docs/rules/no-plusplus.md
index feafe571889..ae0382937f4 100644
--- a/docs/rules/no-plusplus.md
+++ b/docs/rules/no-plusplus.md
@@ -1,13 +1,6 @@
-# Disallow ++ and -- (no-plusplus)
+# disallow the unary operators `++` and `--` (no-plusplus)
 
-The `no-plusplus` rule flags the use of unary operators, `++` and `--`.
-
-```js
-var foo = 0;
-foo++;
-```
-
-The `++` and `--` operators are subject to automatic semicolon insertion. When their use is allowed, introducing whitespace may change semantics of source code. Enabling the rule may prevent this kind of errors.
+Because the unary `++` and `--` operators are subject to automatic semicolon insertion, differences in whitespace can change semantics of source code.
 
 ```js
 var i = 10;
@@ -30,15 +23,9 @@ j
 
 ## Rule Details
 
-This rule is aimed at flagging the use of `++` and `--`. Some believe that the use of these unary operators reduces code quality and clarity. There are some programming languages that completely exclude these operators.
-
-## Options
+This rule disallows the unary operators `++` and `--`.
 
-This rule, in its default state, does not require any arguments. If you would like to enable one or more of the following you may pass an object with the options set as follows:
-
-* `allowForLoopAfterthoughts` set to `true` will allow you to use the unary operators `++` and `--` in the afterthought (final expression) of a `for` loop.
-
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-plusplus: "error"*/
@@ -54,7 +41,7 @@ for (i = 0; i < l; i++) {
 }
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-plusplus: "error"*/
@@ -70,10 +57,18 @@ for (i = 0; i < l; i += 1) {
 }
 ```
 
-The following patterns are not considered problems if `allowForLoopAfterthoughts` is set to true:
+## Options
+
+This rule has an object option.
+
+* `"allowForLoopAfterthoughts": true` allows unary operators `++` and `--` in the afterthought (final expression) of a `for` loop.
+
+### allowForLoopAfterthoughts
+
+Examples of **correct** code for this rule with the `{ "allowForLoopAfterthoughts": true }` option:
 
 ```js
-/*eslint no-plusplus: ["error", { allowForLoopAfterthoughts: true }]*/
+/*eslint no-plusplus: ["error", { "allowForLoopAfterthoughts": true }]*/
 
 for (i = 0; i < l; i++) {
     return;
diff --git a/docs/rules/no-restricted-syntax.md b/docs/rules/no-restricted-syntax.md
index 114af1fb12b..716c69fda53 100644
--- a/docs/rules/no-restricted-syntax.md
+++ b/docs/rules/no-restricted-syntax.md
@@ -1,16 +1,16 @@
-# Disallow certain syntax (no-restricted-syntax)
+# disallow specified syntax (no-restricted-syntax)
 
-JavaScript has a lot of language features, and not everyone likes every features. As a result, some projects choose to disallow the use of certain language features altogether. For instance, you might decide to disallow the use of `try-catch` or `class`.
+JavaScript has a lot of language features, and not everyone likes all of them. As a result, some projects choose to disallow the use of certain language features altogether. For instance, you might decide to disallow the use of `try-catch` or `class`.
 
 Rather than creating separate rules for every language feature you want to turn off, this rule allows you to configure the syntax elements you want to restrict use of. These elements are represented by their [ESTree](https://github.com/estree/estree) node types. For example, a function declaration is represented by `FunctionDeclaration` and the `with` statement is represented by `WithStatement`. You may find the full list of AST node names you can use [on GitHub](https://github.com/eslint/espree/blob/master/lib/ast-node-types.js) and use the [online parser](http://eslint.org/parser/) to see what type of nodes your code consists of.
 
 ## Rule Details
 
-This rule is aimed at eliminating certain syntax from your JavaScript. As such, it warns whenever it sees a node type that is restricted by its options.
+This rule disallows specified (that is, user-defined) syntax.
 
 ## Options
 
-This rule takes a list of strings where strings denote the node types:
+This rule takes a list of strings:
 
 ```json
 {
@@ -20,7 +20,7 @@ This rule takes a list of strings where strings denote the node types:
 }
 ```
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule with the `"FunctionExpression", "WithStatement"` options:
 
 ```js
 /* eslint no-restricted-syntax: ["error", "FunctionExpression", "WithStatement"] */
@@ -32,7 +32,7 @@ with (me) {
 var doSomething = function () {};
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule with the `"FunctionExpression", "WithStatement"` options:
 
 ```js
 /* eslint no-restricted-syntax: ["error", "FunctionExpression", "WithStatement"] */
diff --git a/docs/rules/no-spaced-func.md b/docs/rules/no-spaced-func.md
index 00b63e96b20..d53dab9e5d4 100644
--- a/docs/rules/no-spaced-func.md
+++ b/docs/rules/no-spaced-func.md
@@ -1,4 +1,4 @@
-# Disallow Spaces in Function Calls (no-spaced-func)
+# disallow spacing between `function` identifiers and their applications (no-spaced-func)
 
 (fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
 
@@ -6,13 +6,9 @@ While it's possible to have whitespace between the name of a function and the pa
 
 ## Rule Details
 
-This rule does not allow gaps between the function identifier and application.
+This rule disallows spacing between function identifiers and their applications.
 
-```js
-fn ()
-```
-
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-spaced-func: "error"*/
@@ -23,7 +19,7 @@ fn
 ()
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-spaced-func: "error"*/
diff --git a/docs/rules/no-ternary.md b/docs/rules/no-ternary.md
index 2f02c3627bc..3c95f827d1e 100644
--- a/docs/rules/no-ternary.md
+++ b/docs/rules/no-ternary.md
@@ -1,4 +1,4 @@
-# Disallow Ternary Operators (no-ternary)
+# disallow ternary operators (no-ternary)
 
 The ternary operator is used to conditionally assign a value to a variable. Some believe that the use of ternary operators leads to unclear code.
 
@@ -8,23 +8,21 @@ var foo = isBar ? baz : qux;
 
 ## Rule Details
 
-The `no-ternary` rule aims to disallow the use of ternary operators.
+This rule disallows ternary operators.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-ternary: "error"*/
 
 var foo = isBar ? baz : qux;
 
-foo ? bar() : baz();
-
 function quux() {
-  return foo ? bar : baz;
+  return foo ? bar() : baz();
 }
 ```
 
-The following patterns are considered okay and could be used alternatively:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint no-ternary: "error"*/
@@ -37,17 +35,11 @@ if (isBar) {
     foo = qux;
 }
 
-if (foo) {
-    bar();
-} else {
-    baz();
-}
-
 function quux() {
     if (foo) {
-        return bar;
+        return bar();
     } else {
-        return baz;
+        return baz();
     }
 }
 ```