refactor(oxc_ast): improve doc and reexports

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 <https://github.com/estree/estree/blob/master/es2015.md#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
+    /// <https://tc39.es/ecma262/#prod-FormalParameters>
     FormalParameter,
-    /// https://tc39.es/ecma262/#prod-UniqueFormalParameters
+    /// <https://tc39.es/ecma262/#prod-UniqueFormalParameters>
     UniqueFormalParameters,
-    /// https://tc39.es/ecma262/#prod-ArrowFormalParameters
+    /// <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: <https://github.com/estree/estree/blob/master/es2022.md#modules>
+// <https://github.com/tc39/ecma262/pull/2154>
 // support:
 //   import {"\0 any unicode" as foo} from "";
 //   export {foo as "\0 any unicode"};

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<usize>) -> Option<String> {

crates/oxc_ast/src/ast/mod.rs

@@ -1,3 +1,5 @@
+//! AST Definitions
+
 mod js;
 mod jsdoc;
 mod jsx;

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,
 }

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,

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;

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.

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};
 /// <https://tc39.es/ecma262/#table-additional-fields-of-source-text-module-records>
 #[derive(Debug, Default)]
 pub struct ModuleRecord {
-    /// https://tc39.es/ecma262/#sec-static-semantics-modulerequests
+    /// <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<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]]`.
     /// 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`.

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,

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<Span> for SourceSpan {
     }
 }
 
+/// Get the span for an AST node
 pub trait GetSpan {
     #[must_use]
     fn span(&self) -> Span;

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};

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<u32, Comment>,
 }
 
+/// 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)
     }
 }
 

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)

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)