Improve some comments in parser table construction.

* src/LR0.c (new_itemsets): Explain sorting of itemset and kernel_base.
(generate_states): Don't mention ruleset, which is internal to closure.
* src/closure.c (closure): Explain sorting of core and itemset, which
is required for this function to behave correctly.
* src/closure.h (closure): Mention sorting.

ChangeLog

@@ -6,6 +6,13 @@
 	Again, it's not used yet, but it will be.
 	* src/muscle_tab.h: Likewise.
 
+	Improve some comments in parser table construction.
+	* src/LR0.c (new_itemsets): Explain sorting of itemset and kernel_base.
+	(generate_states): Don't mention ruleset, which is internal to closure.
+	* src/closure.c (closure): Explain sorting of core and itemset, which
+	is required for this function to behave correctly.
+	* src/closure.h (closure): Mention sorting.
+
 2007-05-28  Joel E. Denny  <jdenny@ces.clemson.edu>
 
 	* src/lalr.c (state_lookahead_tokens_count): For code readability,

src/LR0.c

@@ -169,6 +169,10 @@ free_storage (void)
 | shifted.  For each symbol in the grammar, kernel_base[symbol]  |
 | points to a vector of item numbers activated if that symbol is |
 | shifted, and kernel_size[symbol] is their numbers.             |
+|                                                                |
+| itemset is sorted on item number from ritem, which is sorted   |
+| on rule number.  Compute each kernel_base[symbol] with the     |
+| same sort.                                                     |
 `---------------------------------------------------------------*/
 
 static void
@@ -351,10 +355,8 @@ generate_states (void)
 	fprintf (stderr, "Processing state %d (reached by %s)\n",
 		 s->number,
 		 symbols[s->accessing_symbol]->tag);
-      /* Set up ruleset and itemset for the transitions out of this
+      /* Set up itemset for the transitions out of this state.  itemset gets a
-         state.  ruleset gets a 1 bit for each rule that could reduce
+         vector of all the items that could be accepted next.  */
-         now.  itemset gets a vector of all the items that could be
-         accepted next.  */
       closure (s->items, s->nitems);
       /* Record the reductions allowed out of this state.  */
       save_reductions (s);

src/closure.c

@@ -213,6 +213,8 @@ closure (item_number *core, size_t n)
     if (ISVAR (ritem[core[c]]))
       bitset_or (ruleset, ruleset, FDERIVES (ritem[core[c]]));
 
+  /* core is sorted on item number from ritem, which is sorted on rule number.
+     Compute itemset with the same sort.  */
   nitemset = 0;
   c = 0;
   BITSET_FOR_EACH (iter, ruleset, ruleno, 0)

src/closure.h

@@ -32,7 +32,7 @@
 void new_closure (unsigned int n);
 
 
-/* Given the kernel (aka core) of a state (a vector of item numbers
+/* 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.
@@ -41,7 +41,7 @@ void new_closure (unsigned int n);
    all rules which could potentially describe the next input to be
    read.
 
-   ITEMSET is a vector of item numbers; NITEMSET is its size
+   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.  */