4 files changed, 30 insertions, 18 deletions

diff --git a/lcode.c b/lcode.c
index 6f241c94..14d41f1a 100644
--- a/lcode.c
+++ b/lcode.c
@@ -753,7 +753,7 @@ void luaK_setoneret (FuncState *fs, expdesc *e) {
 
 
 /*
-** Ensure that expression 'e' is not a variable (nor a constant).
+** Ensure that expression 'e' is not a variable (nor a <const>).
 ** (Expression still may have jump lists.)
 */
 void luaK_dischargevars (FuncState *fs, expdesc *e) {
@@ -805,8 +805,8 @@ void luaK_dischargevars (FuncState *fs, expdesc *e) {
 
 
 /*
-** Ensures expression value is in register 'reg' (and therefore
-** 'e' will become a non-relocatable expression).
+** Ensure expression value is in register 'reg', making 'e' a
+** non-relocatable expression.
 ** (Expression still may have jump lists.)
 */
 static void discharge2reg (FuncState *fs, expdesc *e, int reg) {
@@ -860,7 +860,8 @@ static void discharge2reg (FuncState *fs, expdesc *e, int reg) {
 
 
 /*
-** Ensures expression value is in any register.
+** Ensure expression value is in a register, making 'e' a
+** non-relocatable expression.
 ** (Expression still may have jump lists.)
 */
 static void discharge2anyreg (FuncState *fs, expdesc *e) {
@@ -946,8 +947,11 @@ int luaK_exp2anyreg (FuncState *fs, expdesc *e) {
       exp2reg(fs, e, e->u.info);  /* put final result in it */
       return e->u.info;
     }
+    /* else expression has jumps and cannot change its register
+       to hold the jump values, because it is a local variable.
+       Go through to the default case. */
   }
-  luaK_exp2nextreg(fs, e);  /* otherwise, use next available register */
+  luaK_exp2nextreg(fs, e);  /* default: use next available register */
   return e->u.info;
 }
 
diff --git a/ldo.c b/ldo.c
index 5729b190..a60972b2 100644
--- a/ldo.c
+++ b/ldo.c
@@ -534,11 +534,11 @@ CallInfo *luaD_precall (lua_State *L, StkId func, int nresults) {
 
 
 /*
-** Call a function (C or Lua). 'inc' can be 1 (increment number
-** of recursive invocations in the C stack) or nyci (the same plus
-** increment number of non-yieldable calls).
+** Call a function (C or Lua) through C. 'inc' can be 1 (increment
+** number of recursive invocations in the C stack) or nyci (the same
+** plus increment number of non-yieldable calls).
 */
-static void docall (lua_State *L, StkId func, int nResults, int inc) {
+static void ccall (lua_State *L, StkId func, int nResults, int inc) {
   CallInfo *ci;
   L->nCcalls += inc;
   if (unlikely(getCcalls(L) >= LUAI_MAXCCALLS))
@@ -552,10 +552,10 @@ static void docall (lua_State *L, StkId func, int nResults, int inc) {
 
 
 /*
-** External interface for 'docall'
+** External interface for 'ccall'
 */
 void luaD_call (lua_State *L, StkId func, int nResults) {
-  return docall(L, func, nResults, 1);
+  ccall(L, func, nResults, 1);
 }
 
 
@@ -563,7 +563,7 @@ void luaD_call (lua_State *L, StkId func, int nResults) {
 ** Similar to 'luaD_call', but does not allow yields during the call.
 */
 void luaD_callnoyield (lua_State *L, StkId func, int nResults) {
-  return docall(L, func, nResults, nyci);
+  ccall(L, func, nResults, nyci);
 }
 
 
@@ -678,7 +678,7 @@ static void resume (lua_State *L, void *ud) {
   StkId firstArg = L->top - n;  /* first argument */
   CallInfo *ci = L->ci;
   if (L->status == LUA_OK)  /* starting a coroutine? */
-    docall(L, firstArg - 1, LUA_MULTRET, 1);  /* just call its body */
+    ccall(L, firstArg - 1, LUA_MULTRET, 1);  /* just call its body */
   else {  /* resuming from previous yield */
     lua_assert(L->status == LUA_YIELD);
     L->status = LUA_OK;  /* mark that it is running (again) */
diff --git a/lparser.h b/lparser.h
index 618cb010..2e6dae72 100644
--- a/lparser.h
+++ b/lparser.h
@@ -23,7 +23,7 @@
 
 /* kinds of variables/expressions */
 typedef enum {
-  VVOID,  /* when 'expdesc' describes the last expression a list,
+  VVOID,  /* when 'expdesc' describes the last expression of a list,
              this kind means an empty list (so, no expression) */
   VNIL,  /* constant nil */
   VTRUE,  /* constant true */
@@ -38,7 +38,8 @@ typedef enum {
   VLOCAL,  /* local variable; var.sidx = stack index (local register);
               var.vidx = relative index in 'actvar.arr'  */
   VUPVAL,  /* upvalue variable; info = index of upvalue in 'upvalues' */
-  VCONST,  /* compile-time constant; info = absolute index in 'actvar.arr'  */
+  VCONST,  /* compile-time <const> variable;
+              info = absolute index in 'actvar.arr'  */
   VINDEXED,  /* indexed variable;
                 ind.t = table register;
                 ind.idx = key's R index */
diff --git a/manual/manual.of b/manual/manual.of
index 86631bbc..606771f4 100644
--- a/manual/manual.of
+++ b/manual/manual.of
@@ -2516,7 +2516,8 @@ Lua's garbage collection can free or move internal memory
 and then invalidate pointers to internal strings.
 To allow a safe use of these pointers,
 The API guarantees that any pointer to a string in a stack index
-is valid while the value at that index is neither modified nor popped.
+is valid while the string value at that index is not removed from the stack.
+(It can be moved to another index, though.)
 When the index is a pseudo-index (referring to an upvalue),
 the pointer is valid while the corresponding call is active and
 the corresponding upvalue is not modified.
@@ -3744,10 +3745,13 @@ except that it allows the called function to yield @see{continuations}.
 }
 
 @APIEntry{void lua_pop (lua_State *L, int n);|
-@apii{n,0,-}
+@apii{n,0,e}
 
 Pops @id{n} elements from the stack.
 
+This function can run arbitrary code when removing an index
+marked as to-be-closed from the stack.
+
 }
 
 @APIEntry{void lua_pushboolean (lua_State *L, int b);|
@@ -4227,7 +4231,7 @@ for the @Q{newindex} event @see{metatable}.
 }
 
 @APIEntry{void lua_settop (lua_State *L, int index);|
-@apii{?,?,-}
+@apii{?,?,e}
 
 Accepts any index, @N{or 0},
 and sets the stack top to this index.
@@ -4235,6 +4239,9 @@ If the new top is greater than the old one,
 then the new elements are filled with @nil.
 If @id{index} @N{is 0}, then all stack elements are removed.
 
+This function can run arbitrary code when removing an index
+marked as to-be-closed from the stack.
+
 }
 
 @APIEntry{void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);|