From df5f8a9bc1042c13f1969c9fbd8c72eee0662daa Mon Sep 17 00:00:00 2001
From: Tanuj Kanti <86398394+Tanujkanti4441@users.noreply.github.com>
Date: Thu, 11 Apr 2024 23:45:53 +0530
Subject: [PATCH] docs: `paths` and `patterns` difference in
 `no-restricted-imports` (#18273)

* docs: mention paths and pattern difference

* docs: add examples for clarification

* fix typo

* update examples
---
 docs/src/rules/no-restricted-imports.md | 29 +++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/src/rules/no-restricted-imports.md b/docs/src/rules/no-restricted-imports.md
index 2211fd21c2f..f7357c0580c 100644
--- a/docs/src/rules/no-restricted-imports.md
+++ b/docs/src/rules/no-restricted-imports.md
@@ -286,6 +286,31 @@ import { AllowedObject } from "foo";
 
 This is also an object option whose value is an array. This option allows you to specify multiple modules to restrict using `gitignore`-style patterns.
 
+Where `paths` option takes exact import paths, `patterns` option can be used to specify the import paths with more flexibility, allowing for the restriction of multiple modules within the same directory. For example:
+
+```json
+"no-restricted-imports": ["error", {
+  "paths": [{
+    "name": "import-foo",
+  }]
+}]
+```
+
+This configuration restricts import of the `import-foo` module but wouldn't restrict the import of `import-foo/bar` or `import-foo/baz`. You can use `patterns` to restrict both:
+
+```json
+"no-restricted-imports": ["error", {
+    "paths": [{
+      "name": "import-foo",
+    }],
+    "patterns": [{
+      "group": ["import-foo/ba*"],
+    }]
+}]
+```
+
+This configuration restricts imports not just from `import-foo` using `path`, but also `import-foo/bar` and `import-foo/baz` using `patterns`.
+
 Because the patterns follow the `gitignore`-style, if you want to reinclude any particular module this can be done by prefixing a negation (`!`) mark in front of the pattern. (Negated patterns should come last in the array because order is important.)
 
 ```json
@@ -294,7 +319,7 @@ Because the patterns follow the `gitignore`-style, if you want to reinclude any
 }]
 ```
 
-Examples of **incorrect** code for `pattern` option:
+Examples of **incorrect** code for `patterns` option:
 
 ::: incorrect { "sourceType": "module" }
 
@@ -328,7 +353,7 @@ import pick from 'import1/private/someModule';
 
 In this example, `"!import1/private/*"` is not reincluding the modules inside `private` because the negation mark (`!`) does not reinclude the files if it's parent directory is excluded by a pattern. In this case, `import1/private` directory is already excluded by the `import1/*` pattern. (The excluded directory can be reincluded using `"!import1/private"`.)
 
-Examples of **correct** code for `pattern` option:
+Examples of **correct** code for `patterns` option:
 
 ::: correct { "sourceType": "module" }