numeric.c: revise docs

* numeric.c: [DOC] revise docs for Numeric, Integer, Float:
  * nodoc Numeric#singleton_method_added
  * mention that result for Integer#** might also be Complex
  * add / simplify / fix some examples
  * mention aliases
  * fix rdoc formatting, typos, grammar
  * clarifications and other improvements

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58580 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 257 insertions, 291 deletions

diff --git a/numeric.c b/numeric.c
index 713a3e482e..77f956a9ea 100644
--- a/numeric.c
+++ b/numeric.c
@@ -409,9 +409,9 @@ num_funcall1(VALUE x, ID func, VALUE y)
  *  call-seq:
  *     num.coerce(numeric)  ->  array
  *
- *  If a +numeric+ is the same type as +num+, returns an array containing
- *  +numeric+ and +num+. Otherwise, returns an array with both a +numeric+ and
- *  +num+ represented as Float objects.
+ *  If +numeric+ is the same type as +num+, returns an array
+ *  <code>[numeric, num]</code>. Otherwise, returns an array with both
+ *  +numeric+ and +num+ represented as Float objects.
  *
  *  This coercion mechanism is used by Ruby to handle mixed-type numeric
  *  operations: it is intended to find a compatible common type between the two
@@ -497,6 +497,8 @@ rb_num_coerce_relop(VALUE x, VALUE y, ID func)
 }
 
 /*
+ * :nodoc:
+ *
  * Trap attempts to add methods to Numeric objects. Always raises a TypeError.
  *
  * Numerics should be values; singleton_methods should not be added to them.
@@ -519,10 +521,9 @@ num_sadded(VALUE x, VALUE name)
 #if 0
 /*
  *  call-seq:
- *     num.clone(freeze: true) -> num
+ *     num.clone(freeze: true)  ->  num
  *
- *  Returns the receiver.
- *  _freeze_ cannot be +false+.
+ *  Returns the receiver.  +freeze+ cannot be +false+.
  */
 static VALUE
 num_clone(int argc, VALUE *argv, VALUE x)
@@ -536,7 +537,7 @@ num_clone(int argc, VALUE *argv, VALUE x)
 #if 0
 /*
  *  call-seq:
- *     num.dup -> num
+ *     num.dup  ->  num
  *
  *  Returns the receiver.
  */
@@ -553,7 +554,7 @@ num_dup(VALUE x)
  *  call-seq:
  *     +num  ->  num
  *
- *  Unary Plus---Returns the receiver's value.
+ *  Unary Plus---Returns the receiver.
  */
 
 static VALUE
@@ -564,10 +565,13 @@ num_uplus(VALUE num)
 
 /*
  *  call-seq:
- *     num.i  ->  Complex(0,num)
+ *     num.i  ->  Complex(0, num)
  *
  *  Returns the corresponding imaginary number.
  *  Not available for complex numbers.
+ *
+ *     -42.i  #=> (0-42i)
+ *     2.0.i  #=> (0+2.0i)
  */
 
 static VALUE
@@ -576,12 +580,11 @@ num_imaginary(VALUE num)
     return rb_complex_new(INT2FIX(0), num);
 }
 
-
 /*
  *  call-seq:
  *     -num  ->  numeric
  *
- *  Unary Minus---Returns the receiver's value, negated.
+ *  Unary Minus---Returns the receiver, negated.
  */
 
 static VALUE
@@ -608,13 +611,12 @@ num_fdiv(VALUE x, VALUE y)
     return rb_funcall(rb_Float(x), '/', 1, y);
 }
 
-
 /*
  *  call-seq:
  *     num.div(numeric)  ->  integer
  *
  *  Uses +/+ to perform division, then converts the result to an integer.
- *  +numeric+ does not define the +/+ operator; this is left to subclasses.
+ *  Numeric does not define the +/+ operator; this is left to subclasses.
  *
  *  Equivalent to <code>num.divmod(numeric)[0]</code>.
  *
@@ -628,12 +630,11 @@ num_div(VALUE x, VALUE y)
     return rb_funcall(num_funcall1(x, '/', y), rb_intern("floor"), 0);
 }
 
-
 /*
  *  call-seq:
  *     num.modulo(numeric)  ->  real
  *
- *     x.modulo(y) means x-y*(x/y).floor
+ *  <code>x.modulo(y)</code> means <code>x-y*(x/y).floor</code>.
  *
  *  Equivalent to <code>num.divmod(numeric)[1]</code>.
  *
@@ -652,7 +653,7 @@ num_modulo(VALUE x, VALUE y)
  *  call-seq:
  *     num.remainder(numeric)  ->  real
  *
- *     x.remainder(y) means x-y*(x/y).truncate
+ *  <code>x.remainder(y)</code> means <code>x-y*(x/y).truncate</code>.
  *
  *  See Numeric#divmod.
  */
@@ -679,12 +680,13 @@ num_remainder(VALUE x, VALUE y)
  *  Returns an array containing the quotient and modulus obtained by dividing
  *  +num+ by +numeric+.
  *
- *  If <code>q, r = * x.divmod(y)</code>, then
+ *  If <code>q, r = x.divmod(y)</code>, then
  *
  *      q = floor(x/y)
- *      x = q*y+r
+ *      x = q*y + r
  *
- *  The quotient is rounded toward -infinity, as shown in the following table:
+ *  The quotient is rounded toward negative infinity, as shown in the
+ *  following table:
  *
  *     a    |  b  |  a.divmod(b)  |   a/b   | a.modulo(b) | a.remainder(b)
  *    ------+-----+---------------+---------+-------------+---------------
@@ -707,11 +709,11 @@ num_remainder(VALUE x, VALUE y)
  *
  *  Examples
  *
- *     11.divmod(3)         #=> [3, 2]
- *     11.divmod(-3)        #=> [-4, -1]
- *     11.divmod(3.5)       #=> [3, 0.5]
- *     (-11).divmod(3.5)    #=> [-4, 3.0]
- *     (11.5).divmod(3.5)   #=> [3, 1.0]
+ *     11.divmod(3)        #=> [3, 2]
+ *     11.divmod(-3)       #=> [-4, -1]
+ *     11.divmod(3.5)      #=> [3, 0.5]
+ *     (-11).divmod(3.5)   #=> [-4, 3.0]
+ *     11.5.divmod(3.5)    #=> [3, 1.0]
  */
 
 static VALUE
@@ -724,7 +726,7 @@ num_divmod(VALUE x, VALUE y)
  *  call-seq:
  *     num.real?  ->  true or false
  *
- *  Returns +true+ if +num+ is a Real number. (i.e. not Complex).
+ *  Returns +true+ if +num+ is a real number (i.e. not Complex).
  */
 
 static VALUE
@@ -739,8 +741,8 @@ num_real_p(VALUE num)
  *
  *  Returns +true+ if +num+ is an Integer.
  *
- *      (1.0).integer? #=> false
- *      (1).integer?   #=> true
+ *      1.0.integer?   #=> false
+ *      1.integer?     #=> true
  */
 
 static VALUE
@@ -760,7 +762,7 @@ num_int_p(VALUE num)
  *     (-34.56).abs   #=> 34.56
  *     -34.56.abs     #=> 34.56
  *
- *  Numeric#magnitude is an alias of Numeric#abs.
+ *  Numeric#magnitude is an alias for Numeric#abs.
  */
 
 static VALUE
@@ -772,7 +774,6 @@ num_abs(VALUE num)
     return num;
 }
 
-
 /*
  *  call-seq:
  *     num.zero?  ->  true or false
@@ -800,7 +801,6 @@ num_zero_p(VALUE num)
     return Qfalse;
 }
 
-
 /*
  *  call-seq:
  *     num.nonzero?  ->  self or nil
@@ -827,7 +827,7 @@ num_nonzero_p(VALUE num)
  *  call-seq:
  *     num.finite?  ->  true or false
  *
- *  Return true if +num+ is finite number, oterwise returns false.
+ *  Returns +true+ if +num+ is a finite number, otherwise returns +false+.
  */
 static VALUE
 num_finite_p(VALUE num)
@@ -837,13 +837,10 @@ num_finite_p(VALUE num)
 
 /*
  *  call-seq:
- *     num.infinite?  ->  nil or 1 or -1
- *
- *  Returns values corresponding to the value of +num+'s magnitude:
+ *     num.infinite?  ->  -1, 1, or nil
  *
- *  +finite+::    +nil+
- *  +-Infinity+:: +-1+
- *  ++Infinity+:: ++1+
+ *  Returns +nil+, -1, or 1 depending on whether the value is
+ *  finite, <code>-Infinity</code>, or <code>+Infinity</code>.
  */
 static VALUE
 num_infinite_p(VALUE num)
@@ -857,9 +854,9 @@ num_infinite_p(VALUE num)
  *
  *  Invokes the child class's +to_i+ method to convert +num+ to an integer.
  *
- *      1.0.class => Float
- *      1.0.to_int.class => Integer
- *      1.0.to_i.class => Integer
+ *      1.0.class          #=> Float
+ *      1.0.to_int.class   #=> Integer
+ *      1.0.to_i.class     #=> Integer
  */
 
 static VALUE
@@ -870,7 +867,7 @@ num_to_int(VALUE num)
 
 /*
  *  call-seq:
- *     num.positive? ->  true or false
+ *     num.positive?  ->  true or false
  *
  *  Returns +true+ if +num+ is greater than 0.
  */
@@ -893,7 +890,7 @@ num_positive_p(VALUE num)
 
 /*
  *  call-seq:
- *     num.negative? ->  true or false
+ *     num.negative?  ->  true or false
  *
  *  Returns +true+ if +num+ is less than 0.
  */
@@ -913,7 +910,7 @@ num_negative_p(VALUE num)
  *  architecture's double-precision floating point representation.
  *
  *  Floating point has a different arithmetic and is an inexact number.
- *  So you should know its esoteric system. see following:
+ *  So you should know its esoteric system. See following:
  *
  *  - http://docs.sun.com/source/806-3568/ncg_goldberg.html
  *  - http://wiki.github.com/rdp/ruby_tutorials_core/ruby-talk-faq#wiki-floats_imprecise
@@ -934,9 +931,9 @@ rb_float_new_in_heap(double d)
  *  call-seq:
  *     float.to_s  ->  string
  *
- *  Returns a string containing a representation of self. As well as a fixed or
- *  exponential form of the +float+, the call may return +NaN+, +Infinity+, and
- *  +-Infinity+.
+ *  Returns a string containing a representation of +self+.
+ *  As well as a fixed or exponential form of the +float+,
+ *  the call may return +NaN+, +Infinity+, and +-Infinity+.
  */
 
 static VALUE
@@ -1014,10 +1011,10 @@ flo_to_s(VALUE flt)
  *  call-seq:
  *     float.coerce(numeric)  ->  array
  *
- *  Returns an array with both a +numeric+ and a +float+ represented as Float
+ *  Returns an array with both +numeric+ and +float+ represented as Float
  *  objects.
  *
- *  This is achieved by converting a +numeric+ to a Float.
+ *  This is achieved by converting +numeric+ to a Float.
  *
  *     1.2.coerce(3)       #=> [3.0, 1.2]
  *     2.5.coerce(1.1)     #=> [1.1, 2.5]
@@ -1033,7 +1030,7 @@ flo_coerce(VALUE x, VALUE y)
  * call-seq:
  *    -float  ->  float
  *
- * Returns float, negated.
+ * Returns +float+, negated.
  */
 
 VALUE
@@ -1046,7 +1043,7 @@ rb_float_uminus(VALUE flt)
  * call-seq:
  *   float + other  ->  float
  *
- * Returns a new float which is the sum of +float+ and +other+.
+ * Returns a new Float which is the sum of +float+ and +other+.
  */
 
 static VALUE
@@ -1070,7 +1067,7 @@ flo_plus(VALUE x, VALUE y)
  * call-seq:
  *   float - other  ->  float
  *
- * Returns a new float which is the difference of +float+ and +other+.
+ * Returns a new Float which is the difference of +float+ and +other+.
  */
 
 static VALUE
@@ -1094,7 +1091,7 @@ flo_minus(VALUE x, VALUE y)
  * call-seq:
  *   float * other  ->  float
  *
- * Returns a new float which is the product of +float+ and +other+.
+ * Returns a new Float which is the product of +float+ and +other+.
  */
 
 static VALUE
@@ -1118,7 +1115,7 @@ flo_mul(VALUE x, VALUE y)
  * call-seq:
  *   float / other  ->  float
  *
- * Returns a new float which is the result of dividing +float+ by +other+.
+ * Returns a new Float which is the result of dividing +float+ by +other+.
  */
 
 static VALUE
@@ -1146,7 +1143,7 @@ flo_div(VALUE x, VALUE y)
 /*
  *  call-seq:
  *     float.fdiv(numeric)  ->  float
- *     float.quo(numeric)  ->  float
+ *     float.quo(numeric)   ->  float
  *
  *  Returns <code>float / numeric</code>, same as Float#/.
  */
@@ -1208,16 +1205,15 @@ ruby_float_mod(double x, double y)
     return mod;
 }
 
-
 /*
  *  call-seq:
  *     float % other        ->  float
  *     float.modulo(other)  ->  float
  *
- *  Return the modulo after division of +float+ by +other+.
+ *  Returns the modulo after division of +float+ by +other+.
  *
- *     6543.21.modulo(137)      #=> 104.21
- *     6543.21.modulo(137.24)   #=> 92.9299999999996
+ *     6543.21.modulo(137)      #=> 104.21000000000004
+ *     6543.21.modulo(137.24)   #=> 92.92999999999961
  */
 
 static VALUE
@@ -1255,8 +1251,8 @@ dbl2ival(double d)
  *
  *  See Numeric#divmod.
  *
- *      42.0.divmod 6 #=> [7, 0.0]
- *      42.0.divmod 5 #=> [8, 2.0]
+ *     42.0.divmod(6)   #=> [7, 0.0]
+ *     42.0.divmod(5)   #=> [8, 2.0]
  */
 
 static VALUE
@@ -1285,12 +1281,11 @@ flo_divmod(VALUE x, VALUE y)
 
 /*
  * call-seq:
- *
- *  float ** other  ->  float
+ *    float ** other  ->  float
  *
  * Raises +float+ to the power of +other+.
  *
- *    2.0**3      #=> 8.0
+ *    2.0**3   #=> 8.0
  */
 
 VALUE
@@ -1322,13 +1317,11 @@ rb_float_pow(VALUE x, VALUE y)
  *     num.eql?(numeric)  ->  true or false
  *
  *  Returns +true+ if +num+ and +numeric+ are the same type and have equal
- *  values.  Contrast this with <code>Numeric#==</code>, which performs
- *  type conversions.
+ *  values.  Contrast this with Numeric#==, which performs type conversions.
  *
- *     1 == 1.0          #=> true
- *     1.eql?(1.0)       #=> false
- *     (1.0).eql?(1.0)   #=> true
- *     68719476736.eql?(68719476736.0)   #=> false
+ *     1 == 1.0        #=> true
+ *     1.eql?(1.0)     #=> false
+ *     1.0.eql?(1.0)   #=> true
  */
 
 static VALUE
@@ -1347,8 +1340,7 @@ num_eql(VALUE x, VALUE y)
  *  call-seq:
  *     number <=> other  ->  0 or nil
  *
- *  Returns zero if +number+ equals +other+, otherwise +nil+ is returned if the
- *  two values are incomparable.
+ *  Returns zero if +number+ equals +other+, otherwise returns +nil+.
  */
 
 static VALUE
@@ -1372,14 +1364,13 @@ num_equal(VALUE x, VALUE y)
  *  call-seq:
  *     float == obj  ->  true or false
  *
- *  Returns +true+ only if +obj+ has the same value as +float+. Contrast this
- *  with Float#eql?, which requires obj to be a Float.
- *
- *  The result of <code>NaN == NaN</code> is undefined, so the
- *  implementation-dependent value is returned.
+ *  Returns +true+ only if +obj+ has the same value as +float+.
+ *  Contrast this with Float#eql?, which requires +obj+ to be a Float.
  *
  *     1.0 == 1   #=> true
  *
+ *  The result of <code>NaN == NaN</code> is undefined,
+ *  so an implementation-dependent value is returned.
  */
 
 VALUE
@@ -1410,7 +1401,7 @@ rb_float_equal(VALUE x, VALUE y)
 
 /*
  * call-seq:
- *   float.hash  ->  integer
+ *    float.hash  ->  integer
  *
  * Returns a hash code for this float.
  *
@@ -1441,13 +1432,14 @@ rb_dbl_cmp(double a, double b)
 
 /*
  *  call-seq:
- *     float <=> real  ->  -1, 0, +1 or nil
+ *     float <=> real  ->  -1, 0, +1, or nil
  *
- *  Returns -1, 0, +1 or nil depending on whether +float+ is less than, equal
- *  to, or greater than +real+. This is the basis for the tests in Comparable.
+ *  Returns -1, 0, or +1 depending on whether +float+ is
+ *  less than, equal to, or greater than +real+.
+ *  This is the basis for the tests in the Comparable module.
  *
- *  The result of <code>NaN <=> NaN</code> is undefined, so the
- *  implementation-dependent value is returned.
+ *  The result of <code>NaN <=> NaN</code> is undefined,
+ *  so an implementation-dependent value is returned.
  *
  *  +nil+ is returned if the two values are incomparable.
  */
@@ -1496,8 +1488,8 @@ rb_float_cmp(VALUE x, VALUE y)
  *
  * Returns +true+ if +float+ is greater than +real+.
  *
- * The result of <code>NaN > NaN</code> is undefined, so the
- * implementation-dependent value is returned.
+ * The result of <code>NaN > NaN</code> is undefined,
+ * so an implementation-dependent value is returned.
  */
 
 VALUE
@@ -1533,8 +1525,8 @@ rb_float_gt(VALUE x, VALUE y)
  *
  * Returns +true+ if +float+ is greater than or equal to +real+.
  *
- * The result of <code>NaN >= NaN</code> is undefined, so the
- * implementation-dependent value is returned.
+ * The result of <code>NaN >= NaN</code> is undefined,
+ * so an implementation-dependent value is returned.
  */
 
 static VALUE
@@ -1570,8 +1562,8 @@ flo_ge(VALUE x, VALUE y)
  *
  * Returns +true+ if +float+ is less than +real+.
  *
- * The result of <code>NaN < NaN</code> is undefined, so the
- * implementation-dependent value is returned.
+ * The result of <code>NaN < NaN</code> is undefined,
+ * so an implementation-dependent value is returned.
  */
 
 static VALUE
@@ -1607,8 +1599,8 @@ flo_lt(VALUE x, VALUE y)
  *
  * Returns +true+ if +float+ is less than or equal to +real+.
  *
- * The result of <code>NaN <= NaN</code> is undefined, so the
- * implementation-dependent value is returned.
+ * The result of <code>NaN <= NaN</code> is undefined,
+ * so an implementation-dependent value is returned.
  */
 
 static VALUE
@@ -1645,10 +1637,10 @@ flo_le(VALUE x, VALUE y)
  *  Returns +true+ only if +obj+ is a Float with the same value as +float+.
  *  Contrast this with Float#==, which performs type conversions.
  *
- *  The result of <code>NaN.eql?(NaN)</code> is undefined, so the
- *  implementation-dependent value is returned.
- *
  *     1.0.eql?(1)   #=> false
+ *
+ *  The result of <code>NaN.eql?(NaN)</code> is undefined,
+ *  so an implementation-dependent value is returned.
  */
 
 static VALUE
@@ -1668,9 +1660,9 @@ flo_eql(VALUE x, VALUE y)
 
 /*
  * call-seq:
- *   float.to_f  ->  self
+ *    float.to_f  ->  self
  *
- * Since +float+ is already a float, returns +self+.
+ * Since +float+ is already a Float, returns +self+.
  */
 
 static VALUE
@@ -1688,7 +1680,9 @@ flo_to_f(VALUE num)
  *
  *     (-34.56).abs   #=> 34.56
  *     -34.56.abs     #=> 34.56
+ *     34.56.abs      #=> 34.56
  *
+ *  Float#magnitude is an alias for Float#abs.
  */
 
 VALUE
@@ -1703,7 +1697,6 @@ rb_float_abs(VALUE flt)
  *     float.zero?  ->  true or false
  *
  *  Returns +true+ if +float+ is 0.0.
- *
  */
 
 static VALUE
@@ -1737,15 +1730,10 @@ flo_is_nan_p(VALUE num)
 
 /*
  *  call-seq:
- *     float.infinite?  ->  nil, -1, +1
- *
- *  Return values corresponding to the value of +float+:
+ *     float.infinite?  ->  -1, 1, or nil
  *
- *  +finite+::	    +nil+
- *  +-Infinity+::   +-1+
- *  ++Infinity+::   +1+
- *
- *  For example:
+ *  Returns +nil+, -1, or 1 depending on whether the value is
+ *  finite, <code>-Infinity</code>, or <code>+Infinity</code>.
  *
  *     (0.0).infinite?        #=> nil
  *     (-1.0/0.0).infinite?   #=> -1
@@ -1768,9 +1756,8 @@ flo_is_infinite_p(VALUE num)
  *  call-seq:
  *     float.finite?  ->  true or false
  *
- *  Returns +true+ if +float+ is a valid IEEE floating point number (it is not
- *  infinite, and Float#nan? is +false+).
- *
+ *  Returns +true+ if +float+ is a valid IEEE floating point number,
+ *  i.e. it is not infinite and Float#nan? is +false+.
  */
 
 static VALUE
@@ -1793,7 +1780,7 @@ flo_is_finite_p(VALUE num)
  *  call-seq:
  *     float.next_float  ->  float
  *
- *  Returns the next representable floating-point number.
+ *  Returns the next representable floating point number.
  *
  *  Float::MAX.next_float and Float::INFINITY.next_float is Float::INFINITY.
  *
@@ -1801,13 +1788,13 @@ flo_is_finite_p(VALUE num)
  *
  *  For example:
  *
- *    p 0.01.next_float  #=> 0.010000000000000002
- *    p 1.0.next_float   #=> 1.0000000000000002
- *    p 100.0.next_float #=> 100.00000000000001
+ *    0.01.next_float    #=> 0.010000000000000002
+ *    1.0.next_float     #=> 1.0000000000000002
+ *    100.0.next_float   #=> 100.00000000000001
  *
- *    p 0.01.next_float - 0.01   #=> 1.734723475976807e-18
- *    p 1.0.next_float - 1.0     #=> 2.220446049250313e-16
- *    p 100.0.next_float - 100.0 #=> 1.4210854715202004e-14
+ *    0.01.next_float - 0.01     #=> 1.734723475976807e-18
+ *    1.0.next_float - 1.0       #=> 2.220446049250313e-16
+ *    100.0.next_float - 100.0   #=> 1.4210854715202004e-14
  *
  *    f = 0.01; 20.times { printf "%-20a %s\n", f, f.to_s; f = f.next_float }
  *    #=> 0x1.47ae147ae147bp-7 0.01
@@ -1833,13 +1820,13 @@ flo_is_finite_p(VALUE num)
  *
  *    f = 0.0
  *    100.times { f += 0.1 }
- *    p f                            #=> 9.99999999999998       # should be 10.0 in the ideal world.
- *    p 10-f                         #=> 1.9539925233402755e-14 # the floating-point error.
- *    p(10.0.next_float-10)          #=> 1.7763568394002505e-15 # 1 ulp (units in the last place).
- *    p((10-f)/(10.0.next_float-10)) #=> 11.0                   # the error is 11 ulp.
- *    p((10-f)/(10*Float::EPSILON))  #=> 8.8                    # approximation of the above.
- *    p "%a" % f                     #=> "0x1.3fffffffffff5p+3" # the last hex digit is 5.  16 - 5 = 11 ulp.
- *
+ *    f                           #=> 9.99999999999998       # should be 10.0 in the ideal world.
+ *    10-f                        #=> 1.9539925233402755e-14 # the floating point error.
+ *    10.0.next_float-10          #=> 1.7763568394002505e-15 # 1 ulp (unit in the last place).
+ *    (10-f)/(10.0.next_float-10) #=> 11.0                   # the error is 11 ulp.
+ *    (10-f)/(10*Float::EPSILON)  #=> 8.8                    # approximation of the above.
+ *    "%a" % 10                   #=> "0x1.4p+3"
+ *    "%a" % f                    #=> "0x1.3fffffffffff5p+3" # the last hex digit is 5.  16 - 5 = 11 ulp.
  */
 static VALUE
 flo_next_float(VALUE vx)
@@ -1854,7 +1841,7 @@ flo_next_float(VALUE vx)
  *  call-seq:
  *     float.prev_float  ->  float
  *
- *  Returns the previous representable floating-point number.
+ *  Returns the previous representable floating point number.
  *
  *  (-Float::MAX).prev_float and (-Float::INFINITY).prev_float is -Float::INFINITY.
  *
@@ -1862,13 +1849,13 @@ flo_next_float(VALUE vx)
  *
  *  For example:
  *
- *    p 0.01.prev_float  #=> 0.009999999999999998
- *    p 1.0.prev_float   #=> 0.9999999999999999
- *    p 100.0.prev_float #=> 99.99999999999999
+ *    0.01.prev_float    #=> 0.009999999999999998
+ *    1.0.prev_float     #=> 0.9999999999999999
+ *    100.0.prev_float   #=> 99.99999999999999
  *
- *    p 0.01 - 0.01.prev_float   #=> 1.734723475976807e-18
- *    p 1.0 - 1.0.prev_float     #=> 1.1102230246251565e-16
- *    p 100.0 - 100.0.prev_float #=> 1.4210854715202004e-14
+ *    0.01 - 0.01.prev_float     #=> 1.734723475976807e-18
+ *    1.0 - 1.0.prev_float       #=> 1.1102230246251565e-16
+ *    100.0 - 100.0.prev_float   #=> 1.4210854715202004e-14
  *
  *    f = 0.01; 20.times { printf "%-20a %s\n", f, f.to_s; f = f.prev_float }
  *    #=> 0x1.47ae147ae147bp-7 0.01
@@ -1891,7 +1878,6 @@ flo_next_float(VALUE vx)
  *    #   0x1.47ae147ae146ap-7 0.00999999999999997
  *    #   0x1.47ae147ae1469p-7 0.009999999999999969
  *    #   0x1.47ae147ae1468p-7 0.009999999999999967
- *
  */
 static VALUE
 flo_prev_float(VALUE vx)
@@ -2316,17 +2302,20 @@ float_invariant_round(double number, int ndigits, VALUE *num)
 
 /*
  *  call-seq:
- *     float.to_i      ->  integer
- *     float.to_int    ->  integer
+ *     float.to_i    ->  integer
+ *     float.to_int  ->  integer
  *
  *  Returns the +float+ truncated to an Integer.
  *
- *  Synonyms are #to_i and #to_int
+ *     1.2.to_i      #=> 1
+ *     (-1.2).to_i   #=> -1
  *
  *  Note that the limited precision of floating point arithmetic
  *  might lead to surprising results:
  *
  *    (0.3 / 0.1).to_i  #=> 2 (!)
+ *
+ *  #to_int is an alias for #to_i.
  */
 
 static VALUE
@@ -2379,7 +2368,7 @@ flo_truncate(int argc, VALUE *argv, VALUE num)
 
 /*
  *  call-seq:
- *     float.positive? ->  true or false
+ *     float.positive?  ->  true or false
  *
  *  Returns +true+ if +float+ is greater than 0.
  */
@@ -2393,7 +2382,7 @@ flo_positive_p(VALUE num)
 
 /*
  *  call-seq:
- *     float.negative? ->  true or false
+ *     float.negative?  ->  true or false
  *
  *  Returns +true+ if +float+ is less than 0.
  */
@@ -2422,7 +2411,6 @@ num_floor(int argc, VALUE *argv, VALUE num)
     return flo_floor(argc, argv, rb_Float(num));
 }
 
-
 /*
  *  call-seq:
  *     num.ceil([ndigits])  ->  integer or float
@@ -2654,6 +2642,7 @@ num_step_size(VALUE from, VALUE args, VALUE eobj)
 
     return ruby_num_interval_step_size(from, to, step, FALSE);
 }
+
 /*
  *  call-seq:
  *     num.step(by: step, to: limit) {|i| block }   ->  self
@@ -2666,28 +2655,26 @@ num_step_size(VALUE from, VALUE args, VALUE eobj)
  *
  *  The loop finishes when the value to be passed to the block is greater than
  *  +limit+ (if +step+ is positive) or less than +limit+ (if +step+ is
- *  negative), where <i>limit</i> is defaulted to infinity.
+ *  negative), where +limit+ is defaulted to infinity.
  *
  *  In the recommended keyword argument style, either or both of
  *  +step+ and +limit+ (default infinity) can be omitted.  In the
  *  fixed position argument style, zero as a step
- *  (i.e. num.step(limit, 0)) is not allowed for historical
+ *  (i.e. <code>num.step(limit, 0)</code>) is not allowed for historical
  *  compatibility reasons.
  *
  *  If all the arguments are integers, the loop operates using an integer
  *  counter.
  *
- *  If any of the arguments are floating point numbers, all are converted to floats, and the loop is executed the following expression:
- *
- *	floor(n + n*epsilon)+ 1
+ *  If any of the arguments are floating point numbers, all are converted
+ *  to floats, and the loop is executed
+ *  <i>floor(n + n*Float::EPSILON) + 1</i> times,
+ *  where <i>n = (limit - num)/step</i>.
  *
- *  Where the +n+ is the following:
- *
- *	n = (limit - num)/step
- *
- *  Otherwise, the loop starts at +num+, uses either the less-than (<) or
- *  greater-than (>) operator to compare the counter against +limit+, and
- *  increments itself using the <code>+</code> operator.
+ *  Otherwise, the loop starts at +num+, uses either the
+ *  less-than (<code><</code>) or greater-than (<code>></code>) operator
+ *  to compare the counter against +limit+,
+ *  and increments itself using the <code>+</code> operator.
  *
  *  If no block is given, an Enumerator is returned instead.
  *
@@ -2695,9 +2682,9 @@ num_step_size(VALUE from, VALUE args, VALUE eobj)
  *
  *     p 1.step.take(4)
  *     p 10.step(by: -1).take(4)
- *     3.step(to: 5) { |i| print i, " " }
- *     1.step(10, 2) { |i| print i, " " }
- *     Math::E.step(to: Math::PI, by: 0.2) { |f| print f, " " }
+ *     3.step(to: 5) {|i| print i, " " }
+ *     1.step(10, 2) {|i| print i, " " }
+ *     Math::E.step(to: Math::PI, by: 0.2) {|f| print f, " " }
  *
  *  Will produce:
  *
@@ -2705,7 +2692,7 @@ num_step_size(VALUE from, VALUE args, VALUE eobj)
  *     [10, 9, 8, 7]
  *     3 4 5
  *     1 3 5 7 9
- *     2.71828182845905 2.91828182845905 3.11828182845905
+ *     2.718281828459045 2.9182818284590453 3.118281828459045
  */
 
 static VALUE
@@ -3122,18 +3109,18 @@ rb_num2ull(VALUE val)
  * Document-class: Integer
  *
  *  Holds Integer values.  You cannot add a singleton method to an
- *  Integer. Any attempt to add a singleton method to an Integer object
- *  will raise a TypeError.
+ *  Integer object, any attempt to do so will raise a TypeError.
  *
  */
 
 /*
  *  call-seq:
- *     int.to_i      ->  integer
+ *     int.to_i    ->  integer
+ *     int.to_int  ->  integer
  *
- *  As +int+ is already an Integer, all these methods simply return the receiver.
+ *  Since +int+ is already an Integer, returns +self+.
  *
- *  Synonyms is #to_int
+ *  #to_int is an alias for #to_i.
  */
 
 static VALUE
@@ -3210,7 +3197,8 @@ int_even_p(VALUE num)
  *     int.next  ->  integer
  *     int.succ  ->  integer
  *
- *  Returns the Integer equal to +int+ + 1.
+ *  Returns the successor of +int+,
+ *  i.e. the Integer equal to <code>int+1</code>.
  *
  *     1.next      #=> 2
  *     (-1).next   #=> 0
@@ -3237,7 +3225,8 @@ rb_int_succ(VALUE num)
  *  call-seq:
  *     int.pred  ->  integer
  *
- *  Returns the Integer equal to +int+ - 1.
+ *  Returns the predecessor of +int+,
+ *  i.e. the Integer equal to <code>int-1</code>.
  *
  *     1.pred      #=> 0
  *     (-1).pred   #=> -2
@@ -3267,8 +3256,8 @@ rb_int_pred(VALUE num)
  *  according to +encoding+.
  *
  *     65.chr    #=> "A"
- *     230.chr   #=> "\346"
- *     255.chr(Encoding::UTF_8)   #=> "\303\277"
+ *     230.chr   #=> "\xE6"
+ *     255.chr(Encoding::UTF_8)   #=> "\u00FF"
  */
 
 VALUE
@@ -3343,12 +3332,12 @@ int_chr(int argc, VALUE *argv, VALUE num)
  *
  *  Returns the +int+ itself.
  *
- *     ?a.ord    #=> 97
+ *     97.ord   #=> 97
  *
- *  This method is intended for compatibility to character constant in Ruby
- *  1.9.
+ *  This method is intended for compatibility to character literals
+ *  in Ruby 1.9.
  *
- *  For example, ?a.ord returns 97 both in 1.8 and 1.9.
+ *  For example, <code>?a.ord</code> returns 97 both in 1.8 and 1.9.
  */
 
 static VALUE
@@ -3365,10 +3354,9 @@ int_ord(VALUE num)
 /*
  * Document-method: Integer#-@
  * call-seq:
- *   -int  ->  integer
+ *    -int  ->  integer
  *
- * Negates +int+.
- * (returns an integer whose value is 0-int)
+ * Returns +int+, negated.
  */
 
 static VALUE
@@ -3394,8 +3382,8 @@ rb_int_uminus(VALUE num)
  *  call-seq:
  *     int.to_s(base=10)  ->  string
  *
- *  Returns a string containing the representation of +int+ radix +base+
- *  (between 2 and 36).
+ *  Returns a string containing the place-value representation of +int+
+ *  with radix +base+ (between 2 and 36).
  *
  *     12345.to_s       #=> "12345"
  *     12345.to_s(2)    #=> "11000000111001"
@@ -3404,7 +3392,6 @@ rb_int_uminus(VALUE num)
  *     12345.to_s(16)   #=> "3039"
  *     12345.to_s(36)   #=> "9ix"
  *     78546939656932.to_s(36)  #=> "rubyrules"
- *
  */
 
 VALUE
@@ -3477,7 +3464,7 @@ rb_int2str(VALUE x, int base)
 /*
  * Document-method: Integer#+
  * call-seq:
- *   int + numeric  ->  numeric_result
+ *    int + numeric  ->  numeric_result
  *
  * Performs addition: the class of the resulting object depends on the class of
  * +numeric+ and on the magnitude of the result. It may return a Bignum.
@@ -3524,7 +3511,7 @@ rb_int_plus(VALUE x, VALUE y)
 /*
  * Document-method: Integer#-
  * call-seq:
- *   int - numeric  ->  numeric_result
+ *    int - numeric  ->  numeric_result
  *
  * Performs subtraction: the class of the resulting object depends on the class
  * of +numeric+ and on the magnitude of the result. It may return a Bignum.
@@ -3568,7 +3555,7 @@ rb_int_minus(VALUE x, VALUE y)
 /*
  * Document-method: Integer#*
  * call-seq:
- *   int * numeric  ->  numeric_result
+ *    int * numeric  ->  numeric_result
  *
  * Performs multiplication: the class of the resulting object depends on the
  * class of +numeric+ and on the magnitude of the result. It may return a
@@ -3650,16 +3637,13 @@ rb_int_fdiv_double(VALUE x, VALUE y)
 /*
  *  Document-method: Integer#fdiv
  *  call-seq:
- *     integer.fdiv(numeric)  ->  float
+ *     int.fdiv(numeric)  ->  float
  *
- *  Returns the floating point result of dividing +integer+ by +numeric+.
- *
- *     654321.fdiv(13731)      #=> 47.6528293642124
- *     654321.fdiv(13731.24)   #=> 47.6519964693647
- *
- *     -1234567890987654321.fdiv(13731)      #=> -89910996357705.5
- *     -1234567890987654321.fdiv(13731.24)   #=> -89909424858035.7
+ *  Returns the floating point result of dividing +int+ by +numeric+.
  *
+ *     654321.fdiv(13731)      #=> 47.652829364212366
+ *     654321.fdiv(13731.24)   #=> 47.65199646936475
+ *     -654321.fdiv(13731)     #=> -47.652829364212366
  */
 
 VALUE
@@ -3674,7 +3658,7 @@ rb_int_fdiv(VALUE x, VALUE y)
 /*
  * Document-method: Integer#/
  * call-seq:
- *   int / numeric  ->  numeric_result
+ *    int / numeric  ->  numeric_result
  *
  * Performs division: the class of the resulting object depends on the class of
  * +numeric+ and on the magnitude of the result. It may return a Bignum.
@@ -3735,10 +3719,10 @@ rb_int_div(VALUE x, VALUE y)
 /*
  * Document-method: Integer#div
  * call-seq:
- *   int.div(numeric)  ->  integer
+ *    int.div(numeric)  ->  integer
  *
- * Performs integer division: returns integer result of dividing +int+ by
- * +numeric+.
+ * Performs integer division: returns the integer result of dividing +int+
+ * by +numeric+.
  */
 
 static VALUE
@@ -3763,8 +3747,8 @@ rb_int_idiv(VALUE x, VALUE y)
  *  Document-method: Integer#%
  *  Document-method: Integer#modulo
  *  call-seq:
- *    int % other        ->  real
- *    int.modulo(other)  ->  real
+ *     int % other        ->  real
+ *     int.modulo(other)  ->  real
  *
  *  Returns +int+ modulo +other+.
  *
@@ -3806,20 +3790,15 @@ rb_int_modulo(VALUE x, VALUE y)
  *  call-seq:
  *     int.remainder(numeric)  ->  real
  *
+ *  Returns the remainder after dividing +int+ by +numeric+.
  *
- *  Returns the remainder after dividing <i>big</i> by <i>numeric</i> as:
- *
- *    x.remainder(y) means x-y*(x/y).truncate
- *
- *  Examples
- *
- *    5.remainder(3)    #=> 2
- *    -5.remainder(3)   #=> -2
- *    5.remainder(-3)   #=> 2
- *    -5.remainder(-3)  #=> -2
+ *  <code>x.remainder(y)</code> means <code>x-y*(x/y).truncate</code>.
  *
- *    -1234567890987654321.remainder(13731)      #=> -6966
- *    -1234567890987654321.remainder(13731.24)   #=> -9906.22531493148
+ *     5.remainder(3)     #=> 2
+ *     -5.remainder(3)    #=> -2
+ *     5.remainder(-3)    #=> 2
+ *     -5.remainder(-3)   #=> -2
+ *     5.remainder(1.5)   #=> 0.5
  *
  *  See Numeric#divmod.
  */
@@ -3839,9 +3818,9 @@ int_remainder(VALUE x, VALUE y)
 /*
  *  Document-method: Integer#divmod
  *  call-seq:
- *     integer.divmod(numeric)  ->  array
+ *     int.divmod(numeric)  ->  array
  *
- *  See <code>Numeric#divmod</code>.
+ *  See Numeric#divmod.
  */
 static VALUE
 fix_divmod(VALUE x, VALUE y)
@@ -3887,20 +3866,20 @@ rb_int_divmod(VALUE x, VALUE y)
 /*
  *  Document-method: Integer#**
  *  call-seq:
- *    integer ** numeric  ->  numeric_result
+ *     int ** numeric  ->  numeric_result
  *
- *  Raises +integer+ to the power of +numeric+, which may be negative or
+ *  Raises +int+ to the power of +numeric+, which may be negative or
  *  fractional.
- *  The result may be an Integer, or a Float
- *
- *    2 ** 3      #=> 8
- *    2 ** -1     #=> (1/2)
- *    2 ** 0.5    #=> 1.4142135623731
+ *  The result may be an Integer, a Float, a Rational, or a complex number.
  *
- *    123456789 ** 2      #=> 15241578750190521
- *    123456789 ** 1.2    #=> 5126464716.09932
- *    123456789 ** -2     #=> (1/15241578750190521)
+ *     2 ** 3        #=> 8
+ *     2 ** -1       #=> (1/2)
+ *     2 ** 0.5      #=> 1.4142135623730951
+ *     (-1) ** 0.5   #=> (0.0+1.0i)
  *
+ *     123456789 ** 2     #=> 15241578750190521
+ *     123456789 ** 1.2   #=> 5126464716.0993185
+ *     123456789 ** -2    #=> (1/15241578750190521)
  */
 
 static VALUE
@@ -4017,15 +3996,15 @@ rb_int_pow(VALUE x, VALUE y)
 
 /*
  * Document-method: Integer#==
+ * Document-method: Integer#===
  * call-seq:
- *   int == other  ->  true or false
+ *    int == other  ->  true or false
  *
- * Return +true+ if +int+ equals +other+ numerically.
- * Contrast this with <code>Integer#eql?</code>, which
- * requires <i>other</i> to be a <code>Integer</code>.
+ * Returns +true+ if +int+ equals +other+ numerically.
+ * Contrast this with Integer#eql?, which requires +other+ to be an Integer.
  *
- *   1 == 2      #=> false
- *   1 == 1.0    #=> true
+ *    1 == 2     #=> false
+ *    1 == 1.0   #=> true
  */
 
 static VALUE
@@ -4059,9 +4038,9 @@ rb_int_equal(VALUE x, VALUE y)
 /*
  *  Document-method: Integer#<=>
  *  call-seq:
- *     int <=> numeric  ->  -1, 0, +1 or nil
+ *     int <=> numeric  ->  -1, 0, +1, or nil
  *
- *  Comparison---Returns +-1+, +0+, ++1+ or +nil+ depending on whether +int+ is
+ *  Comparison---Returns -1, 0, or +1 depending on whether +int+ is
  *  less than, equal to, or greater than +numeric+.
  *
  *  This is the basis for the tests in the Comparable module.
@@ -4111,7 +4090,7 @@ rb_int_cmp(VALUE x, VALUE y)
 /*
  * Document-method: Integer#>
  * call-seq:
- *   int > real  ->  true or false
+ *    int > real  ->  true or false
  *
  * Returns +true+ if the value of +int+ is greater than that of +real+.
  */
@@ -4149,7 +4128,7 @@ rb_int_gt(VALUE x, VALUE y)
 /*
  * Document-method: Integer#>=
  * call-seq:
- *   int >= real  ->  true or false
+ *    int >= real  ->  true or false
  *
  * Returns +true+ if the value of +int+ is greater than or equal to that of
  * +real+.
@@ -4189,7 +4168,7 @@ rb_int_ge(VALUE x, VALUE y)
 /*
  * Document-method: Integer#<
  * call-seq:
- *   int < real  ->  true or false
+ *    int < real  ->  true or false
  *
  * Returns +true+ if the value of +int+ is less than that of +real+.
  */
@@ -4227,7 +4206,7 @@ int_lt(VALUE x, VALUE y)
 /*
  * Document-method: Integer#<=
  * call-seq:
- *   int <= real  ->  true or false
+ *    int <= real  ->  true or false
  *
  * Returns +true+ if the value of +int+ is less than or equal to that of
  * +real+.
@@ -4267,17 +4246,16 @@ int_le(VALUE x, VALUE y)
 /*
  * Document-method: Integer#~
  * call-seq:
- *   ~integer  ->  integer
+ *   ~int  ->  integer
  *
  * One's complement: returns a number where each bit is flipped.
  *
- * Inverts the bits in an integer. As Integers are conceptually infinite
- * length, the result acts as if it had an infinite number of one
- * bits to the left. In hex representations, this is displayed
+ * Inverts the bits in an Integer. As integers are conceptually of
+ * infinite length, the result acts as if it had an infinite number of
+ * one bits to the left. In hex representations, this is displayed
  * as two periods to the left of the digits.
  *
  *   sprintf("%X", ~0x1122334455)    #=> "..FEEDDCCBBAA"
- *
  */
 
 static VALUE
@@ -4330,7 +4308,7 @@ rb_num_coerce_bit(VALUE x, VALUE y, ID func)
 /*
  * Document-method: Integer#&
  * call-seq:
- *   integer & integer  ->  integer_result
+ *   int & other_int  ->  integer
  *
  * Bitwise AND.
  */
@@ -4365,7 +4343,7 @@ rb_int_and(VALUE x, VALUE y)
 /*
  * Document-method: Integer#|
  * call-seq:
- *   integer | integer  ->  integer_result
+ *   int | other_int  ->  integer
  *
  * Bitwise OR.
  */
@@ -4400,7 +4378,7 @@ int_or(VALUE x, VALUE y)
 /*
  * Document-method: Integer#^
  * call-seq:
- *   integer ^ integer  ->  integer_result
+ *   int ^ other_int  ->  integer
  *
  * Bitwise EXCLUSIVE OR.
  */
@@ -4437,7 +4415,8 @@ int_xor(VALUE x, VALUE y)
  * call-seq:
  *   int << count  ->  integer
  *
- * Shifts +int+ left +count+ positions, or right if +count+ is negative.
+ * Returns +int+ shifted left +count+ positions, or right if +count+
+ * is negative.
  */
 
 static VALUE
@@ -4482,7 +4461,8 @@ rb_int_lshift(VALUE x, VALUE y)
  * call-seq:
  *   int >> count  ->  integer
  *
- * Shifts +int+ right +count+ positions, or left if +count+ is negative.
+ * Returns +int+ shifted right +count+ positions, or left if +count+
+ * is negative.
  */
 
 static VALUE
@@ -4528,19 +4508,16 @@ rb_int_rshift(VALUE x, VALUE y)
  *  call-seq:
  *     int[n]  ->  0, 1
  *
- *  Bit Reference---Returns the +n+th bit in the binary representation of
- *  +int+, where <code>int[0]</code> is the least significant bit.
- *
- *  For example:
+ *  Bit Reference---Returns the <code>n</code>th bit in the
+ *  binary representation of +int+, where <code>int[0]</code>
+ *  is the least significant bit.
  *
  *     a = 0b11001100101010
- *     30.downto(0) do |n| print a[n] end
+ *     30.downto(0) {|n| print a[n] }
  *     #=> 0000000000000000011001100101010
  *
  *     a = 9**15
- *     50.downto(0) do |n|
- *       print a[n]
- *     end
+ *     50.downto(0) {|n| print a[n] }
  *     #=> 000101110110100000111000011110010100111100010111001
  */
 
@@ -4588,9 +4565,8 @@ int_aref(VALUE num, VALUE idx)
  *  call-seq:
  *     int.to_f  ->  float
  *
- *  Converts +int+ to a +Float+.  If +int+ doesn't fit in a +Float+,
+ *  Converts +int+ to a Float.  If +int+ doesn't fit in a Float,
  *  the result is infinity.
- *
  */
 
 static VALUE
@@ -4620,10 +4596,11 @@ int_to_f(VALUE num)
  *
  *  Returns the absolute value of +int+.
  *
- *     -12345.abs   #=> 12345
- *     12345.abs    #=> 12345
- *     -1234567890987654321.abs   #=> 1234567890987654321
+ *     (-12345).abs   #=> 12345
+ *     -12345.abs     #=> 12345
+ *     12345.abs      #=> 12345
  *
+ *  Integer#magnitude is an alias for Integer#abs.
  */
 
 static VALUE
@@ -4653,12 +4630,13 @@ rb_int_abs(VALUE num)
  *  call-seq:
  *     int.size  ->  int
  *
- *  Returns the number of bytes in the machine representation of +int+.
+ *  Returns the number of bytes in the machine representation of +int+
+ *  (machine dependent).
  *
- *     1.size            #=> 4
- *     -1.size           #=> 4
- *     2147483647.size   #=> 4
- *     (256**10 - 1).size   #=> 12
+ *     1.size               #=> 8
+ *     -1.size              #=> 8
+ *     2147483647.size      #=> 8
+ *     (256**10 - 1).size   #=> 10
  *     (256**20 - 1).size   #=> 20
  *     (256**40 - 1).size   #=> 40
  */
@@ -4684,20 +4662,17 @@ int_size(VALUE num)
 /*
  *  Document-method: Integer#bit_length
  *  call-seq:
- *     int.bit_length -> integer
+ *     int.bit_length  ->  integer
  *
- *  Returns the number of bits of the value of <i>int</i>.
+ *  Returns the number of bits of the value of +int+.
  *
- *  "the number of bits" means that
- *  the bit position of the highest bit which is different to the sign bit.
- *  (The bit position of the bit 2**n is n+1.)
+ *  "Number of bits" means the bit position of the highest bit
+ *  which is different from the sign bit
+ *  (where the least significant bit has bit position 1).
  *  If there is no such bit (zero or minus one), zero is returned.
  *
- *  I.e. This method returns ceil(log2(int < 0 ? -int : int+1)).
+ *  I.e. this method returns <i>ceil(log2(int < 0 ? -int : int+1))</i>.
  *
- *     (-2**10000-1).bit_length  #=> 10001
- *     (-2**10000).bit_length    #=> 10000
- *     (-2**10000+1).bit_length  #=> 10000
  *     (-2**1000-1).bit_length   #=> 1001
  *     (-2**1000).bit_length     #=> 1000
  *     (-2**1000+1).bit_length   #=> 1000
@@ -4719,11 +4694,8 @@ int_size(VALUE num)
  *     (2**1000-1).bit_length    #=> 1000
  *     (2**1000).bit_length      #=> 1001
  *     (2**1000+1).bit_length    #=> 1001
- *     (2**10000-1).bit_length   #=> 10000
- *     (2**10000).bit_length     #=> 10001
- *     (2**10000+1).bit_length   #=> 10001
  *
- *  This method can be used to detect overflow in Array#pack as follows.
+ *  This method can be used to detect overflow in Array#pack as follows:
  *
  *     if n.bit_length < 32
  *       [n].pack("l") # no overflow
@@ -4756,13 +4728,15 @@ rb_int_bit_length(VALUE num)
 /*
  *  Document-method: Integer#digits
  *  call-seq:
- *     int.digits       -> [int]
- *     int.digits(base) -> [int]
+ *     int.digits        ->  array
+ *     int.digits(base)  ->  array
  *
- *  Returns the array including the digits extracted by place-value notation
- *  with radix +base+ of +int+.
+ *  Returns the digits of +int+'s place-value representation
+ *  with radix +base+ (default: 10).
+ *  The digits are returned as an array with the least significant digit
+ *  as the first array element.
  *
- *  +base+ should be greater than or equal to 2.
+ *  +base+ must be greater than or equal to 2.
  *
  *     12345.digits      #=> [5, 4, 3, 2, 1]
  *     12345.digits(7)   #=> [4, 6, 6, 0, 5]
@@ -4871,10 +4845,7 @@ rb_int_digits(int argc, VALUE *argv, VALUE num)
  *
  *  If no block is given, an Enumerator is returned instead.
  *
- *  For example:
- *
- *     5.upto(10) { |i| print i, " " }
- *     #=> 5 6 7 8 9 10
+ *     5.upto(10) {|i| print i, " " }   #=> 5 6 7 8 9 10
  */
 
 static VALUE
@@ -4913,14 +4884,14 @@ int_upto(VALUE from, VALUE to)
  *     int.downto(limit) {|i| block }  ->  self
  *     int.downto(limit)               ->  an_enumerator
  *
- *  Iterates the given block, passing decreasing values from +int+ down to and
- *  including +limit+.
+ *  Iterates the given block, passing in decreasing values from +int+ down to
+ *  and including +limit+.
  *
  *  If no block is given, an Enumerator is returned instead.
  *
  *     5.downto(1) { |n| print n, ".. " }
- *     print "  Liftoff!\n"
- *     #=> "5.. 4.. 3.. 2.. 1..   Liftoff!"
+ *     puts "Liftoff!"
+ *     #=> "5.. 4.. 3.. 2.. 1.. Liftoff!"
  */
 
 static VALUE
@@ -4964,10 +4935,7 @@ int_downto(VALUE from, VALUE to)
  *
  *  If no block is given, an Enumerator is returned instead.
  *
- *     5.times do |i|
- *       print i, " "
- *     end
- *     #=> 0 1 2 3 4
+ *     5.times {|i| print i, " " }   #=> 0 1 2 3 4
  */
 
 static VALUE
@@ -5273,24 +5241,22 @@ rb_int_s_isqrt(VALUE self, VALUE num)
  *
  *  Raised when attempting to divide an integer by 0.
  *
- *     42 / 0
- *     #=> ZeroDivisionError: divided by 0
+ *     42 / 0   #=> ZeroDivisionError: divided by 0
  *
  *  Note that only division by an exact 0 will raise the exception:
  *
- *     42 /  0.0 #=> Float::INFINITY
- *     42 / -0.0 #=> -Float::INFINITY
- *     0  /  0.0 #=> NaN
+ *     42 /  0.0   #=> Float::INFINITY
+ *     42 / -0.0   #=> -Float::INFINITY
+ *     0  /  0.0   #=> NaN
  */
 
 /*
  *  Document-class: FloatDomainError
  *
  *  Raised when attempting to convert special float values (in particular
- *  +infinite+ or +NaN+) to numerical classes which don't support them.
+ *  +Infinity+ or +NaN+) to numerical classes which don't support them.
  *
- *     Float::INFINITY.to_r
- *     #=> FloatDomainError: Infinity
+ *     Float::INFINITY.to_r   #=> FloatDomainError: Infinity
  */
 
 /*
@@ -5303,7 +5269,7 @@ rb_int_s_isqrt(VALUE self, VALUE num)
  * object which is always passed by value.
  *
  *   a = 1
- *   puts 1.object_id == a.object_id   #=> true
+ *   1.object_id == a.object_id   #=> true
  *
  * There can only ever be one instance of the integer +1+, for example. Ruby ensures this
  * by preventing instantiation and duplication.
@@ -5527,7 +5493,7 @@ Init_Numeric(void)
      */
     rb_define_const(rb_cFloat, "DIG", INT2FIX(DBL_DIG));
     /*
-     *	The smallest posable exponent value in a double-precision floating
+     *	The smallest possible exponent value in a double-precision floating
      *	point.
      *
      *	Usually defaults to -1021.