Build: display rules’ meta data in their docs (fixes eslint#5774)

Makefile.js

@@ -635,6 +635,11 @@ target.gensite = function(prereleaseVersion) {
         };
     }
 
+    const rules = require(".").linter.getRules();
+
+    const RECOMMENDED_TEXT = "\n\n(recommended) The `\"extends\": \"eslint:recommended\"` property in a configuration file enables this rule.";
+    const FIXABLE_TEXT = "\n\n(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) can automatically fix some of the problems reported by this rule.";
+
     // 4. Loop through all files in temporary directory
     find(TEMP_DIR).forEach(filename => {
         if (test("-f", filename) && path.extname(filename) === ".md") {
@@ -650,6 +655,19 @@ target.gensite = function(prereleaseVersion) {
 
             // 5. Prepend page title and layout variables at the top of rules
             if (path.dirname(filename).indexOf("rules") >= 0) {
+
+                // Find out if the rule requires a special docs portion (e.g. if it is recommended and/or fixable)
+                const rule = rules.get(ruleName);
+                const isRecommended = rule && rule.meta.docs.recommended;
+                const isFixable = rule && rule.meta.fixable;
+
+                // Incorporate the special portion into the documentation content
+                const textSplit = text.split("\n");
+                const ruleHeading = textSplit[0];
+                const ruleDocsContent = textSplit.slice(1).join("\n");
+
+                text = `${ruleHeading}${isRecommended ? RECOMMENDED_TEXT : ""}${isFixable ? FIXABLE_TEXT : ""}\n${ruleDocsContent}`;
+
                 text = `---\ntitle: ${ruleName} - Rules\nlayout: doc\n---\n<!-- Note: No pull requests accepted for this file. See README.md in the root directory for details. -->\n\n${text}`;
             } else {
 

docs/rules/array-bracket-spacing.md

@@ -1,7 +1,5 @@
 # Disallow or enforce spaces inside of brackets (array-bracket-spacing)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 A number of style guides require or disallow spaces between array brackets and other tokens. This rule
 applies to both array literals and destructuring assignments (ECMAScript 6).
 

docs/rules/arrow-body-style.md

@@ -1,7 +1,5 @@
 # Require braces in arrow function body (arrow-body-style)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Arrow functions have two syntactic forms for their function bodies.  They may be defined with a *block* body (denoted by curly braces) `() => { ... }` or with a single expression `() => ...`, whose value is implicitly returned.
 
 ## Rule Details

docs/rules/arrow-parens.md

@@ -1,7 +1,5 @@
 # Require parens in arrow function arguments (arrow-parens)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Arrow functions can omit parentheses when they have exactly one parameter. In all other cases the parameter(s) must
 be wrapped in parentheses. This rule enforces the consistent use of parentheses in arrow functions.
 

docs/rules/arrow-spacing.md

@@ -1,7 +1,5 @@
 # Require space before/after arrow function's arrow (arrow-spacing)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 This rule normalize style of spacing before/after an arrow function's arrow(`=>`).
 
 ```js

docs/rules/block-spacing.md

@@ -1,7 +1,5 @@
 # Disallow or enforce spaces inside of single line blocks (block-spacing)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 ## Rule Details
 
 This rule enforces consistent spacing inside single-line blocks.

docs/rules/brace-style.md

@@ -1,7 +1,5 @@
 # Require Brace Style (brace-style)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Brace style is closely related to [indent style](http://en.wikipedia.org/wiki/Indent_style) in programming and describes the placement of braces relative to their control statement and body. There are probably a dozen, if not more, brace styles in the world.
 
 The *one true brace style* is one of the most common brace styles in JavaScript, in which the opening brace of a block is placed on the same line as its corresponding statement or declaration. For example:

docs/rules/capitalized-comments.md

@@ -1,7 +1,5 @@
 # enforce or disallow capitalization of the first letter of a comment (capitalized-comments)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Comments are useful for leaving information for future developers. In order for that information to be useful and not distracting, it is sometimes desirable for comments to follow a particular style. One element of comment formatting styles is whether the first word of a comment should be capitalized or lowercase.
 
 In general, no comment style is any more or less valid than any others, but many developers would agree that a consistent style can improve a project's maintainability.

docs/rules/comma-dangle.md

@@ -1,7 +1,5 @@
 # require or disallow trailing commas (comma-dangle)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Trailing commas in object literals are valid according to the ECMAScript 5 (and ECMAScript 3!) spec. However, IE8 (when not in IE8 document mode) and below will throw an error when it encounters trailing commas in JavaScript.
 
 ```js

docs/rules/comma-spacing.md

@@ -1,7 +1,5 @@
 # Enforces spacing around commas (comma-spacing)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Spacing around commas improve readability of a list of items. Although most of the style guidelines for languages prescribe adding a space after a comma and not before it, it is subjective to the preferences of a project.
 
 ```js

docs/rules/comma-style.md

@@ -1,7 +1,5 @@
 # Comma style (comma-style)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 The Comma Style rule enforces styles for comma-separated lists. There are two comma styles primarily used in JavaScript:
 
 * The standard style, in which commas are placed at the end of the current line

docs/rules/computed-property-spacing.md

@@ -1,7 +1,5 @@
 # Disallow or enforce spaces inside of computed properties (computed-property-spacing)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 While formatting preferences are very personal, a number of style guides require
 or disallow spaces between computed properties in the following situations:
 

docs/rules/curly.md

@@ -1,7 +1,5 @@
 # Require Following Curly Brace Conventions (curly)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 JavaScript allows the omission of curly braces when a block contains only one statement. However, it is considered by many to be best practice to _never_ omit curly braces around blocks, even when they are optional, because it can lead to bugs and reduces code clarity. So the following:
 
 ```js

docs/rules/dot-location.md

@@ -1,7 +1,5 @@
 # Enforce newline before and after dot (dot-location)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 JavaScript allows you to place newlines before or after a dot in a member expression.
 
 Consistency in placing a newline before or after the dot can greatly increase readability.

docs/rules/dot-notation.md

@@ -1,7 +1,5 @@
 # Require Dot Notation (dot-notation)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 In JavaScript, one can access properties using the dot notation (`foo.bar`) or square-bracket notation (`foo["bar"]`). However, the dot notation is often preferred because it is easier to read, less verbose, and works better with aggressive JavaScript minimizers.
 
 ```js

docs/rules/eol-last.md

@@ -1,7 +1,5 @@
 # require or disallow newline at the end of files (eol-last)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Trailing newlines in non-empty files are a common UNIX idiom. Benefits of
 trailing newlines include the ability to concatenate or append to files as well
 as output files to the terminal without interfering with shell prompts.

docs/rules/eqeqeq.md

@@ -1,7 +1,5 @@
 # Require === and !== (eqeqeq)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 It is considered good practice to use the type-safe equality operators `===` and `!==` instead of their regular counterparts `==` and `!=`.
 
 The reason for this is that `==` and `!=` do type coercion which follows the rather obscure [Abstract Equality Comparison Algorithm](http://www.ecma-international.org/ecma-262/5.1/#sec-11.9.3).

docs/rules/func-call-spacing.md

@@ -1,7 +1,5 @@
 # require or disallow spacing between function identifiers and their invocations (func-call-spacing)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 When calling a function, developers may insert optional whitespace between the function's name and the parentheses that invoke it. The following pairs of function calls are equivalent:
 
 ```js

docs/rules/generator-star-spacing.md

@@ -1,7 +1,5 @@
 # Enforce spacing around the * in generator functions (generator-star-spacing)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Generators are a new type of function in ECMAScript 6 that can return multiple values over time.
 These special functions are indicated by placing an `*` after the `function` keyword.
 

docs/rules/indent.md

@@ -1,7 +1,5 @@
 # enforce consistent indentation (indent)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 There are several common guidelines which require specific indentation of nested blocks and statements, like:
 
 ```js

docs/rules/jsx-quotes.md

@@ -1,7 +1,5 @@
 # enforce the consistent use of either double or single quotes in JSX attributes (jsx-quotes)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 JSX attribute values can contain string literals, which are delimited with single or double quotes.
 
 ```xml

docs/rules/key-spacing.md

@@ -1,7 +1,5 @@
 # enforce consistent spacing between keys and values in object literal properties (key-spacing)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 This rule enforces spacing around the colon in object literal properties. It can verify each property individually, or it can ensure horizontal alignment of adjacent properties in an object literal.
 
 ## Rule Details

docs/rules/keyword-spacing.md

@@ -1,7 +1,5 @@
 # enforce consistent spacing before and after keywords (keyword-spacing)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Keywords are syntax elements of JavaScript, such as `function` and `if`.
 These identifiers have special meaning to the language and so often appear in a different color in code editors.
 As an important part of the language, style guides often refer to the spacing that should be used around keywords.

docs/rules/linebreak-style.md

@@ -1,7 +1,5 @@
 # enforce consistent linebreak style (linebreak-style)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 When developing with a lot of people all having different editors, VCS applications and operating systems it may occur that
 different line endings are written by either of the mentioned (might especially happen when using the windows and mac versions of SourceTree together).
 

docs/rules/lines-around-directive.md

@@ -1,7 +1,5 @@
 # require or disallow newlines around directives (lines-around-directive)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Directives are used in JavaScript to indicate to the execution environment that a script would like to opt into a feature such as `"strict mode"`. Directives are grouped together in a [directive prologue](http://www.ecma-international.org/ecma-262/7.0/#directive-prologue) at the top of either a file or function block and are applied to the scope in which they occur.
 
 ```js

docs/rules/new-parens.md

@@ -1,7 +1,5 @@
 # require parentheses when invoking a constructor with no arguments (new-parens)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 JavaScript allows the omission of parentheses when invoking a function via the `new` keyword and the constructor has no arguments. However, some coders believe that omitting the parentheses is inconsistent with the rest of the language and thus makes code less clear.
 
 ```js

docs/rules/newline-after-var.md

@@ -1,7 +1,5 @@
 # require or disallow an empty line after variable declarations (newline-after-var)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 As of today there is no consistency in separating variable declarations from the rest of the code. Some developers leave an empty line between var statements and the rest of the code like:
 
 ```js

docs/rules/newline-before-return.md

@@ -1,7 +1,5 @@
 # require an empty line before `return` statements (newline-before-return)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 There is no hard and fast rule about whether empty lines should precede `return` statements in JavaScript. However, clearly delineating where a function is returning can greatly increase the readability and clarity of the code. For example:
 
 ```js

docs/rules/no-else-return.md

@@ -2,8 +2,6 @@
 
 If an `if` block contains a `return` statement, the `else` block becomes unnecessary. Its contents can be placed outside of the block.
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 ```js
 function foo() {
     if (x) {

docs/rules/no-extra-bind.md

@@ -1,7 +1,5 @@
 # Disallow unnecessary function binding (no-extra-bind)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 The `bind()` method is used to create functions with specific `this` values and, optionally, binds arguments to specific values. When used to specify the value of `this`, it's important that the function actually use `this` in its function body. For example:
 
 ```js

docs/rules/no-extra-boolean-cast.md

@@ -1,7 +1,5 @@
 # disallow unnecessary boolean casts (no-extra-boolean-cast)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 In contexts such as an `if` statement's test where the result of the expression will already be coerced to a Boolean, casting to a Boolean via double negation (`!!`) or a `Boolean` call is unnecessary. For example, these `if` statements are equivalent:
 
 ```js

docs/rules/no-extra-label.md

@@ -1,7 +1,5 @@
 # Disallow Unnecessary Labels (no-extra-label)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 If a loop contains no nested loops or switches, labeling the loop is unnecessary.
 
 ```js

docs/rules/no-extra-parens.md

@@ -1,7 +1,5 @@
 # disallow unnecessary parentheses (no-extra-parens)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 This rule restricts the use of parentheses to only where they are necessary.
 
 ## Rule Details

docs/rules/no-extra-semi.md

@@ -1,7 +1,5 @@
 # disallow unnecessary semicolons (no-extra-semi)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Typing mistakes and misunderstandings about where semicolons are required can lead to semicolons that are unnecessary. While not technically an error, extra semicolons can cause confusion when reading code.
 
 ## Rule Details

docs/rules/no-floating-decimal.md

@@ -1,7 +1,5 @@
 # Disallow Floating Decimals (no-floating-decimal)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Float values in JavaScript contain a decimal point, and there is no requirement that the decimal point be preceded or followed by a number. For example, the following are all valid JavaScript numbers:
 
 ```js

docs/rules/no-implicit-coercion.md

@@ -1,7 +1,5 @@
 # Disallow the type conversion with shorter notations. (no-implicit-coercion)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 In JavaScript, there are a lot of different ways to convert value types.
 Some of them might be hard to read and understand.
 

docs/rules/no-lonely-if.md

@@ -1,7 +1,5 @@
 # disallow `if` statements as the only statement in `else` blocks (no-lonely-if)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 If an `if` statement is the only statement in the `else` block, it is often clearer to use an `else if` form.
 
 ```js

docs/rules/no-multi-spaces.md

@@ -1,7 +1,5 @@
 # Disallow multiple spaces (no-multi-spaces)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Multiple spaces in a row that are not used for indentation are typically mistakes. For example:
 
 ```js

docs/rules/no-multiple-empty-lines.md

@@ -1,7 +1,5 @@
 # disallow multiple empty lines (no-multiple-empty-lines)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 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

docs/rules/no-regex-spaces.md

@@ -1,7 +1,5 @@
 # disallow multiple spaces in regular expression literals (no-regex-spaces)
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 Regular expressions can be very complex and difficult to understand, which is why it's important to keep them as simple as possible in order to avoid mistakes. One of the more error-prone things you can do with a regular expression is to use more than one space, such as:
 
 ```js

docs/rules/no-spaced-func.md

@@ -2,8 +2,6 @@
 
 This rule was **deprecated** in ESLint v3.3.0 and replaced by the [func-call-spacing](func-call-spacing.md) rule.
 
-(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
-
 While it's possible to have whitespace between the name of a function and the parentheses that execute it, such patterns tend to look more like errors.
 
 ## Rule Details