From 6062f9fbc45587c0a7e7351c8909df2007efa2be Mon Sep 17 00:00:00 2001 From: Don Isaac Date: Tue, 30 Jul 2024 11:51:32 -0400 Subject: [PATCH] docs(ast): add doc comments to literal nodes --- crates/oxc_ast/src/ast/literal.rs | 63 ++++++++++++++++++++- crates/oxc_ast/src/generated/ast_builder.rs | 46 +++++++-------- 2 files changed, 85 insertions(+), 24 deletions(-) diff --git a/crates/oxc_ast/src/ast/literal.rs b/crates/oxc_ast/src/ast/literal.rs index 4dd51ab4b651c..eaf89103a1a32 100644 --- a/crates/oxc_ast/src/ast/literal.rs +++ b/crates/oxc_ast/src/ast/literal.rs @@ -18,6 +18,9 @@ use serde::Serialize; #[cfg(feature = "serialize")] use tsify::Tsify; +/// Boolean literal +/// +/// #[ast(visit)] #[derive(Debug, Clone, Hash)] #[cfg_attr(feature = "serialize", derive(Serialize, Tsify))] @@ -28,6 +31,9 @@ pub struct BooleanLiteral { pub value: bool, } +/// Null literal +/// +/// #[ast(visit)] #[derive(Debug, Clone)] #[cfg_attr(feature = "serialize", derive(Serialize, Tsify))] @@ -37,6 +43,9 @@ pub struct NullLiteral { pub span: Span, } +/// Numeric literal +/// +/// #[ast(visit)] #[derive(Debug, Clone)] #[cfg_attr(feature = "serialize", derive(Serialize, Tsify))] @@ -44,12 +53,16 @@ pub struct NullLiteral { pub struct NumericLiteral<'a> { #[serde(flatten)] pub span: Span, + /// The value of the number, converted into base 10 pub value: f64, + /// The number as it appears in the source code pub raw: &'a str, + /// The base representation used by the literal in the source code #[serde(skip)] pub base: NumberBase, } +/// BigInt literal #[ast(visit)] #[derive(Debug, Hash)] #[cfg_attr(feature = "serialize", derive(Serialize, Tsify))] @@ -57,11 +70,16 @@ pub struct NumericLiteral<'a> { pub struct BigIntLiteral<'a> { #[serde(flatten)] pub span: Span, + /// The bigint as it appears in the source code pub raw: Atom<'a>, + /// The base representation used by the literal in the source code #[serde(skip)] pub base: BigintBase, } +/// Regular expression literal +/// +/// #[ast(visit)] #[derive(Debug, Clone, Hash)] #[cfg_attr(feature = "serialize", derive(Serialize, Tsify))] @@ -75,11 +93,16 @@ pub struct RegExpLiteral<'a> { pub regex: RegExp<'a>, } +/// A regular expression +/// +/// #[ast] #[derive(Debug, Clone, Hash)] #[cfg_attr(feature = "serialize", derive(Serialize, Tsify))] pub struct RegExp<'a> { + /// The regex pattern between the slashes pub pattern: Atom<'a>, + /// Regex flags after the closing slash pub flags: RegExpFlags, } @@ -88,6 +111,9 @@ pub struct RegExp<'a> { #[cfg_attr(feature = "serialize", derive(Serialize, Tsify))] pub struct EmptyObject; +/// String literal +/// +/// #[ast(visit)] #[derive(Debug, Clone, Hash)] #[cfg_attr(feature = "serialize", derive(Serialize, Tsify))] @@ -99,16 +125,43 @@ pub struct StringLiteral<'a> { } bitflags! { + /// Regular expression flags. + /// + /// #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct RegExpFlags: u8 { + /// Global flag + /// + /// Causes the pattern to match multiple times. const G = 1 << 0; + /// Ignore case flag + /// + /// Causes the pattern to ignore case. const I = 1 << 1; + /// Multiline flag + /// + /// Causes `^` and `$` to match the start/end of each line. const M = 1 << 2; + /// DotAll flag + /// + /// Causes `.` to also match newlines. const S = 1 << 3; + /// Unicode flag + /// + /// Causes the pattern to treat the input as a sequence of Unicode code points. const U = 1 << 4; + /// Sticky flag + /// + /// Perform a "sticky" search that matches starting at the current position in the target string. const Y = 1 << 5; + /// Indices flag + /// + /// Causes the regular expression to generate indices for substring matches. const D = 1 << 6; - /// v flag from `https://github.com/tc39/proposal-regexp-set-notation` + /// Unicode sets flag + /// + /// Similar to the `u` flag, but also enables the `\\p{}` and `\\P{}` syntax. + /// Added by the [`v` flag proposal](https://github.com/tc39/proposal-regexp-set-notation). const V = 1 << 7; } } @@ -117,13 +170,21 @@ bitflags! { #[wasm_bindgen::prelude::wasm_bindgen(typescript_custom_section)] const TS_APPEND_CONTENT: &'static str = r#" export type RegExpFlags = { + /** Global flag */ G: 1, + /** Ignore case flag */ I: 2, + /** Multiline flag */ M: 4, + /** DotAll flag */ S: 8, + /** Unicode flag */ U: 16, + /** Sticky flag */ Y: 32, + /** Indices flag */ D: 64, + /** Unicode sets flag */ V: 128 }; "#; diff --git a/crates/oxc_ast/src/generated/ast_builder.rs b/crates/oxc_ast/src/generated/ast_builder.rs index 0f9ac7d8ec881..a13e5d1d17dc3 100644 --- a/crates/oxc_ast/src/generated/ast_builder.rs +++ b/crates/oxc_ast/src/generated/ast_builder.rs @@ -78,9 +78,9 @@ impl<'a> AstBuilder<'a> { /// /// ## Parameters /// - span: The [`Span`] covering this node - /// - value - /// - raw - /// - base + /// - value: The value of the number, converted into base 10 + /// - raw: The number as it appears in the source code + /// - base: The base representation used by the literal in the source code #[inline] pub fn numeric_literal( self, @@ -101,9 +101,9 @@ impl<'a> AstBuilder<'a> { /// /// ## Parameters /// - span: The [`Span`] covering this node - /// - value - /// - raw - /// - base + /// - value: The value of the number, converted into base 10 + /// - raw: The number as it appears in the source code + /// - base: The base representation used by the literal in the source code #[inline] pub fn alloc_numeric_literal( self, @@ -124,8 +124,8 @@ impl<'a> AstBuilder<'a> { /// /// ## Parameters /// - span: The [`Span`] covering this node - /// - raw - /// - base + /// - raw: The bigint as it appears in the source code + /// - base: The base representation used by the literal in the source code #[inline] pub fn big_int_literal(self, span: Span, raw: A, base: BigintBase) -> BigIntLiteral<'a> where @@ -140,8 +140,8 @@ impl<'a> AstBuilder<'a> { /// /// ## Parameters /// - span: The [`Span`] covering this node - /// - raw - /// - base + /// - raw: The bigint as it appears in the source code + /// - base: The base representation used by the literal in the source code #[inline] pub fn alloc_big_int_literal( self, @@ -312,9 +312,9 @@ impl<'a> AstBuilder<'a> { /// /// ## Parameters /// - span: The [`Span`] covering this node - /// - value - /// - raw - /// - base + /// - value: The value of the number, converted into base 10 + /// - raw: The number as it appears in the source code + /// - base: The base representation used by the literal in the source code #[inline] pub fn expression_numeric_literal( self, @@ -344,8 +344,8 @@ impl<'a> AstBuilder<'a> { /// /// ## Parameters /// - span: The [`Span`] covering this node - /// - raw - /// - base + /// - raw: The bigint as it appears in the source code + /// - base: The base representation used by the literal in the source code #[inline] pub fn expression_big_int_literal( self, @@ -8153,9 +8153,9 @@ impl<'a> AstBuilder<'a> { /// /// ## Parameters /// - span: The [`Span`] covering this node - /// - value - /// - raw - /// - base + /// - value: The value of the number, converted into base 10 + /// - raw: The number as it appears in the source code + /// - base: The base representation used by the literal in the source code #[inline] pub fn ts_enum_member_name_numeric_literal( self, @@ -8293,9 +8293,9 @@ impl<'a> AstBuilder<'a> { /// /// ## Parameters /// - span: The [`Span`] covering this node - /// - value - /// - raw - /// - base + /// - value: The value of the number, converted into base 10 + /// - raw: The number as it appears in the source code + /// - base: The base representation used by the literal in the source code #[inline] pub fn ts_literal_numeric_literal( self, @@ -8325,8 +8325,8 @@ impl<'a> AstBuilder<'a> { /// /// ## Parameters /// - span: The [`Span`] covering this node - /// - raw - /// - base + /// - raw: The bigint as it appears in the source code + /// - base: The base representation used by the literal in the source code #[inline] pub fn ts_literal_big_int_literal( self,