Docs: Distinguish examples in rules under Best Practices part 1

docs/rules/accessor-pairs.md

@@ -34,18 +34,12 @@ By activating the option `getWithoutSet` it enforces the presence of a setter fo
 
 ## Options
 
-`getWithoutSet` set to `true` will warn for getters without setters (Default `false`).
-`setWithoutGet` set to `true` will warn for setters without getters (Default `true`).
+* `setWithoutGet` set to `true` will warn for setters without getters (Default `true`).
+* `getWithoutSet` set to `true` will warn for getters without setters (Default `false`).
 
-By default `setWithoutGet` option is always set to `true`.
+### setWithoutGet
 
-```json
-{
-    "accessor-pairs": [2, {"getWithoutSet": true}]
-}
-```
-
-The following patterns are considered problems by default:
+Examples of **incorrect** code for the default `{ "setWithoutGet": true }` option:
 
 ```js
 /*eslint accessor-pairs: 2*/
@@ -64,7 +58,7 @@ Object.defineProperty(o, 'c', {
 });
 ```
 
-The following patterns are not considered problems by default:
+Examples of **correct** code for the default `{ "setWithoutGet": true }` option:
 
 ```js
 /*eslint accessor-pairs: 2*/
@@ -90,12 +84,12 @@ Object.defineProperty(o, 'c', {
 
 ```
 
-### `getWithoutSet`
+### getWithoutSet
 
-The following patterns are considered problems with option `getWithoutSet` set:
+Examples of **incorrect** code for the `{ "getWithoutSet": true }` option:
 
 ```js
-/*eslint accessor-pairs: [2, { getWithoutSet: true }]*/
+/*eslint accessor-pairs: [2, { "getWithoutSet": true }]*/
 
 var o = {
     set a(value) {
@@ -124,10 +118,10 @@ Object.defineProperty(o, 'c', {
 });
 ```
 
-The following patterns are not considered problems with option `getWithoutSet` set:
+Examples of **correct** code for the `{ "getWithoutSet": true }` option:
 
 ```js
-/*eslint accessor-pairs: [2, { getWithoutSet: true }]*/
+/*eslint accessor-pairs: [2, { "getWithoutSet": true }]*/
 var o = {
     set a(value) {
         this.val = value;

docs/rules/array-callback-return.md

@@ -28,11 +28,11 @@ This rule finds callback functions of the following methods, then checks usage o
 * [`Array.prototype.sort`](http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.sort)
 * And above of typed arrays.
 
-**Note:** this rule finds by the method name, so the object which has the method might not be an array.
-
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
+/*eslint array-callback-return: 2*/
+
 var indexMap = myArray.reduce(function(memo, item, index) {
     memo[item] = index;
 }, {});
@@ -52,9 +52,11 @@ var bar = foo.filter(function(x) {
 });
 ```
 
-The following patterns are considered not problems:
+Examples of **correct** code for this rule:
 
 ```js
+/*eslint array-callback-return: 2*/
+
 var indexMap = myArray.reduce(function(memo, item, index) {
     memo[item] = index;
     return memo;
@@ -70,6 +72,10 @@ var foo = Array.from(nodes, function(node) {
 var bar = foo.map(node => node.getAttribute("id"));
 ```
 
+## Known Limitations
+
+This rule checks callback functions of methods with the given names, *even if* the object which has the method is *not* an array.
+
 ## When Not To Use It
 
 If you don't want to warn about usage of `return` statement in callbacks of array's methods, then it's safe to disable this rule.

docs/rules/block-scoped-var.md

@@ -2,50 +2,32 @@
 
 The `block-scoped-var` rule generates warnings when variables are used outside of the block in which they were defined. This emulates C-style block scope.
 
-```js
-function doSomething() {
-    if (true) {
-        var build = true;
-    }
-
-    console.log(build);
-}
-```
-
 ## Rule Details
 
 This rule aims to reduce the usage of variables outside of their binding context and emulate traditional block scope from other languages. This is to help newcomers to the language avoid difficult bugs with variable hoisting.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint block-scoped-var: 2*/
 
-function doSomething() {
+function doIf() {
     if (true) {
         var build = true;
     }
 
     console.log(build);
 }
-```
 
-```js
-/*eslint block-scoped-var: 2*/
-
-function doSomething() {
+function doIfElse() {
     if (true) {
         var build = true;
     } else {
         var build = false;
     }
 }
-```
 
-```js
-/*eslint block-scoped-var: 2*/
-
-function doAnother() {
+function doTryCatch() {
     try {
         var build = 1;
     } catch (e) {
@@ -54,12 +36,12 @@ function doAnother() {
 }
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint block-scoped-var: 2*/
 
-function doSomething() {
+function doIf() {
     var build;
 
     if (true) {
@@ -68,12 +50,8 @@ function doSomething() {
 
     console.log(build);
 }
-```
-
-```js
-/*eslint block-scoped-var: 2*/
 
-function doSomething() {
+function doIfElse() {
     var build;
 
     if (true) {
@@ -82,6 +60,17 @@ function doSomething() {
         build = false;
     }
 }
+
+function doTryCatch() {
+    var build;
+    var f;
+
+    try {
+        build = 1;
+    } catch (e) {
+        f = build;
+    }
+}
 ```
 
 ## Further Reading

docs/rules/complexity.md

@@ -18,7 +18,7 @@ function a(x) {
 
 This rule is aimed at reducing code complexity by capping the amount of cyclomatic complexity allowed in a program. As such, it will warn when the cyclomatic complexity crosses the configured threshold (default is `20`).
 
-The following patterns are considered problems:
+Examples of **incorrect** code for a maximum of 2:
 
 ```js
 /*eslint complexity: [2, 2]*/
@@ -34,7 +34,7 @@ function a(x) {
 }
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for a maximum of 2:
 
 ```js
 /*eslint complexity: [2, 2]*/
@@ -48,6 +48,8 @@ function a(x) {
 }
 ```
 
+## Options
+
 Optionally, you may specify a `maximum` object property:
 
 ```json
@@ -57,7 +59,7 @@ Optionally, you may specify a `maximum` object property:
 is equivalent to
 
 ```json
-"complexity": [2, {"maximum": 2}]
+"complexity": [2, { "maximum": 2 }]
 ```
 
 ## When Not To Use It

docs/rules/consistent-return.md

@@ -23,7 +23,7 @@ This rule is aimed at ensuring all `return` statements either specify a value or
 
 It excludes constructors which, when invoked with the `new` operator, return the instantiated object if another object is not explicitly returned.  This rule treats a function as a constructor if its name starts with an uppercase letter.
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint consistent-return: 2*/
@@ -54,7 +54,7 @@ function doSomething(condition) {
 }
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule:
 
 ```js
 /*eslint consistent-return: 2*/