docs(eslint-plugin): cleanup: standardise extension doc style, mark d…

…eprecated rules (#1887)

packages/eslint-plugin/docs/rules/ban-ts-ignore.md

@@ -4,6 +4,11 @@ This rule has been deprecated in favor of [`ban-ts-comment`](./ban-ts-comment.md
 
 Suppressing TypeScript Compiler Errors can be hard to discover.
 
+## DEPRECATED
+
+This rule has been deprecated in favour of the [`ban-ts-comment`](./ban-ts-comment.md) rule.
+It will be removed in a future version of this plugin.
+
 ## Rule Details
 
 Does not allow the use of `// @ts-ignore` comments.

packages/eslint-plugin/docs/rules/brace-style.md

@@ -3,11 +3,11 @@
 ## Rule Details
 
 This rule extends the base [`eslint/brace-style`](https://eslint.org/docs/rules/brace-style) rule.
-It supports all options and features of the base rule.
+It adds support for `enum`, `interface`, `namespace` and `module` declarations.
 
 ## How to use
 
-```cjson
+```jsonc
 {
   // note you must disable the base rule as it can report incorrect errors
   "brace-style": "off",

packages/eslint-plugin/docs/rules/camelcase.md

@@ -1,135 +1,43 @@
 # Enforce camelCase naming convention (`camelcase`)
 
-When it comes to naming variables, style guides generally fall into one of two
-camps: camelCase (`variableName`) and underscores (`variable_name`). This rule
-focuses on using the camelCase approach. If your style guide calls for
-camelCasing your variable names, then this rule is for you!
+## DEPRECATED
 
-## Rule Details
+This rule has been deprecated in favour of the [`naming-convention`](./naming-convention.md) rule.
+It will be removed in a future version of this plugin.
 
-This rule looks for any underscores (`_`) located within the source code.
-It ignores leading and trailing underscores and only checks those in the middle
-of a variable name. If ESLint decides that the variable is a constant
-(all uppercase), then no warning will be thrown. Otherwise, a warning will be
-thrown. This rule only flags definitions and assignments but not function calls.
-In case of ES6 `import` statements, this rule only targets the name of the
-variable that will be imported into the local module scope.
+## Rule Details
 
-**_This rule was taken from the ESLint core rule `camelcase`._**
-**_Available options and test cases may vary depending on the version of ESLint installed in the system._**
+This rule extends the base [`eslint/camelcase`](https://eslint.org/docs/rules/camelcase) rule.
+It adds support for numerous TypeScript features.
 
-## Options
+## How to use
 
-```cjson
+```jsonc
 {
-    // note you must disable the base rule as it can report incorrect errors
-    "camelcase": "off",
-    "@typescript-eslint/camelcase": ["error", { "properties": "always" }]
+  // note you must disable the base rule as it can report incorrect errors
+  "camelcase": "off",
+  "@typescript-eslint/camelcase": ["error"]
 }
 ```
 
-This rule has an object option:
-
-- `"properties": "never"` (default) does not check property names
-- `"properties": "always"` enforces camelCase style for property names
-- `"genericType": "never"` (default) does not check generic identifiers
-- `"genericType": "always"` enforces camelCase style for generic identifiers
-- `"ignoreDestructuring": false` (default) enforces camelCase style for destructured identifiers
-- `"ignoreDestructuring": true` does not check destructured identifiers
-- `allow` (`string[]`) list of properties to accept. Accept regex.
-
-### properties: "always"
-
-Examples of **incorrect** code for this rule with the default `{ "properties": "always" }` option:
-
-```js
-/*eslint @typescript-eslint/camelcase: "error"*/
-
-import { no_camelcased } from 'external-module';
-
-var my_favorite_color = '#112C85';
-
-function do_something() {
-  // ...
-}
-
-obj.do_something = function() {
-  // ...
-};
+## Options
 
-function foo({ no_camelcased }) {
-  // ...
-}
+See [`eslint/camelcase` options](https://eslint.org/docs/rules/camelcase#options).
+This rule adds the following options:
 
-function foo({ isCamelcased: no_camelcased }) {
-  // ...
+```ts
+interface Options extends BaseCamelcaseOptions {
+  genericType?: 'always' | 'never';
 }
 
-function foo({ no_camelcased = 'default value' }) {
-  // ...
-}
-
-var obj = {
-  my_pref: 1,
+const defaultOptions: Options = {
+  ...baseCamelcaseDefaultOptions,
+  genericType: 'never',
 };
-
-var { category_id = 1 } = query;
-
-var { foo: no_camelcased } = bar;
-
-var { foo: bar_baz = 1 } = quz;
-```
-
-Examples of **correct** code for this rule with the default `{ "properties": "always" }` option:
-
-```js
-/*eslint @typescript-eslint/camelcase: "error"*/
-
-import { no_camelcased as camelCased } from 'external-module';
-
-var myFavoriteColor = '#112C85';
-var _myFavoriteColor = '#112C85';
-var myFavoriteColor_ = '#112C85';
-var MY_FAVORITE_COLOR = '#112C85';
-var foo = bar.baz_boom;
-var foo = { qux: bar.baz_boom };
-
-obj.do_something();
-do_something();
-new do_something();
-
-var { category_id: category } = query;
-
-function foo({ isCamelCased }) {
-  // ...
-}
-
-function foo({ isCamelCased: isAlsoCamelCased }) {
-  // ...
-}
-
-function foo({ isCamelCased = 'default value' }) {
-  // ...
-}
-
-var { categoryId = 1 } = query;
-
-var { foo: isCamelCased } = bar;
-
-var { foo: isCamelCased = 1 } = quz;
 ```
 
-### `properties: "never"`
-
-Examples of **correct** code for this rule with the `{ "properties": "never" }` option:
-
-```js
-/*eslint @typescript-eslint/camelcase: ["error", {properties: "never"}]*/
-
-var obj = {
-  my_pref: 1,
-};
-```
+- `"genericType": "never"` (default) does not check generic identifiers
+- `"genericType": "always"` enforces camelCase style for generic identifiers
 
 ### `genericType: "always"`
 
@@ -225,74 +133,4 @@ class Foo {
 }
 ```
 
-### `ignoreDestructuring: false`
-
-Examples of **incorrect** code for this rule with the default `{ "ignoreDestructuring": false }` option:
-
-```js
-/*eslint @typescript-eslint/camelcase: "error"*/
-
-var { category_id } = query;
-
-var { category_id = 1 } = query;
-
-var { category_id: category_id } = query;
-
-var { category_id: category_alias } = query;
-
-var { category_id: categoryId, ...other_props } = query;
-```
-
-### `ignoreDestructuring: true`
-
-Examples of **incorrect** code for this rule with the `{ "ignoreDestructuring": true }` option:
-
-```js
-/*eslint @typescript-eslint/camelcase: ["error", {ignoreDestructuring: true}]*/
-
-var { category_id: category_alias } = query;
-
-var { category_id, ...other_props } = query;
-```
-
-Examples of **correct** code for this rule with the `{ "ignoreDestructuring": true }` option:
-
-```js
-/*eslint @typescript-eslint/camelcase: ["error", {ignoreDestructuring: true}]*/
-
-var { category_id } = query;
-
-var { category_id = 1 } = query;
-
-var { category_id: category_id } = query;
-```
-
-## allow
-
-Examples of **correct** code for this rule with the `allow` option:
-
-```js
-/*eslint @typescript-eslint/camelcase: ["error", {allow: ["UNSAFE_componentWillMount"]}]*/
-
-function UNSAFE_componentWillMount() {
-  // ...
-}
-```
-
-```js
-/*eslint @typescript-eslint/camelcase: ["error", {allow: ["^UNSAFE_"]}]*/
-
-function UNSAFE_componentWillMount() {
-  // ...
-}
-
-function UNSAFE_componentWillMount() {
-  // ...
-}
-```
-
-## When Not To Use It
-
-If you have established coding standards using a different naming convention (separating words with underscores), turn this rule off.
-
 <sup>Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/camelcase.md)</sup>

packages/eslint-plugin/docs/rules/class-name-casing.md

@@ -2,6 +2,11 @@
 
 This rule enforces PascalCase names for classes and interfaces.
 
+## DEPRECATED
+
+This rule has been deprecated in favour of the [`naming-convention`](./naming-convention.md) rule.
+It will be removed in a future version of this plugin.
+
 ## Rule Details
 
 This rule aims to make it easy to differentiate classes from regular variables at a glance.

packages/eslint-plugin/docs/rules/comma-spacing.md

@@ -7,7 +7,7 @@ It adds support for trailing comma in a types parameters list.
 
 ## How to use
 
-```cjson
+```jsonc
 {
   // note you must disable the base rule as it can report incorrect errors
   "comma-spacing": "off",

packages/eslint-plugin/docs/rules/default-param-last.md

@@ -2,7 +2,8 @@
 
 ## Rule Details
 
-This rule enforces default or optional parameters to be the last of parameters.
+This rule extends the base [`eslint/default-param-last`](https://eslint.org/docs/rules/default-param-last) rule.
+It adds support for optional parameters.
 
 Examples of **incorrect** code for this rule:
 
@@ -38,4 +39,18 @@ class Foo {
 }
 ```
 
+## How to use
+
+```jsonc
+{
+  // note you must disable the base rule as it can report incorrect errors
+  "default-param-last": "off",
+  "@typescript-eslint/default-param-last": ["error"]
+}
+```
+
+## Options
+
+See [`eslint/default-param-last` options](https://eslint.org/docs/rules/default-param-last#options).
+
 <sup>Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/default-param-last.md)</sup>

packages/eslint-plugin/docs/rules/func-call-spacing.md

@@ -1,17 +1,13 @@
 # Require or disallow spacing between function identifiers and their invocations (`func-call-spacing`)
 
-When calling a function, developers may insert optional whitespace between the function’s name and the parentheses that invoke it.
-This rule requires or disallows spaces between the function name and the opening parenthesis that calls it.
-
 ## Rule Details
 
 This rule extends the base [`eslint/func-call-spacing`](https://eslint.org/docs/rules/func-call-spacing) rule.
-It supports all options and features of the base rule.
-This version adds support for generic type parameters on function calls.
+It adds support for generic type parameters on function calls.
 
 ## How to use
 
-```cjson
+```jsonc
 {
   // note you must disable the base rule as it can report incorrect errors
   "func-call-spacing": "off",

packages/eslint-plugin/docs/rules/generic-type-naming.md

@@ -3,6 +3,11 @@
 It can be helpful to enforce a consistent naming style for generic type variables used within a type.
 For example, prefixing them with `T` and ensuring a somewhat descriptive name, or enforcing Hungarian notation.
 
+## DEPRECATED
+
+This rule has been deprecated in favour of the [`naming-convention`](./naming-convention.md) rule.
+It will be removed in a future version of this plugin.
+
 ## Rule Details
 
 This rule allows you to enforce conventions over type variables. By default, it does nothing.
@@ -13,7 +18,7 @@ The rule takes a single string option, which is a regular expression that type v
 
 Examples of **correct** code with a configuration of `'^T[A-Z][a-zA-Z]+$'`:
 
-```typescript
+```ts
 type ReadOnly<TType extends object> = {
   readonly [TKey in keyof TType]: TType[TKey];
 };
@@ -25,7 +30,7 @@ interface SimpleMap<TValue> {
 
 Examples of **incorrect** code with a configuration of `'^T[A-Z][a-zA-Z]+$'`:
 
-```typescript
+```ts
 type ReadOnly<T extends object> = { readonly [Key in keyof T]: T[Key] };
 
 interface SimpleMap<T> {