comments (*lots* of them) + asserts

lcode.c

@@ -1,5 +1,5 @@
 /*
-** $Id: lcode.c,v 2.104 2015/12/17 14:52:53 roberto Exp roberto $
+** $Id: lcode.c,v 2.103 2015/11/19 19:16:22 roberto Exp roberto $
 ** Code generator for Lua
 ** See Copyright Notice in lua.h
 */
@@ -36,6 +36,10 @@
 #define hasjumps(e)	((e)->t != (e)->f)
 
 
+/*
+** If expression is a numeric constant, fills 'v' with its value
+** and returns 1. Otherwise, returns 0.
+*/
 static int tonumeral(expdesc *e, TValue *v) {
   if (hasjumps(e))
     return 0;  /* not a numeral */
@@ -51,13 +55,19 @@ static int tonumeral(expdesc *e, TValue *v) {
 }
 
 
+/*
+** Create a OP_LOADNIL instruction, but try to optimize: if the previous
+** instruction is also OP_LOADNIL and ranges are compatible, adjust
+** range of previous instruction instead of emitting a new one. (For
+** instance, 'local a; local b' will generate a single opcode.)
+*/
 void luaK_nil (FuncState *fs, int from, int n) {
   Instruction *previous;
   int l = from + n - 1;  /* last register to set nil */
   if (fs->pc > fs->lasttarget) {  /* no jumps to current position? */
     previous = &fs->f->code[fs->pc-1];
-    if (GET_OPCODE(*previous) == OP_LOADNIL) {
-      int pfrom = GETARG_A(*previous);
+    if (GET_OPCODE(*previous) == OP_LOADNIL) {  /* previous is LOADNIL? */
+      int pfrom = GETARG_A(*previous);  /* get previous range */
       int pl = pfrom + GETARG_B(*previous);
       if ((pfrom <= from && from <= pl + 1) ||
           (from <= pfrom && pfrom <= l + 1)) {  /* can connect both? */
@@ -73,6 +83,10 @@ void luaK_nil (FuncState *fs, int from, int n) {
 }
 
 
+/*
+** Gets the destination address of a jump instruction. Used to traverse
+** a list of jumps.
+*/ 
 static int getjump (FuncState *fs, int pc) {
   int offset = GETARG_sBx(fs->f->code[pc]);
   if (offset == NO_JUMP)  /* point to itself represents end of list */
@@ -82,9 +96,13 @@ static int getjump (FuncState *fs, int pc) {
 }
 
 
+/*
+** Fix jump instruction at position 'pc' to jump to 'dest'.
+** (Jump addresses are relative in Lua)
+*/
 static void fixjump (FuncState *fs, int pc, int dest) {
   Instruction *jmp = &fs->f->code[pc];
-  int offset = dest-(pc+1);
+  int offset = dest - (pc + 1);
   lua_assert(dest != NO_JUMP);
   if (abs(offset) > MAXARG_sBx)
     luaX_syntaxerror(fs->ls, "control structure too long");
@@ -92,35 +110,51 @@ static void fixjump (FuncState *fs, int pc, int dest) {
 }
 
 
+/*
+** Concatenate jump-list 'l2' into jump-list 'l1'
+*/
 void luaK_concat (FuncState *fs, int *l1, int l2) {
-  if (l2 == NO_JUMP) return;
-  else if (*l1 == NO_JUMP)
-    *l1 = l2;
+  if (l2 == NO_JUMP) return;  /* nothing to concatenate? */
+  else if (*l1 == NO_JUMP)  /* no original list? */
+    *l1 = l2;  /* 'l1' points to 'l2' */
   else {
     int list = *l1;
     int next;
     while ((next = getjump(fs, list)) != NO_JUMP)  /* find last element */
       list = next;
-    fixjump(fs, list, l2);
+    fixjump(fs, list, l2);  /* last element links to 'l2' */
   }
 }
 
 
+/*
+** Create a jump instruction and return its position, so its destination
+** can be fixed later (with 'fixjump'). If there are jumps to
+** this position (kept in 'jpc'), link them all together so that
+** 'patchlistaux' will fix all them directly to the final destination.
+*/
 int luaK_jump (FuncState *fs) {
   int jpc = fs->jpc;  /* save list of jumps to here */
   int j;
-  fs->jpc = NO_JUMP;
+  fs->jpc = NO_JUMP;  /* no more jumps to here */
   j = luaK_codeAsBx(fs, OP_JMP, 0, NO_JUMP);
   luaK_concat(fs, &j, jpc);  /* keep them on hold */
   return j;
 }
 
 
+/*
+** Code a 'return' instruction
+*/
 void luaK_ret (FuncState *fs, int first, int nret) {
   luaK_codeABC(fs, OP_RETURN, first, nret+1, 0);
 }
 
 
+/*
+** Code a "conditional jump", that is, a test or comparison opcode
+** followed by a jump. Return jump position.
+*/
 static int condjump (FuncState *fs, OpCode op, int A, int B, int C) {
   luaK_codeABC(fs, op, A, B, C);
   return luaK_jump(fs);
@@ -137,6 +171,11 @@ int luaK_getlabel (FuncState *fs) {
 }
 
 
+/*
+** Returns the position of the instruction "controlling" a given
+** jump (that is, its condition), or the jump itself if it is
+** unconditional.
+*/
 static Instruction *getjumpcontrol (FuncState *fs, int pc) {
   Instruction *pi = &fs->f->code[pc];
   if (pc >= 1 && testTMode(GET_OPCODE(*(pi-1))))
@@ -146,25 +185,42 @@ static Instruction *getjumpcontrol (FuncState *fs, int pc) {
 }
 
 
+/*
+** Patch destination register for a TESTSET instruction.
+** If instruction in position 'node' is not a TESTSET, return 0 ("fails").
+** Otherwise, if 'reg' is not 'NO_REG', set it as the destination
+** register. Otherwise, change instruction to a simple 'TEST' (produces
+** no register value)
+*/
 static int patchtestreg (FuncState *fs, int node, int reg) {
   Instruction *i = getjumpcontrol(fs, node);
   if (GET_OPCODE(*i) != OP_TESTSET)
     return 0;  /* cannot patch other instructions */
   if (reg != NO_REG && reg != GETARG_B(*i))
     SETARG_A(*i, reg);
-  else  /* no register to put value or register already has the value */
+  else {
+     /* no register to put value or register already has the value;
+        change instruction to simple test */
     *i = CREATE_ABC(OP_TEST, GETARG_B(*i), 0, GETARG_C(*i));
-
+  }
   return 1;
 }
 
 
+/*
+** Traverse a list of tests ensuring no one produces a value
+*/
 static void removevalues (FuncState *fs, int list) {
   for (; list != NO_JUMP; list = getjump(fs, list))
       patchtestreg(fs, list, NO_REG);
 }
 
 
+/*
+** Traverse a list of tests, patching their destination address and
+** registers: tests producing values jump to 'vtarget' (and put their
+** values in 'reg'), other tests jump to 'dtarget'.
+*/
 static void patchlistaux (FuncState *fs, int list, int vtarget, int reg,
                           int dtarget) {
   while (list != NO_JUMP) {
@@ -178,21 +234,35 @@ static void patchlistaux (FuncState *fs, int list, int vtarget, int reg,
 }
 
 
+/*
+** Ensure all pending jumps to current position are fixed (jumping
+** to current position with no values) and reset list of pending
+** jumps
+*/
 static void dischargejpc (FuncState *fs) {
   patchlistaux(fs, fs->jpc, fs->pc, NO_REG, fs->pc);
   fs->jpc = NO_JUMP;
 }
 
 
+/*
+** Add elements in 'list' to list of pending jumps to "here"
+** (current position)
+*/
 void luaK_patchtohere (FuncState *fs, int list) {
-  luaK_getlabel(fs);
+  luaK_getlabel(fs);  /* mark "here" as a jump target */
   luaK_concat(fs, &fs->jpc, list);
 }
 
 
+/*
+** Path all jumps in 'list' to jump to 'target'.
+** (The assert means that we cannot fix a jump to a forward address
+** because we only know addresses once code is generated.)
+*/
 void luaK_patchlist (FuncState *fs, int list, int target) {
-  if (target == fs->pc)
-    luaK_patchtohere(fs, list);
+  if (target == fs->pc)  /* 'target' is current position? */
+    luaK_patchtohere(fs, list);  /* add list to pending jumps */
   else {
     lua_assert(target < fs->pc);
     patchlistaux(fs, list, target, NO_REG, target);
@@ -200,6 +270,11 @@ void luaK_patchlist (FuncState *fs, int list, int target) {
 }
 
 
+/*
+** Path all jumps in 'list' to close upvalues up to given 'level'
+** (The assertion checks that jumps either were closing nothing
+** or were closing higher levels, from inner blocks.)
+*/
 void luaK_patchclose (FuncState *fs, int list, int level) {
   level++;  /* argument is +1 to reserve 0 as non-op */
   for (; list != NO_JUMP; list = getjump(fs, list)) {
@@ -211,6 +286,10 @@ void luaK_patchclose (FuncState *fs, int list, int level) {
 }
 
 
+/*
+** Emit instruction 'i', checking for array sizes and saving also its
+** line information. Return 'i' position.
+*/
 static int luaK_code (FuncState *fs, Instruction i) {
   Proto *f = fs->f;
   dischargejpc(fs);  /* 'pc' will change */
@@ -226,6 +305,10 @@ static int luaK_code (FuncState *fs, Instruction i) {
 }
 
 
+/*
+** Format and emit an 'iABC' instruction. (Assertions check consistency
+** of parameters versus opcode.)
+*/
 int luaK_codeABC (FuncState *fs, OpCode o, int a, int b, int c) {
   lua_assert(getOpMode(o) == iABC);
   lua_assert(getBMode(o) != OpArgN || b == 0);
@@ -235,6 +318,9 @@ int luaK_codeABC (FuncState *fs, OpCode o, int a, int b, int c) {
 }
 
 
+/*
+** Format and emit an 'iABx' instruction.
+*/
 int luaK_codeABx (FuncState *fs, OpCode o, int a, unsigned int bc) {
   lua_assert(getOpMode(o) == iABx || getOpMode(o) == iAsBx);
   lua_assert(getCMode(o) == OpArgN);
@@ -243,12 +329,20 @@ int luaK_codeABx (FuncState *fs, OpCode o, int a, unsigned int bc) {
 }
 
 
+/*
+** Emit an "extra argument" instruction (format 'iAx')
+*/
 static int codeextraarg (FuncState *fs, int a) {
   lua_assert(a <= MAXARG_Ax);
   return luaK_code(fs, CREATE_Ax(OP_EXTRAARG, a));
 }
 
 
+/*
+** Emit a "load constant" instruction, using either 'OP_LOADK'
+** (if constant index 'k' fits in 18 bits) or an 'OP_LOADKX'
+** instruction with "extra argument".
+*/
 int luaK_codek (FuncState *fs, int reg, int k) {
   if (k <= MAXARG_Bx)
     return luaK_codeABx(fs, OP_LOADK, reg, k);
@@ -260,6 +354,10 @@ int luaK_codek (FuncState *fs, int reg, int k) {
 }
 
 
+/*
+** Check register-stack level, keeping track of its maximum size
+** in field 'maxstacksize'
+*/
 void luaK_checkstack (FuncState *fs, int n) {
   int newstack = fs->freereg + n;
   if (newstack > fs->f->maxstacksize) {
@@ -271,12 +369,20 @@ void luaK_checkstack (FuncState *fs, int n) {
 }
 
 
+/*
+** Reserve 'n' registers in register stack
+*/
 void luaK_reserveregs (FuncState *fs, int n) {
   luaK_checkstack(fs, n);
   fs->freereg += n;
 }
 
 
+/*
+** Free register 'reg', if it is neither a constant index nor
+** a local variable.
+)
+*/
 static void freereg (FuncState *fs, int reg) {
   if (!ISK(reg) && reg >= fs->nactvar) {
     fs->freereg--;
@@ -285,6 +391,9 @@ static void freereg (FuncState *fs, int reg) {
 }
 
 
+/*
+** Free register used by expression 'e' (if any)
+*/
 static void freeexp (FuncState *fs, expdesc *e) {
   if (e->k == VNONRELOC)
     freereg(fs, e->u.info);
@@ -292,8 +401,11 @@ static void freeexp (FuncState *fs, expdesc *e) {
 
 
 /*
+** Add constant 'v' to prototype's list of constants (field 'k').
 ** Use scanner's table to cache position of constants in constant list
-** and try to reuse constants
+** and try to reuse constants. Because some values should not be used
+** as keys (nil cannot be a key, integer keys can collapse with float
+** keys), the caller must provide a useful 'key' for indexing the cache.
 */
 static int addk (FuncState *fs, TValue *key, TValue *v) {
   lua_State *L = fs->ls->L;
@@ -322,17 +434,21 @@ static int addk (FuncState *fs, TValue *key, TValue *v) {
 }
 
 
+/*
+** Add a string to list of constants and return its index.
+*/
 int luaK_stringK (FuncState *fs, TString *s) {
   TValue o;
   setsvalue(fs->ls->L, &o, s);
-  return addk(fs, &o, &o);
+  return addk(fs, &o, &o);  /* use string itself as key */
 }
 
 
 /*
-** Integers use userdata as keys to avoid collision with floats with same
-** value; conversion to 'void*' used only for hashing, no "precision"
-** problems
+** Add an integer to list of constants and return its index.
+** Integers use userdata as keys to avoid collision with floats with
+** same value; conversion to 'void*' is used only for hashing, so there
+** are no "precision" problems.
 */
 int luaK_intK (FuncState *fs, lua_Integer n) {
   TValue k, o;
@@ -341,21 +457,29 @@ int luaK_intK (FuncState *fs, lua_Integer n) {
   return addk(fs, &k, &o);
 }
 
-
+/*
+** Add a float to list of constants and return its index.
+*/
 static int luaK_numberK (FuncState *fs, lua_Number r) {
   TValue o;
   setfltvalue(&o, r);
-  return addk(fs, &o, &o);
+  return addk(fs, &o, &o);  /* use number itself as key */
 }
 
 
+/*
+** Add a boolean to list of constants and return its index.
+*/
 static int boolK (FuncState *fs, int b) {
   TValue o;
   setbvalue(&o, b);
-  return addk(fs, &o, &o);
+  return addk(fs, &o, &o);  /* use boolean itself as key */
 }
 
 
+/*
+** Add nil to list of constants and return its index.
+*/
 static int nilK (FuncState *fs) {
   TValue k, v;
   setnilvalue(&v);
@@ -365,6 +489,11 @@ static int nilK (FuncState *fs) {
 }
 
 
+/*
+** Fix an expression to return the number of results 'nresults'.
+** Either 'e' is a multi-ret expression (function call or vararg)
+** or 'nresults' is LUA_MULTRET (as any expression can satisfy that).
+*/
 void luaK_setreturns (FuncState *fs, expdesc *e, int nresults) {
   if (e->k == VCALL) {  /* expression is an open function call? */
     SETARG_C(getcode(fs, e), nresults+1);
@@ -374,12 +503,24 @@ void luaK_setreturns (FuncState *fs, expdesc *e, int nresults) {
     SETARG_A(getcode(fs, e), fs->freereg);
     luaK_reserveregs(fs, 1);
   }
+  else lua_assert(nresults == LUA_MULTRET);
 }
 
 
+/*
+** Fix an expression to return one result.
+** If expression is not a multi-ret expression (function call or
+** vararg), it already returns one result, so nothing needs to be done.
+** Function calls become VNONRELOC expressions (as its result comes
+** fixed in the base register of the call), while vararg expressions
+** become VRELOCABLE (as OP_VARARG puts its results where it wants).
+** (Calls are created returning one result, so that does not need
+** to be fixed.)
+*/
 void luaK_setoneret (FuncState *fs, expdesc *e) {
   if (e->k == VCALL) {  /* expression is an open function call? */
-    e->k = VNONRELOC;
+    lua_assert(GETARG_C(getcode(fs, e)) == 2);  /* already returns 1 value */
+    e->k = VNONRELOC;  /* result has fixed position */
     e->u.info = GETARG_A(getcode(fs, e));
   }
   else if (e->k == VVARARG) {
@@ -389,10 +530,14 @@ void luaK_setoneret (FuncState *fs, expdesc *e) {
 }
 
 
+/*
+** Ensure that expression 'e' has a value somewhere (either it
+** is a constant or result is in a register).
+*/
 void luaK_dischargevars (FuncState *fs, expdesc *e) {
   switch (e->k) {
     case VLOCAL: {
-      e->k = VNONRELOC;
+      e->k = VNONRELOC;  /* becomes a non-relocatable value */
       break;
     }
     case VUPVAL: {
@@ -421,6 +566,10 @@ void luaK_dischargevars (FuncState *fs, expdesc *e) {
 }
 
 
+/*
+** Ensures expression value is in register 'reg' (and therefore
+** 'e' will become a non-relocatable expression).
+*/
 static void discharge2reg (FuncState *fs, expdesc *e, int reg) {
   luaK_dischargevars(fs, e);
   switch (e->k) {
@@ -446,7 +595,7 @@ static void discharge2reg (FuncState *fs, expdesc *e, int reg) {
     }
     case VRELOCABLE: {
       Instruction *pc = &getcode(fs, e);
-      SETARG_A(*pc, reg);
+      SETARG_A(*pc, reg);  /* instruction will put result in 'reg' */
       break;
     }
     case VNONRELOC: {
@@ -455,7 +604,7 @@ static void discharge2reg (FuncState *fs, expdesc *e, int reg) {
       break;
     }
     default: {
-      lua_assert(e->k == VVOID || e->k == VJMP);
+      lua_assert(e->k == VJMP);
       return;  /* nothing to do... */
     }
   }
@@ -464,10 +613,13 @@ static void discharge2reg (FuncState *fs, expdesc *e, int reg) {
 }
 
 
+/*
+** Ensures expression value is in any register.
+*/
 static void discharge2anyreg (FuncState *fs, expdesc *e) {
-  if (e->k != VNONRELOC) {
-    luaK_reserveregs(fs, 1);
-    discharge2reg(fs, e, fs->freereg-1);
+  if (e->k != VNONRELOC) {  /* no fixed register yet? */
+    luaK_reserveregs(fs, 1);  /* get a register */
+    discharge2reg(fs, e, fs->freereg-1);  /* put value there */
   }
 }
 
@@ -480,7 +632,7 @@ static int code_loadbool (FuncState *fs, int A, int b, int jump) {
 
 /*
 ** check whether list has any jump that do not produce a value
-** (or produce an inverted value)
+** or produce an inverted value
 */
 static int need_value (FuncState *fs, int list) {
   for (; list != NO_JUMP; list = getjump(fs, list)) {
@@ -491,9 +643,16 @@ static int need_value (FuncState *fs, int list) {
 }
 
 
+/*
+** Ensures final expression result (including results from its jump
+** lists) is in register 'reg'.
+** If expression has jumps, need to patch these jumps either to
+** its final position or to "load" instructions (for those tests
+** that do not produce values).
+*/
 static void exp2reg (FuncState *fs, expdesc *e, int reg) {
   discharge2reg(fs, e, reg);
-  if (e->k == VJMP)
+  if (e->k == VJMP)  /* expression itself is a test? */
     luaK_concat(fs, &e->t, e->u.info);  /* put this jump in 't' list */
   if (hasjumps(e)) {
     int final;  /* position after whole expression */
@@ -515,6 +674,10 @@ static void exp2reg (FuncState *fs, expdesc *e, int reg) {
 }
 
 
+/*
+** Ensures final expression result (including results from its jump
+** lists) is in next available register.
+*/
 void luaK_exp2nextreg (FuncState *fs, expdesc *e) {
   luaK_dischargevars(fs, e);
   freeexp(fs, e);
@@ -523,26 +686,39 @@ void luaK_exp2nextreg (FuncState *fs, expdesc *e) {
 }
 
 
+/*
+** Ensures final expression result (including results from its jump
+** lists) is in some (any) register and return that register.
+*/
 int luaK_exp2anyreg (FuncState *fs, expdesc *e) {
   luaK_dischargevars(fs, e);
-  if (e->k == VNONRELOC) {
-    if (!hasjumps(e)) return e->u.info;  /* exp is already in a register */
+  if (e->k == VNONRELOC) {  /* expression already has a register? */
+    if (!hasjumps(e))  /* no jumps? */
+      return e->u.info;  /* result is already in a register */
     if (e->u.info >= fs->nactvar) {  /* reg. is not a local? */
-      exp2reg(fs, e, e->u.info);  /* put value on it */
+      exp2reg(fs, e, e->u.info);  /* put final result in it */
       return e->u.info;
     }
   }
-  luaK_exp2nextreg(fs, e);  /* default */
+  luaK_exp2nextreg(fs, e);  /* otherwise, use next available register */
   return e->u.info;
 }
 
 
+/*
+** Ensures final expression result is either in a register or in an
+** upvalue.
+*/
 void luaK_exp2anyregup (FuncState *fs, expdesc *e) {
   if (e->k != VUPVAL || hasjumps(e))
     luaK_exp2anyreg(fs, e);
 }
 
 
+/*
+** Ensures final expression result is either in a register or it is
+** a constant.
+*/
 void luaK_exp2val (FuncState *fs, expdesc *e) {
   if (hasjumps(e))
     luaK_exp2anyreg(fs, e);
@@ -551,9 +727,14 @@ void luaK_exp2val (FuncState *fs, expdesc *e) {
 }
 
 
+/*
+** Ensures final expression result is in a valid R/K index
+** (that is, it is either in a register or in 'k' with an index
+** in the range of R/K indices).
+*/  
 int luaK_exp2RK (FuncState *fs, expdesc *e) {
   luaK_exp2val(fs, e);
-  switch (e->k) {
+  switch (e->k) {  /* handle constants */
     case VTRUE:
     case VFALSE:
     case VNIL: {
@@ -587,11 +768,14 @@ int luaK_exp2RK (FuncState *fs, expdesc *e) {
 }
 
 
+/*
+** Generate code to store result of expression 'ex' into variable 'var'.
+*/
 void luaK_storevar (FuncState *fs, expdesc *var, expdesc *ex) {
   switch (var->k) {
     case VLOCAL: {
       freeexp(fs, ex);
-      exp2reg(fs, ex, var->u.info);
+      exp2reg(fs, ex, var->u.info);  /* compute 'ex' into proper place */
       return;
     }
     case VUPVAL: {
@@ -605,29 +789,32 @@ void luaK_storevar (FuncState *fs, expdesc *var, expdesc *ex) {
       luaK_codeABC(fs, op, var->u.ind.t, var->u.ind.idx, e);
       break;
     }
-    default: {
-      lua_assert(0);  /* invalid var kind to store */
-      break;
-    }
+    default: lua_assert(0);  /* invalid var kind to store */
   }
   freeexp(fs, ex);
 }
 
 
+/*
+** Emit SELF instruction (convert expression 'e' into 'e:key(e,').
+*/
 void luaK_self (FuncState *fs, expdesc *e, expdesc *key) {
   int ereg;
   luaK_exp2anyreg(fs, e);
   ereg = e->u.info;  /* register where 'e' was placed */
   freeexp(fs, e);
   e->u.info = fs->freereg;  /* base register for op_self */
-  e->k = VNONRELOC;
+  e->k = VNONRELOC;  /* self expression has a fixed register */
   luaK_reserveregs(fs, 2);  /* function and 'self' produced by op_self */
   luaK_codeABC(fs, OP_SELF, e->u.info, ereg, luaK_exp2RK(fs, key));
   freeexp(fs, key);
 }
 
 
-static void invertjump (FuncState *fs, expdesc *e) {
+/*
+** Negate condition 'e' (where 'e' is a comparison).
+*/
+static void negatecondition (FuncState *fs, expdesc *e) {
   Instruction *pc = getjumpcontrol(fs, e->u.info);
   lua_assert(testTMode(GET_OPCODE(*pc)) && GET_OPCODE(*pc) != OP_TESTSET &&
                                            GET_OPCODE(*pc) != OP_TEST);
@@ -635,6 +822,12 @@ static void invertjump (FuncState *fs, expdesc *e) {
 }
 
 
+/*
+** Emit instruction to jump if 'e' is 'cond' (that is, if 'cond'
+** is true, code will jump if 'e' is true.) Return jump position.
+** Optimize when 'e' is 'not' something, inverting the condition
+** and removing the 'not'.
+*/
 static int jumponcond (FuncState *fs, expdesc *e, int cond) {
   if (e->k == VRELOCABLE) {
     Instruction ie = getcode(fs, e);
@@ -650,13 +843,16 @@ static int jumponcond (FuncState *fs, expdesc *e, int cond) {
 }
 
 
+/*
+** Emit code to go through if 'e' is true, jump otherwise.
+*/
 void luaK_goiftrue (FuncState *fs, expdesc *e) {
-  int pc;  /* pc of last jump */
+  int pc;  /* pc of new jump */
   luaK_dischargevars(fs, e);
   switch (e->k) {
-    case VJMP: {
-      invertjump(fs, e);
-      pc = e->u.info;
+    case VJMP: {  /* condition? */
+      negatecondition(fs, e);  /* jump when it is false */
+      pc = e->u.info;  /* save jump position */
       break;
     }
     case VK: case VKFLT: case VKINT: case VTRUE: {
@@ -664,22 +860,25 @@ void luaK_goiftrue (FuncState *fs, expdesc *e) {
       break;
     }
     default: {
-      pc = jumponcond(fs, e, 0);
+      pc = jumponcond(fs, e, 0);  /* jump when false */
       break;
     }
   }
-  luaK_concat(fs, &e->f, pc);  /* insert last jump in 'f' list */
-  luaK_patchtohere(fs, e->t);
+  luaK_concat(fs, &e->f, pc);  /* insert new jump in false list */
+  luaK_patchtohere(fs, e->t);  /* true list jumps to here (to go through) */
   e->t = NO_JUMP;
 }
 
 
+/*
+** Emit code to go through if 'e' is false, jump otherwise.
+*/
 void luaK_goiffalse (FuncState *fs, expdesc *e) {
-  int pc;  /* pc of last jump */
+  int pc;  /* pc of new jump */
   luaK_dischargevars(fs, e);
   switch (e->k) {
     case VJMP: {
-      pc = e->u.info;
+      pc = e->u.info;  /* already jump if true */
       break;
     }
     case VNIL: case VFALSE: {
@@ -687,29 +886,32 @@ void luaK_goiffalse (FuncState *fs, expdesc *e) {
       break;
     }
     default: {
-      pc = jumponcond(fs, e, 1);
+      pc = jumponcond(fs, e, 1);  /* jump if true */
       break;
     }
   }
-  luaK_concat(fs, &e->t, pc);  /* insert last jump in 't' list */
-  luaK_patchtohere(fs, e->f);
+  luaK_concat(fs, &e->t, pc);  /* insert new jump in 't' list */
+  luaK_patchtohere(fs, e->f);  /* false list jumps to here (to go through) */
   e->f = NO_JUMP;
 }
 
 
+/*
+** Code 'not e', doing constant folding.
+*/
 static void codenot (FuncState *fs, expdesc *e) {
   luaK_dischargevars(fs, e);
   switch (e->k) {
     case VNIL: case VFALSE: {
-      e->k = VTRUE;
+      e->k = VTRUE;  /* true == not nil == not false */
       break;
     }
     case VK: case VKFLT: case VKINT: case VTRUE: {
-      e->k = VFALSE;
+      e->k = VFALSE;  /* false == not "x" == not 0.5 == not 1 == not true */
       break;
     }
     case VJMP: {
-      invertjump(fs, e);
+      negatecondition(fs, e);
       break;
     }
     case VRELOCABLE:
@@ -720,30 +922,32 @@ static void codenot (FuncState *fs, expdesc *e) {
       e->k = VRELOCABLE;
       break;
     }
-    default: {
-      lua_assert(0);  /* cannot happen */
-      break;
-    }
+    default: lua_assert(0);  /* cannot happen */
   }
   /* interchange true and false lists */
   { int temp = e->f; e->f = e->t; e->t = temp; }
-  removevalues(fs, e->f);
+  removevalues(fs, e->f);  /* values are useless when negated */
   removevalues(fs, e->t);
 }
 
 
+/*
+** Create expression 't[k]'. 't' must have its final result already in a
+** register or upvalue.
+*/
 void luaK_indexed (FuncState *fs, expdesc *t, expdesc *k) {
-  lua_assert(!hasjumps(t));
-  t->u.ind.t = t->u.info;
-  t->u.ind.idx = luaK_exp2RK(fs, k);
-  t->u.ind.vt = (t->k == VUPVAL) ? VUPVAL
-                                 : check_exp(vkisinreg(t->k), VLOCAL);
+  lua_assert(!hasjumps(t) && (vkisinreg(t->k) || t->k == VUPVAL));
+  t->u.ind.t = t->u.info;  /* register or upvalue index */
+  t->u.ind.idx = luaK_exp2RK(fs, k);  /* R/K index for key */
+  t->u.ind.vt = (t->k == VUPVAL) ? VUPVAL : VLOCAL;
   t->k = VINDEXED;
 }
 
 
 /*
-** return false if folding can raise an error
+** Return false if folding can raise an error.
+** Bitwise operations need operands convertible to integers; division
+** operations cannot have 0 as divisor.
 */
 static int validop (int op, TValue *v1, TValue *v2) {
   switch (op) {
@@ -760,7 +964,8 @@ static int validop (int op, TValue *v1, TValue *v2) {
 
 
 /*
-** Try to "constant-fold" an operation; return 1 iff successful
+** Try to "constant-fold" an operation; return 1 iff successful.
+** (In this case, 'e1' has the final result.)
 */
 static int constfolding (FuncState *fs, int op, expdesc *e1, expdesc *e2) {
   TValue v1, v2, res;
@@ -771,7 +976,7 @@ static int constfolding (FuncState *fs, int op, expdesc *e1, expdesc *e2) {
     e1->k = VKINT;
     e1->u.ival = ivalue(&res);
   }
-  else {  /* folds neither NaN nor 0.0 (to avoid collapsing with -0.0) */
+  else {  /* folds neither NaN nor 0.0 (to avoid problems with -0.0) */
     lua_Number n = fltvalue(&res);
     if (luai_numisnan(n) || n == 0)
       return 0;
@@ -783,15 +988,19 @@ static int constfolding (FuncState *fs, int op, expdesc *e1, expdesc *e2) {
 
 
 /*
-** Code for binary and unary expressions that "produce values"
-** (arithmetic operations, bitwise operations, concat, length). First
-** try to do constant folding (only for numeric [arithmetic and
-** bitwise] operations, which is what 'lua_arith' accepts).
-** Expression to produce final result will be encoded in 'e1'.
+** Emit code for binary and unary expressions that "produce values"
+** (everything but logical operators 'and', 'or' and comparison
+** operators).
+** First try to do constant folding (only for numeric [arithmetic and
+** bitwise] operations, which is what 'lua_arith' accepts). Expression
+** to produce final result will be encoded in 'e1'.
+** (The "free registers in proper order" reason is tricky: because
+** expression evaluation can be delayed, the final numbering for
+** registers in 'e1' and 'e2' depends on how each one was delayed.)
 */
 static void codeexpval (FuncState *fs, OpCode op,
                         expdesc *e1, expdesc *e2, int line) {
-  lua_assert(op >= OP_ADD);
+  lua_assert(OP_ADD <= op && op <= OP_CONCAT);
   if (op <= OP_BNOT && constfolding(fs, (op - OP_ADD) + LUA_OPADD, e1, e2))
     return;  /* result has been folded */
   else {
@@ -820,10 +1029,16 @@ static void codeexpval (FuncState *fs, OpCode op,
 }
 
 
+/*
+** Emit code for comparisons.
+** Code will jump if result equals 'cond' ('cond' true <=> code will
+** jump if result is true).
+*/
 static void codecomp (FuncState *fs, OpCode op, int cond, expdesc *e1,
                                                           expdesc *e2) {
   int o1 = luaK_exp2RK(fs, e1);
   int o2 = luaK_exp2RK(fs, e2);
+  lua_assert(OP_EQ <= op && op <= OP_LE);  /* comparison operation */
   freeexp(fs, e2);
   freeexp(fs, e1);
   if (cond == 0 && op != OP_EQ) {
@@ -836,8 +1051,11 @@ static void codecomp (FuncState *fs, OpCode op, int cond, expdesc *e1,
 }
 
 
+/*
+** Aplly prefix operation 'op' to expression 'e'.
+*/
 void luaK_prefix (FuncState *fs, UnOpr op, expdesc *e, int line) {
-  expdesc e2;
+  expdesc e2;  /* fake 2nd operand */
   e2.t = e2.f = NO_JUMP; e2.k = VKINT; e2.u.ival = 0;
   switch (op) {
     case OPR_MINUS: case OPR_BNOT: case OPR_LEN: {
@@ -850,14 +1068,18 @@ void luaK_prefix (FuncState *fs, UnOpr op, expdesc *e, int line) {
 }
 
 
+/*
+** Process 1st operand 'v' of binary operation 'op' before reading
+** 2nd operand.
+*/
 void luaK_infix (FuncState *fs, BinOpr op, expdesc *v) {
   switch (op) {
     case OPR_AND: {
-      luaK_goiftrue(fs, v);
+      luaK_goiftrue(fs, v);  /* go ahead only if 'v' is true */
       break;
     }
     case OPR_OR: {
-      luaK_goiffalse(fs, v);
+      luaK_goiffalse(fs, v);  /* go ahead only if 'v' is false */
       break;
     }
     case OPR_CONCAT: {
@@ -869,7 +1091,9 @@ void luaK_infix (FuncState *fs, BinOpr op, expdesc *v) {
     case OPR_MOD: case OPR_POW:
     case OPR_BAND: case OPR_BOR: case OPR_BXOR:
     case OPR_SHL: case OPR_SHR: {
-      if (!tonumeral(v, NULL)) luaK_exp2RK(fs, v);
+      if (!tonumeral(v, NULL))
+        luaK_exp2RK(fs, v);
+      /* else keep numeral, which may be folded with 2nd operand */
       break;
     }
     default: {
@@ -880,18 +1104,24 @@ void luaK_infix (FuncState *fs, BinOpr op, expdesc *v) {
 }
 
 
+/*
+** Finalize code for binary operation, after reading 2nd operand.
+** For '(a .. b .. c)' (which is '(a .. (b .. c))', because
+** concatenation is right associative), merge second CONCAT into first
+** one.
+*/
 void luaK_posfix (FuncState *fs, BinOpr op,
                   expdesc *e1, expdesc *e2, int line) {
   switch (op) {
     case OPR_AND: {
-      lua_assert(e1->t == NO_JUMP);  /* list must be closed */
+      lua_assert(e1->t == NO_JUMP);  /* list closed by 'luK_infix' */
       luaK_dischargevars(fs, e2);
       luaK_concat(fs, &e2->f, e1->f);
       *e1 = *e2;
       break;
     }
     case OPR_OR: {
-      lua_assert(e1->f == NO_JUMP);  /* list must be closed */
+      lua_assert(e1->f == NO_JUMP);  /* list closed by 'luK_infix' */
       luaK_dischargevars(fs, e2);
       luaK_concat(fs, &e2->t, e1->t);
       *e1 = *e2;
@@ -931,15 +1161,25 @@ void luaK_posfix (FuncState *fs, BinOpr op,
 }
 
 
+/*
+** Change line information associated with current position.
+*/
 void luaK_fixline (FuncState *fs, int line) {
   fs->f->lineinfo[fs->pc - 1] = line;
 }
 
 
+/*
+** Emit a SETLIST instruction.
+** 'base' is register that keeps table;
+** 'nelems' is #table plus those to be stored now;
+** 'tostore' is number of values (in registers 'base + 1',...) to add to
+** table (or LUA_MULTRET to add up to stack top).
+*/
 void luaK_setlist (FuncState *fs, int base, int nelems, int tostore) {
   int c =  (nelems - 1)/LFIELDS_PER_FLUSH + 1;
   int b = (tostore == LUA_MULTRET) ? 0 : tostore;
-  lua_assert(tostore != 0);
+  lua_assert(tostore != 0 && tostore <= LFIELDS_PER_FLUSH);
   if (c <= MAXARG_C)
     luaK_codeABC(fs, OP_SETLIST, base, b, c);
   else if (c <= MAXARG_Ax) {