docs: add docs

packages/eslint-plugin/docs/rules/no-unused-vars.md

@@ -4,4 +4,109 @@ Variables that are declared and not used anywhere in the code are most likely an
 
 ## Rule Details
 
-// TODO
+This rule leverages the typescript compiler's unused variable checks to report. This means that with all rule options set to `false`, it should report the same errors as if you used both the `noUnusedLocals` and `noUnusedParameters` compiler options.
+
+This rule is vastly different to, and maintains no compatability with the base eslint version of the rule.
+
+**_NOTE:_** you must disable the base rule as it can report incorrect errors
+
+```json
+{
+  "no-unused-vars": "off",
+  "@typescript-eslint/no-unused-vars": ["error"]
+}
+```
+
+## Supported Nodes
+
+This rule supports checks on the following features:
+
+- Declarations:
+  - `var` / `const` / `let`
+  - `function`
+  - `class`
+  - `enum`
+  - `interface`
+  - `type`
+- Class methods
+- Class properties and parameter properties
+- Function parameters
+- Generic type parameters
+- Import statements
+
+## Options
+
+```ts
+type Options = {
+  ignoredNamesRegex?: string | boolean;
+  ignoreArgsIfArgsAfterAreUsed?: boolean;
+};
+```
+
+### ignoredNamesRegex
+
+This option accepts a regex string to match names against.
+Any matched names will be ignored and have no errors reported.
+If you set it to false, it will never ignore any names.
+
+The default value is `'^_'` (i.e. matches any name prefixed with an underscore).
+
+Examples of valid code with `{ variables: { ignoredNamesRegex: '^_' } }`.
+
+```ts
+const _unusedVar = 'unused';
+class _Unused {
+  private _unused = 1;
+  private _unusedMethod() {}
+}
+function _unusedFunction() {}
+enum _UnusedEnum {
+  a = 1,
+}
+interface _UnusedInterface {}
+type _UnusedType = {};
+```
+
+**_NOTE:_** The typescript compiler automatically ignores imports, function arguments, type parameter declarations, and object destructuring variables prefixed with an underscore.
+As this is hard-coded into the compiler, we cannot change this.
+
+Examples of valid code based on the unchangable compiler settings
+
+```ts
+import _UnusedDefault, { _UnusedNamed } from 'foo';
+export function foo(_unusedProp: string) {}
+export class Foo<_UnusedGeneric> {}
+const { prop: _unusedDesctructure } = foo;
+```
+
+## ignoreArgsIfArgsAfterAreUsed
+
+When true, this option will ignore unused function arguments if the arguments proceeding arguments are used.
+
+Examples of invalid code with `{ ignoreArgsIfArgsAfterAreUsed: false }`
+
+```ts
+function foo(unused: string, used: number) {
+  console.log(used);
+}
+
+class Foo {
+  constructor(unused: string, public used: number) {
+    console.log(used);
+  }
+}
+```
+
+Examples of valid code with `{ ignoreArgsIfArgsAfterAreUsed: true }`
+
+```ts
+function foo(unused: string, used: number) {
+  console.log(used);
+}
+
+class Foo {
+  constructor(unused: string, public used: number) {
+    console.log(used);
+  }
+}
+```