more docs and better read me

lib/parfait/dictionary.rb

@@ -2,24 +2,39 @@
 
 module Parfait
   class Dictionary < Object
+    # only empty initialization for now
+    #
+    # internally we store keys and values in lists, which means this does **not** scale well
     def initialize
       @keys = List.new_object()
       @values = List.new_object()
     end
+
+    # return all values as a list
+    # TODO, list should be copied to avoid inconcisencies
     def values()
       @values
     end
+
+    # return all keys as a list
+    # TODO, list should be copied to avoid inconcisencies
     def keys()
       @keys
     end
+
+    # are there any key/value items in the list
     def empty?
       @keys.empty?
     end
 
+    # How many key/value pairs there are
     def length()
       return @keys.get_length()
     end
 
+    # get a value fot the given key
+    # key ientity is checked with == not === (ie equals not identity)
+    # return nil if no such key
     def get(key)
       index = key_index(key)
       if( index )
@@ -28,10 +43,13 @@ module Parfait
         nil
       end
     end
+
+    # same as get(key)
     def [](key)
       get(key)
     end
 
+    # private method
     def key_index(key)
       len = @keys.get_length()
       index = 1
@@ -46,6 +64,7 @@ module Parfait
       found
     end
 
+    # set key with value, returns value
     def set(key , value)
       index = key_index(key)
       if( index )
@@ -56,10 +75,13 @@ module Parfait
       end
       value
     end
+
+    #same as set(k,v)
     def []=(key,val)
       set(key,val)
     end
 
+    # yield to each key value pair
     def each
       index = 1
       while index <= @keys.get_length