improve docs for #round methods

* numeric.c: [DOC] improve and harmonize documentation
  for {Float,Integer,Numeric}#round.
* rational.c: [DOC] ditto for Rational#round.

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

numeric.c

@@ -2215,12 +2215,16 @@ rb_int_truncate(VALUE num, int ndigits)
 
 /*
  *  call-seq:
- *     float.round([ndigits] [, half: symbol])  ->  integer or float
+ *     float.round([ndigits] [, half: mode])  ->  integer or float
  *
- *  Rounds +float+ to a given precision in decimal digits (default 0 digits).
+ *  Returns +float+ rounded to the nearest value with
+ *  a precision of +ndigits+ decimal digits (default: 0).
  *
- *  Precision may be negative.  Returns a floating point number when +ndigits+
- *  is more than zero.
+ *  When the precision is negative, the returned value is an integer
+ *  with at least <code>ndigits.abs</code> trailing zeros.
+ *
+ *  Returns a floating point number when +ndigits+ is positive,
+ *  otherwise returns an integer.
  *
  *     1.4.round      #=> 1
  *     1.5.round      #=> 2
@@ -2242,20 +2246,23 @@ rb_int_truncate(VALUE num, int ndigits)
  *     34567.89.round(2)   #=> 34567.89
  *     34567.89.round(3)   #=> 34567.89
  *
- *  If the <code>half:</code> optional keyword is given, just-half number
- *  will be rounded according to that value.
- *  Supported values for this keyword are follows.
+ *  If the optional +half+ keyword argument is given,
+ *  numbers that are half-way between two possible rounded values
+ *  will be rounded according to the specified tie-breaking +mode+:
  *
- *  * <code>:up</code> or +nil+: the result will be rounded away from zero
- *  * <code>:even</code>: the result will be rounded to nearest even number
- *  * <code>:down</code>: the result will be rounded close to zero
+ *  * <code>:up</code> or +nil+: round half away from zero (default)
+ *  * <code>:down</code>: round half toward zero
+ *  * <code>:even</code>: round half toward the nearest even number
  *
  *     2.5.round(half: :up)      #=> 3
- *     2.5.round(half: :even) #=> 2
  *     2.5.round(half: :down)    #=> 2
+ *     2.5.round(half: :even)    #=> 2
  *     3.5.round(half: :up)      #=> 4
- *     3.5.round(half: :even) #=> 4
  *     3.5.round(half: :down)    #=> 3
+ *     3.5.round(half: :even)    #=> 4
+ *     (-2.5).round(half: :up)   #=> -3
+ *     (-2.5).round(half: :down) #=> -2
+ *     (-2.5).round(half: :even) #=> -2
  */
 
 static VALUE
@@ -2438,13 +2445,11 @@ num_ceil(int argc, VALUE *argv, VALUE num)
  *  call-seq:
  *     num.round([ndigits])  ->  integer or float
  *
- *  Rounds +num+ to a given precision in decimal digits (default 0 digits).
+ *  Returns +num+ rounded to the nearest value with
+ *  a precision of +ndigits+ decimal digits (default: 0).
  *
- *  Precision may be negative.  Returns a floating point number when +ndigits+
- *  is more than zero.
- *
- *  Numeric implements this by converting itself to a Float and invoking
- *  Float#round.
+ *  Numeric implements this by converting its value to a Float and
+ *  invoking Float#round.
  */
 
 static VALUE
@@ -5010,25 +5015,34 @@ int_dotimes(VALUE num)
 /*
  *  Document-method: Integer#round
  *  call-seq:
- *     int.round([ndigits] [, half: symbol])  ->  integer or float
+ *     int.round([ndigits] [, half: mode])  ->  integer or float
  *
- *  Rounds +int+ to a given precision in decimal digits (default 0 digits).
+ *  Returns +int+ rounded to the nearest value with
+ *  a precision of +ndigits+ decimal digits (default: 0).
  *
- *  Precision may be negative.  Returns a floating point number when +ndigits+
- *  is positive, +self+ for zero, and round down for negative.
+ *  When the precision is negative, the returned value is an integer
+ *  with at least <code>ndigits.abs</code> trailing zeros.
+ *
+ *  Returns a floating point number when +ndigits+ is positive,
+ *  +self+ for zero, and an integer for negative.
  *
  *     1.round           #=> 1
  *     1.round(2)        #=> 1.0
  *     15.round(-1)      #=> 20
+ *     (-15).round(-1)   #=> -20
  *
- *  The <code>half:</code> optional keyword same as Float#round is available.
+ *  The optional +half+ keyword argument is available
+ *  similar to Float#round.
  *
  *     25.round(-1, half: :up)      #=> 30
- *     25.round(-1, half: :even) #=> 20
  *     25.round(-1, half: :down)    #=> 20
+ *     25.round(-1, half: :even)    #=> 20
  *     35.round(-1, half: :up)      #=> 40
- *     35.round(-1, half: :even) #=> 40
  *     35.round(-1, half: :down)    #=> 30
+ *     35.round(-1, half: :even)    #=> 40
+ *     (-25).round(-1, half: :up)   #=> -30
+ *     (-25).round(-1, half: :down) #=> -20
+ *     (-25).round(-1, half: :even) #=> -20
  */
 
 static VALUE

rational.c

@@ -1510,12 +1510,16 @@ nurat_truncate_n(int argc, VALUE *argv, VALUE self)
 
 /*
  * call-seq:
- *    rat.round([ndigits] [, half: symbol])  ->  integer or rational
+ *    rat.round([ndigits] [, half: mode])  ->  integer or rational
  *
- * Rounds +rat+ to a given precision in decimal digits (default 0 digits).
+ * Returns +rat+ rounded to the nearest value with
+ * a precision of +ndigits+ decimal digits (default: 0).
  *
- * Precision may be negative.  Returns a rational when +ndigits+
- * is more than zero.
+ * When the precision is negative, the returned value is an integer
+ * with at least <code>ndigits.abs</code> trailing zeros.
+ *
+ * Returns a rational when +ndigits+ is positive,
+ * otherwise returns an integer.
  *
  *    Rational(3).round      #=> 3
  *    Rational(2, 3).round   #=> 1
@@ -1528,14 +1532,18 @@ nurat_truncate_n(int argc, VALUE *argv, VALUE self)
  *    Rational('-123.456').round(+1).to_f  #=> -123.5
  *    Rational('-123.456').round(-1)       #=> -120
  *
- * The <code>half:</code> optional keyword same as Float#round is available.
+ * The optional +half+ keyword argument is available
+ * similar to Float#round.
  *
  *    Rational(25, 100).round(1, half: :up)    #=> (3/10)
- *    Rational(25, 100).round(1, half: :even) #=> (1/5)
  *    Rational(25, 100).round(1, half: :down)  #=> (1/5)
+ *    Rational(25, 100).round(1, half: :even)  #=> (1/5)
  *    Rational(35, 100).round(1, half: :up)    #=> (2/5)
- *    Rational(35, 100).round(1, half: :even) #=> (2/5)
  *    Rational(35, 100).round(1, half: :down)  #=> (3/10)
+ *    Rational(35, 100).round(1, half: :even)  #=> (2/5)
+ *    Rational(-25, 100).round(1, half: :up)   #=> (-3/10)
+ *    Rational(-25, 100).round(1, half: :down) #=> (-1/5)
+ *    Rational(-25, 100).round(1, half: :even) #=> (-1/5)
  */
 static VALUE
 nurat_round_n(int argc, VALUE *argv, VALUE self)