typescript-eslint · JoshuaKGoldberg · Jul 29, 2024 · Jun 6, 2024 · Jun 6, 2024 · Jun 6, 2024
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,7 @@ yarn-debug.log*
 yarn-error.log*
 
 # Website
+docs/packages/*/generated
 packages/website/.docusaurus
 packages/website/.cache-loader
 packages/website/build

diff --git a/docs/packages/Type_Utils.mdx b/docs/packages/Type_Utils.mdx
@@ -1,20 +1,31 @@
 ---
 id: type-utils
 sidebar_label: type-utils
+toc_max_heading_level: 3
 ---
 
+import GeneratedDocs from './type-utils/generated/index.md';
+
 # `@typescript-eslint/type-utils`
 
 <PackageLink packageName="type-utils" scope="@typescript-eslint" />
 
-> Type utilities for working with TypeScript within ESLint rules. ✨
+> Type utilities for working with TypeScript types ✨
 
-This package contains public utilities for working with TypeScript types that ESLint rules often use.
+This package contains public utilities for working with TypeScript types.
 Rules declared in [`@typescript-eslint/eslint-plugin`](./ESLint_Plugin.mdx) use these utility functions.
 
 The utilities in this package are both:
 
 - More generally ESLint-focused than the broad TypeScript utilities in [`ts-api-utils`](https://npmjs.com/package/ts-api-utils)
 - Separated from [`@typescript-eslint/utils`](./Utils.mdx) so that that package does not require a dependency on `typescript`
 
-> See [Custom Rules](../developers/Custom_Rules.mdx) for documentation on creating your own custom ESLint rules for TypeScript code.
+:::tip
+See [Custom Rules](../developers/Custom_Rules.mdx) for documentation on creating your own custom ESLint rules for TypeScript code.
+:::
+
+---
+
+The following documentation is auto-generated from source code.
+
+<GeneratedDocs />
diff --git a/docs/packages/Utils.mdx b/docs/packages/Utils.mdx
@@ -1,6 +1,7 @@
 ---
 id: utils
 sidebar_label: utils
+toc_max_heading_level: 3
 ---
 
 # `@typescript-eslint/utils`

diff --git a/docs/packages/typescript-estree/AST_Spec.mdx b/docs/packages/typescript-estree/AST_Spec.mdx
@@ -0,0 +1,13 @@
+---
+id: ast-spec
+sidebar_label: AST Specification
+toc_max_heading_level: 3
+---
+
+import GeneratedDocs from '../ast-spec/generated/index.md';
+
+# AST Specification
+
+The following auto-generated documentation describes the Abstract Syntax Tree (AST) generated by [`@typescript-eslint/typescript-estree`](../TypeScript_ESTree.mdx) for parsers such as [`@typescript-eslint/parser`](../Parser.mdx).
+
+<GeneratedDocs />
diff --git a/knip.ts b/knip.ts
@@ -97,6 +97,9 @@ export default {
         '@generated/docusaurus.config',
         '^@theme/.*',
         '^@theme-original/.*',
+        'docusaurus-plugin-typedoc',
+        'typedoc',
+        'typedoc-plugin-markdown',
       ],
     },
     'packages/website-eslint': {

diff --git a/packages/ast-spec/src/ast-node-types.ts b/packages/ast-spec/src/ast-node-types.ts
@@ -88,9 +88,9 @@ export enum AST_NODE_TYPES {
   WhileStatement = 'WhileStatement',
   WithStatement = 'WithStatement',
   YieldExpression = 'YieldExpression',
-  /**
-   * TS-prefixed nodes
-   */
+
+  // TS_prefixed nodes
+
   TSAbstractAccessorProperty = 'TSAbstractAccessorProperty',
   TSAbstractKeyword = 'TSAbstractKeyword',
   TSAbstractMethodDefinition = 'TSAbstractMethodDefinition',

diff --git a/packages/ast-spec/src/base/ClassBase.ts b/packages/ast-spec/src/base/ClassBase.ts
@@ -10,8 +10,9 @@ import type { BaseNode } from './BaseNode';
 export interface ClassBase extends BaseNode {
   /**
    * Whether the class is an abstract class.
-   * ```
-   * abstract class Foo {...}
+   * @example
+   * ```ts
+   * abstract class Foo {}
    * ```
    */
   abstract: boolean;
@@ -21,16 +22,18 @@ export interface ClassBase extends BaseNode {
   body: ClassBody;
   /**
    * Whether the class has been `declare`d:
-   * ```
-   * declare class Foo {...}
+   * @example
+   * ```ts
+   * declare class Foo {}
    * ```
    */
   declare: boolean;
   /**
    * The decorators declared for the class.
-   * ```
+   * @example
+   * ```ts
    * @deco
-   * class Foo {...}
+   * class Foo {}
    * ```
    */
   decorators: Decorator[];

diff --git a/packages/ast-spec/src/base/FunctionBase.ts b/packages/ast-spec/src/base/FunctionBase.ts
@@ -10,9 +10,9 @@ export interface FunctionBase extends BaseNode {
   /**
    * Whether the function is async:
    * ```
-   * async function foo(...) {...}
-   * const x = async function (...) {...}
-   * const x = async (...) => {...}
+   * async function foo() {}
+   * const x = async function () {}
+   * const x = async () => {}
    * ```
    */
   async: boolean;
@@ -27,7 +27,7 @@ export interface FunctionBase extends BaseNode {
   /**
    * This is only `true` if and only if the node is a `TSDeclareFunction` and it has `declare`:
    * ```
-   * declare function foo(...) {...}
+   * declare function foo() {}
    * ```
    */
   declare: boolean;
@@ -42,8 +42,8 @@ export interface FunctionBase extends BaseNode {
   /**
    * Whether the function is a generator function:
    * ```
-   * function *foo(...) {...}
-   * const x = function *(...) {...}
+   * function *foo() {}
+   * const x = function *() {}
    * ```
    * This is always `false` for arrow functions as they cannot be generators.
    */

diff --git a/packages/ast-spec/src/base/NodeOrTokenData.ts b/packages/ast-spec/src/base/NodeOrTokenData.ts
@@ -6,14 +6,9 @@ export interface NodeOrTokenData {
    * The source location information of the node.
    *
    * The loc property is defined as nullable by ESTree, but ESLint requires this property.
-   *
-   * @see {SourceLocation}
    */
   loc: SourceLocation;
 
-  /**
-   * @see {Range}
-   */
   range: Range;
 
   type: string;

diff --git a/packages/ast-spec/src/declaration/ExportAllDeclaration/spec.ts b/packages/ast-spec/src/declaration/ExportAllDeclaration/spec.ts
@@ -9,16 +9,18 @@ export interface ExportAllDeclaration extends BaseNode {
   type: AST_NODE_TYPES.ExportAllDeclaration;
   /**
    * The assertions declared for the export.
-   * ```
-   * export * from 'mod' assert { type: 'json' };
+   * @example
+   * ```ts
+   * export * from 'mod' assert \{ type: 'json' \};
    * ```
    * @deprecated Replaced with {@link `attributes`}.
    */
   assertions: ImportAttribute[];
   /**
    * The attributes declared for the export.
-   * ```
-   * export * from 'mod' with { type: 'json' };
+   * @example
+   * ```ts
+   * export * from 'mod' with \{ type: 'json' \};
    * ```
    */
   attributes: ImportAttribute[];

diff --git a/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts b/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts
@@ -10,24 +10,27 @@ interface ExportNamedDeclarationBase extends BaseNode {
   type: AST_NODE_TYPES.ExportNamedDeclaration;
   /**
    * The assertions declared for the export.
-   * ```
-   * export { foo } from 'mod' assert { type: 'json' };
+   * @example
+   * ```ts
+   * export { foo } from 'mod' assert \{ type: 'json' \};
    * ```
    * This will be an empty array if `source` is `null`
    * @deprecated Replaced with {@link `attributes`}.
    */
   assertions: ImportAttribute[];
   /**
    * The attributes declared for the export.
-   * ```
-   * export { foo } from 'mod' with { type: 'json' };
+   * @example
+   * ```ts
+   * export { foo } from 'mod' with \{ type: 'json' \};
    * ```
    * This will be an empty array if `source` is `null`
    */
   attributes: ImportAttribute[];
   /**
    * The exported declaration.
-   * ```
+   * @example
+   * ```ts
    * export const x = 1;
    * ```
    * This will be `null` if `source` is not `null`, or if there are `specifiers`
@@ -43,7 +46,8 @@ interface ExportNamedDeclarationBase extends BaseNode {
   source: StringLiteral | null;
   /**
    * The specifiers being exported.
-   * ```
+   * @example
+   * ```ts
    * export { a, b };
    * ```
    * This will be an empty array if `declaration` is not `null`

diff --git a/packages/ast-spec/src/declaration/ImportDeclaration/spec.ts b/packages/ast-spec/src/declaration/ImportDeclaration/spec.ts
@@ -9,16 +9,18 @@ export interface ImportDeclaration extends BaseNode {
   type: AST_NODE_TYPES.ImportDeclaration;
   /**
    * The assertions declared for the export.
-   * ```
-   * import * from 'mod' assert { type: 'json' };
+   * @example
+   * ```ts
+   * import * from 'mod' assert \{ type: 'json' \};
    * ```
    * @deprecated Replaced with {@link `attributes`}.
    */
   assertions: ImportAttribute[];
   /**
    * The attributes declared for the export.
-   * ```
-   * import * from 'mod' with { type: 'json' };
+   * @example
+   * ```ts
+   * import * from 'mod' with \{ type: 'json' \};
    * ```
    */
   attributes: ImportAttribute[];

diff --git a/packages/ast-spec/src/declaration/TSEnumDeclaration/spec.ts b/packages/ast-spec/src/declaration/TSEnumDeclaration/spec.ts
@@ -7,15 +7,17 @@ export interface TSEnumDeclaration extends BaseNode {
   type: AST_NODE_TYPES.TSEnumDeclaration;
   /**
    * Whether this is a `const` enum.
-   * ```
-   * const enum Foo {...}
+   * @example
+   * ```ts
+   * const enum Foo {}
    * ```
    */
   const: boolean;
   /**
    * Whether this is a `declare`d enum.
-   * ```
-   * declare enum Foo {...}
+   * @example
+   * ```ts
+   * declare enum Foo {}
    * ```
    */
   declare: boolean;

diff --git a/packages/ast-spec/src/declaration/TSImportEqualsDeclaration/spec.ts b/packages/ast-spec/src/declaration/TSImportEqualsDeclaration/spec.ts
@@ -13,7 +13,8 @@ interface TSImportEqualsDeclarationBase extends BaseNode {
   id: Identifier;
   /**
    * The value being aliased.
-   * ```
+   * @example
+   * ```ts
    * import F1 = A;
    * import F2 = A.B.C;
    * import F3 = require('mod');

diff --git a/packages/ast-spec/src/declaration/TSModuleDeclaration/spec.ts b/packages/ast-spec/src/declaration/TSModuleDeclaration/spec.ts
@@ -26,22 +26,28 @@ interface TSModuleDeclarationBase extends BaseNode {
   body?: TSModuleBlock;
   /**
    * Whether this is a global declaration
+   * @example
+   * ```ts
+   * declare global {}
+   * ```
    *
    * @deprecated Use {@link kind} instead
    */
   // TODO - remove this in the next major (we have `.kind` now)
   global: boolean;
   /**
    * Whether the module is `declare`d
-   * ```
+   * @example
+   * ```ts
    * declare namespace F {}
    * ```
    */
   declare: boolean;
 
   /**
    * The keyword used to define this module declaration
-   * ```
+   * @example
+   * ```ts
    * namespace Foo {}
    * ^^^^^^^^^
    *

diff --git a/packages/ast-spec/src/declaration/TSTypeAliasDeclaration/spec.ts b/packages/ast-spec/src/declaration/TSTypeAliasDeclaration/spec.ts
@@ -8,7 +8,8 @@ export interface TSTypeAliasDeclaration extends BaseNode {
   type: AST_NODE_TYPES.TSTypeAliasDeclaration;
   /**
    * Whether the type was `declare`d.
-   * ```
+   * @example
+   * ```ts
    * declare type T = 1;
    * ```
    */