style: comment changes

[Akim Demaille]

commit 3075d96d44d329f70cadb5b886bc827ad07ddf03
Author: Akim Demaille <address@hidden>
Date:   Fri Jan 25 19:27:48 2019 +0100

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

diff --git a/src/lr0.c b/src/lr0.c
index a54f1e15..9d8d3d55 100644
--- a/src/lr0.c
+++ b/src/lr0.c
@@ -80,7 +80,10 @@ state_list_append (symbol_number sym, size_t core_size, 
item_number *core)
 bitset shift_symbol;
 
 static rule **redset;
-/* For the current state, the states that can be reached via a "shift".  */
+/* For the current state, the list of pointers to states that can be
+   reached via a shift/goto.  Could be indexed by the reaching symbol,
+   but labels of incoming transitions can be recovered by the state
+   itself.  */
 static state **shiftset;
 
 static item_number **kernel_base;
diff --git a/src/state.c b/src/state.c
index 18d3da8b..df30edb8 100644
--- a/src/state.c
+++ b/src/state.c
@@ -41,12 +41,12 @@
 `-----------------------------------------*/
 
 static transitions *
-transitions_new (int num, state **the_states)
+transitions_new (int num, state **dst)
 {
-  size_t states_size = num * sizeof *the_states;
+  size_t states_size = num * sizeof *dst;
   transitions *res = xmalloc (offsetof (transitions, states) + states_size);
   res->num = num;
-  memcpy (res->states, the_states, states_size);
+  memcpy (res->states, dst, states_size);
   return res;
 }
 
@@ -198,10 +198,10 @@ state_free (state *s)
 `---------------------------*/
 
 void
-state_transitions_set (state *s, int num, state **trans)
+state_transitions_set (state *s, int num, state **dst)
 {
   aver (!s->transitions);
-  s->transitions = transitions_new (num, trans);
+  s->transitions = transitions_new (num, dst);
 }
 
 
diff --git a/src/state.h b/src/state.h
index 5b37ed6a..b4a3e351 100644
--- a/src/state.h
+++ b/src/state.h
@@ -51,11 +51,11 @@
    lookahead token alone).  When the states are generated, these
    actions are represented in two other lists.
 
-   Each transition structure describes the possible transitions out
-   of one state, the state whose number is in the number field.  Each
-   contains a vector of numbers of the states that transitions can go
-   to.  The accessing_symbol fields of those states' cores say what
-   kind of input leads to them.
+   Each transition structure describes the possible transitions out of
+   one state (there are NUM of them).  Each contains a vector of
+   numbers of the states that transitions can go to.  The
+   accessing_symbol fields of those states' cores say what kind of
+   input leads to them.
 
    A transition to state zero should be ignored: conflict resolution
    deletes transitions by having them point to zero.
@@ -233,8 +233,8 @@ state *state_new (symbol_number accessing_symbol,
                   size_t core_size, item_number *core);
 state *state_new_isocore (state const *s);
 
-/* Set the transitions of STATE.  */
-void state_transitions_set (state *s, int num, state **trans);
+/* Record that from S we can reach all the DST states (NUM of them).  */
+void state_transitions_set (state *s, int num, state **dst);
 
 /* Set the reductions of STATE.  */
 void state_reductions_set (state *s, int num, rule **reds);