Improve some comments

Author: bengsig

src/rwl.h

@@ -11,6 +11,7 @@
  *
  * History
  *
+ * bengsig  27-may-2024 - Improve some comments
  * bengsig  17-apr-2024 - nostatistics statement
  * bengsig  16-apr-2024 - bit operation on clflags, -=
  * bengsig   4-apr-2024 - $oraerror:showoci directive
@@ -356,11 +357,11 @@ extern int nanosleep(struct timespec *, int);
 
 struct rwl_option
 {
-  const char *longn;
+  const char *longn; // long name e.g. --version
   ub4  optbits;
 #define RWL_OPT_NOLARG 0
 #define RWL_OPT_HASARG 0x00000001 // option must have agument
-  ub4  shortn;
+  ub4  shortn;       // short name e.g. 'v'
 };
 
 
@@ -489,6 +490,7 @@ struct rwl_cinfo
   text serverr[RWL_DB_SERVERR_LEN]; // 
 };
 
+// How was a string allocated in rwl_value
 enum rwl_vsalloc
 { 
   RWL_SVALLOC_NOT = 0 /* no buffer allocated this MUST have value 0 */
@@ -829,6 +831,7 @@ struct rwl_arglist
 };
 #define RWL_USER_ARG_OFFSET 500    // offset from ordinary option val in struct option
 
+// RWLOADSIM_PATH
 struct rwl_pathlist
 {
   text *pathname; // name of entry in RWLOADISM_PATH
@@ -1296,12 +1299,14 @@ struct rwl_main
   text sqlbuffer[RWL_MAXSQL+2];  /* text of last SQL */ 
 } ;
 
+// Linked list of contatenation, currently used by rwldoprintf
 struct rwl_conlist
 {
   rwl_estack *estk;  	// expression
   rwl_conlist *connxt;	// linked list pointer
 };
 
+// Link list of identifiers, e.g. used for rwlreadline
 struct rwl_idlist
 {
   sb4 idnum;   		// variable number
@@ -1415,6 +1420,7 @@ struct rwl_localvar
   rwl_type atype; /* the type of the argument */
 };
 
+// All operators in the RPN evaluations stack
 enum rwl_stack_t
 {
   RWL_STACK_notinuse = 0
@@ -1662,6 +1668,7 @@ enum rwl_code_t
 , RWL_CODE_SQLEND // return from something with database calls - ceptr1 is variable name (of procedure), ceint2 location guess
 };
 
+// Entries in the p-code array
 struct rwl_code
 {
   rwl_code_t ctyp; /* operator - code type */
@@ -1701,7 +1708,9 @@ struct rwl_rastvar /* random string as a variable */
 /* Internal variable names
  * Note that "runseconds" to the user is like
  * a read-only variable, while it really is a
- * function without arguments 
+ * function without arguments.  It should be given
+ * by the user as runseconds() as if it were a 
+ * function
  */
 #define RWL_LOOPNUMBER_VAR (text *)"loopnumber"
 #define RWL_THREADNUMBER_VAR (text *)"threadnumber"
@@ -1753,7 +1762,6 @@ struct rwl_histogram
 /* execution time statistics structure */
 struct rwl_stats
 {
-  //rwl_mutex *mutex_stats; // moved to rwl_identifier due to RWL-600 [rwlmutexget-notinit]
   double wtime, etime, atime, dtime; // wait exec, application time
   ub4 *persec; /* array of per second counters */
   double *wtimsum; // array of per second wait time
@@ -1814,6 +1822,7 @@ extern void rwlexprdestroy(rwl_main *, rwl_estack *);
 // rwlexprbic: vvv -= (vvv/bbb)%2 ? bbb : 0
 // note that bbb must be rwl_onep, rwl_twop, rwl_fourp, etc
 // 
+// They can be much simplified once we get bitwise operators
 #define rwlexprbis(rwm, vvv, bbb) \
  /* vvv */ rwlexprpush(rwm, vvv, RWL_STACK_VAR);  		\
  /* bbb */ rwlexprpush(rwm, bbb, RWL_STACK_NUM);    		\

src/rwlparser.y

@@ -160,6 +160,7 @@
 */
 #define rwlyrwmscanner rwm->rwlyscanner
 
+// pretty print parser syntax errors
 struct rwl_yt2txt
 {
   const char *ytoken;
@@ -168,6 +169,7 @@ struct rwl_yt2txt
 
 typedef struct rwl_yt2txt rwl_yt2txt;
 
+// Note that this must be sorted by ytoken (first column)
 static const rwl_yt2txt rwlyt2[] = 
 {
     {"RWL_T_ABORT", "'abort'"}
@@ -330,6 +332,7 @@ static const rwl_yt2txt rwlyt2[] =
 };
 #define RWL_TOK_COUNT (sizeof(rwlyt2)/sizeof(rwl_yt2txt))
 
+// compare - used by bsearch
 static int rwlcmptok(const void *l1, const void *l2)
 {
   rwl_yt2txt *y1, *y2;
@@ -545,11 +548,6 @@ programelementlist:
 	  }
 	;
 
-/* 
- -----------------------------------------------
- * complex declarations that can only be in main 
- -----------------------------------------------
-*/
 
 programelement:
 	statement
@@ -561,7 +559,6 @@ programelement:
 	  { rwlprintallvars(rwm); } 
 	| RWL_T_PRINTVAR printvarlist 
 	  terminator
-
 	; 
 	/* end of programelement */
 
@@ -856,44 +853,6 @@ dbspec:
 	        if (rwm->dbsav)
 		  bis(rwm->dbsav->flags, RWL_DB_DEFAULT);
 	        rwm->defdb = rwm->dbname;
-#ifdef NEVER
-		// The default database should pick up any -X, -Y, -G, -g arguments
-		if (rwm->argX)
-		{
-		  rwm->dbsav->poolmax = rwm->argX;
-		  if (rwm->argY)
-		    rwm->dbsav->poolmin = rwm->argY;
-		  else
-		    rwm->dbsav->poolmin = 1;
-		  rwm->dbsav->pooltype = RWL_DBPOOL_SESSION;
-		  rwm->dbsav->pooltext = "sessionpool";
-		  if (bit(rwm->m3flags, RWL_P3_DEFRECONN|RWL_P3_DEFTHRDED))
-		    rwlerror(rwm, RWL_ERROR_DBPOOL_ALREADY);
-		    
-		}     
-		else
-		{ 
-		  if (rwm->argY)
-		    rwlerror(rwm, RWL_ERROR_ONLY_POOL_MIN_SET);
-		  if (bit(rwm->m3flags, RWL_P3_DEFRECONN))
-		  {
-		    rwm->dbsav->pooltype = RWL_DBPOOL_RECONNECT;
-		    rwm->dbsav->pooltext = "reconnect";
-		    if (bit(rwm->m3flags, RWL_P3_DEFTHRDED))
-		      rwlerror(rwm, RWL_ERROR_DBPOOL_ALREADY);
-		  }
-		  else if (bit(rwm->m3flags, RWL_P3_DEFTHRDED))
-		  {
-		    rwm->dbsav->pooltype = RWL_DBPOOL_RETHRDED;
-		    rwm->dbsav->pooltext = "threads dedicated";
-		  }
-		  else
-		  {
-		    rwm->dbsav->pooltype = RWL_DBPOOL_DEDICATED;
-		    rwm->dbsav->pooltext = "dedicated";
-		  }
-		}
-#endif
 	      }
 	    }
 	| RWL_T_CONNECTIONPOOL compiletime_expression 
@@ -1517,7 +1476,7 @@ Note that "concatenation" which is two expressions right after
 each other (i.e. just omission of the || operator) causes a 
 well understood bison conflict.  This is because e.g. 
 a - b
-could be both a followed by -b (i.e. to concatenated expressions)
+could be both a followed by -b (i.e. two concatenated expressions)
 or it could be a-b (i.e. the subtraction).  This shift/reduce conflict
 in bison will solved by doing the shift so it is the subtraction.