From 117dff2c47e9b3654fd0df0a084eef5fed0af1de Mon Sep 17 00:00:00 2001
From: overlookmotel <557937+overlookmotel@users.noreply.github.com>
Date: Wed, 14 Aug 2024 11:52:25 +0000
Subject: [PATCH] refactor(transformer): improve comments for `BoundIdentifier`
 helper (#4895)

Add more comments for `BindingIdentifier` helper, and correct comments which were inaccurate.
---
 .../oxc_transformer/src/helpers/bindings.rs   | 36 +++++++++++++++----
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/crates/oxc_transformer/src/helpers/bindings.rs b/crates/oxc_transformer/src/helpers/bindings.rs
index c565b3dd0fe0c..2b6fd83f2865f 100644
--- a/crates/oxc_transformer/src/helpers/bindings.rs
+++ b/crates/oxc_transformer/src/helpers/bindings.rs
@@ -9,7 +9,33 @@ use oxc_syntax::{
 };
 use oxc_traverse::TraverseCtx;
 
-/// Store for a created binding identifier
+/// Info about a binding, from which one can create a `BindingIdentifier` or `IdentifierReference`s.
+///
+/// Typical usage:
+///
+/// ```rs
+/// // Generate a UID for a top-level var
+/// let binding = BoundIdentifier::new_root_uid("foo", SymbolFlags::FunctionScopedVariable, ctx);
+///
+/// // Generate an `IdentifierReference`s and insert them into AST
+/// some_node.id = binding.create_read_reference(ctx);
+/// some_other_node.id = binding.create_read_reference(ctx);
+///
+/// // Store details of the binding for later
+/// self.foo_binding = binding;
+///
+/// // Later on in `exit_program`
+/// let id = binding.create_binding_identifier();
+/// // Insert `var <id> = something;` into `program.body`
+/// ```
+///
+/// Notes:
+///
+/// * `BoundIdentifier` is smaller than `BindingIdentifier`, so takes less memory when you store
+///   it for later use.
+/// * `BoundIdentifier` is `Clone` (unlike `BindingIdentifier`).
+/// * `BoundIdentifier` re-uses the same `Atom` for all `BindingIdentifier` / `IdentifierReference`s
+///   created from it.
 #[derive(Clone)]
 pub struct BoundIdentifier<'a> {
     pub name: Atom<'a>,
@@ -17,7 +43,7 @@ pub struct BoundIdentifier<'a> {
 }
 
 impl<'a> BoundIdentifier<'a> {
-    /// Create `BoundIdentifier` for new binding
+    /// Create `BoundIdentifier` for new binding in specified scope
     pub fn new_uid(
         name: &str,
         scope_id: ScopeId,
@@ -35,14 +61,12 @@ impl<'a> BoundIdentifier<'a> {
         Self::new_uid(name, scope_id, flags, ctx)
     }
 
-    /// Create `IdentifierReference` referencing this binding which is read from
-    /// in current scope
+    /// Create `IdentifierReference` referencing this binding, which is read from, with dummy `Span`
     pub fn create_read_reference(&self, ctx: &mut TraverseCtx<'a>) -> IdentifierReference<'a> {
         self.create_spanned_read_reference(SPAN, ctx)
     }
 
-    /// Create `IdentifierReference` referencing this binding which is read from
-    /// in current scope
+    /// Create `IdentifierReference` referencing this binding, which is read from, with specified `Span`
     pub fn create_spanned_read_reference(
         &self,
         span: Span,