Merge pull request #92 from bovi/master

Add documentation

3 files changed, 202 insertions, 40 deletions

diff --git a/mrblib/enum.rb b/mrblib/enum.rb
index b5a387f43..31a94b93f 100644
--- a/mrblib/enum.rb
+++ b/mrblib/enum.rb
@@ -1,8 +1,17 @@
+##
+# Enumerable
 #
-#  Enumerable
-#
+# ISO 15.3.2
 module Enumerable
-  # 15.3.2.2.1
+
+  ##
+  # Call the given block for each element
+  # which is yield by +each+. Return false
+  # if one block value is false. Otherwise
+  # return true. If no block is given and
+  # +self+ is false return false.
+  #
+  # ISO 15.3.2.2.1
   def all?(&block)
     st = true
     if block
@@ -23,7 +32,14 @@ module Enumerable
     st
   end
 
-  # 15.3.2.2.2
+  ##
+  # Call the given block for each element
+  # which is yield by +each+. Return true
+  # if one block value is true. Otherwise
+  # return false. If no block is given and
+  # +self+ is true object return true.
+  #
+  # ISO 15.3.2.2.2
   def any?(&block)
     st = false
     if block
@@ -44,7 +60,13 @@ module Enumerable
     st
   end
 
-  # 15.3.2.2.3
+  ##
+  # Call the given block for each element
+  # which is yield by +each+. Append all
+  # values of each block together and 
+  # return this value.
+  #
+  # ISO 15.3.2.2.3
   def collect(&block)
     ary = []
     self.each{|val|
@@ -53,7 +75,14 @@ module Enumerable
     ary
   end
 
-  # 15.3.2.2.4
+  ##
+  # Call the given block for each element
+  # which is yield by +each+. Return
+  # +ifnone+ if no block value was true.
+  # Otherwise return the first block value 
+  # which had was true.
+  #
+  # ISO 15.3.2.2.4
   def detect(ifnone=nil, &block)
     ret = ifnone
     self.each{|val|
@@ -65,7 +94,13 @@ module Enumerable
     ret
   end
 
-  # 15.3.2.2.5
+  ##
+  # Call the given block for each element
+  # which is yield by +each+. Pass an
+  # index to the block which starts at 0
+  # and increase by 1 for each element.
+  #
+  # ISO 15.3.2.2.5
   def each_with_index(&block)
     i = 0
     self.each{|val|
@@ -75,7 +110,11 @@ module Enumerable
     self
   end
 
-  # 15.3.2.2.6
+  ##
+  # Return an array of all elements which
+  # are yield by +each+.
+  #
+  # ISO 15.3.2.2.6
   def entries
     ary = []
     self.each{|val|
@@ -84,11 +123,19 @@ module Enumerable
     ary
   end
 
-  # 15.3.2.2.7
-  # find(ifnone=nil, &block)
+  ##
+  # Alias for find
+  #
+  # ISO 15.3.2.2.7
   alias find detect
 
-  # 15.3.2.2.8
+  ##
+  # Call the given block for each element
+  # which is yield by +each+. Return an array
+  # which contains all elements whose block
+  # value was true.
+  #
+  # ISO 15.3.2.2.8
   def find_all(&block)
     ary = []
     self.each{|val|
@@ -97,7 +144,14 @@ module Enumerable
     ary
   end
 
-  # 15.3.2.2.9
+  ##
+  # Call the given block for each element
+  # which is yield by +each+ and which return
+  # value was true when invoking === with
+  # +pattern+. Return an array with all 
+  # elements or the respective block values. 
+  #
+  # ISO 15.3.2.2.9
   def grep(pattern, &block)
     ary = []
     self.each{|val|
@@ -108,7 +162,13 @@ module Enumerable
     ary
   end
 
-  # 15.3.2.2.10
+  ##
+  # Return true if at least one element which
+  # is yield by +each+ returns a true value
+  # by invoking == with +obj+. Otherwise return
+  # false.
+  #
+  # ISO 15.3.2.2.10
   def include?(obj)
     st = false
     self.each{|val|
@@ -120,7 +180,14 @@ module Enumerable
     st
   end
 
-  # 15.3.2.2.11
+  ##
+  # Call the given block for each element
+  # which is yield by +each+. Return value
+  # is the sum of all block values. Pass
+  # to each block the current sum and the
+  # current element.
+  #
+  # ISO 15.3.2.2.11
   def inject(*args, &block)
     raise ArgumentError, "too many arguments" if args.size > 2
     flag = true  # 1st element?
@@ -137,11 +204,19 @@ module Enumerable
     result
   end
 
-  # 15.3.2.2.12
-  # map(&block)
+  ##
+  # Alias for collect
+  #
+  # ISO 15.3.2.2.12
   alias map collect
 
-  # 15.3.2.2.13
+  ##
+  # Return the maximum value of all elements
+  # yield by +each+. If no block is given <=>
+  # will be invoked to define this value. If
+  # a block is given it will be used instead.
+  #
+  # ISO 15.3.2.2.13
   def max(&block)
     flag = true  # 1st element?
     result = nil
@@ -161,7 +236,13 @@ module Enumerable
     result
   end
 
-  # 15.3.2.2.14
+  ##
+  # Return the minimum value of all elements
+  # yield by +each+. If no block is given <=>
+  # will be invoked to define this value. If
+  # a block is given it will be used instead.
+  #
+  # ISO 15.3.2.2.14
   def min(&block)
     flag = true  # 1st element?
     result = nil
@@ -181,11 +262,22 @@ module Enumerable
     result
   end
 
-  # 15.3.2.2.15
-  # member?(obj)
+  ##
+  # Alias for include?
+  #
+  # ISO 15.3.2.2.15
   alias member? include?
 
-  # 15.3.2.2.16
+  ##
+  # Call the given block for each element
+  # which is yield by +each+. Return an 
+  # array which contains two arrays. The
+  # first array contains all elements 
+  # whose block value was true. The second
+  # array contains all elements whose
+  # block value was false.
+  #
+  # ISO 15.3.2.2.16
   def partition(&block)
     ary_T = []
     ary_F = []
@@ -199,7 +291,13 @@ module Enumerable
     [ary_T, ary_F]
   end
 
-  # 15.3.2.2.17
+  ##
+  # Call the given block for each element
+  # which is yield by +each+. Return an
+  # array which contains only the elements
+  # whose block value was false.
+  #
+  # ISO 15.3.2.2.17
   def reject(&block)
     ary = []
     self.each{|val|
@@ -208,11 +306,14 @@ module Enumerable
     ary
   end
 
-  # 15.3.2.2.18
-  # select(&block)
+  ##
+  # Alias for find_all.
+  #
+  # ISO 15.3.2.2.18
   alias select find_all
 
-
+  ##
+  # TODO
   # Does this OK? Please test it.
   def __sort_sub__(sorted, work, src_ary, head, tail, &block)
     if head == tail
@@ -250,7 +351,15 @@ module Enumerable
   end
 #  private :__sort_sub__
 
-  # 15.3.2.2.19
+  ##
+  # Return a sorted array of all elements
+  # which are yield by +each+. If no block
+  # is given <=> will be invoked on each
+  # element to define the order. Otherwise
+  # the given block will be used for
+  # sorting.
+  #
+  # ISO 15.3.2.2.19
   def sort(&block)
     ary = []
     self.each{|val| ary.push(val)}
@@ -260,7 +369,9 @@ module Enumerable
     ary
   end
 
-  # 15.3.2.2.20
-  # to_a
+  ##
+  # Alias for entries.
+  #
+  # ISO 15.3.2.2.20
   alias to_a entries
 end
diff --git a/mrblib/error.rb b/mrblib/error.rb
index 88da1825c..5660d8235 100644
--- a/mrblib/error.rb
+++ b/mrblib/error.rb
@@ -1,8 +1,13 @@
+##
+# Exception
 #
-#  Exception
-#
+# ISO 15.2.22
 class Exception
-  # 15.2.22.4.1
+
+  ##
+  # Raise an exception.
+  #
+  # ISO 15.2.22.4.1
   def self.exception(*args, &block)
     self.new(*args, &block)
   end
diff --git a/mrblib/string.rb b/mrblib/string.rb
index 78f2bea9d..ad7e1fca1 100644
--- a/mrblib/string.rb
+++ b/mrblib/string.rb
@@ -1,8 +1,14 @@
+##
+# String
 #
-#  String
-#
+# ISO 15.2.10
 class String
-  # 15.2.10.5.15
+
+  ##
+  # Calls the given block for each line
+  # and pass the respective line.
+  #
+  # ISO 15.2.10.5.15
   def each_line(&block)
     # expect that str.index accepts an Integer for 1st argument as a byte data
     offset = 0
@@ -14,7 +20,13 @@ class String
     self
   end
 
-  # 15.2.10.5.18
+  ##
+  # Replace all matches of +pattern+ with +replacement+.
+  # Call block (if given) for each match and replace
+  # +pattern+ with the value of the block. Return the
+  # final value.
+  #
+  # ISO 15.2.10.5.18
   def gsub(*args, &block)
     unless (args.size == 1 && block) || args.size == 2
       raise ArgumentError, "wrong number of arguments"
@@ -23,7 +35,13 @@ class String
     ### *** TODO *** ###
   end
 
-  # 15.2.10.5.19
+  ##
+  # Replace all matches of +pattern+ with +replacement+.
+  # Call block (if given) for each match and replace
+  # +pattern+ with the value of the block. Modify 
+  # +self+ with the final value.
+  #
+  # ISO 15.2.10.5.19
   def gsub!(*args, &block)
     str = self.gsub(*args, &block)
     if str != self
@@ -34,12 +52,23 @@ class String
     end
   end
 
-  # 15.2.10.5.32
+  ##
+  # Calls the given block for each match of +pattern+
+  # If no block is given return an array with all
+  # matches of +pattern+.
+  # 
+  # ISO 15.2.10.5.32
   def scan(reg, &block)
     ### *** TODO *** ###
   end
 
-  # 15.2.10.5.36
+  ##
+  # Replace only the first match of +pattern+ with 
+  # +replacement+. Call block (if given) for each 
+  # match and replace +pattern+ with the value of the
+  # block. Return the final value.
+  #
+  # ISO 15.2.10.5.36
   def sub(*args, &block)
     unless (args.size == 1 && block) || args.size == 2
       raise ArgumentError, "wrong number of arguments"
@@ -48,7 +77,13 @@ class String
     ### *** TODO *** ###
   end
 
-  # 15.2.10.5.37
+  ##
+  # Replace only the first match of +pattern+ with   
+  # +replacement+. Call block (if given) for each 
+  # match and replace +pattern+ with the value of the 
+  # block. Modify +self+ with the final value.
+  #
+  # ISO 15.2.10.5.37
   def sub!(*args, &block)
     str = self.sub(*args, &block)
     if str != self
@@ -59,6 +94,9 @@ class String
     end
   end
 
+  ##
+  # Call the given block for each character of
+  # +self+.
   def each_char(&block)
     pos = 0
     while(pos < self.size)
@@ -68,6 +106,8 @@ class String
     self
   end
 
+  ##
+  # Call the given block for each byte of +self+.
   def each_byte(&block)
     bytes = self.unpack("C*")
     pos = 0
@@ -78,6 +118,9 @@ class String
     self
   end
 
+  ##
+  # Modify +self+ by replacing the content of +self+
+  # at the position +pos+ with +value+.
   def []=(pos, value)
     b = self[0, pos]
     a = self[pos+1..-1]
@@ -86,7 +129,10 @@ class String
   end
 end
 
-# include modules
+##
+# String is comparable
+#
+# ISO 15.2.10.3
 module Comparable; end
 class String
   include Comparable