From ab36713768f29084c9393d674ad2c717cea9f994 Mon Sep 17 00:00:00 2001
From: Brice Jaglin <bjaglin@gmail.com>
Date: Sun, 1 Sep 2024 02:05:30 +0200
Subject: [PATCH] docs: explain how users can customize linting behavior of
 rules

---
 docs/users/configuration.md | 68 +++++++++++++++++++++++++++++++++++++
 docs/users/suppression.md   | 11 ++++--
 2 files changed, 77 insertions(+), 2 deletions(-)

diff --git a/docs/users/configuration.md b/docs/users/configuration.md
index 51e48cc36..3ee87f800 100644
--- a/docs/users/configuration.md
+++ b/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
+without touching the rules(s) source code, thanks to `lint.error`.
+
+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
+```
diff --git a/docs/users/suppression.md b/docs/users/suppression.md
index d0280b0d1..8d9559057 100644
--- a/docs/users/suppression.md
+++ b/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.