--- a/python/pyyacc.py	Fri May 24 20:45:03 2013 +0200
+++ b/python/pyyacc.py	Sat May 25 14:26:25 2013 +0200
@@ -9,10 +9,12 @@
 ACCEPT = 3
 
 class ParserGenerationException(Exception):
+    """ Raised when something goes wrong during parser generation """
     pass
 
 
 class ParserException(Exception):
+    """ Raised during a failure in the parsing process """
     pass
 
 
@@ -43,6 +45,11 @@
 
     @property
     def first(self):
+        """ 
+          The first set is a mapping from a grammar symbol to a set of
+          set of all terminal symbols that can be the first terminal when
+          looking for the grammar symbol 
+        """
         if not self._first:
             self._first = self.calcFirstSets()
         return self._first
@@ -85,12 +92,12 @@
             if not itm in itemset:
                 itemset.add(itm)
                 worklist.append(itm)
-        def first2(itm, la):
+        def first2(itm):
             # When using the first sets, create a copy:
-            f = set(self.first[item.NextNext])
+            f = set(self.first[itm.NextNext])
             if EPS in f:
                 f.discard(EPS)
-                f.add(item.look_ahead)
+                f.add(itm.look_ahead)
             return f
         # Start of algorithm: 
         while worklist:
@@ -101,7 +108,7 @@
                 continue
             C = item.Next
             for add_p in self.productionsForName(C):
-                for b in first2(item, item.look_ahead):
+                for b in first2(item):
                     addIt(Item(add_p, 0, b))
         return frozenset(itemset)
 
@@ -194,6 +201,12 @@
 
 
 class Item:
+    """ 
+        Represents a partially parsed item 
+        It has a production it is looking for, a position
+        in this production called the 'dot' and a look ahead
+        symbol that must follow this item.
+    """
     def __init__(self, production, dotpos, look_ahead):
         self.production = production
         self.dotpos = dotpos
@@ -214,14 +227,17 @@
 
     @property
     def IsReduce(self):
+        """ Check if this item has the dot at the end """
         return self.dotpos == len(self.production.symbols)
 
     @property
     def IsShift(self):
+        """ Check if this item is a shift item, i.e. the dot can proceed """
         return not self.IsReduce
 
     @property
     def Next(self):
+        """ Returns the symbol after the dot """
         return self.production.symbols[self.dotpos]
 
     def can_shift_over(self, symbol):
@@ -234,6 +250,7 @@
 
     @property
     def NextNext(self):
+        """ Gets the symbol after the next symbol, or EPS if at the end """
         if self.dotpos + 1 >= len(self.production.symbols):
             return EPS
         else:
@@ -243,8 +260,8 @@
         prod = self.production
         predot = ' '.join(prod.symbols[0:self.dotpos])
         postdot = ' '.join(prod.symbols[self.dotpos:])
-        nt = prod.name
-        args = (nt, predot, postdot, self.look_ahead)
+        name = prod.name
+        args = (name, predot, postdot, self.look_ahead)
         return '[{0} -> {1} . {2} -> {3}]'.format(*args)