Some docs

lib/mom/instruction/slot_load.rb

@@ -22,7 +22,7 @@ module Mom
   #        SlotDefinition (see there)
   #
   # @right: A SlotDefinition with slots or a Mom::Constant
-  # original_source: optinally another mom instruction that wil be passed down to created
+  # original_source: optinally another mom instruction that will be passed down to created
   #   risc instructions. (Because SlotLoad is often used internally in mom)
   class SlotLoad < Instruction
 

lib/ruby/README.md

@@ -0,0 +1,31 @@
+# Ruby
+
+A representation of the ruby code.
+
+## Concrete Syntax tree
+
+Ruby is parsed by the parser gem (big thanks to whitequark). Own attempts at
+this task have failed utterly, because ruby is a _huge_ language (and not well
+defined at that)
+
+Alas, the parser gem creates an abstract syntax tree, meaning one class is used
+to represent all node types.
+
+Imho object oriented languages have a class system to do just that, ie represent
+what we may loosely call type here, ie the kind of statement.
+
+The ruby layer is really all about defining classes for every kind of statement,
+thus "typing" the syntax tree, and making it concrete.
+
+## to Vool
+
+In our nice layers, we are ont the way down to Vool, a simplified version of oo.
+
+It has proven handy to have this layer, so the code for transforming each object
+is in the class representing that object. (As one does in oo, again imho).
+
+## Parfait objects
+
+The compilation process ends up creating (parfait) objects to represent
+things like classes, types and constants. This is not done here yet, but in
+the vool layer.

lib/vool/README.md

@@ -9,16 +9,14 @@ Possibly later other languages can compile to this level and use rx-file as code
 
 ## Syntax tree
 
-Vool is the layer of concrete syntax tree. The Parser gem is used to parse ruby. It creates
+Vool is a layer with concrete syntax tree, just like the ruby layer above.
-an abstract syntax tree which is then transformed.
+Vool is just simplified, without fluff, see below.
 
-The next layer down is the Mom, Minimal object Machine, which uses an instruction tree.
+The next layer down is the Mom, Minimal object Machine, which uses an instruction list.
-That is on the way down we create instructions, but stays in tree format. Only the next step
-down to the Risc layer moves to an instruction stream.
 
-The nodes of the syntax tree are all the things one would expect from a language, if statements
+The nodes of the syntax tree are all the things one would expect from a language,
-and the like. There is no context yet, and actual objects, representing classes and
+if statements and the like. There is no context yet, and actual objects,
-methods, will be created on the way down.
+representing classes and methods, will be created on the way down.
 
 ## Fluff
 
@@ -30,3 +28,9 @@ existence of until, which really means if not. Other examples, some more impactf
 - no case
 - no elseif (no unless, no ternary operator)
 - no global variables.
+
+## Parfait objects
+
+The compilation process ends up creating (parfait) objects to represent
+things like classes, types and constants. This is done in this layer,
+on the way down to MOM (ie not during init)