From d0117c4c01cb3902f8613a1fdfd875a78a436542 Mon Sep 17 00:00:00 2001
From: inglorion <voodoo@inglorion.net>
Date: Mon, 2 Jan 2012 07:32:52 -0800
Subject: [PATCH] Updated documentation for parser

---
 lib/voodoo/parser.rb | 40 ++++++++++++++++++++++++++++++----------
 1 file changed, 30 insertions(+), 10 deletions(-)

diff --git a/lib/voodoo/parser.rb b/lib/voodoo/parser.rb
index 7eae63c..d0cd4cd 100644
--- a/lib/voodoo/parser.rb
+++ b/lib/voodoo/parser.rb
@@ -47,17 +47,36 @@ module Voodoo
 
     # Parses a top-level element.
     # Returns an array containing the parts of the element.
-    # Each element of the array is a Symbol, a String, or an
-    # Integer.
     #
-    # For a label, returns:
-    #   [:label, label_name]
+    # Some examples (Voodoo code, Ruby return values in comments):
     #
-    # For a function definition, returns:
-    #   [:function, [formala, formalb, ...], statementa, statementb, ...]
-    #
-    # For a conditional, returns:
-    #   [condition, expression, [truea, trueb, ...], [falsea, falseb, ...]]
+    #   section functions
+    #   # [:section, :functions]
+    #   
+    #   call foo x 12
+    #   # [:call, :foo, :x, 12]
+    #   
+    #   set x add x 42
+    #   # [:set, :x, :add, :x, 42]
+    #   
+    #   set-byte @x 1 10
+    #   # [:"set-byte", [:"@", :x], 1, 10]
+    #   
+    #   ifeq x y
+    #       set z equal
+    #   else
+    #       set z not-equal
+    #   end if
+    #   # [:ifeq, [:x, :y], [[:set, :z, :equal]], [[:set, :z, :"not-equal"]]]
+    #   
+    #   foo:
+    #   # [:label, :foo]
+    #   
+    #   function x y
+    #       let z add x y
+    #       return z
+    #   end function
+    #   # [:function, [:x, :y], [:let, :z, :add, :x, :y], [:return, :z]]
     #
     def parse_top_level
       # Skip whitespace, comments, and empty lines
@@ -312,6 +331,7 @@ module Voodoo
 
       words = []
       while true
+        # Parse next token
         skip_whitespace
         word = try_parse_token
         if word == nil
@@ -335,7 +355,7 @@ module Voodoo
             parse_error "Unexpected character (#{lookahead}) in input"
           end
         else
-          # Word is not nil
+          # Word is not nil - we got a token
           if words.empty? && word.kind_of?(::Symbol) && word.to_s[-1] == ?:
             # First word is a label
             words = [:label, word.to_s[0..-2].to_sym]
-- 
2.11.4.GIT