Add comments

Author: mischnic

.changeset/red-trees-smoke.md

@@ -2,4 +2,4 @@
 swc_ecma_transforms_base: major
 ---
 
-feat(): Add `renamer_keep_contexts`
+feat(es/transforms): Add `renamer_keep_contexts`

crates/swc_ecma_transforms_base/src/hygiene/tests.rs

@@ -64,6 +64,7 @@ impl Fold for OnceMarker {
     }
 }
 
+/// Apply the n-th mark to idents of the form `name$2`.
 struct InlineContextMarker {
     marks: Vec<Mark>,
 }

crates/swc_ecma_transforms_base/src/rename/mod.rs

@@ -22,6 +22,8 @@ mod eval;
 mod ops;
 
 pub trait Renamer: Send + Sync {
+    /// See the [`RenamedVariable`] documentation, this type determines whether
+    /// impls can be used with [`renamer`] or [`renamer_keep_contexts`] .
     type Target: RenamedVariable;
 
     /// Should reset `n` to 0 for each identifier?
@@ -52,7 +54,7 @@ pub trait Renamer: Send + Sync {
 
 pub type RenameMap = FxHashMap<Id, Atom>;
 
-pub fn rename(map: &RenameMap) -> impl '_ + Pass + VisitMut {
+pub fn rename<V: RenamedVariable>(map: &FxHashMap<Id, V>) -> impl '_ + Pass + VisitMut {
     rename_with_config(map, Default::default())
 }
 
@@ -110,9 +112,22 @@ mod private {
     impl Sealed for Id {}
 }
 
+/// A trait that is used to represent a renamed variable. For
+/// `renamer_keep_contexts`, the syntax contexts of the replacements should be
+/// correct (unique), while for `hygiene` (which calls `renamer`), the resulting
+/// syntax contexts are irrelevant. This type is used to handle both cases
+/// without code duplication by using `HashMap<Id, impl RenamedVariable>`
+/// everywhere:
+/// - For `renamer`, `HashMap<Id, Atom>` is used (and `SyntaxContext::empty()`
+///   isn't store unnecessarily). All replaced idents have the same
+///   SyntaxContext #0.
+/// - For `renamer_keep_contexts`, `HashMap<Id, Id>` is used. All replaced
+///   idents have a unique SyntaxContext.
 pub trait RenamedVariable:
     private::Sealed + Clone + Sized + std::marker::Send + std::marker::Sync + 'static
 {
+    /// Potentially create a new private variable, depending on whether the
+    /// consumer cares about the syntax context after the renaming.
     fn new_private(sym: Atom) -> Self;
     fn to_id(&self) -> Id;
 }

crates/swc_ecma_transforms_base/src/rename/ops.rs

@@ -15,7 +15,7 @@ use crate::{
 
 pub(super) struct Operator<'a, V>
 where
-    V: RenamedVariable + Sync,
+    V: RenamedVariable,
 {
     pub rename: &'a FxHashMap<Id, V>,
     pub config: Config,
@@ -25,7 +25,7 @@ where
 
 impl<V> Operator<'_, V>
 where
-    V: RenamedVariable + Sync,
+    V: RenamedVariable,
 {
     fn keep_class_name(&mut self, ident: &mut Ident, class: &mut Class) -> Option<ClassExpr> {
         if !self.config.keep_class_names {
@@ -64,7 +64,7 @@ where
 
 impl<V> Parallel for Operator<'_, V>
 where
-    V: RenamedVariable + Sync,
+    V: RenamedVariable,
 {
     fn create(&self) -> Self {
         Self {
@@ -85,7 +85,7 @@ where
 
 impl<V> ParExplode for Operator<'_, V>
 where
-    V: RenamedVariable + Sync,
+    V: RenamedVariable,
 {
     fn after_one_stmt(&mut self, _: &mut Vec<Stmt>) {}
 
@@ -96,7 +96,7 @@ where
 
 impl<V> VisitMut for Operator<'_, V>
 where
-    V: RenamedVariable + Sync,
+    V: RenamedVariable,
 {
     noop_visit_mut_type!();
 
@@ -611,15 +611,15 @@ where
 
 struct VarFolder<'a, 'b, V>
 where
-    V: RenamedVariable + Sync,
+    V: RenamedVariable,
 {
     orig: &'a mut Operator<'b, V>,
     renamed: &'a mut Vec<ExportSpecifier>,
 }
 
 impl<V> VisitMut for VarFolder<'_, '_, V>
 where
-    V: RenamedVariable + Sync,
+    V: RenamedVariable,
 {
     noop_visit_mut_type!();
 
@@ -645,7 +645,7 @@ where
 
 impl<V> Operator<'_, V>
 where
-    V: RenamedVariable + Sync,
+    V: RenamedVariable,
 {
     /// Returns `Ok(renamed_ident)` if ident should be renamed.
     fn rename_ident(&mut self, ident: &mut Ident) -> Result<(), ()> {