kernel: tweak some comments

* explain difference between COPY_OBJ and CopyObj
* update comments which referred to "macros" that now are functions
* fix some spelling mistakes

src/calls.h

@@ -71,7 +71,7 @@ typedef Obj (* ObjFunc_6ARGS) (Obj self, Obj a1, Obj a2, Obj a3, Obj a4, Obj a5,
 *F  BODY_FUNC(<func>) . . . . . . . . . . . . . . . . . .  body of a function
 *F  ENVI_FUNC(<func>) . . . . . . . . . . . . . . . environment of a function
 **
-**  These macros  make it possible  to access  the  various components  of  a
+**  These functions make it possible to access the various components of a
 **  function.
 **
 **  'HDLR_FUNC(<func>,<i>)' is the <i>-th handler of the function <func>.

src/intobj.h

@@ -26,10 +26,9 @@
 **  To aid overflow check the most significant two bits must always be equal,
 **  that is to say that the sign bit of immediate integers has a guard bit.
 **
-**  The macros 'INTOBJ_INT' and 'INT_INTOBJ' should be used to convert between
-a
-**  small integer value and its representation as immediate integer handle.
-
+**  The functions 'INTOBJ_INT' and 'INT_INTOBJ' should be used to convert
+**  between a small integer value and its representation as immediate integer
+**  handle.
 */
 
 #ifndef GAP_INTOBJ_H

src/lists.h

@@ -811,8 +811,8 @@ typedef enum {
 **
 **  'SetFiltListTNums[<tnum>][<fnum>]'
 **
-**  The macro  'SET_FILT_LIST' is  used  to  set  the filter  for a  list  by
-**  changing its type number.
+**  'SET_FILT_LIST' is used to set the filter for a list by changing its
+**  type number.
 **
 **  Two values are treated specially:
 **    0 : The default. This tnum should not change.
@@ -854,8 +854,8 @@ Obj SET_FILTER_LIST(Obj list, Obj filter);
 **
 **  'ResetFiltListTNums[<tnum>][<fnum>]'
 **
-**  The macro 'RESET_FILT_LIST' is used  to  set  the filter  for a  list  by
-**  changing its type number.
+**  'RESET_FILT_LIST' is used to set the filter for a list by changing its
+**  type number.
 **
 **  The same special values are used as SetFiltListTNums.
 */
@@ -902,7 +902,7 @@ extern Int HasFiltListTNums [ LAST_REAL_TNUM ] [ LAST_FN + 1 ];
 **
 **  'ClearPropsTNums[<tnum>]'
 **
-**  The macro 'CLEAR_PROPS_LIST' is used to clear all properties of a list.
+**  'CLEAR_PROPS_LIST' is used to clear all properties of a list.
 */
 extern UInt ClearFiltsTNums [ LAST_REAL_TNUM ];
 

src/objects.h

@@ -301,7 +301,7 @@ GAP_STATIC_ASSERT(LAST_REAL_TNUM <= 254, "LAST_REAL_TNUM is too large");
 *F  SET_OBJ_FLAG(<obj>, <flag>) . . . . . . . . . . . . . . . set object flag
 *F  CLEAR_OBJ_FLAG(<obj>, <flag>) . . . . . . . . . . . . . clear object flag
 **
-**  These three macros test, set, and clear object flags, respectively.
+**  These three functions test, set, and clear object flags, respectively.
 **  For non-immediate objects, these are simply the bag flags, see
 **  TEST_BAG_FLAG, SET_BAG_FLAG, CLEAR_BAG_FLAG.
 **
@@ -677,8 +677,8 @@ Obj CopyObj(Obj obj, Int mut);
 **  'COPY_OBJ'  implements  the first pass  of  'CopyObj', i.e., it makes the
 **  structural copy of <obj> and marks <obj> as already copied.
 **
-**  Note that 'COPY_OBJ' is a macro, so do not call it with arguments that
-**  have side effects.
+**  'COPY_OBJ' must only be used from within CopyObjFuncs functions. To copy
+**  an object from regular code, call 'CopyObj'.
 */
 #if !defined(USE_THREADSAFE_COPYING)
 Obj COPY_OBJ(Obj obj, Int mut);

src/plist.h

@@ -14,7 +14,7 @@
 **  current  logical length.  The  last position to  which  an element can be
 **  assigned without resizing the plain list is called the physical length.
 **
-**  This representation  is encoded by  the macros 'NEW_PLIST', 'GROW_PLIST',
+**  This representation is encoded by the functions 'NEW_PLIST', 'GROW_PLIST',
 **  'SHRINK_PLIST', 'SET_LEN_PLIST',    'LEN_PLIST',     'SET_ELM_PLIST', and
 **  'ELM_PLIST', which are used by the functions in this package and the rest
 **  of the {\GAP} kernel to access plain lists.

src/precord.h

@@ -17,7 +17,7 @@
 
 /****************************************************************************
 **
-*F * * * * * * * * * * standard macros for plain records  * * * * * * * * * *
+*F * * * * * * * * * standard functions for plain records * * * * * * * * * *
 */
 
 

src/range.h

@@ -14,8 +14,8 @@
 **  Read  also   "More about Ranges"  about  the different  representation of
 **  ranges.
 **
-**  Ranges  can  be  accessed  through  the macros  'NEW_RANGE',  'IS_RANGE',
-**  'SET_LEN_RANGE',   'GET_LEN_RANGE',  'SET_LOW_RANGE',    'GET_LOW_RANGE',
+**  Ranges can be accessed through the functions 'NEW_RANGE', 'IS_RANGE',
+**  'SET_LEN_RANGE', 'GET_LEN_RANGE', 'SET_LOW_RANGE', 'GET_LOW_RANGE',
 **  'SET_INC_RANGE', 'GET_INC_RANGE', and 'GET_ELM_RANGE'.
 **
 **  This package  also contains  the  list  functions  for ranges, which  are

src/system.h

@@ -72,15 +72,15 @@ GAP_STATIC_ASSERT(sizeof(void *) == SIZEOF_VOID_P, "sizeof(void *) is wrong");
 **  truncated, or GAP aborts.
 **
 **  Note that no fixed buffer size is sufficient to store arbitrary paths
-**  on contemporary operation systems, as paths can have arbitrary length.
+**  on contemporary operating systems, as paths can have arbitrary length.
 **  This also means that the POSIX constant PATH_MAX does not really do the
 **  job its name would suggest (nor do MAXPATHLEN, MAX_PATH etc.).
 **
 **  Writing POSIX compliant code without a hard coded buffer size is rather
 **  challenging, as often there is no way to find out in advance how large a
 **  buffer may need to be. So you have to start with some buffer size, then
 **  check for errors; if 'errno' equals 'ERANGE', double the buffer size and
-**  repeated, until you succeed or run out of memory.
+**  repeat, until you succeed or run out of memory.
 **
 **  Instead of going down this road, we use a fixed buffer size after all.
 **  This way, at least our code stays simple. Also, this is what most (?)