kernel: move some doc comments for GAPState members, and some more comment cleanup

src/code.h

@@ -23,11 +23,24 @@
 **
 *T  StatHeader
 **
+**  Header for any statement or expression encoded in a function body.
 */
 typedef struct {
+    // `visited` starts out as 0 and is set to 1 if the statement or
+    // expression has ever been executed while profiling is turned on
     unsigned int visited : 1;
+
+    // `line` records the line number in the source file in which the
+    // statement or expression started
     unsigned int line : 31;
+
+    // `size` is the length in bytes of the statement or expression in
+    // bytes; the actual encoding rounds this up to a multiple of
+    // `sizeof(Stat)`
     unsigned int size : 24;
+
+    // the type of the expression or statement, see `enum STAT_TNUM`
+    // and `enum EXPR_TNUM`.
     unsigned int type : 8;
 } StatHeader;
 

src/gapstate.h

@@ -41,6 +41,9 @@ typedef struct GAPState {
 #endif
 
     /* From intrprtr.c */
+
+    // 'Tilde' is the object referenced by the operator '~', used in
+    // expressions such as '[ [ 1, 2 ], ~[ 1 ] ]'.
     Obj  Tilde;
 
     // The current assertion level for use in Assert
@@ -50,13 +53,33 @@ typedef struct GAPState {
     Obj CurrNamespace;
 
     /* From vars.c */
-    Bag   CurrLVars;
+
+    // 'CurrLVars' is the bag containing the values of the local variables of
+    // the currently executing interpreted function.
+    //
+    // Assignments to the local variables change this bag. We do not call
+    // 'CHANGED_BAG' for each of such change. Instead we wait until a garbage
+    // collection begins and then call 'CHANGED_BAG' in 'BeginCollectBags'.
+    Bag CurrLVars;
+
+    // 'PtrLVars' is a pointer to the 'CurrLVars' bag. This makes it faster to
+    // access local variables.
+    //
+    // Since a garbage collection may move this bag around, the pointer
+    // 'PtrLVars' must be recalculated afterwards in 'VarsAfterCollectBags'.
     Obj * PtrLVars;
+
     Bag   LVarsPool[16];
 
     /* From read.c */
     jmp_buf ReadJmpError;
 
+    // 'Prompt' holds the string that is to be printed if a new line is read
+    // from the interactive files '*stdin*' or '*errin*'.
+    //
+    // It is set to 'gap> ' or 'brk> ' in the read-eval-print loops and
+    // changed to the partial prompt '> ' in 'Read' after the first symbol is
+    // read.
     char Prompt[80];
 
     /* From stats.c */
@@ -69,6 +92,8 @@ typedef struct GAPState {
     ExecStatFunc * CurrExecStatFuncs;
 
     /* From code.c */
+
+    // A pointer to the current function body being executed
     void * PtrBody;
 
     /* From opers.c */

src/gvars.c

@@ -578,8 +578,6 @@ Obj ExprGVar ( UInt gvar )
 
 #define NSCHAR '@'
 
-/* TL: Obj CurrNamespace = 0; */
-
 static Obj FuncSET_NAMESPACE(Obj self, Obj str)
 {
     STATE(CurrNamespace) = str;

src/intrprtr.c

@@ -1918,13 +1918,10 @@ void IntrFalseExpr(IntrState * intr)
 
 /****************************************************************************
 **
-*F  IntrTildeExpr()  . . . . . . . . . . . . interpret tilde expression
+*F  IntrTildeExpr() . . . . . . . . . . . . . . .  interpret tilde expression
 **
 **  'IntrTildeExpr' is the action to interpret a tilde expression.
 **
-**  'Tilde' is the identifier for the operator '~', used in
-**  expressions such as '[ [ 1, 2 ], ~[ 1 ] ]'.
-**
 */
 void IntrTildeExpr(IntrState * intr)
 {
@@ -1936,7 +1933,7 @@ void IntrTildeExpr(IntrState * intr)
         return;
     }
 
-    if(! (STATE(Tilde)) ) {
+    if (!STATE(Tilde)) {
         // this code should be impossible to reach, the parser won't allow us
         // to get here; but we leave it here out of paranoia
         ErrorQuit("'~' does not have a value here", 0, 0);

src/io.h

@@ -272,18 +272,6 @@ UInt OpenInputLogStream(Obj stream);
 */
 UInt CloseInputLog(void);
 
-/****************************************************************************
- **
- *V  Prompt  . . . . . . . . . . . . . . . . . . . . . . prompt to be printed
- **
- **  'Prompt' holds the string that is to be printed if a  new  line  is read
- **  from the interactive files '*stdin*' or '*errin*'.
- **
- **  It is set to 'gap> ' or 'brk> ' in the read-eval-print loops and changed
- **  to the partial prompt '> ' in 'Read' after the first symbol is read.
- */
-/* TL: extern  const Char *    Prompt; */
-
 /****************************************************************************
 **
 *F  SetPrompt( <prompt> ) . . . . . . . . . . . . . set the user input prompt

src/read.c

@@ -88,54 +88,40 @@
 
 struct ReaderState {
 
-ScannerState s;
-
-IntrState intr;
-
-/****************************************************************************
-**
-*V  StackNams . . . . . . . . . . . . .  stack of local variables names lists
-**
-**  'StackNams' is a stack of local variables  names lists.  A new names list
-**  is pushed onto this stack when the  reader begins to  read a new function
-**  expression  (after  reading the argument   list  and the local  variables
-**  list), and popped again when the reader has finished reading the function
-**  expression (after reading the 'end').
-*/
-Obj  StackNams;
-
-/****************************************************************************
-**
-*V  ReadTop . . . . . . . . . . . . . . . . . . . . . .  top level expression
-*V  ReadTilde . . . . . . . . . . . . . . . . . . . . . . . . . .  tilde read
-**
-**  'ReadTop' is 0 if the reader is currently not reading a list or record
-**  expression. 'ReadTop' is 1 if the reader is currently reading an outmost
-**  list or record expression. 'ReadTop' is larger than 1 if the reader is
-**  currently reading a nested list or record expression.
-**
-**  'ReadTilde' is 1 if the reader has read a reference to a '~' symbol
-**  within the current outmost list or record expression.
-*/
-UInt ReadTop;
-UInt ReadTilde;
-
-/****************************************************************************
-**
-*V  CurrLHSGVar . . . . . . . . . . . .  current left hand side of assignment
-**
-**  'CurrLHSGVar' is the current left hand side of an assignment.  It is used
-**  to prevent undefined global variable  warnings, when reading a  recursive
-**  function.
-*/
-UInt CurrLHSGVar;
-
-
-UInt CurrentGlobalForLoopVariables[100];
-UInt CurrentGlobalForLoopDepth;
-
-UInt LoopNesting;
-
+    ScannerState s;
+
+    IntrState intr;
+
+    // 'StackNams' is a stack of local variables  names lists.  A new names
+    // list is pushed onto this stack when the  reader begins to  read a new
+    // function expression  (after  reading the argument   list  and the local
+    // variables list), and popped again when the reader has finished reading
+    // the function expression (after reading the 'end').
+    Obj StackNams;
+
+    // 'ReadTop' is 0 if the reader is currently not reading a list or record
+    // expression. 'ReadTop' is 1 if the reader is currently reading an
+    // outmost list or record expression. 'ReadTop' is larger than 1 if the
+    // reader is currently reading a nested list or record expression.
+    UInt ReadTop;
+
+    // 'ReadTilde' is 1 if the reader has read a reference to a '~' symbol
+    // within the current outmost list or record expression.
+    UInt ReadTilde;
+
+    // 'CurrLHSGVar' is the current left hand side of an assignment.  It is
+    // used to prevent undefined global variable  warnings, when reading a
+    // recursive function.
+    UInt CurrLHSGVar;
+
+    UInt CurrentGlobalForLoopVariables[100];
+    UInt CurrentGlobalForLoopDepth;
+
+    // 'LoopNesting' records how many nested loops are active. It starts out
+    // at 0 and is increment each time we enter a loop, and decrement when we
+    // exit one. It is used to determine whether 'break' and 'continue'
+    // statements are valid.
+    UInt LoopNesting;
 };
 
 typedef struct ReaderState ReaderState;
@@ -2070,8 +2056,6 @@ static void ReadIf(ReaderState * rs, TypSymbolSet follow)
 **                     <Statements>
 **                 'od' ';'
 */
-
-
 static void ReadFor(ReaderState * rs, TypSymbolSet follow)
 {
     volatile UInt       nrs;            /* number of statements in body    */

src/vars.c

@@ -45,21 +45,6 @@
 
 #include <stdio.h>
 
-
-/****************************************************************************
-**
-*V  CurrLVars   . . . . . . . . . . . . . . . . . . . . . local variables bag
-**
-**  'CurrLVars'  is the bag containing the  values  of the local variables of
-**  the currently executing interpreted function.
-**
-**  Assignments  to  the local variables change   this bag.  We  do  not call
-**  'CHANGED_BAG' for  each of such change.  Instead we wait until  a garbage
-**  collection begins  and then  call  'CHANGED_BAG'  in  'BeginCollectBags'.
-*/
-/* TL: Bag CurrLVars; */
-
-
 /****************************************************************************
 **
 *V  BottomLVars . . . . . . . . . . . . . . . . .  bottom local variables bag
@@ -72,19 +57,6 @@
 static Bag BottomLVars;
 
 
-/****************************************************************************
-**
-*V  PtrLVars  . . . . . . . . . . . . . . . .  pointer to local variables bag
-**
-**  'PtrLVars' is a pointer to the 'STATE(CurrLVars)' bag.  This  makes it faster to
-**  access local variables.
-**
-**  Since   a   garbage collection may  move   this  bag  around, the pointer
-**  'PtrLVars' must be recalculated afterwards in 'VarsAfterCollectBags'.
-*/
-/* TL: Obj * PtrLVars; */
-
-
 /****************************************************************************
 **
 *F  ObjLVar(<lvar>) . . . . . . . . . . . . . . . . value of a local variable

src/vars.h

@@ -25,40 +25,13 @@
 #include "objects.h"
 
 
-/****************************************************************************
-**
-*V  CurrLVars   . . . . . . . . . . . . . . . . . . . . . local variables bag
-**
-**  'CurrLVars'  is the bag containing the  values  of the local variables of
-**  the currently executing interpreted function.
-**
-**  Assignments  to  the local variables change   this bag.  We  do  not call
-**  'CHANGED_BAG' for  each of such change.  Instead we wait until  a garbage
-**  collection begins  and then  call  'CHANGED_BAG'  in  'BeginCollectBags'.
-*/
-/* TL: extern  Bag             CurrLVars; */
-
-
 /****************************************************************************
 **
 *F  IsBottomLVars(<lvars>) . . test whether lvars is at the call stack bottom
 */
 BOOL IsBottomLVars(Obj lvars);
 
 
-/****************************************************************************
-**
-*V  PtrLVars  . . . . . . . . . . . . . . . .  pointer to local variables bag
-**
-**  'PtrLVars' is a pointer to the 'CurrLVars' bag.  This  makes it faster to
-**  access local variables.
-**
-**  Since   a   garbage collection may  move   this  bag  around, the pointer
-**  'PtrLVars' must be recalculated afterwards in 'VarsAfterCollectBags'.
-*/
-/* TL: extern  Obj *           PtrLVars; */
-
-
 /****************************************************************************
 **
 *F  IS_LVARS_OR_HVARS()