Merge pull request #89 from bovi/master

Add documentation for Array, Struct and Kernel

3 files changed, 68 insertions, 13 deletions

diff --git a/mrblib/array.rb b/mrblib/array.rb
index a70832399..905b41cb0 100644
--- a/mrblib/array.rb
+++ b/mrblib/array.rb
@@ -1,8 +1,14 @@
+##
+# Array
 #
-#  Array
-#
+# ISO 15.2.12
 class Array
-  # 15.2.12.5.10
+
+  ##
+  # Calls the given block for each element of +self+
+  # and pass the respective element.
+  #
+  # ISO 15.2.12.5.10
   def each(&block)
     idx = 0
     while(idx < length)
@@ -12,7 +18,11 @@ class Array
     self
   end
 
-  # 15.2.12.5.11
+  ##
+  # Calls the given block for each element of +self+
+  # and pass the index of the respective elment.
+  #
+  # ISO 15.2.12.5.11
   def each_index(&block)
     idx = 0
     while(idx < length)
@@ -22,7 +32,12 @@ class Array
     self
   end
 
-  # 15.2.12.5.7
+  ##
+  # Calls the given block for each element of +self+
+  # and pass the respective element. Each element will
+  # be replaced by the resulting values.
+  #
+  # ISO 15.2.12.5.7
   def collect!(&block)
     self.each_index{|idx|
       self[idx] = block.call(self[idx])
@@ -30,11 +45,16 @@ class Array
     self
   end
 
-  # 15.2.12.5.20
-  # map!(&block)
+  ##
+  # Alias for collect!
+  #  
+  # ISO 15.2.12.5.20
   alias map! collect!
 
-  # 15.2.12.5.15
+  ##
+  # Private method for Array creation.
+  #
+  # ISO 15.2.12.5.15
   def initialize(size=0, obj=nil, &block)
     raise TypeError, "expected Integer for 1st argument" unless size.kind_of? Integer
     raise ArgumentError, "negative array size" if size < 0
@@ -53,6 +73,8 @@ class Array
     self
   end
 
+  ##
+  # Delete element with index +key+
   def delete(key, &block)
     while i = self.index(key)
       self.delete_at(i)
@@ -73,6 +95,9 @@ class Array
   include Enumerable
   include Comparable
 
+  ##
+  # Sort all elements and replace +self+ with these
+  # elements.
   def sort!(&block)
     self.replace(self.sort(&block))
   end
diff --git a/mrblib/print.rb b/mrblib/print.rb
index cb1fad75d..840a1249a 100644
--- a/mrblib/print.rb
+++ b/mrblib/print.rb
@@ -1,4 +1,13 @@
+##
+# Kernel
+#
+# ISO 15.3.1
 module Kernel
+
+  ##
+  # Invoke method +print+ on STDOUT and passing +*args+
+  #
+  # ISO 15.3.1.2.10
   def print(*args)
     i = 0
     len = args.size
@@ -7,6 +16,11 @@ module Kernel
       i += 1
     end
   end
+
+  ##
+  # Invoke method +puts+ on STDOUT and passing +*args*+
+  #
+  # ISO 15.3.1.2.11
   def puts(*args)
     i = 0
     len = args.size
diff --git a/mrblib/struct.rb b/mrblib/struct.rb
index b11f59f2a..4b6d767a9 100644
--- a/mrblib/struct.rb
+++ b/mrblib/struct.rb
@@ -1,8 +1,14 @@
+##
+# Struct
 #
-#  Struct
-#
+# ISO 15.2.18
 class Struct
-  # 15.2.18.4.4
+
+  ##
+  # Calls the given block for each element of +self+
+  # and pass the respective element.
+  #
+  # ISO 15.2.18.4.4
   def each(&block)
     self.class.members.each{|field|
       block.call(self[field])
@@ -10,7 +16,12 @@ class Struct
     self
   end
 
-  # 15.2.18.4.5
+  ##
+  # Calls the given block for each element of +self+
+  # and pass the name and value of the respectiev
+  # element.
+  #
+  # ISO 15.2.18.4.5
   def each_pair(&block)
     self.class.members.each{|field|
       block.call(field.to_sym, self[field])
@@ -18,7 +29,12 @@ class Struct
     self
   end
 
-  # 15.2.18.4.7
+  ##
+  # Calls the given block for each element of +self+
+  # and returns an array with all elements of which
+  # block is not false.
+  #
+  # ISO 15.2.18.4.7
   def select(&block)
     ary = []
     self.class.members.each{|field|