Skip to content

[WIP] Improve documentation of AST #12763

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

Closed
Copilot wants to merge 4 commits into from
Closed

[WIP] Improve documentation of AST #12763

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1a77bd6
Initial plan
Copilot Aug 2, 2025
d4f85c6
Fix inconsistent formatting in AST documentation
Copilot Aug 2, 2025
1b7ebea
Complete formatting fixes in TypeScript AST documentation
Copilot Aug 2, 2025
3a1e5eb
Changes before error encountered
Copilot Aug 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 41 additions & 43 deletions crates/oxc_ast/src/ast/js.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ pub struct IdentifierName<'a> {

/// `x` inside `func` in `const x = 0; function func() { console.log(x); }`
///
/// Represents an identifier reference, which is a reference to a variable, function, class, or object.
/// Represents an identifier reference.
///
/// See: [13.1 Identifiers](https://tc39.es/ecma262/#sec-identifiers)
#[ast(visit)]
Expand All @@ -251,8 +251,7 @@ pub struct IdentifierReference<'a> {

/// `x` in `const x = 0;`
///
/// Represents a binding identifier, which is an identifier that is used to declare a variable,
/// function, class, or object.
/// Represents a binding identifier.
///
/// See: [13.1 Identifiers](https://tc39.es/ecma262/#sec-identifiers)
///
Expand Down Expand Up @@ -281,7 +280,7 @@ pub struct BindingIdentifier<'a> {

/// `loop` in `loop: while (true) { break loop; }`
///
/// Represents a label identifier, which is an identifier that is used to label a statement.
/// Represents a label identifier.
///
/// See: [13.1 Identifiers](https://tc39.es/ecma262/#sec-identifiers)
#[ast(visit)]
Expand Down Expand Up @@ -343,7 +342,7 @@ pub enum ArrayExpressionElement<'a> {

/// empty slot in `const array = [1, , 2];`
///
/// Array Expression Elision Element
/// Array expression elision element
#[ast(visit)]
#[derive(Debug, Clone)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand Down Expand Up @@ -394,7 +393,7 @@ pub struct ObjectProperty<'a> {
}

inherit_variants! {
/// Property Key
/// Property key
///
/// Inherits variants from [`Expression`]. See [`ast` module docs] for explanation of inheritance.
///
Expand Down Expand Up @@ -679,7 +678,7 @@ pub struct UpdateExpression<'a> {

/// `typeof` in `typeof a === "string"`
///
/// Represents a unary expression, which includes an operator and an argument.
/// Represents a unary expression.
/// The following syntaxes are supported: `+a`, `-a`, `~a`, `!a`, `delete a`, `void a`, `typeof a`.
#[ast(visit)]
#[derive(Debug)]
Expand Down Expand Up @@ -717,7 +716,7 @@ pub struct PrivateInExpression<'a> {

/// `||` in `const foo = bar || 2;`
///
/// Represents a logical expression, which includes a left expression, an operator, and a right expression.
/// Represents a logical expression.
/// The following syntaxes are supported: `||`, `&&` and `??`.
#[ast(visit)]
#[derive(Debug)]
Expand All @@ -731,7 +730,7 @@ pub struct LogicalExpression<'a> {

/// `bar ? 1 : 2` in `const foo = bar ? 1 : 2;`
///
/// Represents a conditional expression, which includes a test, a consequent, and an alternate.
/// Represents a conditional expression.
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -744,7 +743,7 @@ pub struct ConditionalExpression<'a> {

/// `foo = 1` in `let foo; foo = 1;`
///
/// Represents an assignment expression, which includes an operator, a target, and an expression.
/// Represents an assignment expression.
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -756,7 +755,7 @@ pub struct AssignmentExpression<'a> {
}

inherit_variants! {
/// Destructuring Assignment
/// Destructuring assignment
///
/// Inherits variants from [`SimpleAssignmentTarget`] and [`AssignmentTargetPattern`].
/// See [`ast` module docs] for explanation of inheritance.
Expand All @@ -774,7 +773,7 @@ pub enum AssignmentTarget<'a> {
}

inherit_variants! {
/// Simple Assignment Target
/// Simple assignment target
///
/// Inherits variants from [`MemberExpression`]. See [`ast` module docs] for explanation of inheritance.
///
Expand Down Expand Up @@ -900,7 +899,7 @@ pub struct AssignmentTargetRest<'a> {
}

inherit_variants! {
/// Assignment Target Maybe Default
/// Assignment target maybe default
///
/// Inherits variants from [`AssignmentTarget`]. See [`ast` module docs] for explanation of inheritance.
///
Expand Down Expand Up @@ -941,8 +940,7 @@ pub enum AssignmentTargetProperty<'a> {

/// `foo` in `({ foo } = obj);`
///
/// Represents an assignment target property identifier, which includes a binding,
/// and an optional init expression.
/// Represents an assignment target property identifier.
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -961,7 +959,7 @@ pub struct AssignmentTargetPropertyIdentifier<'a> {

/// `foo: bar` in `({ foo: bar } = obj);`
///
/// Represents an assignment target property property, which includes a name and a binding.
/// Represents an assignment target property property.
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand Down Expand Up @@ -1034,7 +1032,7 @@ pub struct ChainExpression<'a> {
}

inherit_variants! {
/// Chain Element
/// Chain element
///
/// Inherits variants from [`MemberExpression`]. See [`ast` module docs] for explanation of inheritance.
///
Expand Down Expand Up @@ -1138,7 +1136,7 @@ pub struct BlockStatement<'a> {
pub scope_id: Cell<Option<ScopeId>>,
}

/// Declarations and the Variable Statement
/// Declarations and the `VariableStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, GetAddress, ContentEq, ESTree)]
Expand Down Expand Up @@ -1197,7 +1195,7 @@ pub enum VariableDeclarationKind {
AwaitUsing = 4,
}

/// A single variable declaration in a list of [variable declarations](VariableDeclaration).
/// A single variable declaration in a list of [`VariableDeclaration`]s.
///
/// ## Examples
/// ```ts
Expand All @@ -1218,15 +1216,15 @@ pub struct VariableDeclarator<'a> {
pub definite: bool,
}

/// Empty Statement
/// `EmptyStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
pub struct EmptyStatement {
pub span: Span,
}

/// Expression Statement
/// `ExpressionStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -1236,7 +1234,7 @@ pub struct ExpressionStatement<'a> {
pub expression: Expression<'a>,
}

/// If Statement
/// `IfStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -1257,7 +1255,7 @@ pub struct DoWhileStatement<'a> {
pub test: Expression<'a>,
}

/// While Statement
/// `WhileStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -1267,7 +1265,7 @@ pub struct WhileStatement<'a> {
pub body: Statement<'a>,
}

/// For Statement
/// `ForStatement`
#[ast(visit)]
#[scope]
#[derive(Debug)]
Expand All @@ -1282,7 +1280,7 @@ pub struct ForStatement<'a> {
}

inherit_variants! {
/// For Statement Init
/// `ForStatementInit`
///
/// Inherits variants from [`Expression`]. See [`ast` module docs] for explanation of inheritance.
///
Expand Down Expand Up @@ -1311,7 +1309,7 @@ pub struct ForInStatement<'a> {
}

inherit_variants! {
/// For Statement Left
/// `ForStatementLeft`
///
/// Inherits variants from [`AssignmentTarget`]. See [`ast` module docs] for explanation of inheritance.
///
Expand Down Expand Up @@ -1340,7 +1338,7 @@ pub struct ForOfStatement<'a> {
pub scope_id: Cell<Option<ScopeId>>,
}

/// Continue Statement
/// `ContinueStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -1349,7 +1347,7 @@ pub struct ContinueStatement<'a> {
pub label: Option<LabelIdentifier<'a>>,
}

/// Break Statement
/// `BreakStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -1358,7 +1356,7 @@ pub struct BreakStatement<'a> {
pub label: Option<LabelIdentifier<'a>>,
}

/// Return Statement
/// `ReturnStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -1367,7 +1365,7 @@ pub struct ReturnStatement<'a> {
pub argument: Option<Expression<'a>>,
}

/// With Statement
/// `WithStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -1377,7 +1375,7 @@ pub struct WithStatement<'a> {
pub body: Statement<'a>,
}

/// Switch Statement
/// `SwitchStatement`
#[ast(visit)]
#[scope]
#[derive(Debug)]
Expand All @@ -1399,7 +1397,7 @@ pub struct SwitchCase<'a> {
pub consequent: Vec<'a, Statement<'a>>,
}

/// Labelled Statement
/// `LabeledStatement`
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
Expand All @@ -1409,7 +1407,7 @@ pub struct LabeledStatement<'a> {
pub body: Statement<'a>,
}

/// Throw Statement
/// `ThrowStatement`
///
/// # Example
/// ```ts
Expand All @@ -1425,7 +1423,7 @@ pub struct ThrowStatement<'a> {
pub argument: Expression<'a>,
}

/// Try Statement
/// `TryStatement`
///
/// # Example
/// ```ts
Expand Down Expand Up @@ -1453,7 +1451,7 @@ pub struct TryStatement<'a> {
pub finalizer: Option<Box<'a, BlockStatement<'a>>>,
}

/// Catch Clause in a [`try/catch` statement](TryStatement).
/// Catch Clause in a [`TryStatement`].
///
/// This node creates a new scope inside its `body`.
///
Expand All @@ -1478,7 +1476,7 @@ pub struct CatchClause<'a> {
pub scope_id: Cell<Option<ScopeId>>,
}

/// A caught error parameter in a [catch clause](CatchClause).
/// A caught error parameter in a [`CatchClause`].
///
/// # Examples
///
Expand All @@ -1503,7 +1501,7 @@ pub struct CatchParameter<'a> {
pub pattern: BindingPattern<'a>,
}

/// Debugger Statement
/// `DebuggerStatement`
///
/// # Example
/// ```ts
Expand Down Expand Up @@ -1661,7 +1659,7 @@ pub struct ArrayPattern<'a> {
pub rest: Option<Box<'a, BindingRestElement<'a>>>,
}

/// A `...rest` binding in an [array](ArrayPattern) or [object](ObjectPattern) destructure.
/// A `...rest` binding in an [`ArrayPattern`] or [`ObjectPattern`] destructure.
///
/// ## Examples
/// ```ts
Expand All @@ -1683,7 +1681,7 @@ pub struct BindingRestElement<'a> {
pub argument: BindingPattern<'a>,
}

/// Function Statement or Expression
/// Function statement or expression
///
/// Includes generator functions and function-valued class properties.
/// Arrow functions are represented by [`ArrowFunctionExpression`].
Expand Down Expand Up @@ -2565,7 +2563,7 @@ pub enum ImportAttributeKey<'a> {
StringLiteral(StringLiteral<'a>) = 1,
}

/// Named Export Declaration
/// Named export declaration
///
/// ## Example
///
Expand All @@ -2592,7 +2590,7 @@ pub struct ExportNamedDeclaration<'a> {
pub with_clause: Option<Box<'a, WithClause<'a>>>,
}

/// Export Default Declaration
/// Export default declaration
///
/// ## Example
///
Expand All @@ -2612,7 +2610,7 @@ pub struct ExportDefaultDeclaration<'a> {
pub declaration: ExportDefaultDeclarationKind<'a>,
}

/// Export All Declaration
/// Export all declaration
///
/// ## Example
///
Expand Down Expand Up @@ -2663,7 +2661,7 @@ pub struct ExportSpecifier<'a> {
}

inherit_variants! {
/// Export Default Declaration Kind
/// Export default declaration kind
///
/// Inherits variants from [`Expression`]. See [`ast` module docs] for explanation of inheritance.
///
Expand Down
Loading