From 4f7c9dcce56ad02aae72613c55db68e579facc3e Mon Sep 17 00:00:00 2001 From: Masafumi Koba <473530+ybiquitous@users.noreply.github.com> Date: Tue, 15 Sep 2020 00:41:56 +0900 Subject: [PATCH 1/4] Describe missing `reportedDisables` and `reportDescriptionlessDisables` This documentation change adds missing descriptions about: - the `reportedDisables` property in the returned data of Node.js API - the `reportDescriptionlessDisables` option (flag) Close #4912 --- docs/user-guide/configure.md | 4 ++- docs/user-guide/usage/node-api.md | 10 ++++++- docs/user-guide/usage/options.md | 43 +++++++++++++++++++++++++++++-- 3 files changed, 53 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/configure.md b/docs/user-guide/configure.md index 4811b02908..b3455dbe08 100644 --- a/docs/user-guide/configure.md +++ b/docs/user-guide/configure.md @@ -137,7 +137,7 @@ Reporters may use these severity levels to display violations or exit the proces ### `reportDisables` -You can set the `reportDisables` secondary option to report any disable comments for this rule, effectively disallowing authors to opt out of it. +You can set the `reportDisables` secondary option to report any `stylelint-disable` comments for this rule, effectively disallowing authors to opt out of it. For example: @@ -155,6 +155,8 @@ For example: } ``` +The report is included in the [`reportedDisables`](usage/node-api.md#reporteddisables) property to the returned data of Node.js API. + ## `defaultSeverity` You can set the default severity level for all rules that do not have a severity specified in their secondary options. For example, you can set the default severity to `"warning"`: diff --git a/docs/user-guide/usage/node-api.md b/docs/user-guide/usage/node-api.md index 635b998b0d..f6e67313c6 100644 --- a/docs/user-guide/usage/node-api.md +++ b/docs/user-guide/usage/node-api.md @@ -66,14 +66,22 @@ An array containing all the stylelint result objects (the objects that formatter An object containing the maximum number of warnings and the amount found, e.g. `{ maxWarnings: 0, foundWarnings: 12 }`. +### `reportedDisables` + +An array of objects, one for each source, with tells you which `stylelint-disable` comments for rules enabled [`reportDisables`](../configure.md#reportdisables). + ### `needlessDisables` -An array of objects, one for each source, with tells you which stylelint-disable comments are not blocking a lint violation +An array of objects, one for each source, with tells you which `stylelint-disable` comments are not blocking a lint violation. ### `invalidScopeDisables` An array of objects, one for each source, with tells you which rule in `stylelint-disable ` comment don't exist within the configuration object. +### `descriptionlessDisables` + +An array of objects, one for each source, with tells you which `stylelint-disable` comments without a description. + ## Syntax errors `stylelint.lint()` does not reject the Promise when your CSS contains syntax errors. diff --git a/docs/user-guide/usage/options.md b/docs/user-guide/usage/options.md index c4df930e30..bd26bac146 100644 --- a/docs/user-guide/usage/options.md +++ b/docs/user-guide/usage/options.md @@ -141,7 +141,7 @@ You can use this option to see what your linting results would be like without t CLI flags: `--report-needless-disables, --rd` -Produce a report to clean up your codebase, keeping only the stylelint-disable comments that serve a purpose. +Produce a report to clean up your codebase, keeping only the `stylelint-disable` comments that serve a purpose. If needless disables are found, the: @@ -152,13 +152,52 @@ If needless disables are found, the: CLI flags: `--report-invalid-scope-disables, --risd` -Produce a report of the stylelint-disable comments that used for rules that don't exist within the configuration object. +Produce a report of the `stylelint-disable` comments that used for rules that don't exist within the configuration object. If invalid scope disables are found, the: - CLI process exits with code `2` - Node.js API adds a [`invalidScopeDisables`](node-api.md#invalidscopedisables) property to the returned data +## `reportDescriptionlessDisables` + +CLI flags: `--report-descriptionless-disables, --rdd` + +Produce a report of the `stylelint-disable` comments without a description. + +For example, when the configuration `{ block-no-empty: true }` is given, the following patterns are reported: + +```css +/* stylelint-disable */ +a { +} +``` + +```css +/* stylelint-disable-next-line block-no-empty */ +a { +} +``` + +But, the following patterns are _not_ reported: + +```css +/* stylelint-disable -- This violation is ignorable. */ +a { +} +``` + +```css +/* stylelint-disable-next-line block-no-empty -- This violation is ignorable. */ +a { +} +``` + +If descriptionless disables are found, the: + +- CLI process exits with code `2` +- Node.js API adds a [`descriptionlessDisables`](node-api.md#descriptionlessdisables) property to the returned data + ## `codeFilename` CLI flag: `--stdin-filename` From 7d34f924e3a11de916a5c7a6bbcdd0661ddc44cb Mon Sep 17 00:00:00 2001 From: Masafumi Koba <473530+ybiquitous@users.noreply.github.com> Date: Tue, 15 Sep 2020 00:53:18 +0900 Subject: [PATCH 2/4] Fix grammar --- docs/user-guide/usage/node-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/usage/node-api.md b/docs/user-guide/usage/node-api.md index f6e67313c6..902b0e4cae 100644 --- a/docs/user-guide/usage/node-api.md +++ b/docs/user-guide/usage/node-api.md @@ -76,7 +76,7 @@ An array of objects, one for each source, with tells you which `stylelint-disabl ### `invalidScopeDisables` -An array of objects, one for each source, with tells you which rule in `stylelint-disable ` comment don't exist within the configuration object. +An array of objects, one for each source, with tells you which rule in a `stylelint-disable ` comment doesn't exist within the configuration object. ### `descriptionlessDisables` From 6e0976335f9f8c803a609b3e3bf4037ec0a4b6ef Mon Sep 17 00:00:00 2001 From: Masafumi Koba <473530+ybiquitous@users.noreply.github.com> Date: Tue, 15 Sep 2020 00:55:57 +0900 Subject: [PATCH 3/4] Add `` --- docs/user-guide/usage/options.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/user-guide/usage/options.md b/docs/user-guide/usage/options.md index bd26bac146..a9181c9a1c 100644 --- a/docs/user-guide/usage/options.md +++ b/docs/user-guide/usage/options.md @@ -167,30 +167,30 @@ Produce a report of the `stylelint-disable` comments without a description. For example, when the configuration `{ block-no-empty: true }` is given, the following patterns are reported: + ```css /* stylelint-disable */ -a { -} +a {} ``` + ```css /* stylelint-disable-next-line block-no-empty */ -a { -} +a {} ``` But, the following patterns are _not_ reported: + ```css /* stylelint-disable -- This violation is ignorable. */ -a { -} +a {} ``` + ```css /* stylelint-disable-next-line block-no-empty -- This violation is ignorable. */ -a { -} +a {} ``` If descriptionless disables are found, the: From df06150fe59480e4e089b5c07556669827374525 Mon Sep 17 00:00:00 2001 From: Masafumi Koba <473530+ybiquitous@users.noreply.github.com> Date: Tue, 15 Sep 2020 00:57:40 +0900 Subject: [PATCH 4/4] Add `stylelint-disable -- ` --- docs/user-guide/usage/options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/usage/options.md b/docs/user-guide/usage/options.md index a9181c9a1c..5676c715dc 100644 --- a/docs/user-guide/usage/options.md +++ b/docs/user-guide/usage/options.md @@ -179,7 +179,7 @@ a {} a {} ``` -But, the following patterns are _not_ reported: +But, the following patterns (`stylelint-disable -- `) are _not_ reported: ```css