reader: clarify variable names

[Akim Demaille]

commit ae91c3cce389cafc5d607ec777181ce7e44397ff
Author: Akim Demaille <address@hidden>
Date:   Sat Mar 23 08:07:13 2019 +0100

    reader: clarify variable names
    
    * src/reader.c (grammar_rule_check_and_complete): When 'p' and 'lhs'
    are aliases, prefer the latter, for clarity and consistency.
    (grammar_current_rule_begin): Avoid 'p', current_rule suffices.
    * src/gram.h, src/gram.c: Comment changes.
    
    ptdr#   calc.tab.c

diff --git a/src/gram.h b/src/gram.h
index 24cee8ff..d479121d 100644
--- a/src/gram.h
+++ b/src/gram.h
@@ -146,7 +146,6 @@ item_number_is_symbol_number (item_number i)
 /* Rule numbers.  */
 typedef int rule_number;
 # define RULE_NUMBER_MAX INT_MAX
-extern rule_number nrules;
 
 static inline item_number
 rule_number_as_item_number (rule_number r)
@@ -193,6 +192,7 @@ typedef struct
   /* This symbol was attached to the rule via %prec. */
   sym_content *precsym;
 
+  /* Location of the rhs.  */
   location location;
   bool useful;
   bool is_predicate;
@@ -206,7 +206,9 @@ typedef struct
   location action_location;
 } rule;
 
+/* The used rules (size NRULES).  */
 extern rule *rules;
+extern rule_number nrules;
 
 /* Get the rule associated to this item.  ITEM points inside RITEM.  */
 rule const *item_rule (item_number const *item);
diff --git a/src/parse-gram.y b/src/parse-gram.y
index 0c1558d7..c120d07b 100644
--- a/src/parse-gram.y
+++ b/src/parse-gram.y
@@ -666,7 +666,7 @@ rhs:
 ;
 
 named_ref.opt:
-  %empty         { $$ = 0; }
+  %empty         { $$ = NULL; }
 | BRACKETED_ID   { $$ = named_ref_new ($1, @1); }
 ;
 
diff --git a/src/reader.c b/src/reader.c
index dbc834a4..e776ed1f 100644
--- a/src/reader.c
+++ b/src/reader.c
@@ -226,11 +226,9 @@ grammar_current_rule_begin (symbol *lhs, location loc,
   ++nrules;
   previous_rule_end = grammar_end;
 
-  symbol_list *p = grammar_symbol_append (lhs, loc);
+  current_rule = grammar_symbol_append (lhs, loc);
   if (lhs_name)
-    assign_named_ref (p, named_ref_copy (lhs_name));
-
-  current_rule = grammar_end;
+    assign_named_ref (current_rule, named_ref_copy (lhs_name));
 
   /* Mark the rule's lhs as a nonterminal if not already so.  */
   if (lhs->content->class == unknown_sym)
@@ -293,7 +291,7 @@ grammar_rule_check_and_complete (symbol_list *r)
       if (first_rhs)
         {
           char const *lhs_type = r->content.sym->content->type_name;
-          const char *rhs_type =
+          char const *rhs_type =
             first_rhs->content->type_name ? first_rhs->content->type_name : "";
           if (!UNIQSTR_EQ (lhs_type, rhs_type))
             complain (&r->location, Wother,
@@ -629,8 +627,8 @@ packgram (void)
       /* Don't check the generated rule 0.  It has no action, so some rhs
          symbols may appear unused, but the parsing algorithm ensures that
          %destructor's are invoked appropriately.  */
-      if (p != grammar)
-        grammar_rule_check_and_complete (p);
+      if (lhs != grammar)
+        grammar_rule_check_and_complete (lhs);
 
       rules[ruleno].user_number = ruleno;
       rules[ruleno].number = ruleno;
@@ -645,13 +643,13 @@ packgram (void)
       rules[ruleno].action = lhs->action_props.code;
       rules[ruleno].action_location = lhs->action_props.location;
       rules[ruleno].is_predicate = lhs->action_props.is_predicate;
-      rules[ruleno].expected_sr_conflicts = p->expected_sr_conflicts;
-      rules[ruleno].expected_rr_conflicts = p->expected_rr_conflicts;
+      rules[ruleno].expected_sr_conflicts = lhs->expected_sr_conflicts;
+      rules[ruleno].expected_rr_conflicts = lhs->expected_rr_conflicts;
 
       /* Traverse the rhs.  */
       {
         size_t rule_length = 0;
-        for (p = p->next; p->content.sym; p = p->next)
+        for (p = lhs->next; p->content.sym; p = p->next)
           {
             ++rule_length;
 
diff --git a/src/symlist.h b/src/symlist.h
index d8ae90c9..ee40a851 100644
--- a/src/symlist.h
+++ b/src/symlist.h
@@ -26,7 +26,9 @@
 # include "symtab.h"
 # include "named-ref.h"
 
-/* A list of symbols, used during the parsing to store the rules.  */
+/* A list of symbols, used during the parsing for many different
+   purposes: rules, symbol declarations or properties (such as
+   %destructor, etc.)...  */
 typedef struct symbol_list
 {
   /**
@@ -67,9 +69,10 @@ typedef struct symbol_list
   struct symbol_list *midrule_parent_rule;
   int midrule_parent_rhs_index;
 
-  /* ---------------------------------------------- */
-  /* Apply to the rule (attached to the LHS only).  */
-  /* ---------------------------------------------- */
+  /*--------------------------------------------------------------.
+  | Used for rules only (attached to the "LHS", one per rule even |
+  | when several RHSs are bound to a single lhs via "|").         |
+  `--------------------------------------------------------------*/
 
   /* Precedence/associativity.  */
   symbol *ruleprec;