From f6b84525c29d3b991c080e2e55ca2b057b02409e Mon Sep 17 00:00:00 2001 From: Kenneth Williams Date: Sat, 2 Jul 2016 16:20:54 -0700 Subject: [PATCH] Docs: Distinguish examples in rules under Stylistic Issues part 6 (#6567) --- docs/rules/no-trailing-spaces.md | 29 ++--- docs/rules/no-underscore-dangle.md | 41 +++---- docs/rules/no-unneeded-ternary.md | 33 ++--- docs/rules/no-whitespace-before-property.md | 8 +- docs/rules/object-curly-newline.md | 128 ++++---------------- 5 files changed, 79 insertions(+), 160 deletions(-) diff --git a/docs/rules/no-trailing-spaces.md b/docs/rules/no-trailing-spaces.md index c23a2b199eb..0631e9bdb22 100644 --- a/docs/rules/no-trailing-spaces.md +++ b/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; +//••••• ``` diff --git a/docs/rules/no-underscore-dangle.md b/docs/rules/no-underscore-dangle.md index 5d790092584..3e464e98a9b 100644 --- a/docs/rules/no-underscore-dangle.md +++ b/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 }]*/ diff --git a/docs/rules/no-unneeded-ternary.md b/docs/rules/no-unneeded-ternary.md index 8985788ba8e..b2a6b0281dd 100644 --- a/docs/rules/no-unneeded-ternary.md +++ b/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; ``` diff --git a/docs/rules/no-whitespace-before-property.md b/docs/rules/no-whitespace-before-property.md index 693f870fa3f..2aab5975bd0 100644 --- a/docs/rules/no-whitespace-before-property.md +++ b/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"*/ diff --git a/docs/rules/object-curly-newline.md b/docs/rules/object-curly-newline.md index b2861b2a2fd..43ff38c2f82 100644 --- a/docs/rules/object-curly-newline.md +++ b/docs/rules/object-curly-newline.md @@ -1,4 +1,4 @@ -# require or disallow line breaks inside braces (object-curly-newline) +# enforce consistent line breaks inside braces (object-curly-newline) (fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule. @@ -6,41 +6,33 @@ A number of style guides require or disallow line breaks inside of object braces ## Rule Details -This rule enforces consistent line breaks inside braces. -This rule is applied to both object literals and destructuring assignments. +This rule enforces consistent line breaks inside braces of object literals or destructuring assignments. ## Options -```json -{ - "object-curly-newline": ["error", {"multiline": true}] -} -``` - -This rule has options of 4 kinds: +This rule has either a string option: -* `"always"` - requires line breaks always. -* `"never"` - disallows line breaks. -* `{multiline: true}` (default) - requires line breaks if there are line breaks inside properties or between properties. Otherwise, disallows line breaks. -* `{minProperties: }` - requires line breaks if the number of properties is more than the given integer. Otherwise, disallows line breaks. +* `"always"` requires line breaks inside braces +* `"never"` disallows line breaks inside braces -`multiline` and `minProperties` can be combined. +Or an object option: -* `{multiline: true, minProperties: }` - requires line breaks if there are line breaks inside properties or between properties, or if the number of properties is more than the given integer. Otherwise, disallows line breaks. +* `"multiline": true` (default) requires line breaks if there are line breaks inside properties or between properties +* `"minProperties"` requires line breaks if the number of properties is more than the given integer -Also, we can separate configuration for each object literal and destructuring assignment: +You can specify different options for object literals and destructuring assignments: ```json { "object-curly-newline": ["error", { "ObjectExpression": "always", - "ObjectPattern": {"multiline": true} + "ObjectPattern": { "multiline": true } }] } ``` -* `"ObjectExpression"` - configuration for object literals. -* `"ObjectPattern"` - configuration for object patterns of destructuring assignments. +* `"ObjectExpression"` configuration for object literals +* `"ObjectPattern"` configuration for object patterns of destructuring assignments ### always @@ -184,10 +176,10 @@ let {k = function() { ### multiline -Examples of **incorrect** code for this rule with the default `{"multiline": true}` option: +Examples of **incorrect** code for this rule with the default `{ "multiline": true }` option: ```js -/*eslint object-curly-newline: ["error", {"multiline": true}]*/ +/*eslint object-curly-newline: ["error", { "multiline": true }]*/ /*eslint-env es6*/ let a = { @@ -219,10 +211,10 @@ let {k = function() { }} = obj; ``` -Examples of **correct** code for this rule with the default `{"multiline": true}` option: +Examples of **correct** code for this rule with the default `{ "multiline": true }` option: ```js -/*eslint object-curly-newline: ["error", {"multiline": true}]*/ +/*eslint object-curly-newline: ["error", { "multiline": true }]*/ /*eslint-env es6*/ let a = {}; @@ -254,10 +246,10 @@ let { ### minProperties -Examples of **incorrect** code for this rule with the `{"minProperties": 2}` option: +Examples of **incorrect** code for this rule with the `{ "minProperties": 2 }` option: ```js -/*eslint object-curly-newline: ["error", {"minProperties": 2}]*/ +/*eslint object-curly-newline: ["error", { "minProperties": 2 }]*/ /*eslint-env es6*/ let a = { @@ -289,10 +281,10 @@ let { } = obj; ``` -Examples of **correct** code for this rule with the `{"minProperties": 2}` option: +Examples of **correct** code for this rule with the `{ "minProperties": 2 }` option: ```js -/*eslint object-curly-newline: ["error", {"minProperties": 2}]*/ +/*eslint object-curly-newline: ["error", { "minProperties": 2 }]*/ /*eslint-env es6*/ let a = {}; @@ -322,82 +314,12 @@ let {k = function() { }} = obj; ``` -### multiline and minProperties - -Examples of **incorrect** code for this rule with the `{"multiline": true, "minProperties": 2}` option: - -```js -/*eslint object-curly-newline: ["error", {"multiline": true, "minProperties": 2}]*/ -/*eslint-env es6*/ - -let a = { -}; -let b = { - foo: 1 -}; -let c = {foo: 1, bar: 2}; -let d = {foo: 1, - bar: 2}; -let e = {foo: function() { - dosomething(); -}}; - -let { -} = obj; -let { - f -} = obj; -let {g, h} = obj; -let {i, - j} = obj; -let {k = function() { - dosomething(); -}} = obj; -``` - -Examples of **correct** code for this rule with the `{"multiline": true, "minProperties": 2}` option: - -```js -/*eslint object-curly-newline: ["error", {"multiline": true, "minProperties": 2}]*/ -/*eslint-env es6*/ - -let a = {}; -let b = {foo: 1}; -let c = { - foo: 1, bar: 2 -}; -let d = { - foo: 1, - bar: 2 -}; -let e = { - foo: function() { - dosomething(); - } -}; - -let {} = obj; -let {f} = obj; -let { - g, h -} = obj; -let { - i, - j -} = obj; -let { - k = function() { - dosomething(); - } -} = obj; -``` - -### separating configuration +### ObjectExpression and ObjectPattern -Examples of **incorrect** code for this rule with the `{"ObjectExpression": "always", "ObjectPattern": "never"}` option: +Examples of **incorrect** code for this rule with the `{ "ObjectExpression": "always", "ObjectPattern": "never" }` options: ```js -/*eslint object-curly-newline: ["error", {"ObjectExpression": "always", "ObjectPattern": "never"}]*/ +/*eslint object-curly-newline: ["error", { "ObjectExpression": "always", "ObjectPattern": "never" }]*/ /*eslint-env es6*/ let a = {}; @@ -428,10 +350,10 @@ let { } = obj; ``` -Examples of **correct** code for this rule with the `{"ObjectExpression": "always", "ObjectPattern": "never"}` option: +Examples of **correct** code for this rule with the `{ "ObjectExpression": "always", "ObjectPattern": "never" }` options: ```js -/*eslint object-curly-newline: ["error", {"ObjectExpression": "always", "ObjectPattern": "never"}]*/ +/*eslint object-curly-newline: ["error", { "ObjectExpression": "always", "ObjectPattern": "never" }]*/ /*eslint-env es6*/ let a = [