Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Add Rules page intro and content tweaks #16523

Merged
merged 3 commits into from Nov 16, 2022
Merged

docs: Add Rules page intro and content tweaks #16523

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a7d9a38
docs: add Rules page intro and content tweaks
bpmutter Nov 9, 2022
85e97f9
Add rules link
bpmutter Nov 13, 2022
b1317dd
Apply suggestions from code review
bpmutter Nov 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
30 changes: 21 additions & 9 deletions docs/src/user-guide/configuring/rules.md
View file
Open in desktop
Expand Up @@ -9,9 +9,13 @@ eleventyNavigation:

---

## Configuring Rules
Rules are the core building block of ESLint. A rule validates if your code meets a certain expectation, and what to do if it does not meet that expectation. Rules can also contain additional configuration options specific to that rule.

ESLint comes with a large number of built-in rules and you can add more rules through plugins. You can modify which rules your project uses either using configuration comments or configuration files. To change a rule setting, you must set the rule ID equal to one of these values:
ESLint comes with a large number of [built-in rules](../../rules/) and you can add more rules through plugins. You can modify which rules your project uses with either configuration comments or configuration files.

## Rule Settings
bpmutter marked this conversation as resolved.
Show resolved Hide resolved

To change a rule setting, you must set the rule ID equal to one of these values:
bpmutter marked this conversation as resolved.
Show resolved Hide resolved

* `"off"` or `0` - turn the rule off
* `"warn"` or `1` - turn the rule on as a warning (doesn't affect exit code)
Expand Down Expand Up @@ -41,6 +45,8 @@ If a rule has additional options, you can specify them using array literal synta

This comment specifies the "double" option for the [`quotes`](../../rules/quotes) rule. The first item in the array is always the rule severity (number or string).

#### Configuration Comment Descriptions

Configuration comments can include descriptions to explain why the comment is necessary. The description must occur after the configuration and is separated from the configuration by two or more consecutive `-` characters. For example:

```js
Expand Down Expand Up @@ -86,7 +92,11 @@ rules:
- double
```

To configure a rule which is defined within a plugin you have to prefix the rule ID with the plugin name and a `/`. For example:
## Rules from Plugins

To configure a rule which is defined within a plugin you have to prefix the rule ID with the plugin name and `/`.
bpmutter marked this conversation as resolved.
Show resolved Hide resolved

In a configuration file, for example:

```json
{
Expand Down Expand Up @@ -117,7 +127,9 @@ rules:
plugin1/rule1: error
```

In these configuration files, the rule `plugin1/rule1` comes from the plugin named `plugin1`. You can also use this format with configuration comments, such as:
In these configuration files, the rule `plugin1/rule1` comes from the plugin named `plugin1`.
bpmutter marked this conversation as resolved.
Show resolved Hide resolved

You can also use this format with configuration comments, such as:

```js
/* eslint "plugin1/rule1": "error" */
Expand All @@ -129,7 +141,7 @@ In these configuration files, the rule `plugin1/rule1` comes from the plugin nam

### Using configuration comments

To temporarily disable rule warnings in your file, use block comments in the following format:
To disable rule warnings in a part of a file, use block comments in the following format:

```js
/* eslint-disable */
Expand All @@ -150,7 +162,7 @@ console.log('bar');
/* eslint-enable no-alert, no-console */
```

**Note:** `/* eslint-enable */` without any specific rules listed will cause all disabled rules to be re-enabled.
**Note:** `/* eslint-enable */` without any specific rules listed causes all disabled rules to be re-enabled.

To disable rule warnings in an entire file, put a `/* eslint-disable */` block comment at the top of the file:

Expand Down Expand Up @@ -236,7 +248,7 @@ foo(); /* eslint-disable-line example/rule-name */

#### Comment descriptions

Configuration comments can include descriptions to explain why the comment is necessary. The description must come after the configuration and needs to be separated from the configuration by two or more consecutive `-` characters. For example:
Configuration comments can include descriptions to explain why disabling or re-enabling the rule is necessary. The description must come after the configuration and needs to be separated from the configuration by two or more consecutive `-` characters. For example:

```js
// eslint-disable-next-line no-console -- Here's a description about why this configuration is necessary.
Expand Down Expand Up @@ -269,7 +281,7 @@ To disable rules inside of a configuration file for a group of files, use the `o

### Disabling Inline Comments

To disable all inline config comments, use the `noInlineConfig` setting. For example:
To disable all inline config comments, use the `noInlineConfig` setting in your configuration file. For example:

```json
{
Expand All @@ -278,7 +290,7 @@ To disable all inline config comments, use the `noInlineConfig` setting. For exa
}
```

This setting is similar to [--no-inline-config](../command-line-interface#--no-inline-config) CLI option.
You can also use the [--no-inline-config](../command-line-interface#--no-inline-config) CLI option to disable rule comments, in addition to other in-line configuration.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can also use the [--no-inline-config](../command-line-interface#--no-inline-config) CLI option to disable rule comments, in addition to other in-line configuration.
You can also use the [--no-inline-config](../command-line-interface#--no-inline-config) CLI option to disable rule comments, in addition to other in-line configurations.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe the singular is correct here but will let @bpmutter comment.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, this one seems tricky. Grammarly shows plural

Screenshot 2022-11-15 at 7 17 35 AM

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also feel configuration to be correct here? as we have only one configuration?

Copy link
Member

@amareshsm amareshsm Nov 15, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In addition to other which makes it plural.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@harish-sethuraman only one configuration can pls you brief me?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this place we were meaning inline-config. I guess we specify multiple inline-configs as one inline configuration? (/* eslint indent: "error", curly: "error" */)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

generally the word 'configuration' is only singular - https://www.wordhippo.com/what-is/the-plural-of/configuration.html

'configurations' usually only when there are multiple different sets of configurations.

in this case, i think both could be correct. but singular reads better to me.


#### Report unused `eslint-disable` comments

Expand Down