Remove obvious warnings from docs

9 files changed, 84 insertions, 86 deletions

diff --git a/mrbgems/mruby-array-ext/src/array.c b/mrbgems/mruby-array-ext/src/array.c
index 79dadbee5..37d8739b6 100644
--- a/mrbgems/mruby-array-ext/src/array.c
+++ b/mrbgems/mruby-array-ext/src/array.c
@@ -119,8 +119,8 @@ 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}
  *
  * @mrbgem mruby-array-ext
  */
diff --git a/mrbgems/mruby-enum-ext/mrblib/enum.rb b/mrbgems/mruby-enum-ext/mrblib/enum.rb
index 7efec89c9..b41eaaf1f 100644
--- a/mrbgems/mruby-enum-ext/mrblib/enum.rb
+++ b/mrbgems/mruby-enum-ext/mrblib/enum.rb
@@ -78,10 +78,10 @@ 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]
   #
   # @mrbgem mruby-enum-ext
   def take_while(&block)
@@ -96,13 +96,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]
@@ -130,12 +129,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]
@@ -170,7 +168,7 @@ 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]}
   #
   # @mrbgem mruby-enum-ext
   def group_by(&block)
diff --git a/mrbgems/mruby-enumerator/mrblib/enumerator.rb b/mrbgems/mruby-enumerator/mrblib/enumerator.rb
index d09ffaff8..e9300462a 100644
--- a/mrbgems/mruby-enumerator/mrblib/enumerator.rb
+++ b/mrbgems/mruby-enumerator/mrblib/enumerator.rb
@@ -581,27 +581,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 28ffd8146..415d8ea8f 100644
--- a/mrbgems/mruby-hash-ext/mrblib/hash.rb
+++ b/mrbgems/mruby-hash-ext/mrblib/hash.rb
@@ -7,22 +7,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}
   #
   # @mrbgem mruby-hash-ext
   def self.[](*object)
diff --git a/mrbgems/mruby-kernel-ext/src/kernel.c b/mrbgems/mruby-kernel-ext/src/kernel.c
index a0f78e471..a00fa9d6f 100644
--- a/mrbgems/mruby-kernel-ext/src/kernel.c
+++ b/mrbgems/mruby-kernel-ext/src/kernel.c
@@ -146,10 +146,10 @@ 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
  *
  * @mrbgem mruby-kernel-ext
  */
diff --git a/mrbgems/mruby-math/src/math.c b/mrbgems/mruby-math/src/math.c
index 8cbc2544e..a94c48c7b 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)
diff --git a/mrblib/enum.rb b/mrblib/enum.rb
index f0c9a4884..650d24302 100644
--- a/mrblib/enum.rb
+++ b/mrblib/enum.rb
@@ -1,17 +1,16 @@
 ##
 # Enumerable
 #
-#  ISO 15.3.2
+# The <code>Enumerable</code> mixin provides collection classes with
+# several traversal and searching methods, and with the ability to
+# sort. The class must provide a method `each`, which
+# yields successive members of the collection. If
+# {Enumerable#max}, {#min}, or
+# {#sort} is used, the objects in the collection must also
+# implement a meaningful `<=>` operator, as these methods
+# rely on an ordering between members of the collection.
 #
-#  The <code>Enumerable</code> mixin provides collection classes with
-#  several traversal and searching methods, and with the ability to
-#  sort. The class must provide a method <code>each</code>, which
-#  yields successive members of the collection. If
-#  <code>Enumerable#max</code>, <code>#min</code>, or
-#  <code>#sort</code> is used, the objects in the collection must also
-#  implement a meaningful <code><=></code> operator, as these methods
-#  rely on an ordering between members of the collection.
-
+# @ISO 15.3.2
 module Enumerable
 
   ##
diff --git a/mrblib/hash.rb b/mrblib/hash.rb
index 48ac96e56..e3e709070 100644
--- a/mrblib/hash.rb
+++ b/mrblib/hash.rb
@@ -74,8 +74,8 @@ class Hash
   #
   # If no block is given, an enumerator is returned instead.
   #
-  #  h = { "a" => 100, "b" => 200 }
-  #  h.each {|key, value| puts "#{key} is #{value}" }
+  #     h = { "a" => 100, "b" => 200 }
+  #     h.each {|key, value| puts "#{key} is #{value}" }
   #
   # <em>produces:</em>
   #
diff --git a/src/hash.c b/src/hash.c
index 44b878890..22937dff2 100644
--- a/src/hash.c
+++ b/src/hash.c
@@ -294,22 +294,22 @@ mrb_hash_modify(mrb_state *mrb, mrb_value hash)
  *  default value. It is the block's responsibility to store the value
  *  in the hash if required.
  *
- *     h = Hash.new("Go Fish")
- *     h["a"] = 100
- *     h["b"] = 200
- *     h["a"]           #=> 100
- *     h["c"]           #=> "Go Fish"
- *     # The following alters the single default object
- *     h["c"].upcase!   #=> "GO FISH"
- *     h["d"]           #=> "GO FISH"
- *     h.keys           #=> ["a", "b"]
- *
- *     # While this creates a new default object each time
- *     h = Hash.new { |hash, key| hash[key] = "Go Fish: #{key}" }
- *     h["c"]           #=> "Go Fish: c"
- *     h["c"].upcase!   #=> "GO FISH: C"
- *     h["d"]           #=> "Go Fish: d"
- *     h.keys           #=> ["c", "d"]
+ *      h = Hash.new("Go Fish")
+ *      h["a"] = 100
+ *      h["b"] = 200
+ *      h["a"]           #=> 100
+ *      h["c"]           #=> "Go Fish"
+ *      # The following alters the single default object
+ *      h["c"].upcase!   #=> "GO FISH"
+ *      h["d"]           #=> "GO FISH"
+ *      h.keys           #=> ["a", "b"]
+ *
+ *      # While this creates a new default object each time
+ *      h = Hash.new { |hash, key| hash[key] = "Go Fish: #{key}" }
+ *      h["c"]           #=> "Go Fish: c"
+ *      h["c"].upcase!   #=> "GO FISH: C"
+ *      h["d"]           #=> "Go Fish: d"
+ *      h.keys           #=> ["c", "d"]
  *
  */
 
@@ -517,10 +517,10 @@ mrb_hash_delete_key(mrb_state *mrb, mrb_value hash, mrb_value key)
  *  key is not found, pass in the key and return the result of
  *  <i>block</i>.
  *
- *     h = { "a" => 100, "b" => 200 }
- *     h.delete("a")                              #=> 100
- *     h.delete("z")                              #=> nil
- *     h.delete("z") { |el| "#{el} not found" }   #=> "z not found"
+ *      h = { "a" => 100, "b" => 200 }
+ *      h.delete("a")                              #=> 100
+ *      h.delete("z")                              #=> nil
+ *      h.delete("z") { |el| "#{el} not found" }   #=> "z not found"
  *
  */
 static mrb_value
@@ -541,9 +541,9 @@ mrb_hash_delete(mrb_state *mrb, mrb_value self)
  *  two-item array <code>[</code> <i>key, value</i> <code>]</code>, or
  *  the hash's default value if the hash is empty.
  *
- *     h = { 1 => "a", 2 => "b", 3 => "c" }
- *     h.shift   #=> [1, "a"]
- *     h         #=> {2=>"b", 3=>"c"}
+ *      h = { 1 => "a", 2 => "b", 3 => "c" }
+ *      h.shift   #=> [1, "a"]
+ *      h         #=> {2=>"b", 3=>"c"}
  */
 
 static mrb_value
@@ -580,10 +580,10 @@ mrb_hash_shift(mrb_state *mrb, mrb_value hash)
  *  call-seq:
  *     hsh.clear -> hsh
  *
- *  Removes all key-value pairs from <i>hsh</i>.
+ *  Removes all key-value pairs from `hsh`.
  *
- *     h = { "a" => 100, "b" => 200 }   #=> {"a"=>100, "b"=>200}
- *     h.clear                          #=> {}
+ *      h = { "a" => 100, "b" => 200 }   #=> {"a"=>100, "b"=>200}
+ *      h.clear                          #=> {}
  *
  */
 
@@ -609,10 +609,10 @@ mrb_hash_clear(mrb_state *mrb, mrb_value hash)
  *  use as a key (a <code>String</code> passed as a key will be
  *  duplicated and frozen).
  *
- *     h = { "a" => 100, "b" => 200 }
- *     h["a"] = 9
- *     h["c"] = 4
- *     h   #=> {"a"=>9, "b"=>200, "c"=>4}
+ *      h = { "a" => 100, "b" => 200 }
+ *      h["a"] = 9
+ *      h["c"] = 4
+ *      h   #=> {"a"=>9, "b"=>200, "c"=>4}
  *
  */
 static mrb_value