Merge pull request #5851 from scriptdaemon/docs-stylistic-issues-2

Docs: Distinguish examples in rules under Stylistic Issues part 2

docs/rules/func-style.md

@@ -1,22 +1,22 @@
-# Enforce Function Style (func-style)
+# enforce the consistent use of either `function` declarations or expressions (func-style)
 
-There are two ways of defining functions in JavaScript: function declarations and function expressions. Declarations have the `function` keyword first, followed by a name, followed by its arguments and the function body, such as:
+There are two ways of defining functions in JavaScript: `function` declarations and `function` expressions. Declarations contain the `function` keyword first, followed by a name and then its arguments and the function body, for example:
 
 ```js
 function doSomething() {
     // ...
 }
 ```
 
-Equivalent function expressions begin with the `var` keyword, followed by a name, and then the function itself, such as:
+Equivalent function expressions begin with the `var` keyword, followed by a name and then the function itself, such as:
 
 ```js
 var doSomething = function() {
     // ...
 };
 ```
 
-The primary difference between function declarations and function expressions is that declarations are *hoisted* to the top of the scope in which they are defined, which allows you to write code that uses the function before the declaration. For example:
+The primary difference between `function` declarations and `function expressions` is that declarations are *hoisted* to the top of the scope in which they are defined, which allows you to write code that uses the function before its declaration. For example:
 
 ```js
 doSomething();
@@ -26,9 +26,9 @@ function doSomething() {
 }
 ```
 
-Although this code might seem like an error, it actually works fine because JavaScript engines hoist the function declarations to the top of the scope. That means this code is treated as if the declaration came before the invocation.
+Although this code might seem like an error, it actually works fine because JavaScript engines hoist the `function` declarations to the top of the scope. That means this code is treated as if the declaration came before the invocation.
 
-For function expressions, you must define the function before it is used, otherwise it causes an error. Example:
+For `function` expressions, you must define the function before it is used, otherwise it causes an error. Example:
 
 ```js
 doSomething();  // error!
@@ -44,19 +44,22 @@ Due to these different behaviors, it is common to have guidelines as to which st
 
 ## Rule Details
 
-This rule is aimed at enforcing a particular type of function style throughout a JavaScript file, either declarations or expressions. You can specify which you prefer in the configuration.
+This rule enforces a particular type of `function` style throughout a JavaScript file, either declarations or expressions. You can specify which you prefer in the configuration.
 
 ## Options
 
-### "expression"
+This rule has a string option:
 
-This is the default configuration.  It reports an error when function declarations are used instead of function expressions.
+* `"expression"` (default) requires the use of function expressions instead of function declarations
+* `"declaration"` requires the use of function declarations instead of function expressions
 
-```json
-"func-style": ["error", "expression"]
-```
+This rule has an object option for an exception:
+
+* `"allowArrowFunctions": true` (default `false`) allows the use of arrow functions
 
-The following patterns are considered problems:
+### expression
+
+Examples of **incorrect** code for this rule with the default `"expression"` option:
 
 ```js
 /*eslint func-style: ["error", "expression"]*/
@@ -66,7 +69,7 @@ function foo() {
 }
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule with the default `"expression"` option:
 
 ```js
 /*eslint func-style: ["error", "expression"]*/
@@ -76,37 +79,21 @@ var foo = function() {
 };
 ```
 
-### "declaration"
-
-This reports an error if any function expressions are used where function declarations are expected. You can specify to use expressions instead:
-
-```json
-"func-style": ["error", "declaration"]
-```
-
-An additional option object can be added with a property `"allowArrowFunctions"`.  Setting this to `true` will allow arrow functions.
-
-```json
-"func-style": ["error", "declaration", { "allowArrowFunctions": true }]
-```
+### declaration
 
-The following patterns are considered problems:
+Examples of **incorrect** code for this rule with the `"declaration"` option:
 
 ```js
 /*eslint func-style: ["error", "declaration"]*/
 
 var foo = function() {
     // ...
 };
-```
-
-```js
-/*eslint func-style: ["error", "declaration"]*/
 
 var foo = () => {};
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule with the `"declaration"` option:
 
 ```js
 /*eslint func-style: ["error", "declaration"]*/
@@ -121,13 +108,16 @@ SomeObject.foo = function() {
 };
 ```
 
+### allowSingleLine
+
+Examples of additional **correct** code for this rule with the `"declaration", { "allowSingleLine": true }` options:
+
 ```js
 /*eslint func-style: ["error", "declaration", { "allowArrowFunctions": true }]*/
 
 var foo = () => {};
 ```
 
-
 ## When Not To Use It
 
 If you want to allow developers to each decide how they want to write functions on their own, then you can disable this rule.

docs/rules/id-blacklist.md

@@ -1,41 +1,40 @@
-# Blacklist certain identifiers to prevent them being used (id-blacklist)
+# disallow specified identifiers (id-blacklist)
 
 > "There are only two hard things in Computer Science: cache invalidation and naming things." — Phil Karlton
 
-Bad names can lead to hard to decipher code. Using generic names, such as `data` don't infer much about the code and the values it receives. This rule allows you to configure a blacklist of bad identifier names, that you don't want to see in your code.
+Bad names can lead to hard-to-decipher code. Generic names, such as `data`, don't infer much about the code and the values it receives. This rule allows you to configure a blacklist of bad identifier names, that you don't want to see in your code.
 
 ## Rule Details
 
-This rule compares assignments and function definitions to a provided list of identifier names. If the identifier is present in the list, it will return an error.
+This rule disallows specified identifiers in assignments and `function` definitions.
 
 This rule will catch blacklisted identifiers that are:
 
 - variable declarations
 - function declarations
-- object properties
+- object properties assigned to during object creation
 
 It will not catch blacklisted identifiers that are:
 
 - function calls (so you can still use functions you do not have control over)
 - object properties (so you can still use objects you do not have control over)
 
-
 ## Options
 
-This rule needs a a set of identifier names to blacklist, like so:
+The rule takes one or more strings as options: the names of restricted identifiers.
+
+For example, to restrict the use of common generic identifiers:
 
 ```json
 {
-    "rules": {
-        "id-blacklist": ["error", "data", "err", "e", "cb", "callback"]
-    }
+    "id-blacklist": ["error", "data", "err", "e", "cb", "callback"]
 }
 ```
 
-For the rule in this example, the following patterns are considered problems:
+Examples of **incorrect** code for this rule with sample `"data", "callback"` restricted identifiers:
 
 ```js
-/*eslint id-blacklist: ["error", "data", "err", "e", "cb", "callback"] */
+/*eslint id-blacklist: ["error", "data", "callback"] */
 
 var data = {...};
 
@@ -52,10 +51,10 @@ var itemSet = {
 };
 ```
 
-The following patterns are not considered problems:
+Examples of **correct** code for this rule with sample `"data", "callback"` restricted identifiers:
 
 ```js
-/*eslint id-blacklist: ["error", "data", "err", "e", "cb", "callback"] */
+/*eslint id-blacklist: ["error", "data", "callback"] */
 
 var encodingOptions = {...};
 
@@ -71,11 +70,11 @@ var itemSet = {
     entities: [...]
 };
 
-callback()  // all function calls are ignored
+callback(); // all function calls are ignored
 
-foo.callback() // all function calls are ignored
+foo.callback(); // all function calls are ignored
 
-foo.data // all property names that are not assignments are ignored
+foo.data; // all property names that are not assignments are ignored
 ```
 
 ## When Not To Use It