some docs

lib/register/parfait/behaviour.rb

@@ -1,13 +1,10 @@
+# Behaviour is something that has methods, basically class and modules superclass
 
-# described in the ruby language book as the eigenclass, what you get with
-# class MyClass
-#     class << self        <--- this is called the eigenclass, or metaclass, and really is just
-#     ....                              the class object but gives us the ability to use the
-#                                       syntax as if it were a class
-#
+# instance_methods is the attribute in the including class that has the methods
 
 module Parfait
   module Behaviour
+    # when included we set up the instance_methods attribute
     def self.included(base)
       base.attribute :instance_methods
     end
@@ -22,6 +19,7 @@ module Parfait
       return m if m
       self.instance_methods = List.new
     end
+
     def method_names
       names = List.new
       self.methods.each do |method|

lib/register/parfait/binary_code.rb

@@ -6,7 +6,7 @@
 
 module Parfait
   # obviously not a "Word" but a ByteArray , but no such class yet
-  # As on the other hand has no encoding (yet) it is close enough
+  # As String on the other hand has no encoding (yet) it is close enough
   class BinaryCode < Word
 
     def to_s

lib/register/parfait/class.rb

@@ -1,19 +1,16 @@
-# A class describes the capabilities of a group of objects, ie what data it has
-# and functions it responds to.
+# Class is mainly a list of methods with a name. The methods are untyped.
 
-
-# Class is mainly a list of methods with a name. (Note that methods may have many functions)
 # The memory layout of an object is determined by the Type (see there).
 # The class carries the "current" type, ie the type an object would be if you created an instance
 # of the class. Note that this changes over time and so many types share the same class.
 
-# It is essential that the class (the object defining the class)
+# For dynamic OO it is essential that the class (the object defining the class)
 # can carry methods. It does so as instance variables.
 # In fact this property is implemented in the Type, as methods
-# may be added to any object at run-time
+# may be added to any object at run-time.
 
-# An Object carries the data for the instance variables it has
-# The Type lists the names of the instance variables
+# An Object carries the data for the instance variables it has.
+# The type lists the names of the instance variables
 # The class keeps a list of instance methods, these have a name and code
 
 module Parfait
@@ -47,7 +44,6 @@ module Parfait
       "Class(#{name})"
     end
 
-
     def create_instance_method  method_name , arguments
       raise "create_instance_method #{method_name}.#{method_name.class}" unless method_name.is_a?(Symbol)
       clazz = instance_type().object_class()

lib/register/parfait/indexed.rb

@@ -1,19 +1,18 @@
-# various classes would derive from array in ruby, ie have indexed variables
-#
-# But for our memory type we need the variable part of an object to be after
-# the fixed, ie the instance variables
-#
-# Just using ruby derivation will not allow us to offset the index, so instead the
-# function will be generated and included to the classes that need them.
-#
-# Using ruby include does not work for similar reasons, so Indexed.at is the main
-# function that generates the methods
- # ( do have to use a marker module so we can test with is_a?)
-
 module Parfait
+  # Various classes would derive from array in ruby, ie have indexed variables
+  #
+  # But for our memory type we need the variable part of an object to be after
+  # the fixed, ie the instance variables
+  #
+  # Just using ruby derivation will not allow us to offset the index, so instead the
+  # function will be generated and included to the classes that need them.
+  #
+  # Basic functionality depends on the offset, and those methods are generated by
+  # the offset method that has to be called seperately when including this Module
+
   module Indexed # marker module
     def self.included(base)
-      base.extend(Methods)
+      base.extend(OffsetMethods)
       base.attribute :indexed_length
     end
 
@@ -137,7 +136,9 @@ module Parfait
       ret
     end
 
-    module Methods
+    module OffsetMethods
+      # generate all methods that depend on the (memory) offset
+      # These are get/set shrink_to/grow_to
       def offset( offset  )
         offset += 1 # for the attribute we add (indexed_length)
 

lib/register/parfait/method.rb

@@ -18,6 +18,10 @@ module Parfait
 
   class Method < Object
 
+    attributes [:name , :source , :instructions , :binary ,:arguments , :for_class, :locals ]
+    # not part of the parfait model, hence ruby accessor
+    attr_accessor :source
+
     def initialize clazz , name , arguments
       super()
       raise "No class #{name}" unless clazz
@@ -31,9 +35,6 @@ module Parfait
       self.arguments = arguments
       self.locals = List.new
     end
-    attributes [:name , :source , :instructions , :binary ,:arguments , :for_class, :locals ]
-    # not part of the parfait model, hence ruby accessor
-    attr_accessor :source
 
     # determine whether this method has an argument by the name
     def has_arg name

lib/register/parfait/object.rb

@@ -2,8 +2,8 @@
 # and functions to work on that data.
 # Only the object may access it's data directly.
 
-# From an implementation perspective it is a chunk of memory with an type as the first
-# word.
+# From an implementation perspective it is a chunk of memory with a type as the first
+# word (instance of class Type).
 
 # Objects are arranged or layed out (in memory) according to their Type
 # every object has a Type. Type objects are immutalbe and may be reused for a group/class
@@ -17,6 +17,8 @@ module Parfait
 
   class Object < Value
 
+    # we define new, so we can do memory layout also at compile time.
+    # At compile time we fake memory by using a global array for pages
     def self.new *args
       object = self.allocate
       #HACK, but used to do the adapter in the init, bu that is too late now
@@ -30,9 +32,6 @@ module Parfait
       object
     end
 
-    # Objects memory functions. Object memory is 1 based
-    # but we implement it with ruby array (0 based) and don't use 0
-    # These are the same functions that Builtin implements for run-time
     include Padding
     include Positioned