docs: various updates based on v3 feedback (typescript-eslint#2070)

bradzacher · web-flow · commit 071e5a04d09d · 2020-05-22T11:44:40.000-07:00
diff --git a/docs/getting-started/linting/FAQ.md b/docs/getting-started/linting/FAQ.md
@@ -11,6 +11,10 @@
 
 ---
 
+<br />
+<br />
+<br />
+
 ## My linting feels really slow
 
 As mentioned in the [type-aware linting doc](./TYPED_LINTING.md), if you're using type-aware linting, your lint times should be roughly the same as your build times.
@@ -61,8 +65,16 @@ This rule helps ensure your codebase follows a consistent indentation pattern. H
 
 We recommend not using this rule, and instead using a tool like [`prettier`](https://www.npmjs.com/package/) to enforce a standardized formatting.
 
+<br />
+<br />
+<br />
+
 ---
 
+<br />
+<br />
+<br />
+
 ## I get errors telling me "The file must be included in at least one of the projects provided"
 
 This error means that the file that's being linted is not included in any of the tsconfig files you provided us. A lot of the time this happens when users have test files or similar that are not included.
@@ -78,8 +90,16 @@ There are a couple of solutions to this, depending on what you want to achieve.
     - Check the `include` option of each of the tsconfigs that you provide to `parserOptions.project` - you must ensure that all files match an `include` glob, or else our tooling will not be able to find it.
     - If your file shouldn't be a part of one of your existing tsconfigs (for example, it is a script/tool local to the repo), then consider creating a new tsconfig (we advise calling it `tsconfig.eslint.json`) in your project root which lists this file in its `include`.
 
+<br />
+<br />
+<br />
+
 ---
 
+<br />
+<br />
+<br />
+
 ## I use a framework (like Vue) that requires custom file extensions, and I get errors like "You should add `parserOptions.extraFileExtensions` to your config"
 
 You can use `parserOptions.extraFileExtensions` to specify an array of non-TypeScript extensions to allow, for example:
@@ -92,8 +112,16 @@ You can use `parserOptions.extraFileExtensions` to specify an array of non-TypeS
  },
 ```
 
+<br />
+<br />
+<br />
+
 ---
 
+<br />
+<br />
+<br />
+
 ## I am using a rule from ESLint core, and it doesn't work correctly with TypeScript code
 
 This is a pretty common thing because TypeScript adds new features that ESLint doesn't know about.
@@ -111,16 +139,32 @@ The first step is to [check our list of "extension" rules here](../../../package
 
 If you don't find an existing extension rule, or the extension rule doesn't work for your case, then you can go ahead and check our issues. [The contributing guide outlines the best way to raise an issue](../../../CONTRIBUTING.md#raising-issues).
 
+<br />
+<br />
+<br />
+
 ---
 
+<br />
+<br />
+<br />
+
 ## One of my lint rules isn't working correctly on a pure JavaScript file
 
 This is to be expected - ESLint rules do not check file extensions on purpose, as it causes issues in environments that use non-standard extensions (for example, a `.vue` and a `.md` file can both contain TypeScript code to be linted).
 
 If you have some pure JavaScript code that you do not want to apply certain lint rules to, then you can use [ESLint's `overrides` configuration](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns) to turn off certain rules, or even change the parser based on glob patterns.
 
+<br />
+<br />
+<br />
+
 ---
 
+<br />
+<br />
+<br />
+
 ## TypeScript should be installed locally
 
 Make sure that you have installed TypeScript locally i.e. by using `npm install typescript`, not `npm install -g typescript`,
diff --git a/docs/getting-started/linting/MONOREPO.md b/docs/getting-started/linting/MONOREPO.md
@@ -28,7 +28,6 @@ For example, this is how we specify all of our `tsconfig.json` within this repo.
    plugins: ['@typescript-eslint'],
    extends: [
      'eslint:recommended',
-     'plugin:@typescript-eslint/eslint-recommended',
      'plugin:@typescript-eslint/recommended',
      'plugin:@typescript-eslint/recommended-requiring-type-checking',
    ],
diff --git a/docs/getting-started/linting/README.md b/docs/getting-started/linting/README.md
@@ -102,7 +102,6 @@ To use one of these complete config packages, you would replace the `extends` wi
     ],
     extends: [
 -     'eslint:recommended',
--     'plugin:@typescript-eslint/eslint-recommended',
 -     'plugin:@typescript-eslint/recommended',
 +     'airbnb-typescript',
     ],
@@ -124,7 +123,6 @@ Using this config is as simple as adding it to the end of your `extends`:
     ],
     extends: [
       'eslint:recommended',
-      'plugin:@typescript-eslint/eslint-recommended',
       'plugin:@typescript-eslint/recommended',
 +     'prettier/@typescript-eslint',
     ],
@@ -153,7 +151,6 @@ Every plugin that is out there includes documentation on the various rules they
     ],
     extends: [
       'eslint:recommended',
-      'plugin:@typescript-eslint/eslint-recommended',
       'plugin:@typescript-eslint/recommended',
 +     'plugin:jest/recommended',
     ],
diff --git a/docs/getting-started/linting/TYPED_LINTING.md b/docs/getting-started/linting/TYPED_LINTING.md
@@ -17,7 +17,6 @@ How can we tap into this? There are two small changes you need to make to your c
    plugins: ['@typescript-eslint'],
    extends: [
      'eslint:recommended',
-     'plugin:@typescript-eslint/eslint-recommended',
      'plugin:@typescript-eslint/recommended',
 +    'plugin:@typescript-eslint/recommended-requiring-type-checking',
    ],
diff --git a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md
@@ -26,6 +26,7 @@ export var arrowFn = () => 'test';
 
 // All arguments should be typed
 export var arrowFn = (arg): string => `test ${arg}`;
+export var arrowFn = (arg: any): string => `test ${arg}`;
 
 export class Test {
   // Should indicate that no value is returned (void)
@@ -51,6 +52,10 @@ export var fn = function (): number {
 // A return value of type string
 export var arrowFn = (arg: string): string => `test ${arg}`;
 
+// All arguments should be typed
+export var arrowFn = (arg: string): string => `test ${arg}`;
+export var arrowFn = (arg: unknown): string => `test ${arg}`;
+
 // Class is not exported
 class Test {
   method() {
diff --git a/packages/eslint-plugin/docs/rules/naming-convention.md b/packages/eslint-plugin/docs/rules/naming-convention.md
@@ -320,10 +320,30 @@ Group Selectors are provided for convenience, and essentially bundle up sets of
 }
 ```
 
+### Enforce that interface names do not begin with an `I`
+
+```json
+{
+  "@typescript-eslint/naming-convention": [
+    "error",
+    {
+      "selector": "interface",
+      "format": ["PascalCase"],
+      "prefix": ["T"],
+      "custom": {
+        "regex": "^I[A-Z]",
+        "match": false
+      }
+    }
+  ]
+}
+```
+
 ### Enforce the codebase follows ESLint's `camelcase` conventions
 
 ```json
 {
+  "camelcase": "off",
   "@typescript-eslint/naming-convention": [
     "error",
     {
diff --git a/packages/eslint-plugin/src/configs/README.md b/packages/eslint-plugin/src/configs/README.md
@@ -6,6 +6,8 @@ These configs exist for your convenience. They contain configuration intended to
 
 The `eslint-recommended` ruleset is meant to be used after extending `eslint:recommended`. It disables rules that are already checked by the TypeScript compiler and enables rules that promote using the more modern constructs TypeScript allows for.
 
+This config is automatically included if you use either the `recommended` or `recommended-requiring-type-checking` configs.
+
 ```cjson
 {
   "extends": [
@@ -15,9 +17,11 @@ The `eslint-recommended` ruleset is meant to be used after extending `eslint:rec
 }
 ```
 
+We will not add new rules to the `eslint-recommended` set unless we release a major package version (i.e. it is seen as a breaking change).
+
 ## `recommended`
 
-The recommended set is an **_opinionated_** set of rules that we think you should use because:
+The `recommended` set is an **_opinionated_** set of rules that we think you should use because:
 
 1. They help you adhere to TypeScript best practices.
 2. They help catch probable issue vectors in your code.
@@ -30,9 +34,9 @@ That being said, it is not the only way to use `@typescript-eslint/eslint-plugin
    - The style used by many OSS TypeScript projects.
 2. The combined state of community contributed rulesets at the time of creation.
 
-We will not add new rules to the recommended set unless we release a major package version (i.e. it is seen as a breaking change).
+We will not add new rules to the `recommended` set unless we release a major package version (i.e. it is seen as a breaking change).
 
-### Altering the recommended set to suit your project
+### Altering the `recommended` set to suit your project
 
 If you disagree with a rule (or it disagrees with your codebase), consider using your local config to change the rule config so it works for your project.
 
@@ -46,7 +50,20 @@ If you disagree with a rule (or it disagrees with your codebase), consider using
 }
 ```
 
-### Suggesting changes to the recommended set
+### Suggesting changes to the `recommended` set
 
 <!-- prettier-ignore -->
 If you feel _very_, **very**, ***very*** strongly that a specific rule should (or should not) be in the recommended ruleset, please feel free to file an issue along with a **detailed** argument explaining your reasoning. We expect to see you citing concrete evidence supporting why (or why not) a rule is considered best practice. **Please note that if your reasoning is along the lines of "it's what my project/company does", or "I don't like the rule", then we will likely close the request without discussion.**
+
+## `recommended-requiring-type-checking`
+
+Similar to `recommended`, the `recommended-requiring-type-checking` set is an **_opinionated_** set of rules. The difference being that all rules in this set will require type information to use.
+
+We will not add new rules to the `recommended-requiring-type-checking` set unless we release a major package version (i.e. it is seen as a breaking change).
+
+## `all`
+
+The `all` set simply contains every single rule in this plugin, turn on with its default configuration.
+There may be some conflicts between the rules as defaults do not quite align - please file an issue if you encounter any of these.
+
+This set is considered unstable, as any new rules will be added with only a minor package version bump.
