From 1ea35739697838af161f740e5d6625e1c9ef62ec Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 6 Jun 2024 09:09:30 -0400 Subject: [PATCH 01/16] docs: add type-utils docs with docusaurus-plugin-typedoc --- .gitignore | 1 + docs/packages/Type_Utils.mdx | 17 +++++ packages/website/docusaurus.config.mts | 9 +++ packages/website/package.json | 3 + yarn.lock | 88 +++++++++++++++++++++++++- 5 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 docs/packages/Type_Utils.mdx diff --git a/.gitignore b/.gitignore index cd2f6495f7bf..9c904916eb59 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ yarn-debug.log* yarn-error.log* # Website +docs/packages/type-utils/api packages/website/.docusaurus packages/website/.cache-loader packages/website/build diff --git a/docs/packages/Type_Utils.mdx b/docs/packages/Type_Utils.mdx new file mode 100644 index 000000000000..24ea50f004e6 --- /dev/null +++ b/docs/packages/Type_Utils.mdx @@ -0,0 +1,17 @@ +--- +id: type-utils +sidebar_label: type-utils +--- + +# `@typescript-eslint/type-utils` + + + +> Type utilities for working with TypeScript types ✨ + +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 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. diff --git a/packages/website/docusaurus.config.mts b/packages/website/docusaurus.config.mts index a728e223b119..1e96d831d38b 100644 --- a/packages/website/docusaurus.config.mts +++ b/packages/website/docusaurus.config.mts @@ -322,6 +322,15 @@ const config: Config = { ['@docusaurus/plugin-content-docs', pluginContentDocsOptions], ['@docusaurus/plugin-pwa', pluginPwaOptions], ['@docusaurus/plugin-client-redirects', redirects], + + [ + 'docusaurus-plugin-typedoc', + { + entryPoints: ['../type-utils/src/index.ts'], + tsconfig: '../type-utils/tsconfig.json', + out: '../../docs/packages/type-utils/api', + }, + ], ], themeConfig, // Misleading API name, but these are just tags diff --git a/packages/website/package.json b/packages/website/package.json index a5c649efedf4..1a532f71788b 100644 --- a/packages/website/package.json +++ b/packages/website/package.json @@ -27,6 +27,7 @@ "@typescript-eslint/website-eslint": "7.12.0", "@uiw/react-shields": "2.0.1", "clsx": "^2.1.0", + "docusaurus-plugin-typedoc": "^1.0.1", "eslint": "*", "json5": "^2.2.3", "konamimojisplosion": "^0.5.2", @@ -37,6 +38,8 @@ "react-dom": "^18.2.0", "react-resizable-panels": "^0.0.63", "semver": "^7.6.0", + "typedoc": "^0.25.13", + "typedoc-plugin-markdown": "^4.0.3", "typescript": "*" }, "resolutions": { diff --git a/yarn.lock b/yarn.lock index b39b4b425975..81fb96f82661 100644 --- a/yarn.lock +++ b/yarn.lock @@ -6537,6 +6537,13 @@ __metadata: languageName: node linkType: hard +"ansi-sequence-parser@npm:^1.1.0": + version: 1.1.1 + resolution: "ansi-sequence-parser@npm:1.1.1" + checksum: ead5b15c596e8e85ca02951a844366c6776769dcc9fd1bd3a0db11bb21364554822c6a439877fb599e7e1ffa0b5f039f1e5501423950457f3dcb2f480c30b188 + languageName: node + linkType: hard + "ansi-styles@npm:^3.2.1": version: 3.2.1 resolution: "ansi-styles@npm:3.2.1" @@ -9091,6 +9098,15 @@ __metadata: languageName: node linkType: hard +"docusaurus-plugin-typedoc@npm:^1.0.1": + version: 1.0.1 + resolution: "docusaurus-plugin-typedoc@npm:1.0.1" + peerDependencies: + typedoc-plugin-markdown: ">=4.0.0" + checksum: 0a1f0720f3b62d37cc7cacfa8100769e8354785215b84f33951f38d65951a04d7a3b719089717a1d5dbd653f029931a7e624908334519f16fa60798a5d8224ca + languageName: node + linkType: hard + "dom-converter@npm:^0.2.0": version: 0.2.0 resolution: "dom-converter@npm:0.2.0" @@ -13916,6 +13932,13 @@ __metadata: languageName: node linkType: hard +"lunr@npm:^2.3.9": + version: 2.3.9 + resolution: "lunr@npm:2.3.9" + checksum: 176719e24fcce7d3cf1baccce9dd5633cd8bdc1f41ebe6a180112e5ee99d80373fe2454f5d4624d437e5a8319698ca6837b9950566e15d2cae5f2a543a3db4b8 + languageName: node + linkType: hard + "lz-string@npm:^1.5.0": version: 1.5.0 resolution: "lz-string@npm:1.5.0" @@ -14073,6 +14096,15 @@ __metadata: languageName: node linkType: hard +"marked@npm:^4.3.0": + version: 4.3.0 + resolution: "marked@npm:4.3.0" + bin: + marked: bin/marked.js + checksum: 0db6817893952c3ec710eb9ceafb8468bf5ae38cb0f92b7b083baa13d70b19774674be04db5b817681fa7c5c6a088f61300815e4dd75a59696f4716ad69f6260 + languageName: node + linkType: hard + "marked@npm:^5.1.2": version: 5.1.2 resolution: "marked@npm:5.1.2" @@ -15078,7 +15110,7 @@ __metadata: languageName: node linkType: hard -"minimatch@npm:^9.0.4, minimatch@npm:~9.0.4": +"minimatch@npm:^9.0.3, minimatch@npm:^9.0.4, minimatch@npm:~9.0.4": version: 9.0.4 resolution: "minimatch@npm:9.0.4" dependencies: @@ -18341,6 +18373,18 @@ __metadata: languageName: node linkType: hard +"shiki@npm:^0.14.7": + version: 0.14.7 + resolution: "shiki@npm:0.14.7" + dependencies: + ansi-sequence-parser: ^1.1.0 + jsonc-parser: ^3.2.0 + vscode-oniguruma: ^1.7.0 + vscode-textmate: ^8.0.0 + checksum: 2aec3b3519df977c4391df9e1825cb496e9a4d7e11395f05a0da77e4fa2f7c3d9d6e6ee94029ac699533017f2b25637ee68f6d39f05f311535c2704d0329b520 + languageName: node + linkType: hard + "side-channel@npm:^1.0.4, side-channel@npm:^1.0.6": version: 1.0.6 resolution: "side-channel@npm:1.0.6" @@ -19714,6 +19758,31 @@ __metadata: languageName: node linkType: hard +"typedoc-plugin-markdown@npm:^4.0.3": + version: 4.0.3 + resolution: "typedoc-plugin-markdown@npm:4.0.3" + peerDependencies: + typedoc: 0.25.x + checksum: 46239ad6da69721626dc255c0dca9fd7600bf49a78ff7ee319fa600bdac4f405af2a6f549302b0b10439b6fb77710260a6a60ba57fd25d6388f5c081b44a173c + languageName: node + linkType: hard + +"typedoc@npm:^0.25.13": + version: 0.25.13 + resolution: "typedoc@npm:0.25.13" + dependencies: + lunr: ^2.3.9 + marked: ^4.3.0 + minimatch: ^9.0.3 + shiki: ^0.14.7 + peerDependencies: + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x + bin: + typedoc: bin/typedoc + checksum: 703d1f48137300b0ef3df1998a25ae745db3ca0b126f8dd1f7262918f11243a94d24dfc916cdba2baeb5a7d85d5a94faac811caf7f4fa6b7d07144dc02f7639f + languageName: node + linkType: hard + "typescript-eslint@workspace:^, typescript-eslint@workspace:packages/typescript-eslint": version: 0.0.0-use.local resolution: "typescript-eslint@workspace:packages/typescript-eslint" @@ -20192,6 +20261,20 @@ __metadata: languageName: node linkType: hard +"vscode-oniguruma@npm:^1.7.0": + version: 1.7.0 + resolution: "vscode-oniguruma@npm:1.7.0" + checksum: 53519d91d90593e6fb080260892e87d447e9b200c4964d766772b5053f5699066539d92100f77f1302c91e8fc5d9c772fbe40fe4c90f3d411a96d5a9b1e63f42 + languageName: node + linkType: hard + +"vscode-textmate@npm:^8.0.0": + version: 8.0.0 + resolution: "vscode-textmate@npm:8.0.0" + checksum: 127780dfea89559d70b8326df6ec344cfd701312dd7f3f591a718693812b7852c30b6715e3cfc8b3200a4e2515b4c96f0843c0eacc0a3020969b5de262c2a4bb + languageName: node + linkType: hard + "vscode-uri@npm:^3.0.8": version: 3.0.8 resolution: "vscode-uri@npm:3.0.8" @@ -20445,6 +20528,7 @@ __metadata: clsx: ^2.1.0 copy-webpack-plugin: ^12.0.0 cross-fetch: "*" + docusaurus-plugin-typedoc: ^1.0.1 eslint: "*" history: ^4.9.0 json5: ^2.2.3 @@ -20466,6 +20550,8 @@ __metadata: stylelint-config-standard: ^36.0.0 stylelint-order: ^6.0.4 tsx: "*" + typedoc: ^0.25.13 + typedoc-plugin-markdown: ^4.0.3 typescript: "*" unified: ^11.0.4 vfile: ^6.0.1 From 9b6b2e2d32d50d23800d9552d5b72710e101e94d Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 6 Jun 2024 11:10:49 -0400 Subject: [PATCH 02/16] Well, it works now --- packages/type-utils/src/builtinSymbolLikes.ts | 33 ++++++++++++++----- packages/website/docusaurus.config.mts | 9 +++-- packages/website/sidebars/sidebar.base.js | 1 + 3 files changed, 29 insertions(+), 14 deletions(-) diff --git a/packages/type-utils/src/builtinSymbolLikes.ts b/packages/type-utils/src/builtinSymbolLikes.ts index 3443a0d0382e..a2a03a692a26 100644 --- a/packages/type-utils/src/builtinSymbolLikes.ts +++ b/packages/type-utils/src/builtinSymbolLikes.ts @@ -3,18 +3,24 @@ import * as ts from 'typescript'; import { isSymbolFromDefaultLibrary } from './isSymbolFromDefaultLibrary'; /** - * class Foo extends Promise {} - * Foo.reject - * ^ PromiseLike + * @example + * ```ts + * class DerivedClass extends Promise {} + * DerivedClass.reject + * // ^ PromiseLike + * ``` */ export function isPromiseLike(program: ts.Program, type: ts.Type): boolean { return isBuiltinSymbolLike(program, type, 'Promise'); } /** - * const foo = Promise - * foo.reject - * ^ PromiseConstructorLike + * @example + * ```ts + * const value = Promise + * value.reject + * // ^ PromiseConstructorLike + * ``` */ export function isPromiseConstructorLike( program: ts.Program, @@ -24,17 +30,23 @@ export function isPromiseConstructorLike( } /** + * @example + * ```ts * class Foo extends Error {} * new Foo() - * ^ ErrorLike + * // ^ ErrorLike + * ``` */ export function isErrorLike(program: ts.Program, type: ts.Type): boolean { return isBuiltinSymbolLike(program, type, 'Error'); } /** + * @example + * ```ts * type T = Readonly - * ^ ReadonlyErrorLike + * // ^ ReadonlyErrorLike + * ``` */ export function isReadonlyErrorLike( program: ts.Program, @@ -50,8 +62,11 @@ export function isReadonlyErrorLike( } /** + * @example + * ```ts * type T = Readonly<{ foo: 'bar' }> - * ^ ReadonlyTypeLike + * // ^ ReadonlyTypeLike + * ``` */ export function isReadonlyTypeLike( program: ts.Program, diff --git a/packages/website/docusaurus.config.mts b/packages/website/docusaurus.config.mts index 1e96d831d38b..f15ce1dcc979 100644 --- a/packages/website/docusaurus.config.mts +++ b/packages/website/docusaurus.config.mts @@ -318,11 +318,6 @@ const config: Config = { rules: rulesMeta, }, plugins: [ - require.resolve('./webpack.plugin'), - ['@docusaurus/plugin-content-docs', pluginContentDocsOptions], - ['@docusaurus/plugin-pwa', pluginPwaOptions], - ['@docusaurus/plugin-client-redirects', redirects], - [ 'docusaurus-plugin-typedoc', { @@ -331,6 +326,10 @@ const config: Config = { out: '../../docs/packages/type-utils/api', }, ], + require.resolve('./webpack.plugin'), + ['@docusaurus/plugin-content-docs', pluginContentDocsOptions], + ['@docusaurus/plugin-pwa', pluginPwaOptions], + ['@docusaurus/plugin-client-redirects', redirects], ], themeConfig, // Misleading API name, but these are just tags diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index 4676e1e43612..02cbad567249 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -84,6 +84,7 @@ module.exports = { 'packages/parser', 'packages/rule-tester', 'packages/scope-manager', + 'packages/type-utils', 'packages/typescript-estree', 'packages/typescript-eslint', 'packages/utils', From 09244984e8a884d4a63cdab50ddd10cc33cd4009 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 6 Jun 2024 13:38:01 -0400 Subject: [PATCH 03/16] Wow, single page actually works well --- .gitignore | 2 +- docs/packages/Type_Utils.mdx | 9 +++++++++ packages/type-utils/README.md | 2 -- packages/website/docusaurus.config.mts | 14 +++++++++++++- 4 files changed, 23 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 9c904916eb59..06f2aa52d0d7 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,7 @@ yarn-debug.log* yarn-error.log* # Website -docs/packages/type-utils/api +docs/packages/type-utils/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 index 24ea50f004e6..74891458223c 100644 --- a/docs/packages/Type_Utils.mdx +++ b/docs/packages/Type_Utils.mdx @@ -1,8 +1,11 @@ --- id: type-utils sidebar_label: type-utils +toc_max_heading_level: 3 --- +import GeneratedDocs from './type-utils/generated/index.md'; + # `@typescript-eslint/type-utils` @@ -15,3 +18,9 @@ Rules declared in [`@typescript-eslint/eslint-plugin`](./ESLint_Plugin.mdx) use The utilities in this package are 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. + +--- + +The following documentation is auto-generated from source code. + + diff --git a/packages/type-utils/README.md b/packages/type-utils/README.md index c5d32797dcf0..216c6e2b36d5 100644 --- a/packages/type-utils/README.md +++ b/packages/type-utils/README.md @@ -8,5 +8,3 @@ The utilities in this package are separated from `@typescript-eslint/utils` so that that package does not require a dependency on `typescript`. > See https://typescript-eslint.io for general documentation on typescript-eslint, the tooling that allows you to run ESLint and Prettier on TypeScript code. - - diff --git a/packages/website/docusaurus.config.mts b/packages/website/docusaurus.config.mts index f15ce1dcc979..749caaa7b347 100644 --- a/packages/website/docusaurus.config.mts +++ b/packages/website/docusaurus.config.mts @@ -322,8 +322,20 @@ const config: Config = { 'docusaurus-plugin-typedoc', { entryPoints: ['../type-utils/src/index.ts'], + enumMembersFormat: 'table', + exclude: '**/*.d.ts', + groupOrder: ['Functions', 'Variables', '*'], + hidePageTitle: true, + id: 'typedoc-generated-type-utils', + indexFormat: 'table', + out: '../../docs/packages/type-utils/generated', + outputFileStrategy: 'modules', + parametersFormat: 'table', + propertiesFormat: 'table', + readme: 'none', tsconfig: '../type-utils/tsconfig.json', - out: '../../docs/packages/type-utils/api', + typeDeclarationFormat: 'table', + useCodeBlocks: true, }, ], require.resolve('./webpack.plugin'), From 584df320780061574fa35d58025b4436d316143f Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 6 Jun 2024 13:38:21 -0400 Subject: [PATCH 04/16] Add back comment --- packages/type-utils/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/type-utils/README.md b/packages/type-utils/README.md index 216c6e2b36d5..c5d32797dcf0 100644 --- a/packages/type-utils/README.md +++ b/packages/type-utils/README.md @@ -8,3 +8,5 @@ The utilities in this package are separated from `@typescript-eslint/utils` so that that package does not require a dependency on `typescript`. > See https://typescript-eslint.io for general documentation on typescript-eslint, the tooling that allows you to run ESLint and Prettier on TypeScript code. + + From d0c8ce737228d4cc1b44b6147126b392a8283899 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 6 Jun 2024 14:08:39 -0400 Subject: [PATCH 05/16] chore: update knip.ts --- knip.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/knip.ts b/knip.ts index 25de69c9596b..90e7c141de0b 100644 --- a/knip.ts +++ b/knip.ts @@ -102,6 +102,9 @@ export default { '@generated/docusaurus.config', '^@theme/.*', '^@theme-original/.*', + 'docusaurus-plugin-typedoc', + 'typedoc', + 'typedoc-plugin-markdown', ], }, 'packages/website-eslint': { From 0db3d528007093898ec1c779f429a5582372e2f3 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 7 Jun 2024 06:15:48 -0400 Subject: [PATCH 06/16] Add ast-spec underneath typescript-estree --- .gitignore | 2 +- docs/packages/Utils.mdx | 9 +++++++++ docs/packages/typescript-estree/AST_Spec.mdx | 13 +++++++++++++ packages/ast-spec/src/base/ClassBase.ts | 8 +++++--- packages/ast-spec/src/base/FunctionBase.ts | 12 ++++++------ .../src/declaration/ExportAllDeclaration/spec.ts | 10 ++++++---- .../src/declaration/ExportNamedDeclaration/spec.ts | 10 ++++++---- .../src/declaration/ImportDeclaration/spec.ts | 8 +++++--- .../src/declaration/TSEnumDeclaration/spec.ts | 4 ++-- packages/ast-spec/src/element/TSEnumMember/spec.ts | 6 ++++++ .../src/rules/consistent-type-imports.ts | 5 +++-- packages/utils/src/ts-eslint/Linter.ts | 2 +- packages/website/docusaurus.config.mts | 12 ++++++------ packages/website/sidebars/sidebar.base.js | 11 ++++++++++- 14 files changed, 79 insertions(+), 33 deletions(-) create mode 100644 docs/packages/typescript-estree/AST_Spec.mdx diff --git a/.gitignore b/.gitignore index 06f2aa52d0d7..0757eb2c7f3c 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,7 @@ yarn-debug.log* yarn-error.log* # Website -docs/packages/type-utils/generated +docs/packages/*/generated packages/website/.docusaurus packages/website/.cache-loader packages/website/build diff --git a/docs/packages/Utils.mdx b/docs/packages/Utils.mdx index ea7020466324..014db4beb73c 100644 --- a/docs/packages/Utils.mdx +++ b/docs/packages/Utils.mdx @@ -1,8 +1,11 @@ --- id: utils sidebar_label: utils +toc_max_heading_level: 3 --- +import GeneratedDocs from './utils/generated/index.md'; + # `@typescript-eslint/utils` @@ -28,3 +31,9 @@ Any custom rules you write generally will be as well. | `TSESLint` | Types for ESLint, correctly typed to work with the types found in `TSESTree`. | | `TSESLintScope` | The [`eslint-scope`](https://www.npmjs.com/package/eslint-scope) package, correctly typed to work with the types found in both `TSESTree` and `TSESLint` | | `TSESTree` | Types for the TypeScript flavor of ESTree created by `@typescript-eslint/typescript-estree`. | + +--- + +The following documentation is auto-generated from source code. + + diff --git a/docs/packages/typescript-estree/AST_Spec.mdx b/docs/packages/typescript-estree/AST_Spec.mdx new file mode 100644 index 000000000000..21e1aa1e33d3 --- /dev/null +++ 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). + + diff --git a/packages/ast-spec/src/base/ClassBase.ts b/packages/ast-spec/src/base/ClassBase.ts index 595d1393ac48..b81c1ed77ef0 100644 --- 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. + * @example * ``` - * abstract class Foo {...} + * abstract class Foo {} * ``` */ abstract: boolean; @@ -22,15 +23,16 @@ export interface ClassBase extends BaseNode { /** * Whether the class has been `declare`d: * ``` - * declare class Foo {...} + * declare class Foo {} * ``` */ declare: boolean; /** * The decorators declared for the class. + * @example * ``` * @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 index 035b18a682e9..4e7f9d2779d4 100644 --- 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/declaration/ExportAllDeclaration/spec.ts b/packages/ast-spec/src/declaration/ExportAllDeclaration/spec.ts index 550e8da2ec50..46a05d45be5f 100644 --- 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' assert { type: 'json' }; + * @example + * ```ts + * export * from 'mod' assert \{ type: 'json' \}; * ``` */ attributes: ImportAttribute[]; diff --git a/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts b/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts index c71ed8b07ae6..4d0786d2d1e6 100644 --- a/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts @@ -10,8 +10,9 @@ 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`}. @@ -19,8 +20,9 @@ interface ExportNamedDeclarationBase extends BaseNode { assertions: ImportAttribute[]; /** * The attributes 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` */ diff --git a/packages/ast-spec/src/declaration/ImportDeclaration/spec.ts b/packages/ast-spec/src/declaration/ImportDeclaration/spec.ts index a9d49a75d4c8..b9d305676808 100644 --- 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. + * @example * ``` - * import * from 'mod' with { type: 'json' }; + * 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 index 1625063426c8..35e522c2b026 100644 --- a/packages/ast-spec/src/declaration/TSEnumDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/TSEnumDeclaration/spec.ts @@ -8,14 +8,14 @@ export interface TSEnumDeclaration extends BaseNode { /** * Whether this is a `const` enum. * ``` - * const enum Foo {...} + * const enum Foo {} * ``` */ const: boolean; /** * Whether this is a `declare`d enum. * ``` - * declare enum Foo {...} + * declare enum Foo {} * ``` */ declare: boolean; diff --git a/packages/ast-spec/src/element/TSEnumMember/spec.ts b/packages/ast-spec/src/element/TSEnumMember/spec.ts index 9dd1ddeee696..17afc178df24 100644 --- a/packages/ast-spec/src/element/TSEnumMember/spec.ts +++ b/packages/ast-spec/src/element/TSEnumMember/spec.ts @@ -19,12 +19,18 @@ interface TSEnumMemberBase extends BaseNode { * this should only really happen in semantically invalid code (errors 1164 and 2452) * * VALID: + * @example + * ```ts * enum Foo { ['a'] } + *``` * * INVALID: + * @example + * ```ts * const x = 'a'; * enum Foo { [x] } * enum Bar { ['a' + 'b'] } + * ``` */ export interface TSEnumMemberComputedName extends TSEnumMemberBase { id: PropertyNameComputed; diff --git a/packages/eslint-plugin/src/rules/consistent-type-imports.ts b/packages/eslint-plugin/src/rules/consistent-type-imports.ts index f4e98d2d9e00..c20387f87bfe 100644 --- a/packages/eslint-plugin/src/rules/consistent-type-imports.ts +++ b/packages/eslint-plugin/src/rules/consistent-type-imports.ts @@ -349,8 +349,9 @@ export default createRule({ ) { /** * checks if import has type assertions - * ``` - * import * as type from 'mod' assert { type: 'json' }; + * @example + * ```ts + * import * as type from 'mod' assert \{ type: 'json' \}; * ``` * https://github.com/typescript-eslint/typescript-eslint/issues/7527 */ diff --git a/packages/utils/src/ts-eslint/Linter.ts b/packages/utils/src/ts-eslint/Linter.ts index 8ea129409b8d..163977525db0 100644 --- a/packages/utils/src/ts-eslint/Linter.ts +++ b/packages/utils/src/ts-eslint/Linter.ts @@ -73,7 +73,7 @@ declare class LinterBase { * @param textOrSourceCode The text to parse or a SourceCode object. * @param config An ESLintConfig instance to configure everything. * @param filenameOrOptions The optional filename of the file being checked. - * If this is not set, the filename will default to '' in the rule context. + * If this is not set, the filename will default to (input) in the rule context. * If this is an object, then it has "filename", "allowInlineConfig", and some properties. * @returns The results as an array of messages or an empty array if no messages. */ diff --git a/packages/website/docusaurus.config.mts b/packages/website/docusaurus.config.mts index 749caaa7b347..59ca67bf721a 100644 --- a/packages/website/docusaurus.config.mts +++ b/packages/website/docusaurus.config.mts @@ -318,26 +318,26 @@ const config: Config = { rules: rulesMeta, }, plugins: [ - [ + ...['ast-spec', 'type-utils', 'utils'].map(packageName => [ 'docusaurus-plugin-typedoc', { - entryPoints: ['../type-utils/src/index.ts'], + entryPoints: [`../${packageName}/src/index.ts`], enumMembersFormat: 'table', exclude: '**/*.d.ts', groupOrder: ['Functions', 'Variables', '*'], hidePageTitle: true, - id: 'typedoc-generated-type-utils', + id: `typedoc-generated-${packageName}`, indexFormat: 'table', - out: '../../docs/packages/type-utils/generated', + out: `../../docs/packages/${packageName}/generated`, outputFileStrategy: 'modules', parametersFormat: 'table', propertiesFormat: 'table', readme: 'none', - tsconfig: '../type-utils/tsconfig.json', + tsconfig: `../${packageName}/tsconfig.json`, typeDeclarationFormat: 'table', useCodeBlocks: true, }, - ], + ]), require.resolve('./webpack.plugin'), ['@docusaurus/plugin-content-docs', pluginContentDocsOptions], ['@docusaurus/plugin-pwa', pluginPwaOptions], diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index 02cbad567249..29e158715832 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -85,7 +85,16 @@ module.exports = { 'packages/rule-tester', 'packages/scope-manager', 'packages/type-utils', - 'packages/typescript-estree', + { + collapsible: false, + items: ['packages/typescript-estree/ast-spec'], + label: 'typescript-estree', + link: { + id: 'packages/typescript-estree', + type: 'doc', + }, + type: 'category', + }, 'packages/typescript-eslint', 'packages/utils', ], From f95800957d53bb88972f1d5e20115a954aada9d9 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 7 Jun 2024 06:25:58 -0400 Subject: [PATCH 07/16] Internal ast-spec cleanups --- packages/ast-spec/src/base/NodeOrTokenData.ts | 5 ----- packages/utils/src/ts-eslint/RuleTester.ts | 2 +- packages/utils/src/ts-eslint/SourceCode.ts | 14 +++++++------- packages/website/docusaurus.config.mts | 1 + 4 files changed, 9 insertions(+), 13 deletions(-) diff --git a/packages/ast-spec/src/base/NodeOrTokenData.ts b/packages/ast-spec/src/base/NodeOrTokenData.ts index 013f96002fc4..3f6e83919bf6 100644 --- 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/utils/src/ts-eslint/RuleTester.ts b/packages/utils/src/ts-eslint/RuleTester.ts index 11696716222f..1ffc523fd925 100644 --- a/packages/utils/src/ts-eslint/RuleTester.ts +++ b/packages/utils/src/ts-eslint/RuleTester.ts @@ -158,7 +158,7 @@ declare class RuleTesterBase { * Adds a new rule test to execute. * @param ruleName The name of the rule to run. * @param rule The rule to test. - * @param test The collection of tests to run. + * @param tests The collection of tests to run. */ run>( ruleName: string, diff --git a/packages/utils/src/ts-eslint/SourceCode.ts b/packages/utils/src/ts-eslint/SourceCode.ts index 28f37a58ac42..c9b6974a9e7b 100644 --- a/packages/utils/src/ts-eslint/SourceCode.ts +++ b/packages/utils/src/ts-eslint/SourceCode.ts @@ -42,7 +42,7 @@ declare class TokenStore { /** * Gets the first token of the given node. * @param node The AST node. - * @param option The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. + * @param options The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. * @returns An object representing the token. */ getFirstToken( @@ -53,7 +53,7 @@ declare class TokenStore { * Gets the first token between two non-overlapping nodes. * @param left Node before the desired token range. * @param right Node after the desired token range. - * @param option The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. + * @param options The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. * @returns An object representing the token. */ getFirstTokenBetween( @@ -85,7 +85,7 @@ declare class TokenStore { /** * Gets the last token of the given node. * @param node The AST node. - * @param option The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. + * @param options The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. * @returns An object representing the token. */ getLastToken( @@ -96,7 +96,7 @@ declare class TokenStore { * Gets the last token between two non-overlapping nodes. * @param left Node before the desired token range. * @param right Node after the desired token range. - * @param option The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. + * @param options The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. * @returns An object representing the token. */ getLastTokenBetween( @@ -128,7 +128,7 @@ declare class TokenStore { /** * Gets the token that follows a given node or token. * @param node The AST node or token. - * @param option The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. + * @param options The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. * @returns An object representing the token. */ getTokenAfter( @@ -148,7 +148,7 @@ declare class TokenStore { /** * Gets the token starting at the specified index. * @param offset Index of the start of the token's range. - * @param option The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. + * @param options The option object. If this is a number then it's `options.skip`. If this is a function then it's `options.filter`. * @returns The token starting at index, or null if no such token. */ getTokenByRangeStart( @@ -232,7 +232,7 @@ declare class SourceCodeBase extends TokenStore { getAllComments(): TSESTree.Comment[]; /** * Converts a (line, column) pair into a range index. - * @param loc A line/column location + * @param location A line/column location * @returns The range index of the location in the file. */ getIndexFromLoc(location: TSESTree.Position): number; diff --git a/packages/website/docusaurus.config.mts b/packages/website/docusaurus.config.mts index 59ca67bf721a..bf328f3e2b2d 100644 --- a/packages/website/docusaurus.config.mts +++ b/packages/website/docusaurus.config.mts @@ -324,6 +324,7 @@ const config: Config = { entryPoints: [`../${packageName}/src/index.ts`], enumMembersFormat: 'table', exclude: '**/*.d.ts', + excludeExternals: true, groupOrder: ['Functions', 'Variables', '*'], hidePageTitle: true, id: `typedoc-generated-${packageName}`, From 1698570200d73fb76f3fa8758dc6735ae77b92aa Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 7 Jun 2024 06:44:05 -0400 Subject: [PATCH 08/16] Forked typedoc-plugin-no-inherit --- packages/ast-spec/src/ast-node-types.ts | 6 +- packages/website/docusaurus.config.mts | 1 + .../tools/typedoc-plugin-no-inherit-fork.mjs | 186 ++++++++++++++++++ 3 files changed, 190 insertions(+), 3 deletions(-) create mode 100644 packages/website/tools/typedoc-plugin-no-inherit-fork.mjs diff --git a/packages/ast-spec/src/ast-node-types.ts b/packages/ast-spec/src/ast-node-types.ts index 7a637489eb0d..050bc6f61f34 100644 --- 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/website/docusaurus.config.mts b/packages/website/docusaurus.config.mts index bf328f3e2b2d..93d651708267 100644 --- a/packages/website/docusaurus.config.mts +++ b/packages/website/docusaurus.config.mts @@ -332,6 +332,7 @@ const config: Config = { out: `../../docs/packages/${packageName}/generated`, outputFileStrategy: 'modules', parametersFormat: 'table', + plugin: [require.resolve('./tools/typedoc-plugin-no-inherit-fork.mjs')], propertiesFormat: 'table', readme: 'none', tsconfig: `../${packageName}/tsconfig.json`, diff --git a/packages/website/tools/typedoc-plugin-no-inherit-fork.mjs b/packages/website/tools/typedoc-plugin-no-inherit-fork.mjs new file mode 100644 index 000000000000..a174b28fdef8 --- /dev/null +++ b/packages/website/tools/typedoc-plugin-no-inherit-fork.mjs @@ -0,0 +1,186 @@ +/* eslint-disable @typescript-eslint/explicit-function-return-type, @typescript-eslint/no-unnecessary-condition, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/restrict-plus-operands */ +// Internal fork of https://github.com/jonchardy/typedoc-plugin-no-inherit, +// pending https://github.com/jonchardy/typedoc-plugin-no-inherit/issues/34 +// https://github.com/jonchardy/typedoc-plugin-no-inherit/tree/c799761733e31198107db87d33aea0e673a996c3 + +import { + Converter, + DeclarationReflection, + Reflection, + ReflectionKind, +} from 'typedoc'; + +export function load(app) { + new NoInheritPlugin().initialize(app); +} + +/** + * A handler that deals with inherited reflections. + */ +class NoInheritPlugin { + /** + * Create a new NoInheritPlugin instance. + */ + initialize(app) { + app.converter.on(Converter.EVENT_BEGIN, this.onBegin.bind(this)); + app.converter.on( + Converter.EVENT_CREATE_DECLARATION, + this.onDeclaration.bind(this), + null, + -1100, + ); // after ImplementsPlugin + app.converter.on( + Converter.EVENT_RESOLVE_BEGIN, + this.onBeginResolve.bind(this), + ); + this.logger = app.logger; + } + + /** + * Triggered when the converter begins converting a project. + * + * @param context The context object describing the current state the converter is in. + */ + onBegin() { + this.noInherit = []; + this.inheritedReflections = []; + } + + /** + * Triggered when the converter has created a declaration or signature reflection. + * + * Builds the list of classes/interfaces that don't inherit docs and + * the list of reflections that are inherited that could end up being removed. + * + * @param context The context object describing the current state the converter is in. + * @param reflection The reflection that is currently processed. + * @param node The node that is currently processed if available. + */ + onDeclaration(context, reflection) { + if (reflection instanceof DeclarationReflection) { + // class or interface that won't inherit docs + if ( + reflection.kindOf(ReflectionKind.ClassOrInterface) + // Fork: always add reflections, regardless of a @noInheritDoc tag + // && + // reflection.comment && + // reflection.comment.getTag('@noInheritDoc') + ) { + this.noInherit.push(reflection); + // Fork: we don't use the @noInheritDoc tag + // reflection.comment.removeTags('@noInheritDoc'); + } + // class or interface member inherited from a super + if ( + reflection.inheritedFrom && + reflection.parent && + reflection.parent.kindOf(ReflectionKind.ClassOrInterface) && + (!reflection.overwrites || + (reflection.overwrites && + reflection.overwrites !== reflection.inheritedFrom)) + ) { + this.inheritedReflections.push(reflection); + } + } + } + + /** + * Triggered when the converter begins resolving a project. + * + * Goes over the list of inherited reflections and removes any that are down the hierarchy + * from a class that doesn't inherit docs. + * + * @param context The context object describing the current state the converter is in. + */ + onBeginResolve(context) { + if (this.noInherit) { + const project = context.project; + const removals = []; + + this.inheritedReflections.forEach(reflection => { + // Look through the inheritance chain for a reflection that is flagged as noInherit for this reflection + if (this.isNoInheritRecursive(context, reflection, 0)) { + removals.push(reflection); + } + }); + + removals.forEach(removal => { + project.removeReflection(removal); + }); + } + } + + /** + * Checks whether some DeclarationReflection is in the noInherit list. + * @param search The DeclarationReflection to search for in the list. + */ + isNoInherit(search) { + if ( + this.noInherit.find(no => no.id === search.id && no.name === search.name) + ) { + return true; + } + return false; + } + + /** + * Checks whether some Reflection is in the inheritedReflections list. + * @param search The Reflection to search for in the list. + */ + isInherited(search) { + if ( + this.inheritedReflections.find( + inh => inh.id === search.id && inh.name === search.name, + ) + ) { + return true; + } + return false; + } + + /** + * Checks whether some reflection's inheritance chain is broken by a class or interface that doesn't inherit docs. + * @param context The context object describing the current state the converter is in. + * @param current The current reflection being evaluated for non-inheritance. + * @param depth The current recursion depth, used for stopping on excessively long inheritance chains. + */ + isNoInheritRecursive(context, current, depth) { + if (depth > 20) { + this.logger.warn( + `Found inheritance chain with depth > 20, stopping no inherit check: ${current.getFullName()}`, + ); + return false; // stop if we've recursed more than 20 times + } + + // As we move up the chain, check if the reflection parent is in the noInherit list + const parent = current.parent; + if (!parent) { + return false; + } + if ( + this.isNoInherit(parent) && + (depth === 0 || this.isInherited(current)) + ) { + return true; + } + + const checkExtended = type => { + const extended = type?.reflection; + if (extended instanceof Reflection) { + const upLevel = extended.getChildByName(current.name); + if (upLevel && this.isNoInheritRecursive(context, upLevel, depth + 1)) { + return true; + } + } + return false; + }; + + if (parent.extendedTypes) { + if (parent.extendedTypes.some(checkExtended)) { + return true; + } + } + + return false; + } +} From dda405a8504f4a8810d2bb6860ca95fc5834f888 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 7 Jun 2024 07:34:58 -0400 Subject: [PATCH 09/16] Undo unnecessary Linter.ts change --- packages/utils/src/ts-eslint/Linter.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/utils/src/ts-eslint/Linter.ts b/packages/utils/src/ts-eslint/Linter.ts index 163977525db0..8ea129409b8d 100644 --- a/packages/utils/src/ts-eslint/Linter.ts +++ b/packages/utils/src/ts-eslint/Linter.ts @@ -73,7 +73,7 @@ declare class LinterBase { * @param textOrSourceCode The text to parse or a SourceCode object. * @param config An ESLintConfig instance to configure everything. * @param filenameOrOptions The optional filename of the file being checked. - * If this is not set, the filename will default to (input) in the rule context. + * If this is not set, the filename will default to '' in the rule context. * If this is an object, then it has "filename", "allowInlineConfig", and some properties. * @returns The results as an array of messages or an empty array if no messages. */ From cf490b18579a460c9d974827b8c0f78752fa8c3b Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 7 Jun 2024 08:21:44 -0400 Subject: [PATCH 10/16] Fix up some examples to be true code blocks --- packages/ast-spec/src/base/ClassBase.ts | 7 ++++--- .../ExportNamedDeclaration/spec.ts | 6 ++++-- .../src/declaration/ImportDeclaration/spec.ts | 2 +- .../src/declaration/TSEnumDeclaration/spec.ts | 6 ++++-- .../TSImportEqualsDeclaration/spec.ts | 3 ++- .../declaration/TSModuleDeclaration/spec.ts | 9 +++++--- .../TSTypeAliasDeclaration/spec.ts | 3 ++- .../declaration/VariableDeclaration/spec.ts | 21 ++++++++++++------- 8 files changed, 37 insertions(+), 20 deletions(-) diff --git a/packages/ast-spec/src/base/ClassBase.ts b/packages/ast-spec/src/base/ClassBase.ts index b81c1ed77ef0..34f6d2a49e41 100644 --- a/packages/ast-spec/src/base/ClassBase.ts +++ b/packages/ast-spec/src/base/ClassBase.ts @@ -11,7 +11,7 @@ export interface ClassBase extends BaseNode { /** * Whether the class is an abstract class. * @example - * ``` + * ```ts * abstract class Foo {} * ``` */ @@ -22,7 +22,8 @@ export interface ClassBase extends BaseNode { body: ClassBody; /** * Whether the class has been `declare`d: - * ``` + * @example + * ```ts * declare class Foo {} * ``` */ @@ -30,7 +31,7 @@ export interface ClassBase extends BaseNode { /** * The decorators declared for the class. * @example - * ``` + * ```ts * @deco * class Foo {} * ``` diff --git a/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts b/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts index 4d0786d2d1e6..1047ffbb39a8 100644 --- a/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts @@ -29,7 +29,8 @@ interface ExportNamedDeclarationBase extends BaseNode { 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` @@ -45,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 index b9d305676808..6d08c80a7a35 100644 --- a/packages/ast-spec/src/declaration/ImportDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/ImportDeclaration/spec.ts @@ -19,7 +19,7 @@ export interface ImportDeclaration extends BaseNode { /** * The attributes declared for the export. * @example - * ``` + * ```ts * import * from 'mod' with \{ type: 'json' \}; * ``` */ diff --git a/packages/ast-spec/src/declaration/TSEnumDeclaration/spec.ts b/packages/ast-spec/src/declaration/TSEnumDeclaration/spec.ts index 35e522c2b026..fe1ae6d40b76 100644 --- a/packages/ast-spec/src/declaration/TSEnumDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/TSEnumDeclaration/spec.ts @@ -7,14 +7,16 @@ export interface TSEnumDeclaration extends BaseNode { type: AST_NODE_TYPES.TSEnumDeclaration; /** * Whether this is a `const` enum. - * ``` + * @example + * ```ts * const enum Foo {} * ``` */ const: boolean; /** * Whether this is a `declare`d enum. - * ``` + * @example + * ```ts * declare enum Foo {} * ``` */ diff --git a/packages/ast-spec/src/declaration/TSImportEqualsDeclaration/spec.ts b/packages/ast-spec/src/declaration/TSImportEqualsDeclaration/spec.ts index 15fd64f11ad1..eb8651b14063 100644 --- a/packages/ast-spec/src/declaration/TSImportEqualsDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/TSImportEqualsDeclaration/spec.ts @@ -13,7 +13,8 @@ export interface TSImportEqualsDeclaration 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 index 97319591f9e6..d1c91b3d0554 100644 --- a/packages/ast-spec/src/declaration/TSModuleDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/TSModuleDeclaration/spec.ts @@ -27,7 +27,8 @@ interface TSModuleDeclarationBase extends BaseNode { body?: TSModuleBlock; /** * Whether this is a global declaration - * ``` + * @example + * ```ts * declare global {} * ``` */ @@ -35,7 +36,8 @@ interface TSModuleDeclarationBase extends BaseNode { global: boolean; /** * Whether the module is `declare`d - * ``` + * @example + * ```ts * declare namespace F {} * ``` */ @@ -43,7 +45,8 @@ interface TSModuleDeclarationBase extends BaseNode { /** * 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 index 6d7232344b26..202fce6e7833 100644 --- 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; * ``` */ diff --git a/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts b/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts index 23a04b683248..a3e8afba2325 100644 --- a/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts @@ -11,7 +11,8 @@ export interface LetOrConstOrVarDeclaration extends BaseNode { /** * The variables declared by this declaration. * Note that there may be 0 declarations (i.e. `const;`). - * ``` + * @example + * ```ts * let x; * let y, z; * ``` @@ -20,14 +21,16 @@ export interface LetOrConstOrVarDeclaration extends BaseNode { declarations: LetOrConstOrVarDeclarator[]; /** * Whether the declaration is `declare`d - * ``` + * @example + * ```ts * declare const x = 1; * ``` */ declare: boolean; /** * The keyword used to declare the variable(s) - * ``` + * @example + * ```ts * const x = 1; * let y = 2; * var z = 3; @@ -41,7 +44,8 @@ export interface UsingInNormalContextDeclaration extends BaseNode { /** * The variables declared by this declaration. * Note that there may be 0 declarations (i.e. `const;`). - * ``` + * @example + * ```ts * using x = 1; * using y =1, z = 2; * ``` @@ -55,7 +59,8 @@ export interface UsingInNormalContextDeclaration extends BaseNode { declare: false; /** * The keyword used to declare the variable(s) - * ``` + * @example + * ```ts * using x = 1; * await using y = 2; * ``` @@ -68,7 +73,8 @@ export interface UsingInForOfDeclaration extends BaseNode { /** * The variables declared by this declaration. * Note that there may be 0 declarations (i.e. `const;`). - * ``` + * @example + * ```ts * for(using x of y){} * ``` */ @@ -81,7 +87,8 @@ export interface UsingInForOfDeclaration extends BaseNode { declare: false; /** * The keyword used to declare the variable(s) - * ``` + * @example + * ```ts * for(using x of y){} * for(await using x of y){} * ``` From 9fe744812b81520f46ab52680c9f1cda2441bee9 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 7 Jun 2024 08:44:14 -0400 Subject: [PATCH 11/16] fix lint for some reason --- packages/website/tools/generate-website-dts.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/website/tools/generate-website-dts.ts b/packages/website/tools/generate-website-dts.ts index 48b7d6fa1dc3..4806d5e2b750 100644 --- a/packages/website/tools/generate-website-dts.ts +++ b/packages/website/tools/generate-website-dts.ts @@ -33,7 +33,7 @@ async function getFileAndStoreLocally( const config = await prettier.resolveConfig(path); - let contents = await response.text(); + let contents = (await response.text()) as string; contents = [...banner, '', editFunc(contents)].join('\n'); contents = await prettier.format(contents, { parser: 'typescript', From 302181684866660201aba1e45dbefb97008406df Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 22 Jun 2024 13:08:34 -0700 Subject: [PATCH 12/16] Split up variable multiline examples --- .../ast-spec/src/declaration/VariableDeclaration/spec.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts b/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts index a3e8afba2325..6e2e2dd70fe9 100644 --- a/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts @@ -29,10 +29,17 @@ export interface LetOrConstOrVarDeclaration extends BaseNode { declare: boolean; /** * The keyword used to declare the variable(s) + * ``` * @example * ```ts * const x = 1; + * ``` + * @example + * ```ts * let y = 2; + * ``` + * @example + * ```ts * var z = 3; * ``` */ From 15c087057d9310a392ca1c6e21ac7a139ee8bd18 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 25 Jun 2024 01:52:24 -0400 Subject: [PATCH 13/16] Remove utils TypeDoc generation --- docs/packages/Utils.mdx | 8 -------- packages/website/docusaurus.config.mts | 2 +- 2 files changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/packages/Utils.mdx b/docs/packages/Utils.mdx index 014db4beb73c..1511d0733472 100644 --- a/docs/packages/Utils.mdx +++ b/docs/packages/Utils.mdx @@ -4,8 +4,6 @@ sidebar_label: utils toc_max_heading_level: 3 --- -import GeneratedDocs from './utils/generated/index.md'; - # `@typescript-eslint/utils` @@ -31,9 +29,3 @@ Any custom rules you write generally will be as well. | `TSESLint` | Types for ESLint, correctly typed to work with the types found in `TSESTree`. | | `TSESLintScope` | The [`eslint-scope`](https://www.npmjs.com/package/eslint-scope) package, correctly typed to work with the types found in both `TSESTree` and `TSESLint` | | `TSESTree` | Types for the TypeScript flavor of ESTree created by `@typescript-eslint/typescript-estree`. | - ---- - -The following documentation is auto-generated from source code. - - diff --git a/packages/website/docusaurus.config.mts b/packages/website/docusaurus.config.mts index 93d651708267..dbbcb8688fc6 100644 --- a/packages/website/docusaurus.config.mts +++ b/packages/website/docusaurus.config.mts @@ -318,7 +318,7 @@ const config: Config = { rules: rulesMeta, }, plugins: [ - ...['ast-spec', 'type-utils', 'utils'].map(packageName => [ + ...['ast-spec', 'type-utils'].map(packageName => [ 'docusaurus-plugin-typedoc', { entryPoints: [`../${packageName}/src/index.ts`], From fa89b9e3e8937ab1aa117ce1f3c944d710866b5b Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 20 Jul 2024 16:03:18 -0400 Subject: [PATCH 14/16] one example --- packages/ast-spec/src/element/TSEnumMember/spec.ts | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/packages/ast-spec/src/element/TSEnumMember/spec.ts b/packages/ast-spec/src/element/TSEnumMember/spec.ts index 17afc178df24..ba5b81a13b1a 100644 --- a/packages/ast-spec/src/element/TSEnumMember/spec.ts +++ b/packages/ast-spec/src/element/TSEnumMember/spec.ts @@ -18,15 +18,12 @@ interface TSEnumMemberBase extends BaseNode { /** * this should only really happen in semantically invalid code (errors 1164 and 2452) * - * VALID: * @example * ```ts + * // VALID: * enum Foo { ['a'] } - *``` * - * INVALID: - * @example - * ```ts + * // INVALID: * const x = 'a'; * enum Foo { [x] } * enum Bar { ['a' + 'b'] } From dd17e7a8414386ab40995c46eeb6a125b9073b76 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 29 Jul 2024 09:13:56 -0400 Subject: [PATCH 15/16] Fixed remaining example tags --- .../ast-spec/src/declaration/VariableDeclaration/spec.ts | 6 ------ 1 file changed, 6 deletions(-) diff --git a/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts b/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts index 6e2e2dd70fe9..d78c3203270c 100644 --- a/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts @@ -33,13 +33,7 @@ export interface LetOrConstOrVarDeclaration extends BaseNode { * @example * ```ts * const x = 1; - * ``` - * @example - * ```ts * let y = 2; - * ``` - * @example - * ```ts * var z = 3; * ``` */ From e73bc3f694a7330df12bbb5104a5993b6b3194d0 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 29 Jul 2024 09:14:08 -0400 Subject: [PATCH 16/16] Fixed remaining example tags --- packages/ast-spec/src/declaration/VariableDeclaration/spec.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts b/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts index d78c3203270c..a3e8afba2325 100644 --- a/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts +++ b/packages/ast-spec/src/declaration/VariableDeclaration/spec.ts @@ -29,7 +29,6 @@ export interface LetOrConstOrVarDeclaration extends BaseNode { declare: boolean; /** * The keyword used to declare the variable(s) - * ``` * @example * ```ts * const x = 1;