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

docs(ast): more doc comments for JSX nodes (#4830)

Browse source
This commit is contained in:
DonIsaac 2024-08-12 01:11:53 +00:00
parent 89712f5a24
commit 8827659a84
2 changed files with 117 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
crates/oxc_ast/src/ast/jsx.rs
View file

@ -44,8 +44,11 @@ use super::{inherit_variants, js::*, literal::*, ts::*};
pub struct JSXElement<'a> {
#[serde(flatten)]
pub span: Span,
/// Opening tag of the element.
pub opening_element: Box<'a, JSXOpeningElement<'a>>,
/// Closing tag of the element. Will be [`None`] for self-closing tags.
pub closing_element: Option<Box<'a, JSXClosingElement<'a>>>,
/// Children of the element. This can be text, other elements, or expressions.
pub children: Vec<'a, JSXChild<'a>>,
}
@ -89,7 +92,15 @@ pub struct JSXOpeningElement<'a> {
/// JSX Closing Element
///
/// Closing tag in a [`JSXElement`]. Not all JSX elements have a closing tag.
/// Closing tag in a [`JSXElement`]. Self-closing tags do not have closing elements.
///
/// ## Example
///
/// ```tsx
/// <Foo>Hello, World!</Foo>
/// // ^^^ name
/// <Bar /> // <- no closing element
/// ```
#[ast(visit)]
#[derive(Debug, Hash)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut)]
@ -117,8 +128,11 @@ pub struct JSXClosingElement<'a> {
pub struct JSXFragment<'a> {
#[serde(flatten)]
pub span: Span,
/// `<>`
pub opening_fragment: JSXOpeningFragment,
/// `</>`
pub closing_fragment: JSXClosingFragment,
/// Elements inside the fragment.
pub children: Vec<'a, JSXChild<'a>>,
}
@ -240,6 +254,7 @@ pub enum JSXMemberExpressionObject<'a> {
pub struct JSXExpressionContainer<'a> {
#[serde(flatten)]
pub span: Span,
/// The expression inside the container.
pub expression: JSXExpression<'a>,
}
@ -276,21 +291,35 @@ pub struct JSXEmptyExpression {
// 1.3 JSX Attributes
/// JSX Attributes
///
/// ## Example
///
/// ```tsx
/// <Component foo="bar" baz={4} {...rest} />
/// // ^^^^^^^^^ ^^^^^^^ ^^^^^^^^^
/// // Attribute SpreadAttribute
/// ```
#[ast(visit)]
#[derive(Debug, Hash)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut)]
#[cfg_attr(feature = "serialize", derive(Serialize, Tsify))]
#[serde(untagged)]
pub enum JSXAttributeItem<'a> {
/// A `key="value"` attribute
Attribute(Box<'a, JSXAttribute<'a>>) = 0,
/// a `{...spread}` attribute
SpreadAttribute(Box<'a, JSXSpreadAttribute<'a>>) = 1,
}
/// JSX Attribute
///
/// An attribute in a JSX opening tag. May or may not have a value. Part of
/// [`JSXAttributeItem`].
///
/// ## Example
///
/// ```tsx
/// // `has-no-value` is a JSXAttribute with no value.
/// <Component has-no-value foo="foo" />
/// // name ^^^ ^^^^ value
#[ast(visit)]
@ -301,7 +330,11 @@ pub enum JSXAttributeItem<'a> {
pub struct JSXAttribute<'a> {
#[serde(flatten)]
pub span: Span,
/// The name of the attribute. This is a prop in React-like applications.
pub name: JSXAttributeName<'a>,
/// The value of the attribute. This can be a string literal, an expression,
/// or an element. Will be [`None`] for boolean-like attributes (e.g.
/// `<button disabled />`).
pub value: Option<JSXAttributeValue<'a>>,
}
@ -326,19 +359,48 @@ pub struct JSXSpreadAttribute<'a> {
/// JSX Attribute Name
///
/// Part of a [`JSXAttribute`].
///
/// "Normal" attributes will be a [`JSXIdentifier`], while namespaced attributes
/// will be a [`JSXNamespacedName`].
///
/// ## Example
///
/// ```tsx
/// const Foo = <Component foo="bar" />;
/// // ^^^ Identifier
/// const Bar = <Component foo:bar="baz" />;
/// // ^^^^^^^ NamespacedName
/// ```
#[ast(visit)]
#[derive(Debug, Hash)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut)]
#[cfg_attr(feature = "serialize", derive(Serialize, Tsify))]
#[serde(untagged)]
pub enum JSXAttributeName<'a> {
/// An attribute name without a namespace prefix, e.g. `foo` in `foo="bar"`.
Identifier(Box<'a, JSXIdentifier<'a>>) = 0,
/// An attribute name with a namespace prefix, e.g. `foo:bar` in `foo:bar="baz"`.
NamespacedName(Box<'a, JSXNamespacedName<'a>>) = 1,
}
/// JSX Attribute Value
///
/// Part of a [`JSXAttribute`].
///
/// You're most likely interested in [`StringLiteral`] and
/// [`JSXExpressionContainer`].
///
/// ## Example
///
/// ```tsx
/// // v ExpressionContainer storing a NumericLiteral
/// <Component foo="bar" baz={4} />
/// // ^^^ StringLiteral
///
/// // not a very common case, but it is valid syntax. Could also be a fragment.
/// <Component foo=<Element /> />
/// // ^^^^^^^^^^^ Element
/// ```
#[ast(visit)]
#[derive(Debug, Hash)]
#[generate_derive(CloneIn, GetSpan, GetSpanMut)]
@ -364,6 +426,7 @@ pub enum JSXAttributeValue<'a> {
pub struct JSXIdentifier<'a> {
#[serde(flatten)]
pub span: Span,
/// The name of the identifier.
pub name: Atom<'a>,
}
@ -401,6 +464,7 @@ pub enum JSXChild<'a> {
pub struct JSXSpreadChild<'a> {
#[serde(flatten)]
pub span: Span,
/// The expression being spread.
pub expression: Expression<'a>,
}
@ -422,5 +486,6 @@ pub struct JSXSpreadChild<'a> {
pub struct JSXText<'a> {
#[serde(flatten)]
pub span: Span,
/// The text content.
pub value: Atom<'a>,
}

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

@ -1243,9 +1243,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_element
/// - closing_element
/// - children
/// - opening_element: Opening tag of the element.
/// - closing_element: Closing tag of the element. Will be [`None`] for self-closing tags.
/// - children: Children of the element. This can be text, other elements, or expressions.
#[inline]
pub fn expression_jsx_element<T1, T2>(
self,
@ -1281,9 +1281,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_fragment
/// - closing_fragment
/// - children
/// - opening_fragment: `<>`
/// - closing_fragment: `</>`
/// - children: Elements inside the fragment.
#[inline]
pub fn expression_jsx_fragment(
self,
@ -12670,9 +12670,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_element
/// - closing_element
/// - children
/// - opening_element: Opening tag of the element.
/// - closing_element: Closing tag of the element. Will be [`None`] for self-closing tags.
/// - children: Children of the element. This can be text, other elements, or expressions.
#[inline]
pub fn jsx_element<T1, T2>(
self,
@ -12699,9 +12699,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_element
/// - closing_element
/// - children
/// - opening_element: Opening tag of the element.
/// - closing_element: Closing tag of the element. Will be [`None`] for self-closing tags.
/// - children: Children of the element. This can be text, other elements, or expressions.
#[inline]
pub fn alloc_jsx_element<T1, T2>(
self,
@ -12817,9 +12817,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_fragment
/// - closing_fragment
/// - children
/// - opening_fragment: `<>`
/// - closing_fragment: `</>`
/// - children: Elements inside the fragment.
#[inline]
pub fn jsx_fragment(
self,
@ -12837,9 +12837,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_fragment
/// - closing_fragment
/// - children
/// - opening_fragment: `<>`
/// - closing_fragment: `</>`
/// - children: Elements inside the fragment.
#[inline]
pub fn alloc_jsx_fragment(
self,
@ -12860,7 +12860,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - name
/// - name: The name of the identifier.
#[inline]
pub fn jsx_element_name_jsx_identifier<A>(self, span: Span, name: A) -> JSXElementName<'a>
where
@ -13014,7 +13014,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - name
/// - name: The name of the identifier.
#[inline]
pub fn jsx_member_expression_object_jsx_identifier<A>(
self,
@ -13077,7 +13077,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - expression
/// - expression: The expression inside the container.
#[inline]
pub fn jsx_expression_container(
self,
@ -13093,7 +13093,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - expression
/// - expression: The expression inside the container.
#[inline]
pub fn alloc_jsx_expression_container(
self,
@ -13154,8 +13154,8 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - name
/// - value
/// - name: The name of the attribute. This is a prop in React-like applications.
/// - value: The value of the attribute. This can be a string literal, an expression,
#[inline]
pub fn jsx_attribute_item_jsx_attribute(
self,
@ -13206,8 +13206,8 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - name
/// - value
/// - name: The name of the attribute. This is a prop in React-like applications.
/// - value: The value of the attribute. This can be a string literal, an expression,
#[inline]
pub fn jsx_attribute(
self,
@ -13224,8 +13224,8 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - name
/// - value
/// - name: The name of the attribute. This is a prop in React-like applications.
/// - value: The value of the attribute. This can be a string literal, an expression,
#[inline]
pub fn alloc_jsx_attribute(
self,
@ -13274,7 +13274,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - name
/// - name: The name of the identifier.
#[inline]
pub fn jsx_attribute_name_jsx_identifier<A>(self, span: Span, name: A) -> JSXAttributeName<'a>
where
@ -13355,7 +13355,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - expression
/// - expression: The expression inside the container.
#[inline]
pub fn jsx_attribute_value_jsx_expression_container(
self,
@ -13385,9 +13385,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_element
/// - closing_element
/// - children
/// - opening_element: Opening tag of the element.
/// - closing_element: Closing tag of the element. Will be [`None`] for self-closing tags.
/// - children: Children of the element. This can be text, other elements, or expressions.
#[inline]
pub fn jsx_attribute_value_jsx_element<T1, T2>(
self,
@ -13423,9 +13423,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_fragment
/// - closing_fragment
/// - children
/// - opening_fragment: `<>`
/// - closing_fragment: `</>`
/// - children: Elements inside the fragment.
#[inline]
pub fn jsx_attribute_value_jsx_fragment(
self,
@ -13457,7 +13457,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - name
/// - name: The name of the identifier.
#[inline]
pub fn jsx_identifier<A>(self, span: Span, name: A) -> JSXIdentifier<'a>
where
@ -13472,7 +13472,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - name
/// - name: The name of the identifier.
#[inline]
pub fn alloc_jsx_identifier<A>(self, span: Span, name: A) -> Box<'a, JSXIdentifier<'a>>
where
@ -13487,7 +13487,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - value
/// - value: The text content.
#[inline]
pub fn jsx_child_jsx_text<A>(self, span: Span, value: A) -> JSXChild<'a>
where
@ -13511,9 +13511,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_element
/// - closing_element
/// - children
/// - opening_element: Opening tag of the element.
/// - closing_element: Closing tag of the element. Will be [`None`] for self-closing tags.
/// - children: Children of the element. This can be text, other elements, or expressions.
#[inline]
pub fn jsx_child_jsx_element<T1, T2>(
self,
@ -13549,9 +13549,9 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - opening_fragment
/// - closing_fragment
/// - children
/// - opening_fragment: `<>`
/// - closing_fragment: `</>`
/// - children: Elements inside the fragment.
#[inline]
pub fn jsx_child_jsx_fragment(
self,
@ -13583,7 +13583,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - expression
/// - expression: The expression inside the container.
#[inline]
pub fn jsx_child_jsx_expression_container(
self,
@ -13608,7 +13608,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - expression
/// - expression: The expression being spread.
#[inline]
pub fn jsx_child_jsx_spread_child(
self,
@ -13633,7 +13633,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - expression
/// - expression: The expression being spread.
#[inline]
pub fn jsx_spread_child(self, span: Span, expression: Expression<'a>) -> JSXSpreadChild<'a> {
JSXSpreadChild { span, expression }
@ -13645,7 +13645,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - expression
/// - expression: The expression being spread.
#[inline]
pub fn alloc_jsx_spread_child(
self,
@ -13661,7 +13661,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - value
/// - value: The text content.
#[inline]
pub fn jsx_text<A>(self, span: Span, value: A) -> JSXText<'a>
where
@ -13676,7 +13676,7 @@ impl<'a> AstBuilder<'a> {
///
/// ## Parameters
/// - span: The [`Span`] covering this node
/// - value
/// - value: The text content.
#[inline]
pub fn alloc_jsx_text<A>(self, span: Span, value: A) -> Box<'a, JSXText<'a>>
where