docs: add comments for some parser routines

Author: tueda

sources/compiler.c

@@ -424,19 +424,32 @@ int ParenthesesTest(UBYTE *sin)
 /*
  		#] ParenthesesTest : 
  		#[ SkipAName :
-
-		Skips a name and gives a pointer to the object after the name.
-		If there is not a proper name, it returns a zero pointer.
-		In principle the brackets match already, so the `if ( *s == 0 )'
-		code is not really needed, but you never know how the program
-		is extended later.
 */
 
+/**
+ * Skips a name and gives a pointer to the character after the name.
+ * If there is not a proper name, it emits a compiler message and then returns
+ * a null pointer.
+ * This function supports formal names (e.g., `[x+a]`) and $-variables
+ * in addition to ordinary identifiers.
+ *
+ * @note The brackets are assumed to be matched already.
+ *
+ * @param[in]  s  Pointer to a null-terminated input string that starts
+ *                with a name.
+ * @return        Pointer to the character after the name, or a null pointer
+ *                if the name is invalid.
+ */
 UBYTE *SkipAName(UBYTE *s)
 {
 	UBYTE *t = s;
 	if ( *s == '[' ) {
 		SKIPBRA1(s)
+/*
+		In principle the brackets match already, so the `if ( *s == 0 )'
+		code is not really needed, but you never know how the program
+		is extended later.
+*/
 		if ( *s == 0 ) {
 			MesPrint("&Illegal name: '%s'",t);
 			return(0);

sources/ftypes.h

@@ -187,10 +187,13 @@ typedef int (*TFUN)();
 typedef int (*TFUN1)();
 #endif
 
+/*
+	Flags used in the compiler's KEYWORD tables.
+*/
 
 #define NOAUTO 0
-#define PARTEST 1
-#define WITHAUTO 2
+#define PARTEST 1	/* parentheses test */
+#define WITHAUTO 2	/* auto-declaration */
 
 #define ALLVARIABLES -1
 #define SYMBOLONLY 1

sources/tools.c

@@ -1918,6 +1918,17 @@ UBYTE *strDup1(UBYTE *instring, char *ifwrong)
  		#[ EndOfToken :
 */
 
+/**
+ * Skips over alphanumeric characters to find the end of the token.
+ *
+ * @note This function does not handle formal names (e.g., `[x+a]`).
+ * To handle them, use `SkipAName` instead.
+ *
+ * @param[in]  s  Pointer to a null-terminated input buffer.
+ * @return        Pointer to the first non-alphanumeric character (i.e., the
+ *                character immediately after the token), or the null
+ *                terminator if the token reaches the end of the string.
+ */
 UBYTE *EndOfToken(UBYTE *s)
 {
 	UBYTE c;
@@ -1930,6 +1941,17 @@ UBYTE *EndOfToken(UBYTE *s)
  		#[ ToToken :
 */
 
+/**
+ * Skips over non-alphanumeric characters to find the start of a token.
+ *
+ * @note This function does not handle formal names (e.g., `[x+a]`).
+ * To handle them, consider simply skipping whitespace, e.g., by using
+ * `SkipSpaces`.
+ *
+ * @param[in]  s  Pointer to a null-terminated input buffer.
+ * @return        Pointer to the first alphanumeric character (i.e., the start
+ *                of the token), or the null terminator if none is found.
+ */
 UBYTE *ToToken(UBYTE *s)
 {
 	UBYTE c;
@@ -1940,11 +1962,17 @@ UBYTE *ToToken(UBYTE *s)
 /*
  		#] ToToken : 
  		#[ SkipField :
-
-	Skips from s to the end of a declaration field.
-	par is the number of parentheses that still has to be closed.
 */
- 
+
+/**
+ * Skips from `s` to the end of a declaration field
+ * (e.g., `x`, `1+2*[x+a]`, or `f({x,[x+a]},1)`).
+ *
+ * @param[in]  s      Pointer to a null-terminated input buffer.
+ * @param[in]  level  Number of parentheses that still have to be closed.
+ * @return            Pointer to the character after the field, which is either
+ *                    a comma at level 0 or the null terminator.
+ */
 UBYTE *SkipField(UBYTE *s, int level)
 {
 	while ( *s ) {