Merge pull request #2999 from sagmor/better-docs

More Docs

1 files changed, 78 insertions, 80 deletions

diff --git a/mrbgems/mruby-enumerator/mrblib/enumerator.rb b/mrbgems/mruby-enumerator/mrblib/enumerator.rb
index c54959e91..9abaca38a 100644
--- a/mrbgems/mruby-enumerator/mrblib/enumerator.rb
+++ b/mrbgems/mruby-enumerator/mrblib/enumerator.rb
@@ -6,92 +6,91 @@
 # A class which allows both internal and external iteration.
 #
 # An Enumerator can be created by the following methods.
-# - Kernel#to_enum
-# - Kernel#enum_for
-# - Enumerator.new
+# - {Kernel#to_enum}
+# - {Kernel#enum_for}
+# - {Enumerator#initialize Enumerator.new}
 #
 # Most methods have two forms: a block form where the contents
 # are evaluated for each item in the enumeration, and a non-block form
 # which returns a new Enumerator wrapping the iteration.
 #
-#   enumerator = %w(one two three).each
-#   puts enumerator.class # => Enumerator
+#       enumerator = %w(one two three).each
+#       puts enumerator.class # => Enumerator
 #
-#   enumerator.each_with_object("foo") do |item, obj|
-#     puts "#{obj}: #{item}"
-#   end
+#       enumerator.each_with_object("foo") do |item, obj|
+#         puts "#{obj}: #{item}"
+#       end
 #
-#   # foo: one
-#   # foo: two
-#   # foo: three
+#       # foo: one
+#       # foo: two
+#       # foo: three
 #
-#   enum_with_obj = enumerator.each_with_object("foo")
-#   puts enum_with_obj.class # => Enumerator
+#       enum_with_obj = enumerator.each_with_object("foo")
+#       puts enum_with_obj.class # => Enumerator
 #
-#   enum_with_obj.each do |item, obj|
-#     puts "#{obj}: #{item}"
-#   end
+#       enum_with_obj.each do |item, obj|
+#         puts "#{obj}: #{item}"
+#       end
 #
-#   # foo: one
-#   # foo: two
-#   # foo: three
+#       # foo: one
+#       # foo: two
+#       # foo: three
 #
 # This allows you to chain Enumerators together.  For example, you
 # can map a list's elements to strings containing the index
 # and the element as a string via:
 #
-#   puts %w[foo bar baz].map.with_index { |w, i| "#{i}:#{w}" }
-#   # => ["0:foo", "1:bar", "2:baz"]
+#       puts %w[foo bar baz].map.with_index { |w, i| "#{i}:#{w}" }
+#       # => ["0:foo", "1:bar", "2:baz"]
 #
 # An Enumerator can also be used as an external iterator.
 # For example, Enumerator#next returns the next value of the iterator
 # or raises StopIteration if the Enumerator is at the end.
 #
-#   e = [1,2,3].each   # returns an enumerator object.
-#   puts e.next   # => 1
-#   puts e.next   # => 2
-#   puts e.next   # => 3
-#   puts e.next   # raises StopIteration
+#       e = [1,2,3].each   # returns an enumerator object.
+#       puts e.next   # => 1
+#       puts e.next   # => 2
+#       puts e.next   # => 3
+#       puts e.next   # raises StopIteration
 #
 # You can use this to implement an internal iterator as follows:
 #
-#   def ext_each(e)
-#     while true
-#       begin
-#         vs = e.next_values
-#       rescue StopIteration
-#         return $!.result
+#       def ext_each(e)
+#         while true
+#           begin
+#             vs = e.next_values
+#           rescue StopIteration
+#             return $!.result
+#           end
+#           y = yield(*vs)
+#           e.feed y
+#         end
 #       end
-#       y = yield(*vs)
-#       e.feed y
-#     end
-#   end
 #
-#   o = Object.new
+#       o = Object.new
 #
-#   def o.each
-#     puts yield
-#     puts yield(1)
-#     puts yield(1, 2)
-#     3
-#   end
+#       def o.each
+#         puts yield
+#         puts yield(1)
+#         puts yield(1, 2)
+#         3
+#       end
 #
-#   # use o.each as an internal iterator directly.
-#   puts o.each {|*x| puts x; [:b, *x] }
-#   # => [], [:b], [1], [:b, 1], [1, 2], [:b, 1, 2], 3
+#       # use o.each as an internal iterator directly.
+#       puts o.each {|*x| puts x; [:b, *x] }
+#       # => [], [:b], [1], [:b, 1], [1, 2], [:b, 1, 2], 3
+#
+#       # convert o.each to an external iterator for
+#       # implementing an internal iterator.
+#       puts ext_each(o.to_enum) {|*x| puts x; [:b, *x] }
+#       # => [], [:b], [1], [:b, 1], [1, 2], [:b, 1, 2], 3
 #
-#   # convert o.each to an external iterator for
-#   # implementing an internal iterator.
-#   puts ext_each(o.to_enum) {|*x| puts x; [:b, *x] }
-#   # => [], [:b], [1], [:b, 1], [1, 2], [:b, 1, 2], 3
-
 class Enumerator
   include Enumerable
 
   ##
-  # call-seq:
-  #   Enumerator.new(size = nil) { |yielder| ... }
-  #   Enumerator.new(obj, method = :each, *args)
+  # @overload initialize(size = nil, &block)
+  # @overload initialize(obj, method = :each, *args)
   #
   # Creates a new Enumerator object, which can be used as an
   # Enumerable.
@@ -100,15 +99,15 @@ class Enumerator
   # which a "yielder" object, given as block parameter, can be used to
   # yield a value by calling the +yield+ method (aliased as +<<+):
   #
-  #   fib = Enumerator.new do |y|
-  #     a = b = 1
-  #     loop do
-  #       y << a
-  #       a, b = b, a + b
+  #     fib = Enumerator.new do |y|
+  #       a = b = 1
+  #       loop do
+  #         y << a
+  #         a, b = b, a + b
+  #       end
   #     end
-  #   end
   #
-  #   p fib.take(10) # => [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
+  #     p fib.take(10) # => [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
   #
   def initialize(obj=nil, meth=:each, *args, &block)
     if block_given?
@@ -188,8 +187,7 @@ class Enumerator
   #
   # If no block is given, returns a new Enumerator.
   #
-  # === Example
-  #
+  # @example
   #   to_three = Enumerator.new do |y|
   #     3.times do |x|
   #       y << x
@@ -582,27 +580,27 @@ module Kernel
   #
   # Here is such an example, with parameter passing and a sizing block:
   #
-  #   module Enumerable
-  #     # a generic method to repeat the values of any enumerable
-  #     def repeat(n)
-  #       raise ArgumentError, "#{n} is negative!" if n < 0
-  #       unless block_given?
-  #         return to_enum(__method__, n) do # __method__ is :repeat here
-  #           sz = size     # Call size and multiply by n...
-  #           sz * n if sz  # but return nil if size itself is nil
+  #     module Enumerable
+  #       # a generic method to repeat the values of any enumerable
+  #       def repeat(n)
+  #         raise ArgumentError, "#{n} is negative!" if n < 0
+  #         unless block_given?
+  #           return to_enum(__method__, n) do # __method__ is :repeat here
+  #             sz = size     # Call size and multiply by n...
+  #             sz * n if sz  # but return nil if size itself is nil
+  #           end
+  #         end
+  #         each do |*val|
+  #           n.times { yield *val }
   #         end
-  #       end
-  #       each do |*val|
-  #         n.times { yield *val }
   #       end
   #     end
-  #   end
   #
-  #   %i[hello world].repeat(2) { |w| puts w }
-  #     # => Prints 'hello', 'hello', 'world', 'world'
-  #   enum = (1..14).repeat(3)
-  #     # => returns an Enumerator when called without a block
-  #   enum.first(4) # => [1, 1, 1, 2]
+  #     %i[hello world].repeat(2) { |w| puts w }
+  #       # => Prints 'hello', 'hello', 'world', 'world'
+  #     enum = (1..14).repeat(3)
+  #       # => returns an Enumerator when called without a block
+  #     enum.first(4) # => [1, 1, 1, 2]
   #
   def to_enum(meth=:each, *args)
     Enumerator.new self, meth, *args