Add Documentation for Array

mrblib/array.rb

+##
+# 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