indexable.rb in facets-2.2.0

- old
+ new

@@ -2,13 +2,16 @@
 require 'facets/array/splice'
 
 class Array
   include Indexable
 
-  #--
-  # Maybe not appropriate for indexable.rb, but where?
-  #++
+  # Alias for #include?.
+  #
+  #   TODO: Maybe not appropriate for indexable.rb, but where?
+  #
+  #   CREDIT: Trans
+
   alias_method :contains?, :include?
 
   #alias_method :/, :[]
 
   # Alias for shift, which removes and returns
@@ -16,19 +19,23 @@
   #
   #  a = ["a","y","z"]
   #  a.first!      #=> "a"
   #  p a           #=> ["y","z"]
   #
+  #   CREDIT: Trans
+
   alias_method :first!, :shift
 
   # Alias for pop, which removes and returns
   # the last element in an array.
   #
   #  a = [1,2]
   #  a.last! 3
   #  p a           #=> [1,2,3]
   #
+  #   CREDIT: Trans
+
   alias_method :last!, :pop
 
   # Iteration object.
 
   class It
@@ -49,9 +56,29 @@
       @value = @after.shift
     end
   end
 
   # Iterate over each element of array using an iteration object.
+  #
+  #   [1,2,3].each_iteration do |it|
+  #     p it.index
+  #     p it.value
+  #     p it.first?
+  #     p it.last?
+  #     p it.prior
+  #     p it.after
+  #   end
+  #
+  # on each successive iteration produces:
+  #
+  #   0          1          2
+  #   1          2          3
+  #   true       false      false
+  #   false      false      true
+  #   []         [1]        [1,2]
+  #   [2,3]      [3]        []
+  #
+  #  CREDIT: Trans
 
   def each_iteration
     if block_given?
       it = It.new(self)
       each do |e|