From fdbe365ac758f4208a68e41636cbe16fa851d7b2 Mon Sep 17 00:00:00 2001 From: Boshen Date: Sat, 1 Apr 2023 17:09:43 +0800 Subject: [PATCH] refactor(oxc_ast): improve doc and reexports --- crates/oxc_ast/src/ast/js.rs | 12 ++++---- crates/oxc_ast/src/ast/literal.rs | 2 +- crates/oxc_ast/src/ast/mod.rs | 2 ++ crates/oxc_ast/src/ast_builder.rs | 3 +- crates/oxc_ast/src/ast_kind.rs | 1 + crates/oxc_ast/src/context.rs | 2 +- crates/oxc_ast/src/lib.rs | 29 ++++++++++--------- crates/oxc_ast/src/module_record.rs | 9 +++--- crates/oxc_ast/src/source_type.rs | 6 +++- crates/oxc_ast/src/span.rs | 4 ++- .../oxc_ast/src/syntax_directed_operations.rs | 2 +- crates/oxc_ast/src/trivia.rs | 18 +++++++----- crates/oxc_ast/src/visit.rs | 3 +- crates/oxc_ast/src/visit_mut.rs | 3 +- 14 files changed, 55 insertions(+), 41 deletions(-) diff --git a/crates/oxc_ast/src/ast/js.rs b/crates/oxc_ast/src/ast/js.rs index d1491114f..b1a065c9e 100644 --- a/crates/oxc_ast/src/ast/js.rs +++ b/crates/oxc_ast/src/ast/js.rs @@ -346,7 +346,7 @@ impl<'a> PropertyKey<'a> { #[derive(Debug, PartialEq, Hash)] #[cfg_attr(feature = "serde", derive(Serialize), serde(untagged))] pub enum PropertyValue<'a> { - // for AssignmentProperty in ObjectPattern https://github.com/oxc_ast/oxc_ast/blob/master/es2015.md#objectpattern + // For AssignmentProperty in ObjectPattern Pattern(BindingPattern<'a>), Expression(Expression<'a>), } @@ -1325,11 +1325,11 @@ pub struct FormalParameter<'a> { #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum FormalParameterKind { - /// https://tc39.es/ecma262/#prod-FormalParameters + /// FormalParameter, - /// https://tc39.es/ecma262/#prod-UniqueFormalParameters + /// UniqueFormalParameters, - /// https://tc39.es/ecma262/#prod-ArrowFormalParameters + /// ArrowFormalParameters, /// Part of TypeScript type signatures Signature, @@ -1789,8 +1789,8 @@ impl<'a> ExportDefaultDeclarationKind<'a> { } } -// es2022: https://github.com/oxc_ast/oxc_ast/blob/master/es2022.md#modules -// https://github.com/tc39/ecma262/pull/2154 +// es2022: +// // support: // import {"\0 any unicode" as foo} from ""; // export {foo as "\0 any unicode"}; diff --git a/crates/oxc_ast/src/ast/literal.rs b/crates/oxc_ast/src/ast/literal.rs index dcb7f158a..f27f1419e 100644 --- a/crates/oxc_ast/src/ast/literal.rs +++ b/crates/oxc_ast/src/ast/literal.rs @@ -197,7 +197,7 @@ impl<'a> NumberLiteral<'a> { } /// From [boa](https://github.com/boa-dev/boa/blob/52bc15bc2320cd6cbc661a138ae955ceb0c9597a/boa_engine/src/builtins/number/mod.rs#L417) - /// [spec]: `https://tc39.es/ecma262/#sec-number.prototype.toprecision` + /// [spec](https://tc39.es/ecma262/#sec-number.prototype.toprecision) #[allow(clippy::cast_sign_loss, clippy::cast_possible_wrap, clippy::cast_possible_truncation)] #[must_use] pub fn to_precision(&self, precision: Option) -> Option { diff --git a/crates/oxc_ast/src/ast/mod.rs b/crates/oxc_ast/src/ast/mod.rs index d59dc4196..2b54f9da4 100644 --- a/crates/oxc_ast/src/ast/mod.rs +++ b/crates/oxc_ast/src/ast/mod.rs @@ -1,3 +1,5 @@ +//! AST Definitions + mod js; mod jsdoc; mod jsx; diff --git a/crates/oxc_ast/src/ast_builder.rs b/crates/oxc_ast/src/ast_builder.rs index aaea066aa..62e417151 100644 --- a/crates/oxc_ast/src/ast_builder.rs +++ b/crates/oxc_ast/src/ast_builder.rs @@ -1,5 +1,3 @@ -//! AST builder for creating AST spans - #![allow(clippy::unused_self, clippy::too_many_arguments)] use oxc_allocator::{Allocator, Box, String, Vec}; @@ -7,6 +5,7 @@ use oxc_allocator::{Allocator, Box, String, Vec}; #[allow(clippy::wildcard_imports)] use crate::{ast::*, Atom, SourceType, Span}; +/// AST builder for creating AST spans pub struct AstBuilder<'a> { pub allocator: &'a Allocator, } diff --git a/crates/oxc_ast/src/ast_kind.rs b/crates/oxc_ast/src/ast_kind.rs index 8bce31938..0af1310d6 100644 --- a/crates/oxc_ast/src/ast_kind.rs +++ b/crates/oxc_ast/src/ast_kind.rs @@ -1,6 +1,7 @@ #[allow(clippy::wildcard_imports)] use crate::{ast::*, Atom, GetSpan, Span}; +/// Untyped AST Node Kind #[derive(Debug, Clone, Copy, PartialEq)] pub enum AstKind<'a> { Root, diff --git a/crates/oxc_ast/src/context.rs b/crates/oxc_ast/src/context.rs index 8ece4f421..cf6a7db9f 100644 --- a/crates/oxc_ast/src/context.rs +++ b/crates/oxc_ast/src/context.rs @@ -1,4 +1,4 @@ -//! ECMAScript Grammar Contexts: [In] [Yield] [Await] +//! ECMAScript Grammar Contexts: `[In`] `[Yield]` `[Await]` #![allow(non_upper_case_globals)] use bitflags::bitflags; diff --git a/crates/oxc_ast/src/lib.rs b/crates/oxc_ast/src/lib.rs index f22a31f9a..20db17d10 100644 --- a/crates/oxc_ast/src/lib.rs +++ b/crates/oxc_ast/src/lib.rs @@ -1,5 +1,6 @@ -//! AST -//! NOTE: This is not compatible with estree. +//! Oxc AST +//! +//! This is 90% similar to estree expect a few places such as `BindingIdentifier` and `AssignmentTarget`. #![feature(let_chains)] #![feature(is_some_and)] @@ -8,26 +9,28 @@ mod serialize; pub mod ast; -pub mod ast_builder; -pub mod ast_kind; +mod ast_builder; +mod ast_kind; pub mod context; pub mod module_record; -pub mod source_type; -pub mod span; +mod source_type; +mod span; pub mod syntax_directed_operations; -pub mod trivia; +mod trivia; pub mod visit; pub mod visit_mut; -pub use ast_kind::AstKind; +use compact_str::CompactString; pub use num_bigint::BigUint; -pub use crate::ast_builder::*; -pub use crate::source_type::*; -pub use crate::span::*; -pub use crate::trivia::*; +pub use crate::ast_builder::AstBuilder; +pub use crate::ast_kind::AstKind; +pub use crate::source_type::{Language, LanguageVariant, ModuleKind, SourceType, VALID_EXTENSIONS}; +pub use crate::span::{GetSpan, Span}; +pub use crate::trivia::{CommentKind, Trivias}; -pub type Atom = compact_str::CompactString; +/// Type alis for [`CompactString`] +pub type Atom = CompactString; // After experimenting with two types of boxed enum variants: // 1. diff --git a/crates/oxc_ast/src/module_record.rs b/crates/oxc_ast/src/module_record.rs index 765411b92..84c60c4f3 100644 --- a/crates/oxc_ast/src/module_record.rs +++ b/crates/oxc_ast/src/module_record.rs @@ -1,5 +1,4 @@ -//! Module Record -//! `https://tc39.es/ecma262/#sec-abstract-module-records` +//! [ECMAScript Module Record](https://tc39.es/ecma262/#sec-abstract-module-records) use rustc_hash::FxHashMap; @@ -9,7 +8,7 @@ use crate::{Atom, Span}; /// #[derive(Debug, Default)] pub struct ModuleRecord { - /// https://tc39.es/ecma262/#sec-static-semantics-modulerequests + /// /// Module requests from: /// import ImportClause FromClause /// import ModuleSpecifier @@ -70,7 +69,7 @@ pub struct ImportEntry { /// String value of the ModuleSpecifier of the ImportDeclaration. pub module_request: NameSpan, - /// The name under which the desired binding is exported by the module identified by [[ModuleRequest]]. + /// The name under which the desired binding is exported by the module identified by `[[ModuleRequest]]`. pub import_name: ImportImportName, /// The name that is used to locally access the imported value from within the importing module. @@ -107,7 +106,7 @@ pub struct ExportEntry { /// null if the ExportDeclaration does not have a ModuleSpecifier. pub module_request: Option, - /// The name under which the desired binding is exported by the module identified by [[ModuleRequest]]. + /// The name under which the desired binding is exported by the module identified by `[[ModuleRequest]]`. /// null if the ExportDeclaration does not have a ModuleSpecifier. /// "all" is used for `export * as ns from "mod"`` declarations. /// "all-but-default" is used for `export * from "mod" declarations`. diff --git a/crates/oxc_ast/src/source_type.rs b/crates/oxc_ast/src/source_type.rs index 351165d26..6cdc41160 100644 --- a/crates/oxc_ast/src/source_type.rs +++ b/crates/oxc_ast/src/source_type.rs @@ -4,6 +4,7 @@ use thiserror::Error; use crate::context::Context; +/// Source Type for JavaScript vs TypeScript / Script vs Module / JSX #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct SourceType { /// JavaScript or TypeScript, default JavaScript @@ -12,7 +13,7 @@ pub struct SourceType { /// Script or Module, default Module module_kind: ModuleKind, - /// support JSX for JavaScript and TypeScript? default without JSX + /// Support JSX for JavaScript and TypeScript? default without JSX variant: LanguageVariant, /// Mark strict mode as always strict @@ -20,18 +21,21 @@ pub struct SourceType { always_strict: bool, } +/// JavaScript or TypeScript #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Language { JavaScript, TypeScript { is_definition_file: bool }, } +/// Script or Module #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum ModuleKind { Script, Module, } +/// JSX for JavaScript and TypeScript #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum LanguageVariant { Standard, diff --git a/crates/oxc_ast/src/span.rs b/crates/oxc_ast/src/span.rs index 2dbbabe58..e5a0f0880 100644 --- a/crates/oxc_ast/src/span.rs +++ b/crates/oxc_ast/src/span.rs @@ -7,7 +7,8 @@ use serde::Serialize; #[allow(clippy::wildcard_imports)] use crate::ast::*; -/// Newtype for working with text sizes/ranges. +/// Newtype for working with text ranges +/// /// See the [`text-size`](https://docs.rs/text-size) crate for details. /// Utility methods can be copied from the `text-size` crate if they are needed. /// NOTE: `u32` is sufficient for "all" reasonable programs. Larger than u32 is a 4GB JS file. @@ -54,6 +55,7 @@ impl From for SourceSpan { } } +/// Get the span for an AST node pub trait GetSpan { #[must_use] fn span(&self) -> Span; diff --git a/crates/oxc_ast/src/syntax_directed_operations.rs b/crates/oxc_ast/src/syntax_directed_operations.rs index 2b1f47626..aa4319d20 100644 --- a/crates/oxc_ast/src/syntax_directed_operations.rs +++ b/crates/oxc_ast/src/syntax_directed_operations.rs @@ -1,4 +1,4 @@ -//! [Syntax-Directed Operations](https://tc39.es/ecma262/#sec-syntax-directed-operations) +//! [ECMA262 Syntax-Directed Operations](https://tc39.es/ecma262/#sec-syntax-directed-operations) #[allow(clippy::wildcard_imports)] use crate::{ast::*, Span}; diff --git a/crates/oxc_ast/src/trivia.rs b/crates/oxc_ast/src/trivia.rs index 07ce158fb..ed9dda374 100644 --- a/crates/oxc_ast/src/trivia.rs +++ b/crates/oxc_ast/src/trivia.rs @@ -1,16 +1,18 @@ -//! Trivia (called that because it's trivial) represent the parts of the source text that are largely insignificant for normal understanding of the code. -//! For example: whitespace, comments, and even conflict markers. - use std::collections::BTreeMap; use crate::Span; +/// Trivias such as comments +/// +/// Trivia (called that because it's trivial) represent the parts of the source text that are largely insignificant for normal understanding of the code. +/// For example: whitespace, comments, and even conflict markers. #[derive(Debug, Default)] pub struct Trivias { /// Keyed by span.start comments: BTreeMap, } +/// Single or multi line comment #[derive(Debug, Clone, Copy)] #[allow(unused)] pub struct Comment { @@ -31,18 +33,18 @@ impl Comment { } #[must_use] - pub fn end(&self) -> u32 { + pub fn end(self) -> u32 { self.end } #[must_use] - pub fn is_single_line(&self) -> bool { - self.kind == CommentKind::SingleLine + pub fn is_single_line(self) -> bool { + matches!(self.kind, CommentKind::SingleLine) } #[must_use] - pub fn is_multi_line(&self) -> bool { - self.kind == CommentKind::MultiLine + pub fn is_multi_line(self) -> bool { + matches!(self.kind, CommentKind::MultiLine) } } diff --git a/crates/oxc_ast/src/visit.rs b/crates/oxc_ast/src/visit.rs index 2ba37df53..74e2ca0af 100644 --- a/crates/oxc_ast/src/visit.rs +++ b/crates/oxc_ast/src/visit.rs @@ -1,4 +1,5 @@ -//! AST Visitor Pattern. +//! AST Visitor Pattern +//! //! See: //! * [visitor pattern](https://rust-unofficial.github.io/patterns/patterns/behavioural/visitor.html) //! * [rustc visitor](https://github.com/rust-lang/rust/blob/master/compiler/rustc_ast/src/visit.rs) diff --git a/crates/oxc_ast/src/visit_mut.rs b/crates/oxc_ast/src/visit_mut.rs index 11b149e22..f26ca338d 100644 --- a/crates/oxc_ast/src/visit_mut.rs +++ b/crates/oxc_ast/src/visit_mut.rs @@ -1,4 +1,5 @@ -//! AST `VisitMut` Pattern. +//! AST `VisitMut` Pattern +//! //! See: //! * [syn](https://docs.rs/syn/latest/syn/visit_mut/index.html) //! * [swc](https://rustdoc.swc.rs/swc_ecma_visit/trait.VisitMut.html)