From d7a3e03f7d2c2cf51862f2071006b26a838e6cbc Mon Sep 17 00:00:00 2001
From: overlookmotel <557937+overlookmotel@users.noreply.github.com>
Date: Fri, 1 Aug 2025 20:35:24 +0000
Subject: [PATCH] docs(ast): improve docs for `ImportSpecifier` (#12740)

Clarify and simplify the docs for `ImportSpecifier`.

It seems AI is incapable of such changes (see the fiasco that is #12729) so a REAL MAN has to step up and do it.
---
 crates/oxc_ast/src/ast/js.rs                | 32 ++++++++++++---------
 crates/oxc_ast/src/generated/ast_builder.rs | 18 ++++++------
 2 files changed, 28 insertions(+), 22 deletions(-)

diff --git a/crates/oxc_ast/src/ast/js.rs b/crates/oxc_ast/src/ast/js.rs
index 75b8185919b01..d9cd24e63368c 100644
--- a/crates/oxc_ast/src/ast/js.rs
+++ b/crates/oxc_ast/src/ast/js.rs
@@ -2466,26 +2466,32 @@ pub enum ImportDeclarationSpecifier<'a> {
     ImportNamespaceSpecifier(Box<'a, ImportNamespaceSpecifier<'a>>) = 2,
 }
 
-// import {imported} from "source"
-// import {imported as local} from "source"
+/// Import specifier.
+///
+/// ```ts
+/// import { imported, imported2 } from "source";
+/// //       ^^^^^^^^  ^^^^^^^^^
+/// import { imported as local } from "source";
+/// //       ^^^^^^^^^^^^^^^^^
+/// import { type Foo } from "source";
+/// //       ^^^^^^^^
+/// ```
+///
+/// In the case of `import { foo }`, `imported` and `local` both are the same name,
+/// and have the same `Span`.
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
 pub struct ImportSpecifier<'a> {
     pub span: Span,
+    /// Imported symbol.
+    /// Can only be `IdentifierName` or `StringLiteral`.
     pub imported: ModuleExportName<'a>,
-    /// The name of the imported symbol.
-    ///
-    /// ## Example
-    /// ```ts
-    /// // local and imported name are the same
-    /// import { Foo } from 'foo';
-    /// //       ^^^
-    /// // imports can be renamed, changing the local name
-    /// import { Foo as Bar } from 'foo';
-    /// //              ^^^
-    /// ```
+    /// Binding for local symbol.
     pub local: BindingIdentifier<'a>,
+    /// Value or type.
+    /// `import { foo }`      -> `ImportOrExportKind::Value`
+    /// `import { type Bar }` -> `ImportOrExportKind::Type`
     #[ts]
     pub import_kind: ImportOrExportKind,
 }
diff --git a/crates/oxc_ast/src/generated/ast_builder.rs b/crates/oxc_ast/src/generated/ast_builder.rs
index 6f2855d2c9da6..d3a456e58c465 100644
--- a/crates/oxc_ast/src/generated/ast_builder.rs
+++ b/crates/oxc_ast/src/generated/ast_builder.rs
@@ -7482,9 +7482,9 @@ impl<'a> AstBuilder<'a> {
     ///
     /// ## Parameters
     /// * `span`: The [`Span`] covering this node
-    /// * `imported`
-    /// * `local`: The name of the imported symbol.
-    /// * `import_kind`
+    /// * `imported`: Imported symbol.
+    /// * `local`: Binding for local symbol.
+    /// * `import_kind`: Value or type.
     #[inline]
     pub fn import_declaration_specifier_import_specifier(
         self,
@@ -7544,9 +7544,9 @@ impl<'a> AstBuilder<'a> {
     ///
     /// ## Parameters
     /// * `span`: The [`Span`] covering this node
-    /// * `imported`
-    /// * `local`: The name of the imported symbol.
-    /// * `import_kind`
+    /// * `imported`: Imported symbol.
+    /// * `local`: Binding for local symbol.
+    /// * `import_kind`: Value or type.
     #[inline]
     pub fn import_specifier(
         self,
@@ -7565,9 +7565,9 @@ impl<'a> AstBuilder<'a> {
     ///
     /// ## Parameters
     /// * `span`: The [`Span`] covering this node
-    /// * `imported`
-    /// * `local`: The name of the imported symbol.
-    /// * `import_kind`
+    /// * `imported`: Imported symbol.
+    /// * `local`: Binding for local symbol.
+    /// * `import_kind`: Value or type.
     #[inline]
     pub fn alloc_import_specifier(
         self,