Add comments

Author: edemaine

src/nodes.coffee

@@ -361,9 +361,18 @@ exports.Base = class Base
       else
         return true if children.replaceInContext match, replacement
 
-  findReferencedVars: (scopes) ->
+  # `findReferencedVars` recurses through the source parse tree to mark every
+  # "scope" parse node (`Root` and `Code`s) with all referenced
+  # (accessed or assigned) variables in that source scope, so that every scope
+  # knows what to avoid when generating new variable names.
+  # Specifically, it takes in an array of `scopeNodes`,
+  # each of which already has a `@referencedVars` attribute that is a `Set`.
+  # For each found reference to an identifier (see `IdentifierLiteral`'s
+  # override for `findReferencedVars`), it adds the name (as a `String`)
+  # to each scope node's `referencedVars` Set.
+  findReferencedVars: (scopeNodes) ->
     @eachChild (child) ->
-      child.findReferencedVars scopes
+      child.findReferencedVars scopeNodes
 
   invert: ->
     new Op '!', this
@@ -519,12 +528,15 @@ exports.Root = class Root extends Base
     super()
 
     @isAsync = (new Code [], @body).isAsync
-    @referencedVars = new Set
+    @referencedVars = new Set  # all referenced variable names in this scope
 
   children: ['body']
 
-  findReferencedVars: (scopes = []) ->
-    super scopes.concat @
+  findReferencedVars: (scopeNodes = []) ->
+    # This is called at the top level to start the recursion,
+    # so initialize `scopeNodes` to the empty array.
+    # Also, Root is a scope node, so add self to the (possibly empty) array.
+    super scopeNodes.concat @
 
   # Wrap everything in a safety closure, unless requested not to. It would be
   # better not to generate them in the first place, but for now, clean up
@@ -1180,8 +1192,10 @@ exports.IdentifierLiteral = class IdentifierLiteral extends Literal
       name: @value
       declaration: !!@isDeclaration
 
-  findReferencedVars: (scopes) ->
-    scope.referencedVars.add @value for scope in scopes
+  findReferencedVars: (scopeNodes) ->
+    # Add this identifier name to the `referencedVars` `Set` of all
+    # containing scopeNodes, to avoid generating a conflicting variable name.
+    scopeNode.referencedVars.add @value for scopeNode in scopeNodes
 
 exports.PropertyName = class PropertyName extends Literal
   isAssignable: YES
@@ -3915,7 +3929,7 @@ exports.Code = class Code extends Base
     @isGenerator = no
     @isAsync     = no
     @isMethod    = no
-    @referencedVars = new Set
+    @referencedVars = new Set  # all referenced variable names in this scope
 
     @body.traverseChildren no, (node) =>
       if (node instanceof Op and node.isYield()) or node instanceof YieldReturn
@@ -3933,8 +3947,9 @@ exports.Code = class Code extends Base
 
   jumps: NO
 
-  findReferencedVars: (scopes) ->
-    super scopes.concat @
+  findReferencedVars: (scopeNodes) ->
+    # Code is a scope node, so add self to the `scopeNodes` array.
+    super scopeNodes.concat @
 
   makeScope: (parentScope) ->
     new Scope parentScope, @body, this, @referencedVars

src/scope.litcoffee

@@ -10,7 +10,7 @@ with external scopes.
 Initialize a scope with its parent, for lookups up the chain,
 as well as a reference to the **Block** node it belongs to, which is
 where it should declare its variables, a reference to the function that
-it belongs to, and a list of variables referenced in the source code
+it belongs to, and a list of variables referenced in the source code scope
 and therefore should be avoided when generating variables. Also track comments
 that should be output as part of variable declarations.