done documenting

improved/parser.py

@@ -18,11 +18,25 @@ BOOLEAN_PRECEDENCE = [
 
 #Helper
 def precedence(value_parser, precedences, combine):
+    """
+        Given a parser, a list of precedenses and
+        a combination function, it build a parser
+        matching the precedences.
+
+        value_parser -- the parser
+        precedences  -- the list (possibly nested) of
+                        operators, ordered by precedences
+        combine      -- the combination function
+
+        returns -- a parser able to parse any operator
+                   given, respecting its' respective
+                   precedence
+    """
     def op_parser(precedence):
         return any_op_in_list(precedence) ^ combine
     parser = value_parser * op_parser(precedences[0])
-    for precedence in precedences[1:]:
-        parser = parser * op_parser(precedence)
+    for prec in precedences[1:]:
+        parser = parser * op_parser(prec)
     return parser
 
 def process_binop(op):
@@ -71,6 +85,14 @@ def process_logic(op):
         raise RuntimeError('unknown logic operator: ' + op)
 
 def process_group(parsed):
+    """
+        Takes a tuple of the form ((foo, important), bar)
+        and only returns the important part.
+
+        parsed -- a tuple of the form ((foo, important), bar)
+
+        returns -- the middle part (denoted as important)
+    """
     ((_, p), _) = parsed
     return p
 
@@ -118,6 +140,11 @@ def arithmetic_value():
             (imp_id  ^ (lambda v: VarArithmeticExp(v))))
 
 def read_statement():
+    """
+        Builds a parser for read statements.
+
+        returns -- a parser for read statements
+    """
     def internal(parsed):
         return ReadStatement()
     return keyword('read') ^ internal
@@ -184,12 +211,22 @@ def boolean_exp():
                       process_logic)
 
 def assign_statement():
+    """
+        Builds a parser for assignment statements.
+
+        returns -- a parser for assignment statements
+    """
     def internal(parsed):
         ((name, _), exp) = parsed
         return AssignStatement(name, exp)
     return imp_id + keyword(':=') + arithmetic_exp() ^ internal
 
 def if_statement():
+    """
+        Builds a parser for if statements.
+
+        returns -- a parser for if statements
+    """
     def internal(parsed):
         (((((_, condition), _), on_true), false_parsed), _) = parsed
         if false_parsed:
@@ -203,6 +240,11 @@ def if_statement():
             + keyword('end') ^ internal)
 
 def while_statement():
+    """
+        Builds a parser for while statements.
+
+        returns -- a parser for while statements
+    """
     def internal(parsed):
         ((((_, condition), _), body), _) = parsed
         return WhileStatement(condition, body)