feat(typescript-eslint): add JSDoc comments on generated configs (typescript-eslint#9672)

JoshuaKGoldberg · web-flow · commit 90576fa72afd · 2024-08-12T10:29:46.000-04:00
* feat(typescript-eslint): add JSDoc comments on generated configs

* Also add to index.ts
diff --git a/packages/typescript-eslint/src/configs/all.ts b/packages/typescript-eslint/src/configs/all.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * Enables each the rules provided as a part of typescript-eslint. Note that many rules are not applicable in all codebases, or are meant to be configured.
+ * @see {@link https://typescript-eslint.io/users/configs#all}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/base.ts b/packages/typescript-eslint/src/configs/base.ts
@@ -1,5 +1,10 @@
 import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 
+/**
+ * A minimal ruleset that sets only the required parser and plugin options needed to run typescript-eslint.
+ * We don't recommend using this directly; instead, extend from an earlier recommended rule.
+ * @see {@link https://typescript-eslint.io/users/configs#base}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/disable-type-checked.ts b/packages/typescript-eslint/src/configs/disable-type-checked.ts
@@ -7,6 +7,10 @@
 
 import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 
+/**
+ * A utility ruleset that will disable type-aware linting and all type-aware rules available in our project.
+ * @see {@link https://typescript-eslint.io/users/configs#disable-type-checked}
+ */
 export default (
   _plugin: FlatConfig.Plugin,
   _parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/eslint-recommended.ts b/packages/typescript-eslint/src/configs/eslint-recommended.ts
@@ -5,6 +5,7 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
  * This is a compatibility ruleset that:
  * - disables rules from eslint:recommended which are already handled by TypeScript.
  * - enables rules that make sense due to TS's typechecking / transpilation.
+ * @see {@link https://typescript-eslint.io/users/configs/#eslint-recommended}
  */
 export default (
   _plugin: FlatConfig.Plugin,
diff --git a/packages/typescript-eslint/src/configs/recommended-type-checked-only.ts b/packages/typescript-eslint/src/configs/recommended-type-checked-only.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * A version of `recommended` that only contains type-checked rules and disables of any corresponding core ESLint rules.
+ * @see {@link https://typescript-eslint.io/users/configs#recommended-type-checked-only}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/recommended-type-checked.ts b/packages/typescript-eslint/src/configs/recommended-type-checked.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * Contains all of `recommended` along with additional recommended rules that require type information.
+ * @see {@link https://typescript-eslint.io/users/configs#recommended-type-checked}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/recommended.ts b/packages/typescript-eslint/src/configs/recommended.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * Recommended rules for code correctness that you can drop in without additional configuration.
+ * @see {@link https://typescript-eslint.io/users/configs#recommended}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/strict-type-checked-only.ts b/packages/typescript-eslint/src/configs/strict-type-checked-only.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * A version of `strict` that only contains type-checked rules and disables of any corresponding core ESLint rules.
+ * @see {@link https://typescript-eslint.io/users/configs#strict-type-checked-only}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/strict-type-checked.ts b/packages/typescript-eslint/src/configs/strict-type-checked.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * Contains all of `recommended`, `recommended-type-checked`, and `strict`, along with additional strict rules that require type information.
+ * @see {@link https://typescript-eslint.io/users/configs#strict-type-checked}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/strict.ts b/packages/typescript-eslint/src/configs/strict.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * Contains all of `recommended`, as well as additional strict rules that can also catch bugs.
+ * @see {@link https://typescript-eslint.io/users/configs#strict}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/stylistic-type-checked-only.ts b/packages/typescript-eslint/src/configs/stylistic-type-checked-only.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * A version of `stylistic` that only contains type-checked rules and disables of any corresponding core ESLint rules.
+ * @see {@link https://typescript-eslint.io/users/configs#stylistic-type-checked-only}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/stylistic-type-checked.ts b/packages/typescript-eslint/src/configs/stylistic-type-checked.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * Contains all of `stylistic`, along with additional stylistic rules that require type information.
+ * @see {@link https://typescript-eslint.io/users/configs#stylistic-type-checked}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/configs/stylistic.ts b/packages/typescript-eslint/src/configs/stylistic.ts
@@ -10,6 +10,10 @@ import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
 import baseConfig from './base';
 import eslintRecommendedConfig from './eslint-recommended';
 
+/**
+ * Rules considered to be best practice for modern TypeScript codebases, but that do not impact program logic.
+ * @see {@link https://typescript-eslint.io/users/configs#stylistic}
+ */
 export default (
   plugin: FlatConfig.Plugin,
   parser: FlatConfig.Parser,
diff --git a/packages/typescript-eslint/src/index.ts b/packages/typescript-eslint/src/index.ts
@@ -53,18 +53,85 @@ const plugin: TSESLint.FlatConfig.Plugin = pluginBase as Omit<
 >;
 
 const configs = {
+  /**
+   * Enables each the rules provided as a part of typescript-eslint. Note that many rules are not applicable in all codebases, or are meant to be configured.
+   * @see {@link https://typescript-eslint.io/users/configs#all}
+   */
   all: allConfig(plugin, parser),
+
+  /**
+   * A minimal ruleset that sets only the required parser and plugin options needed to run typescript-eslint.
+   * We don't recommend using this directly; instead, extend from an earlier recommended rule.
+   * @see {@link https://typescript-eslint.io/users/configs#base}
+   */
   base: baseConfig(plugin, parser),
+
+  /**
+   * A utility ruleset that will disable type-aware linting and all type-aware rules available in our project.
+   * @see {@link https://typescript-eslint.io/users/configs#disable-type-checked}
+   */
   disableTypeChecked: disableTypeCheckedConfig(plugin, parser),
+
+  /**
+   * This is a compatibility ruleset that:
+   * - disables rules from eslint:recommended which are already handled by TypeScript.
+   * - enables rules that make sense due to TS's typechecking / transpilation.
+   * @see {@link https://typescript-eslint.io/users/configs/#eslint-recommended}
+   */
   eslintRecommended: eslintRecommendedConfig(plugin, parser),
+
+  /**
+   * Recommended rules for code correctness that you can drop in without additional configuration.
+   * @see {@link https://typescript-eslint.io/users/configs#recommended}
+   */
   recommended: recommendedConfig(plugin, parser),
+
+  /**
+   * Contains all of `recommended` along with additional recommended rules that require type information.
+   * @see {@link https://typescript-eslint.io/users/configs#recommended-type-checked}
+   */
   recommendedTypeChecked: recommendedTypeCheckedConfig(plugin, parser),
+
+  /**
+   * A version of `recommended` that only contains type-checked rules and disables of any corresponding core ESLint rules.
+   * @see {@link https://typescript-eslint.io/users/configs#recommended-type-checked-only}
+   */
   recommendedTypeCheckedOnly: recommendedTypeCheckedOnlyConfig(plugin, parser),
+
+  /**
+   * Contains all of `recommended`, as well as additional strict rules that can also catch bugs.
+   * @see {@link https://typescript-eslint.io/users/configs#strict}
+   */
   strict: strictConfig(plugin, parser),
+
+  /**
+   * Contains all of `recommended`, `recommended-type-checked`, and `strict`, along with additional strict rules that require type information.
+   * @see {@link https://typescript-eslint.io/users/configs#strict-type-checked}
+   */
   strictTypeChecked: strictTypeCheckedConfig(plugin, parser),
+
+  /**
+   * A version of `strict` that only contains type-checked rules and disables of any corresponding core ESLint rules.
+   * @see {@link https://typescript-eslint.io/users/configs#strict-type-checked-only}
+   */
   strictTypeCheckedOnly: strictTypeCheckedOnlyConfig(plugin, parser),
+
+  /**
+   * Rules considered to be best practice for modern TypeScript codebases, but that do not impact program logic.
+   * @see {@link https://typescript-eslint.io/users/configs#stylistic}
+   */
   stylistic: stylisticConfig(plugin, parser),
+
+  /**
+   * Contains all of `stylistic`, along with additional stylistic rules that require type information.
+   * @see {@link https://typescript-eslint.io/users/configs#stylistic-type-checked}
+   */
   stylisticTypeChecked: stylisticTypeCheckedConfig(plugin, parser),
+
+  /**
+   * A version of `stylistic` that only contains type-checked rules and disables of any corresponding core ESLint rules.
+   * @see {@link https://typescript-eslint.io/users/configs#stylistic-type-checked-only}
+   */
   stylisticTypeCheckedOnly: stylisticTypeCheckedOnlyConfig(plugin, parser),
 };
 
diff --git a/tools/scripts/generate-configs.mts b/tools/scripts/generate-configs.mts
