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

Part of #5870
oxc-project · Sep 22, 2024 · 47c2faa · 47c2faa
1 parent 612f638
commit 47c2faa
Show file tree

Hide file tree

Showing 2 changed files with 76 additions and 18 deletions.
diff --git a/crates/oxc_ast/src/ast/js.rs b/crates/oxc_ast/src/ast/js.rs
@@ -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)]

diff --git a/crates/oxc_ast/src/generated/ast_builder.rs b/crates/oxc_ast/src/generated/ast_builder.rs
@@ -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,