Skip to content

Documentation for AST node types #2726

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
3 tasks done
paulius-valiunas opened this issue Oct 30, 2020 · 3 comments · Fixed by #9293
Closed
3 tasks done

Documentation for AST node types #2726

paulius-valiunas opened this issue Oct 30, 2020 · 3 comments · Fixed by #9293
Assignees
@Josh-Cena
Labels
accepting prs Go ahead, send a pull request that resolves this issue documentation Documentation ("docs") that needs adding/updating locked due to age Please open a new issue if you'd like to say more. See https://typescript-eslint.io/contributing. package: ast-spec Issues related to @typescript-eslint/ast-spec

Comments

@paulius-valiunas
Copy link

  • I have tried restarting my IDE and the issue persists.
  • I have updated to the latest version of the packages.
  • I have read the FAQ and my problem is not listed.

Repro

not applicable

Expected Result

not applicable

Actual Result

not applicable

Additional Info

This is a meta issue about documentation.

I couldn't find any information about the AST node types, especially the ones that are Typescript-specific. For example, if I'm extending a rule and I come across a place where it's dealing with TSTypeParameterInstantiation - how do I know what that means? Ideally, it would be great to have a gallery with code snippets (examples) for every available node type. I know that's a great effort, but even starting to add some JSDoc comments with very brief explanations or short snippets to the code would help a lot.

Here's an example of what I'm thinking of:

Before

export interface CallExpression extends CallExpressionBase {
  type: AST_NODE_TYPES.CallExpression;
}

After

/**
 * A function/method call.
 * @example function1<Type1>(arg1);
 */
export interface CallExpression extends CallExpressionBase {
  type: AST_NODE_TYPES.CallExpression;
}

Of course, that's an easy example, everyone knows what a call expression is. But for more complex types, this would make writing rules significantly easier.

Versions

package version
@typescript-eslint/typescript-estree 4.6.0
TypeScript 3.4.3
node 12.19.0
@paulius-valiunas paulius-valiunas added package: typescript-estree Issues related to @typescript-eslint/typescript-estree triage Waiting for team members to take a look labels Oct 30, 2020
@bradzacher bradzacher added documentation Documentation ("docs") that needs adding/updating and removed triage Waiting for team members to take a look labels Oct 30, 2020
@bradzacher
Copy link
Member

This is something that has been on my radar for quite some time.
My plan was to:

  • refactor the parser to isolate the node converters
  • colocate the fixtures + snapshots with the isolated node converters
  • include a markdown file explaining each node and the cases in which it occurs.

It's just that it's going to take quite some time to do this and document every single AST node.
Essentially we'd be documenting the entire TS AST from scratch (TS itself doesn't even have that!), so yeah definitely not a small piece of work.

In the interim - I have found that the best way to see when a specific AST Node can occur is by grepping through our snapshots: https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/typescript-estree/tests/snapshots

The snapshots are the output of every single fixture test and have names matching the fixture file.

bradzacher added a commit that referenced this issue Jan 2, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
df02888 
Fixes #2726

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and it was intimidating to look at.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- (in a future PR)
    - We can easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - We can colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
@bradzacher bradzacher mentioned this issue Jan 2, 2021
Merged
5 tasks
bradzacher added a commit that referenced this issue Jan 2, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
6e593a6 
Fixes #2726

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and it was intimidating to look at.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- (in a future PR)
    - We can easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - We can colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Jan 2, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
86c57ab 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Jan 2, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
2be09bf 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Jan 2, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
f8b983b 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Jan 3, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
dc7e3cb 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Jan 4, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
43d7bc4 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Jan 4, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
36c8a52 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Mar 30, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
c3b4cc1 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Mar 30, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
3b25794 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Mar 30, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
1803d71 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Mar 30, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
9b03bb0 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Mar 30, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
07860e0 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue Mar 31, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
f69c8ef 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue May 4, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
3f04cd5 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
bradzacher added a commit that referenced this issue May 4, 2021
@bradzacher
feat: refactor to split AST specification out as its own module
a5f8933 
Fixes #2726
Fixes #2912

This PR is the basis for a big cleanup and reorganisation of the AST.
This first step takes the file `types/src/ts-estree.ts` and splits it up in its entirety.
This file was a monolith at 1700 lines - meaning it was a pain to organise and manage, and there was no way to isolate/restrict certain things (aside from adding comments).

This PR should ultimately be a no-op - there should be no breaking changes here.
I did fix up a number of types which I found when organising files into their folders.

Whilst this PR ultimately creates more LOC, the isolation enables a few things:
- By splitting the AST into its own module, it's isolated so easier to manage / govern
- By splitting each AST node into its own folder we can cleanly document and link to individual node specs
- By grouping nodes decls by folder, it's easier to inspect the types to validate unions are correct.
    - I found a number of invalid nodes in unions in this PR which have been fixed.
- In a future PR we can:
    - Add lint rule(s) to validate unions are correct (eg ensure all `Expression` types are included in the `Expression` union).
    - Easily add documentation about the node without cluttering things up
    - Colocate fixtures/snapshots with the node specs to document the cases that we expect a node to show up
    - Colocate the conversion logic here so that it's easier to validate that the spec and the conversion logic are in sync
        - This will make it much easier to implement and maintain #1852
@JoshuaKGoldberg JoshuaKGoldberg moved this to Todo in Documentation Nov 9, 2021
@JoshuaKGoldberg JoshuaKGoldberg added the accepting prs Go ahead, send a pull request that resolves this issue label Feb 24, 2022
@JoshuaKGoldberg JoshuaKGoldberg mentioned this issue May 26, 2022
Merged
@JoshuaKGoldberg JoshuaKGoldberg mentioned this issue Dec 26, 2023
Open
2 tasks
@Josh-Cena Josh-Cena added package: ast-spec Issues related to @typescript-eslint/ast-spec and removed package: typescript-estree Issues related to @typescript-eslint/typescript-estree labels Jun 4, 2024
@Josh-Cena Josh-Cena self-assigned this Jun 4, 2024
This was referenced Jun 6, 2024
Closed
Merged
Open
@github-project-automation github-project-automation bot moved this from Todo to Done in Documentation Jul 29, 2024
@paulius-valiunas
Copy link
Author

It's nice to finally have online documentation for the properties of each interface, but it's still difficult to map an interface to a code snippet, which was the primary concern of this issue. As in the example I originally wrote in the issue description, TSTypeParameterInstantiation still doesn't provide any information about how to recognize this AST node in code. If a developer wants to be efficient at working with the AST (e.g. writing ESLint rules), they have to be able to:

  1. Upon seeing a code snippet, understand what AST nodes it comprises. This can currently be done with the help of https://astexplorer.net/
  2. Upon encountering an AST type, visualize it as a code snippet in their mind.

Both can be done with the help of a debugger, or simply "printf-debugging", but that significantly slows down any development effort until the developer memorizes the bigger part of the AST types after applying them in practice multiple times. Having some reference material to help deal with problem no.1 would be tremendously helpful. As per @bradzacher's suggestion, I'm able to search through this repo and find a snapshot containing the type I need and then map it to the corresponding snippet, but unfortunately that is a time-consuming process and it would be much more helpful to have each interface in the documentation (or at least some of them) link to a minimal example snippet.

@JoshuaKGoldberg JoshuaKGoldberg mentioned this issue Jul 30, 2024
Open
2 tasks
@JoshuaKGoldberg
Copy link
Member

Good point, thanks - filed #9671 as a followup. 👍

@github-actions github-actions bot added the locked due to age Please open a new issue if you'd like to say more. See https://typescript-eslint.io/contributing. label Aug 7, 2024
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 7, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@Josh-Cena Josh-Cena

Labels
accepting prs Go ahead, send a pull request that resolves this issue documentation Documentation ("docs") that needs adding/updating locked due to age Please open a new issue if you'd like to say more. See https://typescript-eslint.io/contributing. package: ast-spec Issues related to @typescript-eslint/ast-spec
Projects
No open projects
Documentation
Status: Done
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

docs: add ast-spec, type-utils docs with docusaurus-plugin-typedoc JoshuaKGoldberg/typescript-eslint
4 participants
@JoshuaKGoldberg @bradzacher @Josh-Cena @paulius-valiunas