From bb3e9d66e3821f37633d8c8077d807418c3f6f18 Mon Sep 17 00:00:00 2001
From: Brad Zacher <brad.zacher@gmail.com>
Date: Sat, 5 Sep 2020 21:07:52 -0700
Subject: [PATCH] docs(eslint-plugin): [no-redeclare] clearly document
 type/variable redeclare case (#2500)

Addresses #2477
---
 packages/eslint-plugin/docs/rules/no-redeclare.md | 10 ++++++++++
 .../tests/rules/no-redeclare.test.ts              | 15 +++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/packages/eslint-plugin/docs/rules/no-redeclare.md b/packages/eslint-plugin/docs/rules/no-redeclare.md
index a794250d6f1..d9e7042447d 100644
--- a/packages/eslint-plugin/docs/rules/no-redeclare.md
+++ b/packages/eslint-plugin/docs/rules/no-redeclare.md
@@ -66,4 +66,14 @@ function Baz() {}
 namespace Baz {}
 ```
 
+**Note:** Even with this option set to true, this rule will report if you name a type and a variable the same name. **_This is intentional_**.
+Declaring a variable and a type and a variable the same is usually an accident, and it can lead to hard-to-understand code.
+If you have a rare case where you're intentionally naming a type the same name as a variable, use a disable comment. For example:
+
+```ts
+type something = string;
+// eslint-disable-next-line @typescript-eslint/no-redeclare -- intentionally naming the variable the same as the type
+const something = 2;
+```
+
 <sup>Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-redeclare.md)</sup>
diff --git a/packages/eslint-plugin/tests/rules/no-redeclare.test.ts b/packages/eslint-plugin/tests/rules/no-redeclare.test.ts
index 5a91d1c9822..f227c5ac891 100644
--- a/packages/eslint-plugin/tests/rules/no-redeclare.test.ts
+++ b/packages/eslint-plugin/tests/rules/no-redeclare.test.ts
@@ -627,5 +627,20 @@ namespace A {}
         },
       ],
     },
+    {
+      code: `
+type something = string;
+const something = 2;
+      `,
+      errors: [
+        {
+          messageId: 'redeclared',
+          data: {
+            id: 'something',
+          },
+          line: 3,
+        },
+      ],
+    },
   ],
 });