From 6eeb0e63858e86ea7e2c0d863ccc8aeaa89884a4 Mon Sep 17 00:00:00 2001
From: Boshen <1430279+Boshen@users.noreply.github.com>
Date: Fri, 25 Oct 2024 14:31:34 +0000
Subject: [PATCH] docs(ast): mention typescript-eslint, field ordering and
 shape (#6863)

closes #6453
---
 crates/oxc_ast/src/lib.rs | 29 ++++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/crates/oxc_ast/src/lib.rs b/crates/oxc_ast/src/lib.rs
index 27e138c6795bf..5f498740e71fd 100644
--- a/crates/oxc_ast/src/lib.rs
+++ b/crates/oxc_ast/src/lib.rs
@@ -3,13 +3,24 @@
 #![allow(clippy::self_named_module_files)]
 #![warn(missing_docs)]
 
-//! # Oxc AST
+//! # Oxc AST (Abstract Syntax Tree) Nodes
 //!
-//! Abstract Syntax Tree nodes for Oxc. Supports both TypeScript and JavaScript.
+//! Supports JavaScript, TypeScript and JSX.
 //!
-//! This is almost similar to [estree](https://github.com/estree/estree) except a few places:
-//! * `Identifier` is replaced with explicit [`BindingIdentifier`], [`IdentifierReference`], [`IdentifierName`] per spec
-//! * `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,8 +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;