docs: explain how users can customize linting behavior of rules

docs/users/configuration.md

@@ -57,3 +57,71 @@ triggered.rules = [
   DisableSyntax
 ]
 ```
+
+## Overriding the linting behavior
+
+By default, only lints raised with `LintSeverity.Error` will result in a
+non-zero exit code. To force Scalafix to return a non-zero exit code for other
+diagnostics, it is possible to promote non-error diagnostics to the error level
+via `lint.error`, without changing the rule(s).
+
+This key accepts as value either
+* a string, interpreted as a regular expression to match diagnostics using the
+  `<rule_name>.<lint_id>` pattern,
+* a list of strings, treated as several regular expressions like above,
+* an object, with `include` and `exclude` attributes, each treated as regular
+  expressions like above.
+
+As an example, to force all linter reports to trigger an error, except for unused
+suppressions, any of the 3 configuration files below can be used, as they are
+effectively equivalent.
+
+```scala
+// .scalafix.conf
+lint.error = "^((?!UnusedScalafixSuppression).)*$"
+```
+
+```scala
+// .scalafix.conf
+lint.error = [
+  "^((?!UnusedScalafixSuppression).)*$"
+]
+```
+
+```scala
+// .scalafix.conf
+lint.error = {
+  includes = ".*"
+  excludes = "UnusedScalafixSuppression"
+}
+```
+
+Similarly, diagnostics can be controlled through `lint.ignore`, `lint.info`,
+and `lint.warning` which respectively suppress matching diagnostics, force them
+to be at info level, and force them to be at warning level.
+
+## Passing configuration as CLI arguments
+
+It is possible to pass configuration flags with scalar values as CLI arguments,
+overriding any potential value set in the configuration file, by prefixing the
+qualified name of each attribute with `--settings.`.
+
+For example, the configuration file below
+
+```scala
+// .scalafix.conf
+DisableSyntax {
+  noFinalize = true
+}
+lint.error.includes = ".*"
+lint.error.excludes = "UnusedScalafixSuppression"
+```
+
+is equivalent to the following CLI arguments
+
+```
+scalafix ... \
+  --settings.DisableSyntax.noFinalize=true \
+  --settings.lint.error.includes=.* \
+  --settings.lint.error.excludes=UnusedScalafixSuppression
+```

docs/users/suppression.md

@@ -3,8 +3,15 @@ id: suppression
 title: Suppressing rules
 ---
 
-Sometimes you need to ignore the output from Scalafix. Scalafix provides two
-methods for suppressing rules: annotations and comments.
+Sometimes you need to ignore the output from Scalafix.
+
+For linters, and for linters only, an easy way to achieve that is to
+selectively ignore some diagnostics via
+[`lint.ignore`](configuration.md#overriding-the-linting-behavior).
+However, this toggle is global, which is rarely what is needed.
+
+Scalafix provides two methods for suppressing rules in source code: annotations
+and comments.
 
 - Annotations: great for disabling regions of code but some source code
   locations are impossible to annotate.