Merge pull request #101 from bovi/master

Add documentation for Hash, Kernel, Numeric, Array and Range

5 files changed, 94 insertions, 23 deletions

diff --git a/mrblib/array.rb b/mrblib/array.rb
index 905b41cb0..881f22df7 100644
--- a/mrblib/array.rb
+++ b/mrblib/array.rb
@@ -88,10 +88,12 @@ class Array
   end
 end
 
-# include modules
+##
+# Array is enumerable and comparable
 module Enumerable; end
 module Comparable; end
 class Array
+  # ISO 15.2.12.3
   include Enumerable
   include Comparable
 
diff --git a/mrblib/hash.rb b/mrblib/hash.rb
index 7157684f8..d6ad55e47 100644
--- a/mrblib/hash.rb
+++ b/mrblib/hash.rb
@@ -1,8 +1,17 @@
+##
+# Hash
 #
-#  Hash
-#
+# ISO 15.2.13
 class Hash
-  # 15.2.13.4.8
+
+  ##
+  # Delete the element with the key +key+.
+  # Return the value of the element if +key+
+  # was found. Return nil if nothing was
+  # found. If a block is given, call the
+  # block with the value of the element.
+  #
+  # ISO 15.2.13.4.8
   def delete(key, &block)
     if block && ! self.has_key?(key)
       block.call(key)
@@ -11,30 +20,52 @@ class Hash
     end
   end
 
-  # 15.2.13.4.9
+  ##
+  # Calls the given block for each element of +self+
+  # and pass the key and value of each element.
+  #
+  # ISO 15.2.13.4.9
   def each(&block)
     self.keys.each{|k| block.call([k, self[k]])}
     self
   end
 
-  # 15.2.13.4.10
+  ##
+  # Calls the given block for each element of +self+
+  # and pass the key of each element.
+  #
+  # ISO 15.2.13.4.10
   def each_key(&block)
     self.keys.each{|k| block.call(k)}
     self
   end
 
-  # 15.2.13.4.11
+  ##
+  # Calls the given block for each element of +self+
+  # and pass the value of each element.
+  #
+  # ISO 15.2.13.4.11
   def each_value(&block)
     self.keys.each{|k| block.call(self[k])}
     self
   end
 
-  # 15.2.13.4.16
+  ##
+  # Create a direct instance of the class Hash.
+  #
+  # ISO 15.2.13.4.16
   def initialize(*args, &block)
     self.__init_core(block, *args)
   end
 
-  # 15.2.13.4.22
+  ##
+  # Return a hash which contains the content of
+  # +self+ and +other+. If a block is given
+  # it will be called for each element with
+  # a duplicate key. The value of the block
+  # will be the final value of this element.
+  # 
+  # ISO 15.2.13.4.22
   def merge(other, &block)
     h = {}
     raise "can't convert argument into Hash" unless other.respond_to?(:to_hash)
@@ -51,7 +82,10 @@ class Hash
   end
 end
 
-# include modules
+##
+# Hash is enumerable
+#
+# ISO 15.2.13.3
 module Enumerable; end
 class Hash
   include Enumerable
diff --git a/mrblib/kernel.rb b/mrblib/kernel.rb
index c09755d6c..f98284d24 100644
--- a/mrblib/kernel.rb
+++ b/mrblib/kernel.rb
@@ -1,21 +1,33 @@
+##
+# Kernel
 #
-#  Kernel
-#
+# ISO 15.3.1
 module Kernel
-  # 15.3.1.2.6
+
+  ##
+  # Takes the given block, create a lambda
+  # out of it and +call+ it.
+  #
+  # ISO 15.3.1.2.6
   def self.lambda(&block)
     ### *** TODO *** ###
     block  # dummy
   end
 
-  # 15.3.1.2.8
+  ##
+  # Calls the given block repetitively.
+  #
+  # ISO 15.3.1.2.8
   def self.loop #(&block)
     while(true)
       yield
     end
   end
 
-  # 15.3.1.3.4
+  ##
+  # Alias for +send+.
+  #
+  # ISO 15.3.1.3.4
   def __send__(symbol, *args, &block)
     ### *** TODO *** ###
   end
@@ -25,20 +37,31 @@ module Kernel
     ### *** TODO *** ###
   end
 
-  # 15.3.1.3.27
+  ##
+  # Alias for +Kernel.lambda+.
+  #
+  # ISO 15.3.1.3.27
   def lambda(&block)
     ### *** TODO *** ###
     block # dummy
   end
 
-  # 15.3.1.3.29
+  ##
+  # Alias for +Kernel.loop+.
+  #
+  # ISO 15.3.1.3.29
   def loop #(&block)
     while(true)
       yield
     end
   end
 
-  # 15.3.1.3.44
+  ##
+  # Invoke the method with the name +symbol+ on
+  # the receiver and pass +args+ and the given
+  # block.
+  #
+  # ISO 15.3.1.3.44
   def send(symbol, *args, &block)
     ### *** TODO *** ###
   end
diff --git a/mrblib/numeric.rb b/mrblib/numeric.rb
index 08600b0bf..9f65d5633 100644
--- a/mrblib/numeric.rb
+++ b/mrblib/numeric.rb
@@ -48,7 +48,10 @@ class Integer
   end
 end
 
-# include modules
+##
+# Numeric is comparable
+#
+# ISO 15.2.7.3
 module Comparable; end
 class Numeric
   include Comparable
diff --git a/mrblib/range.rb b/mrblib/range.rb
index 79bc40ecd..44be0305b 100644
--- a/mrblib/range.rb
+++ b/mrblib/range.rb
@@ -1,8 +1,14 @@
+##
+# Range
 #
-#  Range
-#
+# ISO 15.2.14
 class Range
-  # 15.2.14.4.4
+
+  ##
+  # Calls the given block for each element of +self+
+  # and pass the respective element.
+  #
+  # ISO 15.2.14.4.4
   def each(&block)
     val = self.first
     unless val.respond_to? :succ
@@ -23,7 +29,10 @@ class Range
   end
 end
 
-# include modules
+##
+# Range is enumerable
+#
+# ISO 15.2.14.3
 module Enumerable; end
 class Range
   include Enumerable