Bug 1217001 - Part 4: Improve the comments on VarEmitOption. r=shu.

--HG--
extra : commitid : 7Noyvd57pmn
extra : rebase_source : 013f400cc0658deae9312224ddefa5bf820cbb58

js/src/frontend/BytecodeEmitter.h

@@ -104,16 +104,24 @@ struct StmtInfoBCE;
 typedef Vector<jsbytecode, 0> BytecodeVector;
 typedef Vector<jssrcnote, 0> SrcNotesVector;
 
-// This enum tells EmitVariables and the destructuring functions how emit the
-// given Parser::variables parse tree. In the base case, DefineVars, the caller
-// only wants variables to be defined in the prologue (if necessary). For
-// PushInitialValues, variable initializer expressions are evaluated and left
-// on the stack. For InitializeVars, the initializer expressions values are
-// assigned (to local variables) and popped.
+// This enum tells BytecodeEmitter::emitVariables and the destructuring
+// methods how emit the given Parser::variables parse tree.
 enum VarEmitOption {
-    DefineVars        = 0,
-    PushInitialValues = 1,
-    InitializeVars    = 2
+    // The normal case. Emit code to evaluate initializer expressions and
+    // assign them to local variables. Also emit JSOP_DEF{VAR,LET,CONST}
+    // opcodes in the prologue if the declaration occurs at toplevel.
+    InitializeVars,
+
+    // Emit only JSOP_DEFVAR opcodes, in the prologue, if necessary. This is
+    // used in one case: `for (var $BindingPattern in/of obj)`. If we're at
+    // toplevel, the variable(s) must be defined with JSOP_DEFVAR, but they're
+    // populated inside the loop, via emitAssignment.
+    DefineVars,
+
+    // Emit code to evaluate initializer expressions and leave those values on
+    // the stack. This is used to implement `for (let/const ...;;)` and
+    // deprecated `let` blocks.
+    PushInitialValues
 };
 
 struct BytecodeEmitter