style: comment changes

[Akim Demaille]

commit 296660304c9c3bfa8d260c8ed155195cafac7033
Author: Akim Demaille <address@hidden>
Date:   Sat Feb 22 20:25:12 2020 +0100

    style: comment changes
    
    * src/symtab.h, src/lr0.c: here.

diff --git a/src/gram.h b/src/gram.h
index 582bb069..afae95a7 100644
--- a/src/gram.h
+++ b/src/gram.h
@@ -42,9 +42,9 @@
 
    Internally, we cannot use the number 0 for a rule because for
    instance RITEM stores both symbol (the RHS) and rule numbers: the
-   symbols are shorts >= 0, and rule number are stored negative.
+   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).
+   0, and the token $end.
 
    Actions are accessed via the rule number.
 
@@ -55,8 +55,7 @@
 
    RULES[R].lhs -- the symbol of the left hand side of rule R.
 
-   RULES[R].rhs -- the index in RITEM of the beginning of the portion
-   for rule R.
+   RULES[R].rhs -- the beginning of the portion of RITEM for rule R.
 
    RULES[R].prec -- the symbol providing the precedence level of R.
 
@@ -75,16 +74,16 @@
 
    RULES[R].line -- the line where R was defined.
 
-   RULES[R].useful -- whether the rule is used (i.e., false if thrown
-   away by reduce).
+   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 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
-   contains minus R, which identifies it as the end of a portion and
-   says which rule it is for.
+   contains -R, which identifies it as the end of a portion and says
+   which rule it is for.
 
    The portions of RITEM come in order of increasing rule number.
    NRITEMS is the total length of RITEM.  Each element of RITEM is
diff --git a/src/lr0.c b/src/lr0.c
index 079fbdf9..2ebdcf8a 100644
--- a/src/lr0.c
+++ b/src/lr0.c
@@ -58,10 +58,11 @@ core_print (size_t core_size, item_number *core, FILE *out)
     }
 }
 
-/*------------------------------------------------------------------.
-| A state was just discovered from another state.  Queue it for     |
-| later examination, in order to find its transitions.  Return it.  |
-`------------------------------------------------------------------*/
+/*-----------------------------------------------------------------.
+| A state was just discovered by transitioning on SYM from another |
+| state.  Queue this state for later examination, in order to find |
+| its outgoing transitions.  Return it.                            |
+`-----------------------------------------------------------------*/
 
 static state *
 state_list_append (symbol_number sym, size_t core_size, item_number *core)
@@ -98,7 +99,7 @@ static state **shiftset;
 
 
 /* KERNEL_BASE[symbol-number] -> list of item numbers (offsets inside
-   RITEM) of lenngth KERNEL_SIZE[symbol-number]. */
+   RITEM) of length KERNEL_SIZE[symbol-number]. */
 static item_number **kernel_base;
 static int *kernel_size;
 
diff --git a/src/reader.c b/src/reader.c
index 63029436..e0a3a699 100644
--- a/src/reader.c
+++ b/src/reader.c
@@ -607,7 +607,7 @@ packgram (void)
 {
   int itemno = 0;
   ritem = xnmalloc (nritems + 1, sizeof *ritem);
-  /* This sentinel is used by build_relations in gram.c.  */
+  /* This sentinel is used by build_relations() in lalr.c.  */
   *ritem++ = 0;
 
   rule_number ruleno = 0;
diff --git a/src/symtab.h b/src/symtab.h
index 66017525..c7e916b5 100644
--- a/src/symtab.h
+++ b/src/symtab.h
@@ -230,7 +230,8 @@ void symbol_precedence_set (symbol *sym, int prec, assoc a, 
location loc);
 /** Set the \c class associated with \c sym.
 
     Whether \c declaring means whether this class definition comes
-    from %nterm or %token (but not %type, prec/assoc, etc.).  */
+    from %nterm or %token (but not %type, prec/assoc, etc.).  A symbol
+    can have "declaring" set only at most once.  */
 void symbol_class_set (symbol *sym, symbol_class class, location loc,
                        bool declaring);