clarify on field order + reformat

crates/oxc_ast/src/lib.rs

@@ -7,9 +7,20 @@
 //!
 //! Supports JavaScript, TypeScript and JSX.
 //!
-//! Compared to [estree] and [typescript-eslint]'s definition, node ordering is identifical and the shape is similar except a few places:
-//! * `Identifier` is replaced with explicit [`BindingIdentifier`], [`IdentifierReference`], [`IdentifierName`] per ECMAScript Specification
-//! * `AssignmentExpression`.`left` `Pattern` is replaced with [`AssignmentTarget`]
+//! ## Types
+//!
+//! AST types are similar to [estree] and [typescript-eslint]'s definition, with a few notable exceptions:
+//!
+//! * `Identifier` is replaced with explicit [`BindingIdentifier`], [`IdentifierReference`],
+//!   [`IdentifierName`], per ECMAScript Specification.
+//! * `AssignmentExpression`.`left` `Pattern` is replaced with [`AssignmentTarget`].
+//! * `Literal` is replaced with [`BooleanLiteral`], [`NumericLiteral`], [`StringLiteral`] etc.
+//!
+//! Field order of types follows "Evaluation order" defined by [ECMAScript spec].
+//! For TypeScript types, we follow how field order is defined in [tsc].
+//!
+//! Oxc's visitors ([`Visit`], [`VisitMut`], [`Traverse`]) visit AST node fields in same order
+//! as they are defined in the types here.
 //!
 //! ## Parsing
 //!
@@ -22,10 +33,16 @@
 //! [`IdentifierReference`]: ast::IdentifierReference
 //! [`IdentifierName`]: ast::IdentifierName
 //! [`AssignmentTarget`]: ast::AssignmentTarget
+//! [`BooleanLiteral`]: ast::BooleanLiteral
+//! [`NumericLiteral`]: ast::NumericLiteral
+//! [`StringLiteral`]: ast::StringLiteral
 //! [`oxc_parser`]: <https://docs.rs/oxc_parser>
 //! [`Parser`]: <https://docs.rs/oxc_parser/latest/oxc_parser/struct.Parser.html>
 //! [estree]: <https://github.com/estree/estree>
 //! [typescript-eslint]: <https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/ast-spec>
+//! [ECMAScript spec]: <https://tc39.es/ecma262/>
+//! [tsc]: <https://github.com/microsoft/TypeScript>
+//! [`Traverse`]: <https://github.com/oxc-project/oxc/tree/main/crates/oxc_traverse>
 
 #[cfg(feature = "serialize")]
 mod serialize;