[PATCH 3/5] style: comment changes

[Akim Demaille]

* src/closure.h, src/closure.c, src/lalr.c: here.
---
 TODO          | 36 ++++++++++++++++++++++++++++++++++++
 src/closure.c |  3 +++
 src/closure.h | 19 ++++++++-----------
 src/lalr.c    |  6 ++++++
 4 files changed, 53 insertions(+), 11 deletions(-)

diff --git a/TODO b/TODO
index 6e7e387e..edf8f3ed 100644
--- a/TODO
+++ b/TODO
@@ -53,6 +53,20 @@ 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.
+
+
 ** 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 +77,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.
diff --git a/src/closure.c b/src/closure.c
index e63b1fb9..385f35c4 100644
--- a/src/closure.c
+++ b/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.  */
diff --git a/src/closure.h b/src/closure.h
index 5d5b15c7..1352a4ea 100644
--- a/src/closure.h
+++ b/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.
-
-   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.  */
+   items are the active ones.  */
 
 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;
 
diff --git a/src/lalr.c b/src/lalr.c
index 09e5ae3a..69fbd8c7 100644
--- a/src/lalr.c
+++ b/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 ω.
-- 
2.21.0