refactor(transformer): improve comments for BoundIdentifier helper

crates/oxc_transformer/src/helpers/bindings.rs

@@ -9,15 +9,41 @@ 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>,
     pub symbol_id: SymbolId,
 }
 
 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,