Some docs and to_s testing

somewhat code_climate inspired

lib/ruby/call_statement.rb

@@ -1,5 +1,14 @@
 module Ruby
 
+  # A CallStatement is the abstraction of Send and Yield. The two are really
+  # much more similar than different.
+  #
+  # A CallStatement has a name, receiver and arguments
+  #
+  # Using the "vool_brother" we can create the right Vool class for it.
+  # Arguments in vool must be simple, so any complex expressions get
+  # hoisted and assigned to temporary variables.
+  #
   class CallStatement < Statement
     attr_reader :name , :receiver , :arguments
 

lib/ruby/if_statement.rb

@@ -1,6 +1,15 @@
 require_relative "normalizer"
 
 module Ruby
+  # The if must have condition and a true branch, the false is optional
+  #
+  # It maps pretty much one to one to a Vool, except for "hoisting"
+  #
+  # Ruby may have super complex expressions as the condition, whereas
+  # Vool may not. Ie of a Statement list all but the last are hoisted to before
+  # the vool if. This is equivalent, just easier to compile later
+  #
+  # The hoisintg code is in Normalizer, as it is also useed in return and while
   class IfStatement < Statement
     include Normalizer
 
@@ -28,8 +37,8 @@ module Ruby
     end
 
     def to_s(depth = 0)
-      parts = ["if (#{@condition})" , @body.to_s(depth + 1) ]
-      parts += ["else" ,  "@if_false.to_s(depth + 1)"] if(@false)
+      parts = ["if(#{@condition})" , @if_true.to_s(depth + 1) ]
+      parts += ["else" ,  @if_false.to_s(depth + 1)] if(@if_false)
       parts << "end"
       at_depth(depth , *parts )
     end

lib/ruby/send_statement.rb

@@ -1,5 +1,8 @@
 module Ruby
-
+  # Send and yield are very very similar, so they have a base class CallStatement
+  #
+  # The SendStatement really only provides to_s, so see CallStatement
+  #
   class SendStatement < CallStatement
     def to_s
       "#{receiver}.#{name}(#{arguments.join(', ')})"

lib/ruby/statement.rb

@@ -7,17 +7,26 @@ module Ruby
   #
   class Statement
 
+    # Many statements exist in the vool layer in quite a similar arrangement
+    # Especially for different types of assignment we can abstract the creation
+    # of the vool, by using the right class to instantiate, the "vool_brother"
+    # Ie same class_name, but in the Vool module  
+    def vool_brother
+      eval "Vool::#{class_name}"
+    end
+
+    # return the class name without the module
+    # used to evaluate the vool_brother
+    def class_name
+      self.class.name.split("::").last
+    end
+
+    # helper method for formatting source code
+    # depth is the depth in the tree (os the ast)
+    # and the string are the ones to be indented (2 spaces)
     def at_depth(depth , *strings)
       prefix = " " * 2 * depth
       strings.collect{|str| prefix + str}.join("\n")
     end
-
-    def vool_brother
-      eval "Vool::#{class_name}"
-    end
-    def class_name
-      self.class.name.split("::").last
-    end
   end
-
 end

lib/ruby/yield_statement.rb

@@ -1,7 +1,14 @@
 module Ruby
 
+  # Send and yield are very very similar, so they have a base class CallStatement
+  #
+  # The YieldStatement really only provides to_s, and has slightly
+  # different constructor. See CallStatement
+  #
   class YieldStatement < CallStatement
 
+    # We give the instance of the yield and auto generated name
+    # Also, a yield is always (for now) on self
     def initialize(arguments)
       super("yield_#{object_id}".to_sym , SelfExpression.new , arguments)
     end