kernel: add or adjust some comments

src/compiler.c

@@ -3050,7 +3050,7 @@ static CVar CompElmListLev(Expr expr)
     // get the level
     level = READ_EXPR(expr, 2);
 
-    /* emit the code to select the elements from several lists (to <lists>)*/
+    // emit the code to select the elements from several lists (to <lists>)
     Emit( "ElmListLevel( %c, %c, %d );\n", lists, pos, level );
 
     // free the temporaries
@@ -3080,7 +3080,7 @@ static CVar CompElmsListLev(Expr expr)
     // get the level
     level = READ_EXPR(expr, 2);
 
-    /* emit the code to select the elements from several lists (to <lists>)*/
+    // emit the code to select the elements from several lists (to <lists>)
     Emit( "ElmsListLevelCheck( %c, %c, %d );\n", lists, poss, level );
 
     // free the temporaries
@@ -3748,7 +3748,7 @@ static void CompIf(Stat stat)
         // compile the body
         CompStat(READ_STAT(stat, 2 * (i - 1) + 1));
 
-        /* remember what we know after executing one of the previous bodies*/
+        // remember what we know after executing one of the previous bodies
         MergeInfoCVars( info_out, INFO_FEXP(CURR_FUNC()) );
 
         // emit the rest code
@@ -3773,7 +3773,7 @@ static void CompIf(Stat stat)
         // compile the body
         CompStat(READ_STAT(stat, 2 * (i - 1) + 1));
 
-        /* remember what we know after executing one of the previous bodies*/
+        // remember what we know after executing one of the previous bodies
         MergeInfoCVars( info_out, INFO_FEXP(CURR_FUNC()) );
 
         // emit the rest code
@@ -3787,7 +3787,7 @@ static void CompIf(Stat stat)
         // this is what we know if we enter this branch
         CopyInfoCVars( INFO_FEXP(CURR_FUNC()), info_in );
 
-        /* remember what we know after executing one of the previous bodies*/
+        // remember what we know after executing one of the previous bodies
         MergeInfoCVars( info_out, INFO_FEXP(CURR_FUNC()) );
 
     }
@@ -5173,6 +5173,18 @@ static void CompFunc(Obj func)
 /****************************************************************************
 **
 *F  CompileFunc( <filename>, <func>, <name>, <crc>, <magic2> ) . . compile
+**
+**  The meaning of the arguments is as follows:
+**  - 'filename': the file the generated C code should be written to.
+**  - 'func': a function generated by parsing the input GAP file via
+**    'READ_AS_FUNC' resp. 'ReadEvalFile'.
+**  - 'name' is the designated name for the entry function of the kernel
+**    extension generated by the compiler, e.g. `Init__type1`.
+**  - 'crc' is a checksum of the content of the input file.
+**  - 'magic2' is a string used as name for the module. Typically this is the
+**     name of GAP source file being compiled; but for compiled GAP code
+**     that is statically linked into the kernel, the placeholder GAPROOT is
+**     used in there, e.g. in `GAPROOT/lib/oper1.g`.
 */
 Int CompileFunc(Obj filename, Obj func, Obj name, Int crc, Obj magic2)
 {

src/cyclotom.c

@@ -824,7 +824,7 @@ static UInt FindCommonField(UInt nl, UInt nr, UInt *ml, UInt *mr)
   if (n8 > INT_INTOBJ_MAX)
     ErrorMayQuit("This computation would require a cyclotomic field too large to be handled", 0, 0);
 
-  /* Switch to UInt now we know we can*/
+  // Switch to UInt now we know we can
   n = (UInt)n8;
 
   // Handle the soft limit
@@ -1418,7 +1418,7 @@ static Obj PowCyc(Obj opL, Obj opR)
     // get the exponent
     exp = INT_INTOBJ(opR);
 
-    /* for $cyc^0$ return 1, for $cyc^1$ return cyc, for $rat^exp$ delegate*/
+    // for $cyc^0$ return 1, for $cyc^1$ return cyc, for $rat^exp$ delegate
     if ( exp == 0 ) {
         pow = INTOBJ_INT(1);
     }
@@ -1568,7 +1568,7 @@ static Obj FuncIS_CYC_INT(Obj self, Obj val)
     const Obj *         cfs;            // pointer to the coefficients
     UInt                i;              // loop variable
 
-    /* return 'true' if <obj> is a cyclotomic integer and 'false' otherwise*/
+    // return 'true' if <obj> is a cyclotomic integer and 'false' otherwise
     if ( IS_INT(val) ) {
         return True;
     }

src/debug.h

@@ -14,10 +14,8 @@
 #ifndef GAP_DEBUG_H
 #define GAP_DEBUG_H
 
-/* GAP_ASSERT is a version of 'assert' which is enabled by the
-** configure option --enable-debug
-*/
-
+// GAP_ASSERT is a version of 'assert' which is enabled by the
+// configure option --enable-debug
 #ifdef GAP_KERNEL_DEBUG
 #define GAP_ASSERT(x) assert(x)
 

src/error.c

@@ -72,9 +72,9 @@ UInt OpenErrorOutput(TypOutputFile * output)
     }
 
     if (!ret) {
-        /* It may be we already tried and failed to open *errout* above but
-         * but this is an extreme case so it can't hurt to try again
-         * anyways */
+        // It may be we already tried and failed to open *errout* above but
+        // but this is an extreme case so it can't hurt to try again
+        // anyways
         ret = OpenOutput(output, "*errout*", FALSE);
         if (ret) {
             Pr("failed to open error stream\n", 0, 0);
@@ -276,8 +276,8 @@ Obj CALL_WITH_CATCH(Obj func, volatile Obj args)
         // in case func was a kernel function.
         TakeInterrupt();
 #ifdef HPCGAP
-        /* There should be no locks to pop off the stack, but better safe than
-         * sorry. */
+        // There should be no locks to pop off the stack, but better safe than
+        // sorry.
         PopRegionLocks(lockSP);
         TLS(currentRegion) = savedRegion;
 #endif

src/gap.c

@@ -1490,8 +1490,8 @@ void InitializeGap (
         LoadWorkspace(SyRestoring);
         SyRestoring = NULL;
 
-        /* Call POST_RESTORE which is a GAP function that now takes control,
-           calls the post restore functions and then runs a GAP session */
+        // Call POST_RESTORE which is a GAP function that now takes control,
+        // calls the post restore functions and then runs a GAP session
         Obj POST_RESTORE = ValGVar(GVarName("POST_RESTORE"));
         if (POST_RESTORE != 0 && IS_FUNC(POST_RESTORE)) {
           Call0ArgsInNewReader(POST_RESTORE);
@@ -1513,10 +1513,9 @@ void InitializeGap (
     // check initialisation
     ModulesCheckInit();
 
-    /* read the init files
-       this now actually runs the GAP session, we only get
-       past here when we're about to exit.
-                                           */
+    // read the init files
+    // this now actually runs the GAP session, we only get
+    // past here when we're about to exit.
     if ( SyLoadSystemInitFile ) {
       GAP_TRY {
         if ( READ_GAP_ROOT("lib/init.g") == 0 ) {

src/gvars.c

@@ -105,23 +105,10 @@ static SymbolTable GVarSymbolTable;
 **
 *V  TLVars  . . . . . . . . . . . . . . . . . . . . . thread-local variables
 */
-
 static Obj TLVars;
 
 #endif
 
-/****************************************************************************
-**
-*F  VAL_GVAR(<gvar>)  . . . . . . . . . . . . . . .  value of global variable
-**
-**  'VAL_GVAR' returns the  value of the global  variable  <gvar>.  If <gvar>
-**  has no  assigned value, 'VAL_GVAR' returns 0.   In this case <gvar> might
-**  be an automatic global variable, and one should call 'ValAutoGVar', which
-**  will return the value of <gvar>  after evaluating <gvar>-s expression, or
-**  0 if <gvar> was not an automatic variable.
-**
-*/
-
 #ifdef USE_GVAR_BUCKETS
 
 // FIXME/TODO: Do we still need the VAL_GVAR_INTERN macro, or can we replace

src/intrprtr.c

@@ -4173,8 +4173,7 @@ static Int InitKernel (
 
     InitFopyGVar( "CONVERT_FLOAT_LITERAL_EAGER", &CONVERT_FLOAT_LITERAL_EAGER);
 
-
-    /* The work of handling Options is also delegated*/
+    // The work of handling options is also delegated
     ImportFuncFromLibrary( "PushOptions", &PushOptions );
     ImportFuncFromLibrary( "PopOptions",  &PopOptions  );
 

src/macfloat.c

@@ -653,7 +653,7 @@ static Int InitKernel (
     // equivalents
 
     // Anything else, like mixed ops with rationals, we can leave to the
-    // library at least for a while */
+    // library at least for a while
 
     return 0;
 }

src/stats.c

@@ -348,8 +348,6 @@ static ALWAYS_INLINE ExecStatus ExecForHelper(Stat stat, UInt nr)
     Stat                body2;          // second stat. of body of loop
     Stat                body3;          // third  stat. of body of loop
     UInt                i;              // loop variable
-    Obj                 nfun, dfun;     /* functions for NextIterator and
-                                           IsDoneIterator                  */
 
     GAP_ASSERT(1 <= nr && nr <= 3);
 
@@ -410,6 +408,8 @@ static ALWAYS_INLINE ExecStatus ExecForHelper(Stat stat, UInt nr)
 
     // general case
     else {
+        Obj nfun;    // function for NextIterator
+        Obj dfun;    // function for IsDoneIterator
 
         // get the iterator
         list = CALL_1ARGS( ITERATOR, list );

src/sysmem.c

@@ -303,8 +303,8 @@ int SyTryToIncreasePool(void)
 
 static void *SyMMapStart = NULL;   // Start of mmap'ed region for POOL
 static void *SyMMapEnd;            // End of mmap'ed region for POOL
-static void *SyMMapAdvised;        /* We have already advised about non-usage
-                                      up to here. */
+static void *SyMMapAdvised;        // We have already advised about non-usage
+                                   // up to here.
 
 void SyMAdviseFree(void)
 {

src/sysstr.c

@@ -22,22 +22,22 @@ size_t gap_strlcpy(char * dst, const char * src, size_t len)
     if (len > 0) {
         // Copy up to len-1 bytes (reserve one for the terminating zero).
         while (--len > 0) {
-            /* Copy from src to dst; if we reach the string end, we are
-               done and can simply return the total source string length */
+            // Copy from src to dst; if we reach the string end, we are
+            // done and can simply return the total source string length
             if ((*dst++ = *src++) == 0) {
                 // return length of source string without the zero byte
                 return src - orig_src - 1;
             }
         }
 
-        /* If we got here, then we used up the whole buffer and len is zero.
-           We must make sure to terminate the destination string. */
+        // If we got here, then we used up the whole buffer and len is zero.
+        // We must make sure to terminate the destination string.
         *dst = 0;
     }
 
-    /* in the end, we must return the length of the source string, no
-       matter whether we completely copied or not; so advance src
-       till its terminator is reached */
+    // in the end, we must return the length of the source string, no
+    // matter whether we completely copied or not; so advance src
+    // till its terminator is reached
     while (*src++)
         ;
 
@@ -56,14 +56,14 @@ size_t gap_strlcat(char * dst, const char * src, size_t len)
         len--;
     }
 
-    /* We can only append anything if there is free space left in the
-       destination buffer. */
+    // We can only append anything if there is free space left in the
+    // destination buffer.
     if (len > 0) {
         // One byte goes away for the terminating zero.
         len--;
 
-        /* Do the actual work and append from src to dst, until we either
-           appended everything, or reached the dst buffer's end. */
+        // Do the actual work and append from src to dst, until we either
+        // appended everything, or reached the dst buffer's end.
         while (*src != 0 && len > 0) {
             *dst++ = *src++;
             len--;