fix inconsistent comment format in src/*.h files

This makes it easier to deal programmatically with the comments.
The most relevant changes concern '*V' vs. '*F',
round and square brackets in '*V' and '*T' lines,
and the analogue of GAPDoc's <C> element.
Besides that, I have fixed some obvious typos.

src/blister.h

@@ -164,8 +164,9 @@ static inline const UInt * CONST_BLOCK_ELM_BLIST_PTR(Obj list, UInt pos)
 **
 *F  MASK_POS_BLIST( <pos> )  . . . .  bit mask for position of a Boolean list
 **
-**  MASK_POS_BLIST(<pos>) returns a UInt with   a single set bit in  position
-**  (pos-1) % BIPEB, useful for accessing the pos'th element of a blist
+**  'MASK_POS_BLIST(<pos>)' returns a UInt with a single set bit in  position
+**  '(<pos>-1) % BIPEB',
+**  useful for accessing the <pos>-th element of a blist.
 */
 static inline UInt MASK_POS_BLIST(UInt pos)
 {
@@ -221,7 +222,7 @@ static inline void CLEAR_BIT_BLIST(Obj list, UInt pos)
 **
 *F  COUNT_TRUES_BLOCK( <block> ) . . . . . . . . . . .  count number of trues
 **
-** 'COUNT_TRUES_BLOCK( <block> )' returns the number of 1 bits in the
+**  'COUNT_TRUES_BLOCK( <block> )' returns the number of 1 bits in the
 **  UInt <block>. Two implementations are included below. One uses the
 **  gcc builtin __builtin_popcount which usually generates the popcntl
 **  or popcntq instruction on sufficiently recent CPUs. The other uses
@@ -353,7 +354,7 @@ extern void AssBlist (
 **
 *F  ConvBlist( <list> ) . . . . . . . . .  convert a list into a boolean list
 **
-**  `ConvBlist' changes the representation of boolean  lists into the compact
+**  'ConvBlist' changes the representation of boolean  lists into the compact
 **  representation of type 'T_BLIST' described above.
 */
 extern void ConvBlist (
@@ -365,7 +366,7 @@ extern void ConvBlist (
 *F  CopyBits( <fromblock>, <from-starting-bit>, <toblock>, <to-starting-bit>,
 **            <numbits> )
 **
-**  `CopyBits' copies <numbits> bits (numbering bits within a UInt
+**  'CopyBits' copies <numbits> bits (numbering bits within a UInt
 **   from the least significant to the most significant) starting with
 **   bit number <from-starting-bit> of UInt *<fromblock> to a destination
 **   starting at bit <to-starting-bit> of *<toblock>. The source and 

src/calls.h

@@ -432,9 +432,9 @@ extern Obj NewFunctionCT (
 **
 *F  ArgStringToList( <nams_c> )
 **
-** 'ArgStringToList' takes a C string <nams_c> containing a list of comma
-** separated argument names, and turns it into a plist of strings, ready
-** to be passed to 'NewFunction' as <nams>.
+**  'ArgStringToList' takes a C string <nams_c> containing a list of comma
+**  separated argument names, and turns it into a plist of strings, ready
+**  to be passed to 'NewFunction' as <nams>.
 */
 extern Obj ArgStringToList(const Char *nams_c);
 

src/code.h

@@ -43,12 +43,12 @@ typedef struct {
 
 /****************************************************************************
 **
-** Function body headers
+**  Function body headers
 **
-** 'FILENAME_BODY' is a string containing the file of a function
-** 'STARTLINE_BODY' is the line number where a function starts.
-** 'ENDLINE_BODY' is the line number where a function ends.
-** 'LOCATION_BODY' is a string describing the location of a function.
+**  'FILENAME_BODY' is a string containing the file of a function.
+**  'STARTLINE_BODY' is the line number where a function starts.
+**  'ENDLINE_BODY' is the line number where a function ends.
+**  'LOCATION_BODY' is a string describing the location of a function.
 **  Typically this will be the name of a C function implementing it.
 **
 **  These each have a 'GET' and a 'SET' variant, to read or set the value.

src/gap.h

@@ -67,14 +67,14 @@ extern void ViewObjHandler ( Obj obj );
 
 /****************************************************************************
 **
-*F RegisterBreakloopObserver( <func> )
+*F  RegisterBreakloopObserver( <func> )
 **
-** Register a function which will be called when the break loop is entered
-** and left. Function should take a single Int argument which will be 1 when
-** break loop is entered, 0 when leaving.
+**  Register a function which will be called when the break loop is entered
+**  and left. Function should take a single Int argument which will be 1 when
+**  break loop is entered, 0 when leaving.
 **
-** Note that it is also possible to leave the break loop (or any GAP code)
-** by longjmping. This should be tracked with RegisterSyLongjmpObserver.
+**  Note that it is also possible to leave the break loop (or any GAP code)
+**  by longjmping. This should be tracked with RegisterSyLongjmpObserver.
 */
 
 typedef void (*intfunc)(Int);

src/gaputils.h

@@ -21,7 +21,7 @@
 
 /****************************************************************************
 **
-** Compute the number of elements of a given C array.
+**  Compute the number of elements of a given C array.
 **/
 #define ARRAY_SIZE(arr)     ( sizeof(arr) / sizeof((arr)[0]) )
 

src/gasman.h

@@ -142,12 +142,12 @@ static inline UInt TNUM_BAG(Bag bag) {
 **  To test that all of them are set, compare the result to the original
 **  flags, e.g.
 **
-** 	if (TEST_BAG_FLAG(obj, FLAG1 | FLAG2 ) == (FLAG1 | FLAG2)) ...
+**  	if (TEST_BAG_FLAG(obj, FLAG1 | FLAG2 ) == (FLAG1 | FLAG2)) ...
 **
 **  Similary, if you wish to test that FLAG1 is set and FLAG2 is not set,
 **  use:
 **
-** 	if (TEST_BAG_FLAG(obj, FLAG1 | FLAG2 ) == FLAG1) ...
+**  	if (TEST_BAG_FLAG(obj, FLAG1 | FLAG2 ) == FLAG1) ...
 **
 **  Each flag must be a an integer with exactly one bit set, e.g. a value
 **  of the form (1 << i). Currently, 'i' must be in the range from 0 to
@@ -1053,9 +1053,9 @@ extern  void            InitCollectFuncBags (
 
 /****************************************************************************
 **
-*F  CheckMasterPointers() . . . . . . . . . . . . .do some consistency checks
+*F  CheckMasterPointers() . . . . . . . . . . . .  do some consistency checks
 **
-**  'CheckMasterPointers()' tests for masterpoinetrs which are not one of the
+**  'CheckMasterPointers' tests for masterpointers which are not one of the
 **  following:
 **
 **  0                       denoting the end of the free chain
@@ -1130,9 +1130,9 @@ extern void FinishBags( void );
 **
 *F  CallbackForAllBags( <func> ) call a C function on all non-zero mptrs
 **
-** This calls a   C  function on every    bag, including ones  that  are  not
-** reachable from    the root, and    will  be deleted  at the   next garbage
-** collection, by simply  walking the masterpointer area. Not terribly safe
+**  This calls a   C  function on every   bag, including ones  that  are  not
+**  reachable from    the root, and   will  be deleted  at the   next garbage
+**  collection, by simply  walking the masterpointer area. Not terribly safe.
 ** 
 */
 #ifdef USE_GASMAN

src/gvars.h

@@ -51,7 +51,7 @@ extern Obj ValGVar(UInt gvar);
 *V  ErrorMustEvalToFuncFunc . . . . . . . . .  function that signals an error
 **
 **  'ErrorMustEvalToFuncFunc' is a (variable number of  args)  function  that
-**  signals the error ``Function: <func> be a function''.
+**  signals the error ``Function Calls: <func> must be a function''.
 */
 extern Obj ErrorMustEvalToFuncFunc;
 

src/integer.h

@@ -97,7 +97,7 @@ static inline const mp_limb_t * CONST_ADDR_INT(Obj obj)
 
 /**************************************************************************
 **
-**  'SIZE_INT returns the number of limbs in a large integer object.
+**  'SIZE_INT' returns the number of limbs in a large integer object.
 */
 static inline UInt SIZE_INT(Obj obj)
 {
@@ -108,7 +108,7 @@ static inline UInt SIZE_INT(Obj obj)
 
 /**************************************************************************
 **
-**  IS_NEG_INT' returns 1 if 'obj' is a negative large or immediate
+**  'IS_NEG_INT' returns 1 if 'obj' is a negative large or immediate
 **  integer object, and 0 for all other kinds of objects.
 */
 static inline Int IS_NEG_INT(Obj obj)
@@ -156,9 +156,9 @@ static inline Int IS_EVEN_INT(Obj obj)
 
 /**************************************************************************
 **
-** The following functions convert Int, UInt or Int8 respectively into
-** a GAP integer, either an immediate, small integer if possible or 
-** otherwise a new GAP bag with TNUM T_INTPOS or T_INTNEG.
+**  The following functions convert Int, UInt or Int8 respectively into
+**  a GAP integer, either an immediate, small integer if possible or 
+**  otherwise a new GAP bag with TNUM T_INTPOS or T_INTNEG.
 */
 extern Obj ObjInt_Int(Int i);
 extern Obj ObjInt_UInt(UInt i);
@@ -167,8 +167,8 @@ extern Obj ObjInt_UInt8(UInt8 i);
 
 /**************************************************************************
 **
-** The following functions convert a GAP integer into an Int, UInt,
-** Int8 or UInt8 if it is in range. Otherwise it gives an error.
+**  The following functions convert a GAP integer into an Int, UInt,
+**  Int8 or UInt8 if it is in range. Otherwise it gives an error.
 */
 extern Int Int_ObjInt(Obj i);    
 extern UInt UInt_ObjInt(Obj i);    
@@ -178,10 +178,10 @@ extern UInt8 UInt8_ObjInt(Obj i);
 
 /****************************************************************************
 **
-** Reduce and normalize the given large integer object if necessary.
+**  Reduce and normalize the given large integer object if necessary.
 **
-** TODO: This is an internal implementation detail and ideally should not
-** be exported; unfortunately, FuncNUMBER_GF2VEC currently needs this.
+**  TODO: This is an internal implementation detail and ideally should not
+**  be exported; unfortunately, FuncNUMBER_GF2VEC currently needs this.
 */
 extern Obj GMP_REDUCE( Obj gmp );
 extern Obj GMP_NORMALIZE( Obj gmp );
@@ -353,8 +353,8 @@ extern Obj InverseModInt(Obj base, Obj mod);
 
 /****************************************************************************
 **
-** Compute log2 of the absolute value of an Int, i.e. the index of the highest
-** set bit. For input 0, return -1.
+**  Compute log2 of the absolute value of an Int, i.e. the index of the highest
+**  set bit. For input 0, return -1.
 */
 extern Int CLog2Int( Int intnum );
 

src/intrprtr.h

@@ -347,7 +347,7 @@ enum {
 *F  IntrRepeatEndBody(<nr>) . . . . . interpret repeat-statement, end of body
 *F  IntrRepeatEnd() . . . . . .  interpret repeat-statement, end of statement
 **
-**  'IntrRepeatBegin"  is an action to interpret  a  repeat-statement.  It is
+**  'IntrRepeatBegin'  is an action to interpret  a  repeat-statement.  It is
 **  called when the read encounters the 'repeat'.
 **
 **  'IntrRepeatBeginBody' is an action  to interpret a  repeat-statement.  It
@@ -918,7 +918,7 @@ extern void             IntrEmpty ( void );
 *F  IntrInfoBegin() . . . . . . . . .  start interpretation of Info statement
 *F  IntrInfoMiddle() . . . . . . .  shift to interpreting printable arguments
 *F  IntrInfoEnd( <narg> ) . . Info statement complete, <narg> things to print
-*V  InfoCheckLevel(<selectors>,<level>) . . . . . check if Info should output
+*F  InfoCheckLevel( <selectors>, <level> )  . . . check if Info should output
 */
 
 extern void             IntrInfoBegin ( void );

src/io.h

@@ -200,8 +200,8 @@ extern UInt CloseInputLog ( void );
  *V  EndLineHook . . . . . . . . . . . function called at end of command line
  **  
  **  These functions can be set on GAP-level. If they are not bound  the 
- **  default is: Instead of `PrintPromptHook' the `Prompt' is printed and
- **  instead of `EndLineHook' nothing is done.
+ **  default is: Instead of 'PrintPromptHook' the 'Prompt' is printed and
+ **  instead of 'EndLineHook' nothing is done.
  */
 /* TL: extern Obj  PrintPromptHook; */
 extern Obj  EndLineHook;

src/lists.h

@@ -262,9 +262,9 @@ static inline Obj ELM_DEFAULT_LIST(Obj list, Int pos, Obj def)
 *V  Elmv0ListFuncs[ <type> ]  . . . . . . . . .  table of selection functions
 **
 **  A package implementing  a lists type  <type> must provide a function  for
-**  'ELMV0_LIST' and install it  in 'Elmv0ListFuncs[<type>]'.   This function
-**  need not test   whether <pos> is less  than   or equal to  the  length of
-**  <list>.
+**  'ELMV0_LIST( <list>, <pos> )' and install it in 'Elmv0ListFuncs[<type>]'.
+**  This function need not test whether <pos> is less than or equal to the
+**  length of <list>.
 */
 extern  Obj (*Elm0vListFuncs[LAST_REAL_TNUM+1]) ( Obj list, Int pos );
 
@@ -290,9 +290,9 @@ static inline Obj ELMV0_LIST(Obj list, Int pos)
 *V  ElmListFuncs[ <type> ]  . . . . . . . . . .  table of selection functions
 **
 **  A package implementing a  list  type <type> must  provide a  function for
-**  'ELM_LIST' and install it  in 'ElmListFuncs[<type>]'.  This function must
-**  signal an error if <pos> is larger than the length of <list> or if <list>
-**  has no assigned object at <pos>.
+**  'ELM_LIST( <list>, <pos> )' and install it in 'ElmListFuncs[<type>]'.
+**  This function must signal an error if <pos> is larger than the length of
+**  <list> or if <list> has no assigned object at <pos>.
 */
 extern Obj (*ElmListFuncs[LAST_REAL_TNUM+1]) ( Obj list, Int pos );
 
@@ -308,8 +308,8 @@ extern Obj (*ElmListFuncs[LAST_REAL_TNUM+1]) ( Obj list, Int pos );
 **  is the responsibility  of the caller to  ensure that <pos>  is a positive
 **  integer.
 **
-**  The difference between ELM_LIST and ELMB_LIST is that ELMB_LIST accepts
-**  an object as the second argument
+**  The difference between 'ELM_LIST' and 'ELMB_LIST' is that 'ELMB_LIST'
+**  accepts an object as the second argument.
 **  It is intended as an interface for access to elements of large external
 **  lists, on the rare occasions when the kernel needs to do this.
 */
@@ -431,7 +431,7 @@ static inline Obj ELMS_LIST(Obj list, Obj poss)
 
 /****************************************************************************
 **
-*F  ElmsListDefault( <list>, <poss> ) . . .  default function for `ELMS_LIST'
+*F  ElmsListDefault( <list>, <poss> ) . . .  default function for 'ELMS_LIST'
 */
 extern Obj ElmsListDefault (
             Obj                 list,
@@ -440,7 +440,7 @@ extern Obj ElmsListDefault (
 
 /****************************************************************************
 **
-*F  ElmsListCheck( <list>, <poss> ) . . . . . . . . .  `ELMS_LIST' with check
+*F  ElmsListCheck( <list>, <poss> ) . . . . . . . . .  'ELMS_LIST' with check
 */
 extern Obj ElmsListCheck (
     Obj                 list,
@@ -449,7 +449,7 @@ extern Obj ElmsListCheck (
 
 /****************************************************************************
 **
-*F  ElmsListLevelCheck( <lists>, <poss>, <level> ) `ElmsListLevel' with check
+*F  ElmsListLevelCheck( <lists>, <poss>, <level> ) 'ElmsListLevel' with check
 */
 extern void ElmsListLevelCheck (
     Obj                 lists,
@@ -807,31 +807,31 @@ extern  Obj             TYPES_LIST_FAM (
 */
 
 enum {
-    /** filter number for `IsEmpty' */
+    /** filter number for 'IsEmpty' */
     FN_IS_EMPTY,
 
-    /** filter number for `IsSSortedList' */
+    /** filter number for 'IsSSortedList' */
     FN_IS_SSORT,
 
-    /** filter number for `IsNSortedList' */
+    /** filter number for 'IsNSortedList' */
     FN_IS_NSORT,
 
-    /** filter number for `IsDenseList' */
+    /** filter number for 'IsDenseList' */
     FN_IS_DENSE,
 
-    /** filter number for `IsNDenseList' */
+    /** filter number for 'IsNDenseList' */
     FN_IS_NDENSE,
 
-    /** filter number for `IsHomogeneousList' */
+    /** filter number for 'IsHomogeneousList' */
     FN_IS_HOMOG,
 
-    /** filter number for `IsNonHomogeneousList' */
+    /** filter number for 'IsNonHomogeneousList' */
     FN_IS_NHOMOG,
 
-    /** filter number for `IsTable' */
+    /** filter number for 'IsTable' */
     FN_IS_TABLE,
 
-    /** filter number for `IsRectangularTable' */
+    /** filter number for 'IsRectangularTable' */
     FN_IS_RECT,
 
     LAST_FN = FN_IS_RECT
@@ -845,9 +845,9 @@ enum {
 **  If a list  with type number <tnum>  gains  the filter  with filter number
 **  <fnum>, then the new type number is stored in:
 **
-**  `SetFiltListTNums[<tnum>][<fnum>]'
+**  'SetFiltListTNums[<tnum>][<fnum>]'
 **
-**  The macro  `SET_FILT_LIST' is  used  to  set  the filter  for a  list  by
+**  The macro  'SET_FILT_LIST' is  used  to  set  the filter  for a  list  by
 **  changing its type number.
 */
 extern UInt SetFiltListTNums [ LAST_REAL_TNUM ] [ LAST_FN + 1 ];
@@ -882,9 +882,9 @@ extern Obj FuncSET_FILTER_LIST ( Obj self, Obj list, Obj filter );
 **  If a list  with type number <tnum>  loses  the filter  with filter number
 **  <fnum>, then the new type number is stored in:
 **
-**  `ResetFiltListTNums[<tnum>][<fnum>]'
+**  'ResetFiltListTNums[<tnum>][<fnum>]'
 **
-**  The macro `RESET_FILT_LIST' is used  to  set  the filter  for a  list  by
+**  The macro 'RESET_FILT_LIST' is used  to  set  the filter  for a  list  by
 **  changing its type number.
 */
 extern UInt ResetFiltListTNums [ LAST_REAL_TNUM ] [ LAST_FN + 1 ];
@@ -928,9 +928,9 @@ extern Int HasFiltListTNums [ LAST_REAL_TNUM ] [ LAST_FN + 1 ];
 **  The type  number without any  known properties  of a  list of type number
 **  <tnum> is stored in:
 **
-**  `ClearPropsTNums[<tnum>]'
+**  'ClearPropsTNums[<tnum>]'
 **
-**  The macro `CLEAR_PROPS_LIST' is used to clear all properties of a list.
+**  The macro 'CLEAR_PROPS_LIST' is used to clear all properties of a list.
 */
 extern UInt ClearFiltsTNums [ LAST_REAL_TNUM ];