Merge pull request #2999 from sagmor/better-docs

More Docs

20 files changed, 275 insertions, 211 deletions

diff --git a/.yardopts b/.yardopts
index 017b7ce70..27f6d59a1 100644
--- a/.yardopts
+++ b/.yardopts
@@ -1,6 +1,15 @@
+--markup markdown
 --plugin mruby
 --plugin coderay
 --output-dir doc/api
+
+src/**/*.c
+mrblib/**/*.rb
+include/**/*.h
+
+mrbgems/*/src/**/*.c
+mrbgems/*/mrblib/**/*.rb
+mrbgems/*/include/**/*.h
 -
 AUTHORS
 MITL
diff --git a/include/mruby.h b/include/mruby.h
index b0161aff7..2338f66ac 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -574,42 +574,45 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o
 #define MRB_ARGS_NONE()     ((mrb_aspec)0)
 
 /**
- * Format specifiers for \ref mrb_get_args function
- *
- * Must be a list of following format specifiers:
- *
- * | char | mruby type     | retrieve types      |note                                                |
- * |:----:|----------------|---------------------|----------------------------------------------------|
- * | o    | Object         | mrb_value           | Could be used to retrieve any type of argument     |
- * | C    | Class/Module   | mrb_value           |                                                    |
- * | S    | String         | mrb_value           | when ! follows, the value may be nil               |
- * | A    | Array          | mrb_value           | when ! follows, the value may be nil               |
- * | H    | Hash           | mrb_value           | when ! follows, the value may be nil               |
- * | s    | String         | char *, mrb_int      |  Receive two arguments; s! gives (NULL,0) for nil  |
- * | z    | String         | char *               | NUL terminated string; z! gives NULL for nil       |
- * | a    | Array          | mrb_value *, mrb_int | Receive two arguments; a! gives (NULL,0) for nil   |
- * | f    | Float          | mrb_float           |                                                    |
- * | i    | Integer        | mrb_int             |                                                    |
- * | b    | boolean        | mrb_bool            |                                                    |
- * | n    | Symbol         | mrb_sym             |                                                    |
- * | &    | block          | mrb_value           |                                                    |
- * | *    | rest arguments | mrb_value *, mrb_int | Receive the rest of arguments as an array.         |
- * | \|   | optional       |                     | After this spec following specs would be optional. |
- * | ?    | optional given | mrb_bool            | True if preceding argument is given. Used to check optional argument is given. |
+ * Format specifiers for {mrb_get_args} function
+ *
+ * Must be a C string composed of the following format specifiers:
+ *
+ * | char | Ruby type      | C types           | Notes                                               |
+ * |:----:|----------------|-------------------|----------------------------------------------------|
+ * | `o`  | {Object}       | {mrb_value}       | Could be used to retrieve any type of argument     |
+ * | `C`  | {Class}/{Module} | {mrb_value}     |                                                    |
+ * | `S`  | {String}       | {mrb_value}       | when `!` follows, the value may be `nil`           |
+ * | `A`  | {Array}        | {mrb_value}       | when `!` follows, the value may be `nil`           |
+ * | `H`  | {Hash}         | {mrb_value}       | when `!` follows, the value may be `nil`           |
+ * | `s`  | {String}       | char *, {mrb_int} |  Receive two arguments; `s!` gives (`NULL`,`0`) for `nil`       |
+ * | `z`  | {String}       | char *            | `NULL` terminated string; `z!` gives `NULL` for `nil`           |
+ * | `a`  | {Array}        | {mrb_value} *, {mrb_int} | Receive two arguments; `a!` gives (`NULL`,`0`) for `nil` |
+ * | `f`  | {Float}        | {mrb_float}       |                                                    |
+ * | `i`  | {Integer}      | {mrb_int}         |                                                    |
+ * | `b`  | boolean        | {mrb_bool}        |                                                    |
+ * | `n`  | {Symbol}       | {mrb_sym}         |                                                    |
+ * | `&`  | block          | {mrb_value}       |                                                    |
+ * | `*`  | rest arguments | {mrb_value} *, {mrb_int} | Receive the rest of arguments as an array.  |
+ * | | | optional     |                   | After this spec following specs would be optional. |
+ * | `?`  | optional given | {mrb_bool}        | `TRUE` if preceding argument is given. Used to check optional argument is given. |
+ *
+ * @see mrb_get_args
  */
 typedef const char *mrb_args_format;
 
 /**
  * Retrieve arguments from mrb_state.
  *
- * When applicable, implicit conversions (such as to_str, to_ary, to_hash) are
+ * When applicable, implicit conversions (such as `to_str`, `to_ary`, `to_hash`) are
  * applied to received arguments.
- * Use it inside a function pointed by mrb_func_t.
+ * Used inside a function of mrb_func_t type.
  *
  * @param mrb The current MRuby state.
- * @param format is a list of format specifiers see @ref mrb_args_format
+ * @param format [mrb_args_format] is a list of format specifiers
  * @param ... The passing variadic arguments must be a pointer of retrieving type.
  * @return the number of arguments retrieved.
+ * @see mrb_args_format
  */
 MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...);
 
@@ -726,7 +729,7 @@ MRB_API void mrb_close(mrb_state *mrb);
 /**
  * The default allocation function.
  *
- * @ref mrb_allocf
+ * @see mrb_allocf
  */
 MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*);
 
@@ -854,9 +857,26 @@ MRB_API mrb_value mrb_attr_get(mrb_state *mrb, mrb_value obj, mrb_sym id);
 MRB_API mrb_bool mrb_respond_to(mrb_state *mrb, mrb_value obj, mrb_sym mid);
 MRB_API mrb_bool mrb_obj_is_instance_of(mrb_state *mrb, mrb_value obj, struct RClass* c);
 
-/* fiber functions (you need to link mruby-fiber mrbgem to use) */
+
+/*
+ * Resume a Fiber
+ *
+ * @mrbgem mruby-fiber
+ */
 MRB_API mrb_value mrb_fiber_resume(mrb_state *mrb, mrb_value fib, mrb_int argc, const mrb_value *argv);
+
+/*
+ * Yield a Fiber
+ *
+ * @mrbgem mruby-fiber
+ */
 MRB_API mrb_value mrb_fiber_yield(mrb_state *mrb, mrb_int argc, const mrb_value *argv);
+
+/*
+ * FiberError reference
+ *
+ * @mrbgem mruby-fiber
+ */
 #define E_FIBER_ERROR (mrb_class_get(mrb, "FiberError"))
 
 /* memory pool implementation */
diff --git a/include/mruby/error.h b/include/mruby/error.h
index 8b6430137..1ac0791a2 100644
--- a/include/mruby/error.h
+++ b/include/mruby/error.h
@@ -32,12 +32,34 @@ MRB_API mrb_noreturn void mrb_no_method_error(mrb_state *mrb, mrb_sym id, mrb_va
 /* declaration for fail method */
 MRB_API mrb_value mrb_f_raise(mrb_state*, mrb_value);
 
-/* functions defined in mruby-error mrbgem */
+/**
+ * Protect
+ *
+ * @mrbgem mruby-error
+ */
 MRB_API mrb_value mrb_protect(mrb_state *mrb, mrb_func_t body, mrb_value data, mrb_bool *state);
+
+/**
+ * Ensure
+ *
+ * @mrbgem mruby-error
+ */
 MRB_API mrb_value mrb_ensure(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
                              mrb_func_t ensure, mrb_value e_data);
+
+/**
+ * Rescue
+ *
+ * @mrbgem mruby-error
+ */
 MRB_API mrb_value mrb_rescue(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
                              mrb_func_t rescue, mrb_value r_data);
+
+/**
+ * Rescue exception
+ *
+ * @mrbgem mruby-error
+ */
 MRB_API mrb_value mrb_rescue_exceptions(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
                                         mrb_func_t rescue, mrb_value r_data,
                                         mrb_int len, struct RClass **classes);
diff --git a/include/mruby/value.h b/include/mruby/value.h
index dfad3ec73..002ea8511 100644
--- a/include/mruby/value.h
+++ b/include/mruby/value.h
@@ -98,6 +98,22 @@ enum mrb_vtype {
 
 #include "mruby/object.h"
 
+#ifdef MRB_DOCUMENTATION_BLOCK
+
+/**
+ * @abstract
+ * MRuby value boxing.
+ *
+ * Actual implementation depends on configured boxing type.
+ *
+ * @see mruby/boxing_no.h Default boxing representation
+ * @see mruby/boxing_word.h Word representation
+ * @see mruby/boxing_nan.h Boxed double representation
+ */
+typedef void mrb_value;
+
+#endif
+
 #if defined(MRB_NAN_BOXING)
 #include "boxing_nan.h"
 #elif defined(MRB_WORD_BOXING)
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)
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/array.c b/src/array.c
index aa914952a..2ef9c2a47 100644
--- a/src/array.c
+++ b/src/array.c
@@ -1068,7 +1068,7 @@ mrb_init_array(mrb_state *mrb)
 {
   struct RClass *a;
 
-  a = mrb->array_class = mrb_define_class(mrb, "Array", mrb->object_class);            /* 15.2.12 */
+  mrb->array_class = a = mrb_define_class(mrb, "Array", mrb->object_class);            /* 15.2.12 */
   MRB_SET_INSTANCE_TT(a, MRB_TT_ARRAY);
 
   mrb_define_class_method(mrb, a, "[]",        mrb_ary_s_create,     MRB_ARGS_ANY());  /* 15.2.12.4.1 */
diff --git a/src/hash.c b/src/hash.c
index ffb8bd931..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
@@ -827,7 +827,7 @@ mrb_init_hash(mrb_state *mrb)
 {
   struct RClass *h;
 
-  h = mrb->hash_class = mrb_define_class(mrb, "Hash", mrb->object_class);              /* 15.2.13 */
+  mrb->hash_class = h = mrb_define_class(mrb, "Hash", mrb->object_class);              /* 15.2.13 */
   MRB_SET_INSTANCE_TT(h, MRB_TT_HASH);
 
   mrb_define_method(mrb, h, "[]",              mrb_hash_aget,        MRB_ARGS_REQ(1)); /* 15.2.13.4.2  */
diff --git a/src/kernel.c b/src/kernel.c
index 759dc42b7..a6c967b27 100644
--- a/src/kernel.c
+++ b/src/kernel.c
@@ -1097,7 +1097,7 @@ mrb_init_kernel(mrb_state *mrb)
 {
   struct RClass *krn;
 
-  krn = mrb->kernel_module = mrb_define_module(mrb, "Kernel");                                                    /* 15.3.1 */
+  mrb->kernel_module = krn = mrb_define_module(mrb, "Kernel");                                                    /* 15.3.1 */
   mrb_define_class_method(mrb, krn, "block_given?",         mrb_f_block_given_p_m,           MRB_ARGS_NONE());    /* 15.3.1.2.2  */
   mrb_define_class_method(mrb, krn, "global_variables",     mrb_f_global_variables,          MRB_ARGS_NONE());    /* 15.3.1.2.4  */
   mrb_define_class_method(mrb, krn, "iterator?",            mrb_f_block_given_p_m,           MRB_ARGS_NONE());    /* 15.3.1.2.5  */
diff --git a/src/numeric.c b/src/numeric.c
index 1a3c903f0..5d595f6a9 100644
--- a/src/numeric.c
+++ b/src/numeric.c
@@ -1161,7 +1161,7 @@ mrb_init_numeric(mrb_state *mrb)
   mrb_define_method(mrb, integer, "to_int", int_to_i, MRB_ARGS_NONE());
 
   /* Fixnum Class */
-  fixnum = mrb->fixnum_class = mrb_define_class(mrb, "Fixnum", integer);
+  mrb->fixnum_class = fixnum = mrb_define_class(mrb, "Fixnum", integer);
   mrb_define_method(mrb, fixnum,  "+",        fix_plus,          MRB_ARGS_REQ(1)); /* 15.2.8.3.1  */
   mrb_define_method(mrb, fixnum,  "-",        fix_minus,         MRB_ARGS_REQ(1)); /* 15.2.8.3.2  */
   mrb_define_method(mrb, fixnum,  "*",        fix_mul,           MRB_ARGS_REQ(1)); /* 15.2.8.3.3  */
@@ -1181,7 +1181,7 @@ mrb_init_numeric(mrb_state *mrb)
   mrb_define_method(mrb, fixnum,  "divmod",   fix_divmod,        MRB_ARGS_REQ(1)); /* 15.2.8.3.30 (x) */
 
   /* Float Class */
-  fl = mrb->float_class = mrb_define_class(mrb, "Float", numeric);                 /* 15.2.9 */
+  mrb->float_class = fl = mrb_define_class(mrb, "Float", numeric);                 /* 15.2.9 */
   mrb_undef_class_method(mrb,  fl, "new");
   mrb_define_method(mrb, fl,      "+",         flo_plus,         MRB_ARGS_REQ(1)); /* 15.2.9.3.1  */
   mrb_define_method(mrb, fl,      "-",         flo_minus,        MRB_ARGS_REQ(1)); /* 15.2.9.3.2  */
diff --git a/src/object.c b/src/object.c
index 2e0bd245f..da60ebbcd 100644
--- a/src/object.c
+++ b/src/object.c
@@ -264,7 +264,7 @@ mrb_init_object(mrb_state *mrb)
   struct RClass *t;
   struct RClass *f;
 
-  n = mrb->nil_class   = mrb_define_class(mrb, "NilClass",   mrb->object_class);
+  mrb->nil_class   = n = mrb_define_class(mrb, "NilClass",   mrb->object_class);
   mrb_undef_class_method(mrb, n, "new");
   mrb_define_method(mrb, n, "&",    false_and,      MRB_ARGS_REQ(1));  /* 15.2.4.3.1  */
   mrb_define_method(mrb, n, "^",    false_xor,      MRB_ARGS_REQ(1));  /* 15.2.4.3.2  */
@@ -273,7 +273,7 @@ mrb_init_object(mrb_state *mrb)
   mrb_define_method(mrb, n, "to_s", nil_to_s,       MRB_ARGS_NONE());  /* 15.2.4.3.5  */
   mrb_define_method(mrb, n, "inspect", nil_inspect, MRB_ARGS_NONE());
 
-  t = mrb->true_class  = mrb_define_class(mrb, "TrueClass",  mrb->object_class);
+  mrb->true_class  = t = mrb_define_class(mrb, "TrueClass",  mrb->object_class);
   mrb_undef_class_method(mrb, t, "new");
   mrb_define_method(mrb, t, "&",    true_and,       MRB_ARGS_REQ(1));  /* 15.2.5.3.1  */
   mrb_define_method(mrb, t, "^",    true_xor,       MRB_ARGS_REQ(1));  /* 15.2.5.3.2  */
@@ -281,7 +281,7 @@ mrb_init_object(mrb_state *mrb)
   mrb_define_method(mrb, t, "|",    true_or,        MRB_ARGS_REQ(1));  /* 15.2.5.3.4  */
   mrb_define_method(mrb, t, "inspect", true_to_s,   MRB_ARGS_NONE());
 
-  f = mrb->false_class = mrb_define_class(mrb, "FalseClass", mrb->object_class);
+  mrb->false_class = f = mrb_define_class(mrb, "FalseClass", mrb->object_class);
   mrb_undef_class_method(mrb, f, "new");
   mrb_define_method(mrb, f, "&",    false_and,      MRB_ARGS_REQ(1));  /* 15.2.6.3.1  */
   mrb_define_method(mrb, f, "^",    false_xor,      MRB_ARGS_REQ(1));  /* 15.2.6.3.2  */
diff --git a/src/string.c b/src/string.c
index b597c3da9..ef84459ed 100644
--- a/src/string.c
+++ b/src/string.c
@@ -2674,7 +2674,7 @@ mrb_init_string(mrb_state *mrb)
 
   mrb_static_assert(RSTRING_EMBED_LEN_MAX < (1 << 5), "pointer size too big for embedded string");
 
-  s = mrb->string_class = mrb_define_class(mrb, "String", mrb->object_class);             /* 15.2.10 */
+  mrb->string_class = s = mrb_define_class(mrb, "String", mrb->object_class);             /* 15.2.10 */
   MRB_SET_INSTANCE_TT(s, MRB_TT_STRING);
 
   mrb_define_method(mrb, s, "bytesize",        mrb_str_bytesize,        MRB_ARGS_NONE());
diff --git a/src/symbol.c b/src/symbol.c
index f1c0bf80a..e380a5b5e 100644
--- a/src/symbol.c
+++ b/src/symbol.c
@@ -478,7 +478,7 @@ mrb_init_symbol(mrb_state *mrb)
 {
   struct RClass *sym;
 
-  sym = mrb->symbol_class = mrb_define_class(mrb, "Symbol", mrb->object_class);                 /* 15.2.11 */
+  mrb->symbol_class = sym = mrb_define_class(mrb, "Symbol", mrb->object_class);                 /* 15.2.11 */
 
   mrb_define_method(mrb, sym, "===",             sym_equal,      MRB_ARGS_REQ(1));              /* 15.2.11.3.1  */
   mrb_define_method(mrb, sym, "id2name",         mrb_sym_to_s,   MRB_ARGS_NONE());              /* 15.2.11.3.2  */