style: comment and formatting changes, and fixes

[Akim Demaille]

commit 4b0cd01fb7a1586e6886207376c587516c3152b5
Author: Akim Demaille <akim.demaille@gmail.com>
Date:   Sun Oct 4 14:28:39 2020 +0200

    style: comment and formatting changes, and fixes
    
    * examples/c/lexcalc/parse.y: Fix option handling.
    * src/gram.h: Clarify comments.
    * src/ielr.c: Fix indentation.
    * src/print.c, src/state.h: More comments.

diff --git a/examples/c/lexcalc/parse.y b/examples/c/lexcalc/parse.y
index 1da92a3e..377dbf70 100644
--- a/examples/c/lexcalc/parse.y
+++ b/examples/c/lexcalc/parse.y
@@ -132,11 +132,11 @@ int main (int argc, const char *argv[])
   int nerrs = 0;
 
   // Enable parse traces on option -p.
-  for (int i = 0; i < argc; ++i)
-    if (1 < argc && strcmp (argv[1], "-p") == 0)
-      yydebug = 1;
-    else if (strcmp (argv[i], "-e") == 0)
+  for (int i = 1; i < argc; ++i)
+    if (strcmp (argv[i], "-e") == 0)
       parse_expression_p = 1;
+    else if (strcmp (argv[i], "-p") == 0)
+      yydebug = 1;
 
   if (parse_expression_p)
     {
diff --git a/src/gram.h b/src/gram.h
index c6ce4194..95fec9be 100644
--- a/src/gram.h
+++ b/src/gram.h
@@ -24,12 +24,12 @@
 /* Representation of the grammar rules:
 
    NTOKENS is the number of tokens, and NNTERMS is the number of
-   variables (nonterminals).  NSYMS is the total number, ntokens +
-   nnterms.
+   nonterminals (aka variables).  NSYMS is the total number, NTOKENS +
+   NNTERMS.
 
-   Each symbol (either token or variable) receives a symbol number.
+   Each symbol (either token or nterm) receives a symbol number.
    Numbers 0 to NTOKENS - 1 are for tokens, and NTOKENS to NSYMS - 1
-   are for variables.  Symbol number zero is the end-of-input token.
+   are for nterms.  Symbol number zero is the end-of-input token.
    This token is counted in ntokens.  The true number of token values
    assigned is NTOKENS reduced by one for each alias declaration.
 
@@ -41,7 +41,7 @@
    are 0, 1, 2...
 
    Internally, we cannot use the number 0 for a rule because for
-   instance RITEM stores both symbol (the RHS) and rule numbers: the
+   instance RITEM stores both symbols (the RHS) and rule numbers: the
    symbols are integers >= 0, and rule numbers are stored negative.
    Therefore 0 cannot be used, since it would be both the rule number
    0, and the token $end.
@@ -77,8 +77,8 @@
    RULES[R].useful -- whether the rule is used.  False if thrown away
    by reduce().
 
-   The right hand side is stored as symbol numbers in a portion of
-   RITEM.
+   The right hand side of rules is stored as symbol numbers in a
+   portion of RITEM.
 
    The length of the portion is one greater than the number of symbols
    in the rule's right hand side.  The last element in the portion
@@ -87,7 +87,8 @@
 
    The portions of RITEM come in order of increasing rule number.
    NRITEMS is the total length of RITEM.  Each element of RITEM is
-   called an "item" and its index in RITEM is an item number.
+   called an "item" of type item_number and its index in RITEM is an
+   item_index.
 
    Item numbers are used in the finite state machine to represent
    places that parsing can get to.
diff --git a/src/ielr.c b/src/ielr.c
index 93fe3ac2..26754a72 100644
--- a/src/ielr.c
+++ b/src/ielr.c
@@ -701,8 +701,8 @@ ielr_compute_state (bitsetv follow_kernel_items, bitsetv 
always_follows,
         AnnotationIndex ai;
         AnnotationList *a;
         for (ai = 0, a = annotation_lists[lr0_isocore->state->number];
-           a;
-           ++ai, a = a->next)
+             a;
+             ++ai, a = a->next)
         work1[ai] =
           AnnotationList__computeDominantContribution (
             a, lr0_isocore->state->nitems, lookaheads, false);
@@ -982,7 +982,7 @@ ielr_split_states (bitsetv follow_kernel_items, bitsetv 
always_follows,
          this_state;
          this_state = this_state->next)
       {
-        state *s = this_state->state;
+        const state *s = this_state->state;
         for (int i = 0; i < s->transitions->num; ++i)
           {
             state *t = s->transitions->states[i];
diff --git a/src/print.c b/src/print.c
index 467e2f2f..4555ba98 100644
--- a/src/print.c
+++ b/src/print.c
@@ -43,6 +43,8 @@
 #include "symtab.h"
 #include "tables.h"
 
+/* For a given state, the symbol numbers of the lookahead tokens for
+   shifts and errors (i.e. not reduce).  */
 static bitset no_reduce_set;
 
 
diff --git a/src/state.h b/src/state.h
index 6a2fd1c3..7024b3b5 100644
--- a/src/state.h
+++ b/src/state.h
@@ -234,6 +234,8 @@ extern state *final_state;
 /* Create a new state with ACCESSING_SYMBOL for those items.  */
 state *state_new (symbol_number accessing_symbol,
                   size_t core_size, item_index *core);
+/* Create a new state with the same kernel as S (same accessing
+   symbol, transitions, reductions, consistency and items).  */
 state *state_new_isocore (state const *s);
 
 /* Record that from S we can reach all the DST states (NUM of them).  */