dan/oxc
1
0
Fork 0
mirror of https://github.com/danbulant/oxc synced 2026-05-19 12:19:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(ast): document TryStatement and related nodes (#5970)

Browse source 
Part of #5870
This commit is contained in:
DonIsaac 2024-09-22 15:54:27 +00:00
parent 612f638bcd
commit 47c2faa7a9
2 changed files with 76 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
crates/oxc_ast/src/ast/js.rs
View file

@ -1511,6 +1511,12 @@ pub struct LabeledStatement<'a> {
}
/// Throw Statement
///
/// # Example
/// ```ts
/// throw new Error('something went wrong!');
/// // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ argument
/// ```
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ContentHash)]
@ -1519,10 +1525,25 @@ pub struct LabeledStatement<'a> {
pub struct ThrowStatement<'a> {
#[serde(flatten)]
pub span: Span,
/// The expression being thrown, e.g. `err` in `throw err;`
pub argument: Expression<'a>,
}
/// Try Statement
///
/// # Example
/// ```ts
/// var x;
/// let didRun = false;
///
/// try { // block
/// x = 1;
/// } catch (e) { // handler
/// console.error(e);
/// } finally { // finalizer
/// didRun = true;
/// }
/// ```
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ContentHash)]
@ -1531,12 +1552,27 @@ pub struct ThrowStatement<'a> {
pub struct TryStatement<'a> {
#[serde(flatten)]
pub span: Span,
/// Statements in the `try` block
pub block: Box<'a, BlockStatement<'a>>,
/// The `catch` clause, including the parameter and the block statement
pub handler: Option<Box<'a, CatchClause<'a>>>,
/// The `finally` clause
#[visit(as(FinallyClause))]
pub finalizer: Option<Box<'a, BlockStatement<'a>>>,
}
/// Catch Clause in a [`try/catch` statement](TryStatement).
///
/// This node creates a new scope inside its `body`.
///
/// # Example
/// ```ts
/// try {
/// throw new Error('foo');
/// } catch (e) { // `param` is `e`
/// console.error(e); // `body`
/// }
/// ```
#[ast(visit)]
#[scope(flags(ScopeFlags::CatchClause))]
#[derive(Debug)]
@ -1546,13 +1582,28 @@ pub struct TryStatement<'a> {
pub struct CatchClause<'a> {
#[serde(flatten)]
pub span: Span,
/// The caught error parameter, e.g. `e` in `catch (e) {}`
pub param: Option<CatchParameter<'a>>,
/// The statements run when an error is caught
pub body: Box<'a, BlockStatement<'a>>,
#[serde(skip)]
#[clone_in(default)]
pub scope_id: Cell<Option<ScopeId>>,
}
/// A caught error parameter in a [catch clause](CatchClause).
///
/// # Examples
///
/// ```ts
/// try {} catch (err) {}
/// // ^^^ pattern
/// ```
///
/// ```ts
/// try {} catch ({ err }) {}
/// // ^^^^^^^ pattern
/// ```
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ContentHash)]
@ -1561,10 +1612,17 @@ pub struct CatchClause<'a> {
pub struct CatchParameter<'a> {
#[serde(flatten)]
pub span: Span,
/// The bound error
pub pattern: BindingPattern<'a>,
}
/// Debugger Statement
///
/// # Example
/// ```ts
/// let x = 1;
/// debugger; // <--
/// ```
#[ast(visit)]
#[derive(Debug)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ContentHash)]

36
crates/oxc_ast/src/generated/ast_builder.rs
View file

@ -3925,7 +3925,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - argument
/// - argument: The expression being thrown, e.g. `err` in `throw err;`
#[inline]
pub fn statement_throw(self, span: Span, argument: Expression<'a>) -> Statement<'a> {
Statement::ThrowStatement(self.alloc(self.throw_statement(span, argument)))
@ -3946,9 +3946,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - block
/// - handler
/// - finalizer
/// - block: Statements in the `try` block
/// - handler: The `catch` clause, including the parameter and the block statement
/// - finalizer: The `finally` clause
#[inline]
pub fn statement_try<T1, T2, T3>(
self,
@ -5183,7 +5183,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - argument
/// - argument: The expression being thrown, e.g. `err` in `throw err;`
#[inline]
pub fn throw_statement(self, span: Span, argument: Expression<'a>) -> ThrowStatement<'a> {
ThrowStatement { span, argument }
@ -5195,7 +5195,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - argument
/// - argument: The expression being thrown, e.g. `err` in `throw err;`
#[inline]
pub fn alloc_throw_statement(
self,
@ -5211,9 +5211,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - block
/// - handler
/// - finalizer
/// - block: Statements in the `try` block
/// - handler: The `catch` clause, including the parameter and the block statement
/// - finalizer: The `finally` clause
#[inline]
pub fn try_statement<T1, T2, T3>(
self,
@ -5241,9 +5241,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - block
/// - handler
/// - finalizer
/// - block: Statements in the `try` block
/// - handler: The `catch` clause, including the parameter and the block statement
/// - finalizer: The `finally` clause
#[inline]
pub fn alloc_try_statement<T1, T2, T3>(
self,
@ -5266,8 +5266,8 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - param
/// - body
/// - param: The caught error parameter, e.g. `e` in `catch (e) {}`
/// - body: The statements run when an error is caught
#[inline]
pub fn catch_clause<T1>(
self,
@ -5292,8 +5292,8 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - param
/// - body
/// - param: The caught error parameter, e.g. `e` in `catch (e) {}`
/// - body: The statements run when an error is caught
#[inline]
pub fn alloc_catch_clause<T1>(
self,
@ -5313,7 +5313,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - pattern
/// - pattern: The bound error
#[inline]
pub fn catch_parameter(self, span: Span, pattern: BindingPattern<'a>) -> CatchParameter<'a> {
CatchParameter { span, pattern }
@ -5325,7 +5325,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - pattern
/// - pattern: The bound error
#[inline]
pub fn alloc_catch_parameter(
self,