Describe missing reportedDisables and `reportDescriptionlessDisable…

…s` (#4939)

* 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

* Fix grammar

* Add `<!-- prettier-ignore -->`

* Add `stylelint-disable -- <description>`

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"`:

docs/user-guide/usage/node-api.md

@@ -66,13 +66,21 @@ 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 <rule>` 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 <rule>` comment doesn'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
 

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:
+
+<!-- prettier-ignore -->
+```css
+/* stylelint-disable */
+a {}
+```
+
+<!-- prettier-ignore -->
+```css
+/* stylelint-disable-next-line block-no-empty */
+a {}
+```
+
+But, the following patterns (`stylelint-disable -- <description>`) are _not_ reported:
+
+<!-- prettier-ignore -->
+```css
+/* stylelint-disable -- This violation is ignorable. */
+a {}
+```
+
+<!-- prettier-ignore -->
+```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`