docs(eslint-plugin): [no-redeclare] clearly document type/variable re…

…declare case (typescript-eslint#2500)

Addresses typescript-eslint#2477

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>

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,
+        },
+      ],
+    },
   ],
 });