cleaning, docs

lib/slot_language/load_maker.rb

@@ -1,5 +1,11 @@
 module SlotLanguage
+  # A LoadMaker makes SlotLoad. That means it stores the information
+  # to be able to create a SlotLoad
+  #
+  # Just like the SlotLoad stores two Slots, here we store two SlotMakers
+  #
   class LoadMaker
+    # The two SlotMakers that become Slots in to_slot
     attr_reader :left , :right
 
     def initialize(left , right)
@@ -9,9 +15,10 @@ module SlotLanguage
       raise "No Slot #{right}" unless right.is_a?(SlotMaker)
     end
 
+    # create the SlotLoad, by creating the two Slots from the SlotMakers
     def to_slot(compiler)
-      left_d = @left.slot_def(compiler)
-      right_d = @right.slot_def(compiler)
+      left_d = @left.to_slot(compiler)
+      right_d = @right.to_slot(compiler)
       SlotMachine::SlotLoad.new("source" , left_d , right_d)
     end
   end

lib/slot_language/macro_maker.rb

@@ -1,21 +1,51 @@
 
 module SlotLanguage
+  # MacroMaker instances represent Macros at the Slot level
+  #
+  # Macros are like SlotInstruction instances in that they transform to Risc
+  # But all SlotInstructions form a whole that lets us reduce Sol to Slot to risc.
+  # Each Macro on the other hand represents a functionality (kind of method)
+  # that can not be coded in sol. It transforms to a sequence of risc Instructions
+  # that can not be coded any other way. They are not Methods, as they have no
+  # scope, hence the name Macro.
+  #
+  # This MacroMaker is an attempt to code these kind of sequences in SlotLanguage
+  # The SlotCompiler is used to transform a file of SlotLanguage code into and
+  # array of SlotLanguage constructs, which in turn can be transformed into
+  # SlotInstructions.
+  # To start with we work backwards from existing large SlotInstructions, to
+  # get a list of constructs that will transform to the same SlotInstructions
+  # that transform to the same  risc as the current large instruction (+ some redundandency)
   class MacroMaker
+    # an array of Makers
     attr_reader :source
 
+    # load slot code from a file, in a subdir code/ + filename
+    # use load_string to compile the content
     def self.load_file(relative_name)
       path = File.expand_path(  "../code/#{relative_name}" , __FILE__)
       load_string( File.read(path))
     end
+
+    # compile the given SlotLanguage source
+    # the compiler returns an array of Makers which a new MacroMaker
+    # instance stores
+    # return the MacroMaker that represents the source
     def self.load_string(source_code)
       MacroMaker.new( SlotCompiler.compile(source_code) )
     end
 
+    # must initialize with an array of Makers, which is stored
     def initialize( source )
       @source = source
       raise "undefined source #{source}" unless source.is_a?(Array)
     end
 
+    # Basically calls to_slot on each Element of the source array
+    #
+    # Thus transforming an array of Makers into a linked list of
+    # SlotInstructions.
+    # Return the head of the linked list.
     def to_slot(compiler)
       chain = do_link( @source.first , compiler)
       rest = @source.dup

lib/slot_language/slot_compiler.rb

@@ -9,6 +9,7 @@ module SlotLanguage
       ast = Parser::CurrentRuby.parse( input )
       self.new.process(ast)
     end
+
     def not_implemented(node)
       raise "Not implemented #{node.type}"
     end

lib/slot_language/slot_maker.rb

@@ -1,28 +1,36 @@
 module SlotLanguage
+  # A SlotMaker makes Slots. A Slot s the central SlotMachines description of a
+  # variable in an object. This Language level "Maker" holds the information
+  # (names of instance variables) to be able to create the Slot instance
+  #
+  # In the SlotLanguage this is used in the LoadMaker. Just as a Slotload stores
+  # two slots to define what is loaded where, the LoadMaker, that creates a SlotLoad,
+  # uses two SlotMakers.
   class SlotMaker
-    attr_reader :leaps
+    # stores the (instance) names that allow us to create a Slot
+    attr_reader :names
 
-    def initialize(leaps)
-      case leaps
+    def initialize(names)
+      case names
       when Array
-        @leaps = leaps
+        @names = names
       when nil
-        raise "No leaps given"
+        raise "No names given"
       else
-        @leaps = [leaps]
+        @names = [names]
       end
     end
 
     def add_slot_name(name)
-      @leaps << name
+      @names << name
     end
 
-    def slot_def(compiler)
-      SlotMachine::Slot.for(:message , leaps)
+    def to_slot(compiler)
+      SlotMachine::Slot.for(:message , names)
     end
 
     def to_s
-      "message." + leaps.join(",")
+      "message." + names.join(",")
     end
   end
 end

test/slot_language/test_slot_compiler.rb

@@ -59,7 +59,7 @@ module SlotLanguage
     def test_shift
       load = compile("word = name.member")
       assert_equal LoadMaker , load.class
-      assert_equal :word , load.left.leaps.first
+      assert_equal :word , load.left.names.first
       assert_equal SlotMaker , load.right.class
     end
   end

test/slot_language/test_slot_maker.rb

@@ -8,7 +8,7 @@ module SlotLanguage
       @maker = SlotMaker.new(:hi )
     end
     def test_slot
-      @maker.slot_def(@compiler)
+      @maker.to_slot(@compiler)
     end
   end
 end