style: comment changes

* src/closure.h, src/closure.c, src/lalr.c: here.

TODO

@@ -53,6 +53,27 @@ syntax error, unexpected $end, expecting ↦ or 🎅🐃 or '\n'
 While at it, we should stop using "$end" by default, in favor of "end of
 file", or "end of input", whatever.
 
+** clean up
+*** lalr.c
+Introduce a goto struct, and use it in place of from_state/to_state.
+Rename states1 as path, length as pathlen.
+Introduce inline functions for things such as nullable[*rp - ntokens]
+where we need to map from symbol number to nterm number.
+
+There are probably a significant part of the the relations management that
+should be migrated on top of a bitsetv.
+
+*** closure
+It should probably take a "state*" instead of two arguments.
+
+*** traces
+The "automaton" and "set" categories are not so useful.  We should probably
+introduce lr(0) and lalr, just the way we have ielr categories.  The
+"closure" function is too verbose, it should probably have its own category.
+
+"set" can still be used for summariring the important sets.  That would make
+tests easy to maintain.
+
 ** use gettext-h in gnulib instead of gettext
 ** use gnulib-po
 For some reason, according to syntax-check, we have to keep getopt.c in
@@ -63,6 +84,28 @@ fixed.
 Meanwhile, bitset/stats.c is removed from the set of translations, which is
 not too much of a problem as users are not expected to see this.
 
+** bad diagnostics
+
+%token <val> NUM
+%type  <val> expr term fact
+
+%%
+
+res:  expr { printf ("%d\n", $1); };
+expr: expr '+' term { $$ = $1 + $3; } | term;
+term: NUM | { $$ = 0; };
+
+The second warning about fact is... useless.
+
+$ bison /tmp/bar.y
+/tmp/bar.y:2.24-27: warning: symbol fact is used, but is not defined as a token and has no rules [-Wother]
+ %type  <val> expr term fact
+                        ^~~~
+/tmp/bar.y: warning: 1 nonterminal useless in grammar [-Wother]
+/tmp/bar.y:2.24-27: warning: nonterminal useless in grammar: fact [-Wother]
+ %type  <val> expr term fact
+                        ^~~~
+
 
 * Completion
 Several features are not available in all the backends.

src/closure.c

@@ -35,6 +35,9 @@
 item_number *itemset;
 size_t nitemset;
 
+/* RULESET contains a bit for each rule.  CLOSURE sets the bits for
+   all rules which could potentially describe the next input to be
+   read.  */
 static bitset ruleset;
 
 /* internal data.  See comments before set_fderives and set_firsts.  */

src/closure.h

@@ -33,24 +33,21 @@ void closure_new (unsigned n);
 /* Given the kernel (aka core) of a state (a sorted vector of item numbers
    ITEMS, of length N), set up RULESET and ITEMSET to indicate what
    rules could be run and which items could be accepted when those
-   items are the active ones.
+   items are the active ones.  */
-
-   RULESET contains a bit for each rule.  CLOSURE sets the bits for
-   all rules which could potentially describe the next input to be
-   read.
-
-   ITEMSET is a sorted vector of item numbers; NITEMSET is its size
-   (actually, points to just beyond the end of the part of it that is
-   significant).  CLOSURE places there the indices of all items which
-   represent units of input that could arrive next.  */
 
 void closure (item_number const *items, size_t n);
 
 
-/* Frees ITEMSET, RULESET and internal data.  */
+/* Free ITEMSET, RULESET and internal data.  */
 
 void closure_free (void);
 
+
+/* ITEMSET is a sorted vector of item numbers; NITEMSET is its size
+   (actually, points to just beyond the end of the part of it that is
+   significant).  CLOSURE places there the indices of all items which
+   represent units of input that could arrive next.  */
+
 extern item_number *itemset;
 extern size_t nitemset;
 

src/lalr.c

@@ -72,6 +72,12 @@ static bitsetv LA = NULL;
 size_t nLA;
 
 
+/* "(p, A) includes (p', B)" iff
+   B → βAγ, γ nullable, and p'-- β --> p (i.e., state p' reaches p on label β).
+
+   Definition p.621 [DeRemer 1982].
+
+   INCLUDES[(p, A)] = [(p', B),...] */
 static goto_number **includes;
 
 /* "(q, A → ω) lookback (p, A)" iff state p reaches state q on label ω.