Merge pull request #2999 from sagmor/better-docs

More Docs

7 files changed, 129 insertions, 131 deletions

diff --git a/mrbgems/mruby-array-ext/src/array.c b/mrbgems/mruby-array-ext/src/array.c
index d69f0ac44..177dd7123 100644
--- a/mrbgems/mruby-array-ext/src/array.c
+++ b/mrbgems/mruby-array-ext/src/array.c
@@ -113,8 +113,9 @@ mrb_ary_values_at(mrb_state *mrb, mrb_value self)
  *  Returns the result of interpreting <i>aray</i> as an array of
  *  <tt>[key, value]</tt> paris.
  *
- *     [[:foo, :bar], [1, 2]].to_h
- *       # => {:foo => :bar, 1 => 2}
+ *      [[:foo, :bar], [1, 2]].to_h
+ *        # => {:foo => :bar, 1 => 2}
+ *
  */
 
 static mrb_value
diff --git a/mrbgems/mruby-enum-ext/mrblib/enum.rb b/mrbgems/mruby-enum-ext/mrblib/enum.rb
index d469f0651..ed1943f30 100644
--- a/mrbgems/mruby-enum-ext/mrblib/enum.rb
+++ b/mrbgems/mruby-enum-ext/mrblib/enum.rb
@@ -77,11 +77,11 @@ module Enumerable
   # Passes elements to the block until the block returns +nil+ or +false+,
   # then stops iterating and returns an array of all prior elements.
   #
-  #  If no block is given, an enumerator is returned instead.
+  # If no block is given, an enumerator is returned instead.
+  #
+  #     a = [1, 2, 3, 4, 5, 0]
+  #     a.take_while {|i| i < 3 }   #=> [1, 2]
   #
-  #    a = [1, 2, 3, 4, 5, 0]
-  #    a.take_while {|i| i < 3 }   #=> [1, 2]
-
   def take_while(&block)
     return to_enum :take_while unless block
 
@@ -94,13 +94,12 @@ module Enumerable
   end
 
   ##
-  # call-seq:
-  #   enum.each_cons(n) {...}   ->  nil
-  #
   # Iterates the given block for each array of consecutive <n>
   # elements.
   #
-  # e.g.:
+  # @return [nil]
+  #
+  # @example
   #     (1..10).each_cons(3) {|a| p a}
   #     # outputs below
   #     [1, 2, 3]
@@ -127,12 +126,11 @@ module Enumerable
   end
 
   ##
-  # call-seq:
-  #   enum.each_slice(n) {...}  ->  nil
-  #
   # Iterates the given block for each slice of <n> elements.
   #
-  # e.g.:
+  # @return [nil]
+  #
+  # @example
   #     (1..10).each_slice(3) {|a| p a}
   #     # outputs below
   #     [1, 2, 3]
@@ -166,8 +164,8 @@ module Enumerable
   # block, and values are arrays of elements in <i>enum</i>
   # corresponding to the key.
   #
-  #    (1..6).group_by {|i| i%3}   #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
-
+  #     (1..6).group_by {|i| i%3}   #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
+  #
   def group_by(&block)
     return to_enum :group_by unless block
 
diff --git a/mrbgems/mruby-enum-lazy/mrblib/lazy.rb b/mrbgems/mruby-enum-lazy/mrblib/lazy.rb
index 2ffeb1808..8ce363c6d 100644
--- a/mrbgems/mruby-enum-lazy/mrblib/lazy.rb
+++ b/mrbgems/mruby-enum-lazy/mrblib/lazy.rb
@@ -1,30 +1,29 @@
-# = Enumerable#lazy implementation
-#
-# Enumerable#lazy returns an instance of Enumerable::Lazy.
-# You can use it just like as normal Enumerable object,
-# except these methods act as 'lazy':
-#
-#   - map       collect
-#   - select    find_all
-#   - reject
-#   - grep
-#   - drop
-#   - drop_while
-#   - take_while
-#   - flat_map  collect_concat
-#   - zip
-#
-# == Acknowledgements
-#
-#   Based on https://github.com/yhara/enumerable-lazy
-#   Inspired by https://github.com/antimon2/enumerable_lz
-#   http://jp.rubyist.net/magazine/?0034-Enumerable_lz (ja)
-
 module Enumerable
+
+  # = Enumerable#lazy implementation
+  #
+  # Enumerable#lazy returns an instance of Enumerable::Lazy.
+  # You can use it just like as normal Enumerable object,
+  # except these methods act as 'lazy':
+  #
+  #   - map       collect
+  #   - select    find_all
+  #   - reject
+  #   - grep
+  #   - drop
+  #   - drop_while
+  #   - take_while
+  #   - flat_map  collect_concat
+  #   - zip
   def lazy
     Lazy.new(self)
   end
 
+  # == Acknowledgements
+  #
+  #   Based on https://github.com/yhara/enumerable-lazy
+  #   Inspired by https://github.com/antimon2/enumerable_lz
+  #   http://jp.rubyist.net/magazine/?0034-Enumerable_lz (ja)
   class Lazy < Enumerator
     def initialize(obj, &block)
       super(){|yielder|
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
diff --git a/mrbgems/mruby-hash-ext/mrblib/hash.rb b/mrbgems/mruby-hash-ext/mrblib/hash.rb
index ec8bd05fb..d243aec24 100644
--- a/mrbgems/mruby-hash-ext/mrblib/hash.rb
+++ b/mrbgems/mruby-hash-ext/mrblib/hash.rb
@@ -5,22 +5,22 @@ class Hash
 
   ##
   # call-seq:
-  # Hash[ key, value, ... ] -> new_hash
-  # Hash[ [ [key, value], ... ] ] -> new_hash
-  # Hash[ object ] -> new_hash
+  #     Hash[ key, value, ... ] -> new_hash
+  #     Hash[ [ [key, value], ... ] ] -> new_hash
+  #     Hash[ object ] -> new_hash
   #
   # Creates a new hash populated with the given objects.
   #
-  # Similar to the literal <code>{ _key_ => _value_, ... }</code>. In the first
+  # Similar to the literal `{ _key_ => _value_, ... }`. In the first
   # form, keys and values occur in pairs, so there must be an even number of
   # arguments.
   #
   # The second and third form take a single argument which is either an array
   # of key-value pairs or an object convertible to a hash.
   #
-  # Hash["a", 100, "b", 200] #=> {"a"=>100, "b"=>200}
-  # Hash[ [ ["a", 100], ["b", 200] ] ] #=> {"a"=>100, "b"=>200}
-  # Hash["a" => 100, "b" => 200] #=> {"a"=>100, "b"=>200}
+  #     Hash["a", 100, "b", 200] #=> {"a"=>100, "b"=>200}
+  #     Hash[ [ ["a", 100], ["b", 200] ] ] #=> {"a"=>100, "b"=>200}
+  #     Hash["a" => 100, "b" => 200] #=> {"a"=>100, "b"=>200}
   #
 
   def self.[](*object)
diff --git a/mrbgems/mruby-kernel-ext/src/kernel.c b/mrbgems/mruby-kernel-ext/src/kernel.c
index baccbd303..c578b6793 100644
--- a/mrbgems/mruby-kernel-ext/src/kernel.c
+++ b/mrbgems/mruby-kernel-ext/src/kernel.c
@@ -138,10 +138,11 @@ mrb_f_array(mrb_state *mrb, mrb_value self)
  *  <i>arg</i><code>.to_hash</code>. Returns an empty <code>Hash</code> when
  *  <i>arg</i> is <tt>nil</tt> or <tt>[]</tt>.
  *
- *     Hash([])          #=> {}
- *     Hash(nil)         #=> {}
- *     Hash(key: :value) #=> {:key => :value}
- *     Hash([1, 2, 3])   #=> TypeError
+ *      Hash([])          #=> {}
+ *      Hash(nil)         #=> {}
+ *      Hash(key: :value) #=> {:key => :value}
+ *      Hash([1, 2, 3])   #=> TypeError
+ *
  */
 static mrb_value
 mrb_f_hash(mrb_state *mrb, mrb_value self)
diff --git a/mrbgems/mruby-math/src/math.c b/mrbgems/mruby-math/src/math.c
index 109112578..79ad18b90 100644
--- a/mrbgems/mruby-math/src/math.c
+++ b/mrbgems/mruby-math/src/math.c
@@ -236,7 +236,8 @@ math_tan(mrb_state *mrb, mrb_value obj)
  *  call-seq:
  *     Math.asin(x)    -> float
  *
- *  Computes the arc sine of <i>x</i>. Returns -{PI/2} .. {PI/2}.
+ *  Computes the arc sine of <i>x</i>.
+ *  @return computed value between `-(PI/2)` and `(PI/2)`.
  */
 static mrb_value
 math_asin(mrb_state *mrb, mrb_value obj)
@@ -276,7 +277,7 @@ math_acos(mrb_state *mrb, mrb_value obj)
  *  call-seq:
  *     Math.atan(x)    -> float
  *
- *  Computes the arc tangent of <i>x</i>. Returns -{PI/2} .. {PI/2}.
+ *  Computes the arc tangent of <i>x</i>. Returns `-(PI/2) .. (PI/2)`.
  */
 static mrb_value
 math_atan(mrb_state *mrb, mrb_value obj)