From e592f94a643de0bf8d62f6c6128fe752c673f5ac Mon Sep 17 00:00:00 2001
From: Roberto Ierusalimschy <roberto@inf.puc-rio.br>
Date: Tue, 22 Oct 2019 14:08:22 -0300
Subject: [PATCH] Details (mostly comments)

---
 lgc.c     |  1 +
 lobject.h | 31 +++++++++++++++++++++++--------
 ltable.c  |  3 +++
 ltests.c  |  2 +-
 4 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/lgc.c b/lgc.c
index cf62a45c..db519c6d 100644
--- a/lgc.c
+++ b/lgc.c
@@ -1565,6 +1565,7 @@ static void incstep (lua_State *L, global_State *g) {
 */
 void luaC_step (lua_State *L) {
   global_State *g = G(L);
+  lua_assert(!g->gcemergency);
   if (g->gcrunning) {  /* running? */
     if(isdecGCmodegen(g))
       genstep(L, g);
diff --git a/lobject.h b/lobject.h
index a22148c0..0c38affe 100644
--- a/lobject.h
+++ b/lobject.h
@@ -17,11 +17,12 @@
 
 
 /*
-** Extra tags for non-values
+** Extra tags for collectable non-values
 */
 #define LUA_TUPVAL	LUA_NUMTAGS  /* upvalues */
 #define LUA_TPROTO	(LUA_NUMTAGS+1)  /* function prototypes */
 
+
 /*
 ** number of all possible tags (including LUA_TNONE)
 */
@@ -30,7 +31,7 @@
 
 /*
 ** tags for Tagged Values have the following use of bits:
-** bits 0-3: actual tag (a LUA_T* value)
+** bits 0-3: actual tag (a LUA_T* constant)
 ** bits 4-5: variant bits
 ** bit 6: whether value is collectable
 */
@@ -86,24 +87,35 @@ typedef struct TValue {
 
 
 /* Macros for internal tests */
+
+/* collectable object has the same tag as the original value */
 #define righttt(obj)		(ttypetag(obj) == gcvalue(obj)->tt)
 
+/*
+** Any value being manipulated by the program either is non
+** collectable, or the collectable object has the right tag
+** and it is not dead.
+*/
 #define checkliveness(L,obj) \
 	((void)L, lua_longassert(!iscollectable(obj) || \
 		(righttt(obj) && (L == NULL || !isdead(G(L),gcvalue(obj))))))
 
 
 /* Macros to set values */
+
+/* set a value's tag */
 #define settt_(o,t)	((o)->tt_=(t))
 
 
+/* main macro to copy values (from 'obj1' to 'obj2') */
 #define setobj(L,obj1,obj2) \
 	{ TValue *io1=(obj1); const TValue *io2=(obj2); \
-          io1->value_ = io2->value_; io1->tt_ = io2->tt_; \
-	  checkliveness(L,io1); lua_assert(!isreallyempty(io1)); }
+          io1->value_ = io2->value_; settt_(io1, io2->tt_); \
+	  checkliveness(L,io1); lua_assert(!isnonstrictnil(io1)); }
 
 /*
-** different types of assignments, according to destination
+** Different types of assignments, according to source and destination.
+** (They are mostly equal now, but may be different in the future.)
 */
 
 /* from stack to stack */
@@ -118,13 +130,16 @@ typedef struct TValue {
 #define setobj2t	setobj
 
 
-
+/*
+** Entries in the Lua stack
+*/
 typedef union StackValue {
   TValue val;
 } StackValue;
 
 
-typedef StackValue *StkId;  /* index to stack elements */
+/* index to stack elements */
+typedef StackValue *StkId;
 
 /* convert a 'StackValue' to a 'TValue' */
 #define s2v(o)	(&(o)->val)
@@ -166,7 +181,7 @@ typedef StackValue *StkId;  /* index to stack elements */
 /*
 ** macro to detect non-standard nils (used only in assertions)
 */
-#define isreallyempty(v)	(ttisnil(v) && !ttisstrictnil(v))
+#define isnonstrictnil(v)	(ttisnil(v) && !ttisstrictnil(v))
 
 
 /*
diff --git a/ltable.c b/ltable.c
index 5561d45e..4c7ae994 100644
--- a/ltable.c
+++ b/ltable.c
@@ -155,6 +155,9 @@ static Node *mainposition (const Table *t, int ktt, const Value *kvl) {
 }
 
 
+/*
+** Returns the main position of an element given as a 'TValue'
+*/
 static Node *mainpositionTV (const Table *t, const TValue *key) {
   return mainposition(t, rawtt(key), valraw(key));
 }
diff --git a/ltests.c b/ltests.c
index 0d4ec938..bb5dad54 100644
--- a/ltests.c
+++ b/ltests.c
@@ -80,7 +80,7 @@ static int tpanic (lua_State *L) {
 
 
 /*
-** Warning function for tests. Fist, it concatenates all parts of
+** Warning function for tests. First, it concatenates all parts of
 ** a warning in buffer 'buff'. Then, it has three modes:
 ** - 0.normal: messages starting with '#' are shown on standard output;
 ** - other messages abort the tests (they represent real warning