docs: clarify depguard configuration

Author: maratori

.golangci.next.reference.yml

@@ -367,34 +367,42 @@ linters-settings:
     #
     # Variables:
     # - File Variables
-    #   you can still use and exclamation mark ! in front of a variable to say not to use it.
-    #   Example !$test will match any file that is not a go test file.
+    #   Use an exclamation mark `!` to negate a variable.
+    #   Example: `!$test` matches any file that is not a go test file.
     #
     #   `$all` - matches all go files
     #   `$test` - matches all go test files
     #
     # - Package Variables
     #
-    #  `$gostd` - matches all of go's standard library (Pulled from `GOROOT`)
+    #   `$gostd` - matches all of go's standard library (Pulled from `GOROOT`)
     #
-    # Default: Only allow $gostd in all files.
+    # Default (applies if no custom rules are defined): Only allow $gostd in all files.
     rules:
       # Name of a rule.
       main:
-        # Used to determine the package matching priority.
-        # There are three different modes: `original`, `strict`, and `lax`.
+        # Defines package matching behavior. Available modes:
+        # - `original`: allowed if it doesn't match the deny list and either matches the allow list or the allow list is empty.
+        # - `strict`: allowed only if it matches the allow list and either doesn't match the deny list or the allow rule is more specific (longer) than the deny rule.
+        # - `lax`: allowed if it doesn't match the deny list or the allow rule is more specific (longer) than the deny rule.
         # Default: "original"
         list-mode: lax
         # List of file globs that will match this list of settings to compare against.
         # Default: $all
         files:
           - "!**/*_a _file.go"
         # List of allowed packages.
+        # Entries can be a variable (starting with $), a string prefix, or an exact match (if ending with $).
+        # Default: []
         allow:
           - $gostd
           - github.com/OpenPeeDeeP
-        # Packages that are not allowed where the value is a suggestion.
+        # List of packages that are not allowed.
+        # Entries can be a variable (starting with $), a string prefix, or an exact match (if ending with $).
+        # Default: []
         deny:
+          - pkg: "math/rand$"
+            desc: use math/rand/v2
           - pkg: "github.com/sirupsen/logrus"
             desc: not allowed
           - pkg: "github.com/pkg/errors"

.golangci.reference.yml

@@ -367,34 +367,42 @@ linters-settings:
     #
     # Variables:
     # - File Variables
-    #   you can still use and exclamation mark ! in front of a variable to say not to use it.
-    #   Example !$test will match any file that is not a go test file.
+    #   Use an exclamation mark `!` to negate a variable.
+    #   Example: `!$test` matches any file that is not a go test file.
     #
     #   `$all` - matches all go files
     #   `$test` - matches all go test files
     #
     # - Package Variables
     #
-    #  `$gostd` - matches all of go's standard library (Pulled from `GOROOT`)
+    #   `$gostd` - matches all of go's standard library (Pulled from `GOROOT`)
     #
-    # Default: Only allow $gostd in all files.
+    # Default (applies if no custom rules are defined): Only allow $gostd in all files.
     rules:
       # Name of a rule.
       main:
-        # Used to determine the package matching priority.
-        # There are three different modes: `original`, `strict`, and `lax`.
+        # Defines package matching behavior. Available modes:
+        # - `original`: allowed if it doesn't match the deny list and either matches the allow list or the allow list is empty.
+        # - `strict`: allowed only if it matches the allow list and either doesn't match the deny list or the allow rule is more specific (longer) than the deny rule.
+        # - `lax`: allowed if it doesn't match the deny list or the allow rule is more specific (longer) than the deny rule.
         # Default: "original"
         list-mode: lax
         # List of file globs that will match this list of settings to compare against.
         # Default: $all
         files:
           - "!**/*_a _file.go"
         # List of allowed packages.
+        # Entries can be a variable (starting with $), a string prefix, or an exact match (if ending with $).
+        # Default: []
         allow:
           - $gostd
           - github.com/OpenPeeDeeP
-        # Packages that are not allowed where the value is a suggestion.
+        # List of packages that are not allowed.
+        # Entries can be a variable (starting with $), a string prefix, or an exact match (if ending with $).
+        # Default: []
         deny:
+          - pkg: "math/rand$"
+            desc: use math/rand/v2
           - pkg: "github.com/sirupsen/logrus"
             desc: not allowed
           - pkg: "github.com/pkg/errors"