bit of code docs

lib/mom/instruction/instruction.rb

@@ -1,26 +1,34 @@
 module Mom
 
   # Base class for MOM instructions
+  # At the base class level instructions are a linked list.
+  #
+  # Mom::Instructions are created by the Vool level as an intermediate step
+  # towards the next level down, the Risc level.
+  # Mom and Risc are both abstract machines (ie have instructions), so both
+  # share the linked list functionality (In Common::List)
+  #
+  # To convert a Mom instruction to it's Risc equivalent to_risc is called
+  #
   class Instruction
     include Common::List
 
-    def to_risc(m)
-      Risc::Label.new(self.class.name, self.class.name + "_todo")
+    # to_risc, like the name says, converts the instruction to it's Risc equivalent.
+    # The Risc machine is basically a simple register machine (kind of arm).
+    # In other words Mom is the higher abstraction and so mom instructions convert
+    # to many (1-10) risc instructions
+    #
+    # The argument that is passed is a MethodCompiler, which has the method and some
+    # state about registers used. (also provides helpers to generate risc instructions)
+    def to_risc(compiler)
+      raise Risc::Label.new(self.class.name, self.class.name + "_todo")
     end
   end
 
-  # A label with a name
-  class Label < Instruction
-    attr_reader :name
-    def initialize(name)
-      @name = name
-    end
-    def to_risc(compiler)
-      Risc::Label.new(self,name)
-    end
-  end
 end
 
+require_relative "label"
+require_relative "check"
 require_relative "basic_values"
 require_relative "simple_call"
 require_relative "dynamic_call"

lib/mom/instruction/label.rb

@@ -0,0 +1,33 @@
+module Mom
+
+  # A Label is the only legal target for a branch (this is true in Mom and Risc)
+  #
+  # In the dynamic view (runtime) where the instructions form a graph,
+  # branches fan out, Labels collect. In other words a branch is the place where
+  # several roads lead off, and a Label where several roads arrive.
+  #
+  # A Label has a name which is mainly used for debugging.
+  #
+  class Label < Instruction
+    attr_reader :name
+    def initialize(name)
+      @name = name
+    end
+
+    # A Mom::Label converts one2one to a Risc::Label. So in a way it could not be more
+    # simple.
+    # Alas, since almost by definition several roads lead to this label, all those
+    # several converted instructions must also point to the identical label on the
+    # risc level.
+    #
+    # This is achieved by caching the created Risc::Label in an instance variable.
+    # All branches that lead to this label can thus safely call the to_risc and
+    # whoever calls first triggers the labels creation, but all get the same label.
+    #
+    # Off course some specific place still has to be responsible for actually
+    # adding the label to the instruction list (usually an if/while)
+    def to_risc(compiler)
+      @risc_label ||= Risc::Label.new(self,name)
+    end
+  end
+end