From d3ed29520e28ae95ee8a150db0ceeb569e92210d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Torsten=20R=C3=BCger?= <torsten@webdev.camp>
Date: Tue, 6 Aug 2019 17:42:15 +0300
Subject: [PATCH] Some docs

---
 lib/mom/instruction/slot_load.rb |  2 +-
 lib/ruby/README.md               | 31 +++++++++++++++++++++++++++++++
 lib/vool/README.md               | 20 ++++++++++++--------
 3 files changed, 44 insertions(+), 9 deletions(-)
 create mode 100644 lib/ruby/README.md

diff --git a/lib/mom/instruction/slot_load.rb b/lib/mom/instruction/slot_load.rb
index 347459bb..65c3326b 100644
--- a/lib/mom/instruction/slot_load.rb
+++ b/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
 
diff --git a/lib/ruby/README.md b/lib/ruby/README.md
new file mode 100644
index 00000000..dc4ef9a0
--- /dev/null
+++ b/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.
diff --git a/lib/vool/README.md b/lib/vool/README.md
index 64f153d6..2c5e8982 100644
--- a/lib/vool/README.md
+++ b/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
-an abstract syntax tree which is then transformed.
+Vool is a layer with concrete syntax tree, just like the ruby layer above.
+Vool is just simplified, without fluff, see below.
 
-The next layer down is the Mom, Minimal object Machine, which uses an instruction tree.
-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 next layer down is the Mom, Minimal object Machine, which uses an instruction list.
 
-The nodes of the syntax tree are all the things one would expect from a language, if statements
-and the like. There is no context yet, and actual objects, representing classes and
-methods, will be created on the way down.
+The nodes of the syntax tree are all the things one would expect from a language,
+if statements and the like. There is no context yet, and actual objects,
+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)