Merge pull request #5903 from eslint/docs-possible-errors-1

Docs: Describe options in rules under Possible Errors part 1

docs/rules/comma-dangle.md

@@ -1,4 +1,4 @@
-# Disallow or Enforce Dangling Commas (comma-dangle)
+# require or disallow trailing commas (comma-dangle)
 
 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.
 
@@ -17,16 +17,16 @@ This rule enforces consistent use of trailing commas in object and array literal
 
 ## Options
 
-This rule takes one argument, which can be one of the following options:
+This rule has a string option:
 
-- `"never"` - warn whenever a trailing comma is detected. The default value of this option is `"never"`.
-- `"always"` - warn whenever a missing comma is detected.
-- `"always-multiline"` - warn if there is a missing trailing comma on arrays or objects that span multiple lines, and warns if there is a trailing comma present on single line arrays or objects.
-- `"only-multiline"` - warn whenever a trailing comma is detected on single line nodes.
+* `"never"` (default) disallows trailing commas
+* `"always"` requires trailing commas
+* `"always-multiline"` requires trailing commas when the last element or property is in a *different* line than the closing `]` or `}` and disallows trailing commas when the last element or property is on the *same* line as the closing `]` or `}`
+* `"only-multiline"` allows (but does not require) trailing commas when the last element or property is in a *different* line than the closing `]` or `}` and disallows trailing commas when the last element or property is on the *same* line as the closing `]` or `}`
 
 ### never
 
-Examples of **incorrect** code for the default `"never"` option:
+Examples of **incorrect** code for this rule with the default `"never"` option:
 
 ```js
 /*eslint comma-dangle: ["error", "never"]*/
@@ -44,7 +44,7 @@ foo({
 });
 ```
 
-Examples of **correct** code for the default `"never"` option:
+Examples of **correct** code for this rule with the default `"never"` option:
 
 ```js
 /*eslint comma-dangle: ["error", "never"]*/
@@ -64,7 +64,7 @@ foo({
 
 ### always
 
-Examples of **incorrect** code for the `"always"` option:
+Examples of **incorrect** code for this rule with the `"always"` option:
 
 ```js
 /*eslint comma-dangle: ["error", "always"]*/
@@ -82,7 +82,7 @@ foo({
 });
 ```
 
-Examples of **correct** code for the `"always"` option:
+Examples of **correct** code for this rule with the `"always"` option:
 
 ```js
 /*eslint comma-dangle: ["error", "always"]*/
@@ -102,7 +102,7 @@ foo({
 
 ### always-multiline
 
-Examples of **incorrect** code for the `"always-multiline"` option:
+Examples of **incorrect** code for this rule with the `"always-multiline"` option:
 
 ```js
 /*eslint comma-dangle: ["error", "always-multiline"]*/
@@ -130,7 +130,7 @@ foo({
 });
 ```
 
-Examples of **correct** code for the `"always-multiline"` option:
+Examples of **correct** code for this rule with the `"always-multiline"` option:
 
 ```js
 /*eslint comma-dangle: ["error", "always-multiline"]*/
@@ -159,7 +159,7 @@ foo({
 
 ### only-multiline
 
-Examples of **incorrect** code for the `"only-multiline"` option:
+Examples of **incorrect** code for this rule with the `"only-multiline"` option:
 
 ```js
 /*eslint comma-dangle: ["error", "only-multiline"]*/
@@ -173,7 +173,7 @@ var arr = [1,
 
 ```
 
-Examples of **correct** code for the `"only-multiline"` option:
+Examples of **correct** code for this rule with the `"only-multiline"` option:
 
 ```js
 /*eslint comma-dangle: ["error", "only-multiline"]*/

docs/rules/no-cond-assign.md

@@ -1,4 +1,4 @@
-# Disallow Assignment in Conditional Statements (no-cond-assign)
+# disallow assignment operators in conditional statements (no-cond-assign)
 
 In conditional statements, it is very easy to mistype a comparison operator (such as `==`) as an assignment operator (such as `=`). For example:
 
@@ -13,20 +13,18 @@ There are valid reasons to use assignment operators in conditional statements. H
 
 ## Rule Details
 
-This rule is aimed at eliminating ambiguous assignments in `for`, `if`, `while`, and `do...while` conditional statements.
+This rule disallows ambiguous assignment operators in test conditions of `if`, `for`, `while`, and `do...while` statements.
 
 ## Options
 
-The rule takes one option, a string, which must contain one of the following values:
+This rule has a string option:
 
-* `except-parens` (default): Disallow assignments unless they are enclosed in parentheses.
-* `always`: Disallow all assignments.
+* `"except-parens"` (default) allows assignments in test conditions *only if* they are enclosed in parentheses (for example, to allow reassigning a variable in the test of a `while` or `do...while` loop)
+* `"always"` disallows all assignments in test conditions
 
 ### except-parens
 
-The default `"except-parens"` option disallows assignment expressions unless they are enclosed in parentheses. It allows common patterns, such as reassigning a value in the condition of a `while` or `do...while` loop.
-
-Examples of **incorrect** code for the default `"except-parens"` option:
+Examples of **incorrect** code for this rule with the default `"except-parens"` option:
 
 ```js
 /*eslint no-cond-assign: "error"*/
@@ -46,7 +44,7 @@ function setHeight(someNode) {
 }
 ```
 
-Examples of **correct** code for the default `"except-parens"` option:
+Examples of **correct** code for this rule with the default `"except-parens"` option:
 
 ```js
 /*eslint no-cond-assign: "error"*/
@@ -76,9 +74,7 @@ function setHeight(someNode) {
 
 ### always
 
-The `"always"` option disallows assignment expressions in the test of a conditional statement.
-
-Examples of **incorrect** code for the `"always"` option:
+Examples of **incorrect** code for this rule with the `"always"` option:
 
 ```js
 /*eslint no-cond-assign: ["error", "always"]*/
@@ -114,7 +110,7 @@ function setHeight(someNode) {
 }
 ```
 
-Examples of **correct** code for the `"always"` option:
+Examples of **correct** code for this rule with the `"always"` option:
 
 ```js
 /*eslint no-cond-assign: ["error", "always"]*/

docs/rules/no-console.md

@@ -1,4 +1,4 @@
-# Disallow Use of console (no-console)
+# disallow the use of `console` (no-console)
 
 In JavaScript that is designed to be executed in the browser, it's considered a best practice to avoid using methods on `console`. Such messages are considered to be for debugging purposes and therefore not suitable to ship to the client. In general, calls using `console` should be stripped before being pushed to production.
 
@@ -7,18 +7,18 @@ console.log("Made it here.");
 console.error("That shouldn't have happened.");
 ```
 
-
 ## Rule Details
 
-This rule is aimed at eliminating unwanted `console` references from your JavaScript. As such, it warns whenever it sees `console` used as an identifier in code.
+This rule disallows calls to methods of the `console` object.
 
 Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-console: "error"*/
 
-console.log("Hello world!");
-console.error("Something bad happened.");
+console.log("Log a debug level message.");
+console.warn("Log a warn level message.");
+console.error("Log an error level message.");
 ```
 
 Examples of **correct** code for this rule:
@@ -32,16 +32,17 @@ Console.log("Hello world!");
 
 ## Options
 
-This rule supports the following options:
+This rule has an object option for exceptions:
+
+* `"allow"` has an array of strings which are allowed methods of the `console` object
 
-`allow`: The list of console operations to be used as exceptions to the rule. For example:
+Examples of additional **correct** code for this rule with a sample `{ "allow": ["warn", "error"] }` option:
 
 ```js
 /*eslint no-console: ["error", { allow: ["warn", "error"] }] */
 
-console.log("this will be considered a problem");
-console.warn("this will not be considered a problem");
-console.error("this will not be considered a problem");
+console.warn("Log a warn level message.");
+console.error("Log an error level message.");
 ```
 
 ## When Not To Use It

docs/rules/no-constant-condition.md

@@ -1,18 +1,16 @@
-# Disallow use of constant expressions in conditions (no-constant-condition)
+# disallow constant expressions in conditions (no-constant-condition)
 
-Comparing a literal expression in a condition is usually a typo or development trigger for a specific behavior.
+A constant expression (for example, a literal) as a test condition might be a typo or development trigger for a specific behavior. For example, the following code looks as if it is not ready for production.
 
 ```js
 if (false) {
     doSomethingUnfinished();
 }
 ```
 
-This pattern is most likely an error and should be avoided.
-
 ## Rule Details
 
-The rule is aimed at preventing a constant expression in the test of:
+This rule disallows constant expressions in the test condition of:
 
 * `if`, `for`, `while`, or `do...while` statement
 * `?:` ternary expression
@@ -26,11 +24,11 @@ if (false) {
     doSomethingUnfinished();
 }
 
-for (;true;) {
+for (;-2;) {
     doSomethingForever();
 }
 
-while (-2) {
+while (typeof x) {
     doSomethingForever();
 }
 
@@ -41,15 +39,6 @@ do{
 var result = 0 ? a : b;
 ```
 
-```js
-/*eslint no-constant-condition: "error"*/
-
-if (typeof x) {
-    doSomething();
-}
-```
-
-
 Examples of **correct** code for this rule:
 
 ```js
@@ -63,7 +52,7 @@ for (;;) {
     doSomethingForever();
 }
 
-while (x) {
+while (typeof x === "undefined") {
     doSomething();
 }
 
@@ -73,11 +62,3 @@ do{
 
 var result = x !== 0 ? a : b;
 ```
-
-```js
-/*eslint no-constant-condition: "error"*/
-
-if (typeof x === 'undefined') {
-    doSomething();
-}
-```

docs/rules/no-control-regex.md

@@ -1,11 +1,10 @@
-# Disallow Controls Characters in Regular Expressions (no-control-regex)
+# disallow control characters in regular expressions (no-control-regex)
 
 Control characters are special, invisible characters in the ASCII range 0-31. These characters are rarely used in JavaScript strings so a regular expression containing these characters is most likely a mistake.
 
 ## Rule Details
 
-This rule is aimed at ensuring all regular expressions don't use control characters.
-
+This rule disallows control characters in regular expressions.
 
 Examples of **incorrect** code for this rule:
 

docs/rules/no-debugger.md

@@ -1,14 +1,31 @@
-# Disallow debugger (no-debugger)
+# disallow the use of `debugger` (no-debugger)
 
 The `debugger` statement is used to tell the executing JavaScript environment to stop execution and start up a debugger at the current point in the code. This has fallen out of favor as a good practice with the advent of modern debugging and development tools. Production code should definitely not contain `debugger`, as it will cause the browser to stop executing code and open an appropriate debugger.
 
+## Rule Details
+
+This rule disallows `debugger` statements.
+
+Example of **incorrect** code for this rule:
+
 ```js
-debugger;
+/*eslint no-debugger: "error"*/
+
+function isTruthy(x) {
+    debugger;
+    return Boolean(x);
+}
 ```
 
-## Rule Details
+Example of **correct** code for this rule:
+
+```js
+/*eslint no-debugger: "error"*/
 
-This rule is aimed at eliminating `debugger` references from your JavaScript. As such, it warns whenever it sees `debugger` used as an identifier in code.
+function isTruthy(x) {
+    return Boolean(x); // set a breakpoint at this line
+}
+```
 
 ## When Not To Use It
 

docs/rules/no-dupe-args.md

@@ -1,11 +1,11 @@
-# No duplicate arguments (no-dupe-args)
+# disallow duplicate arguments in `function` definitions (no-dupe-args)
 
 In strict mode you will receive a `SyntaxError` if a function takes multiple arguments with the same name.
 Outside of strict mode duplicate arguments will mask the value of the first argument.
 
 ## Rule Details
 
-This rule prevents duplicate parameter names in a function.
+This rule disallows duplicate parameters in function definitions.
 
 Examples of **incorrect** code for this rule:
 
@@ -15,6 +15,10 @@ Examples of **incorrect** code for this rule:
 function foo(a, b, a) {
     console.log("which a is it?", a);
 }
+
+var bar = function (a, b, a) {
+    console.log("which a is it?", a);
+};
 ```
 
 Examples of **correct** code for this rule:
@@ -25,8 +29,11 @@ Examples of **correct** code for this rule:
 function foo(a, b, c) {
     console.log(a, b, c);
 }
-```
 
+var bar = function (a, b, c) {
+    console.log(a, b, c);
+};
+```
 
 ## When Not To Use It
 

docs/rules/no-dupe-keys.md

@@ -1,6 +1,6 @@
-# Disallow Duplicate Keys (no-dupe-keys)
+# disallow duplicate keys in object literals (no-dupe-keys)
 
-Creating objects with duplicate keys in objects can cause unexpected behavior in your application. The `no-dupe-keys` rule flags the use of duplicate keys in object literals.
+Multiple properties with the same key in object literals can cause unexpected behavior in your application.
 
 ```js
 var foo = {
@@ -11,7 +11,7 @@ var foo = {
 
 ## Rule Details
 
-This rule is aimed at preventing possible errors and unexpected behavior that might arise from using duplicate keys in object literals. As such, it warns whenever it finds a duplicate key.
+This rule disallows duplicate keys in object literals.
 
 Examples of **incorrect** code for this rule: