rational.c: improve docs

* rational.c: [DOC] improve docs for Rational and related methods
  * improve class documentation for Rational
  * fix call-seq's
  * simplify examples for Rational#{floor,ceil,truncate,round}
  * fix wrong examples for #floor, subtraction, and exponentiation
  * improve docs for #<=>, Kernel#Rational, {String,Float}#to_r,
    Integer.{gcd,lcm,gcdlcm}
  * fix typos, grammar, and rdoc formatting
  * other improvements

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

1 files changed, 119 insertions, 93 deletions

diff --git a/rational.c b/rational.c
index cefdfecdbf..cb555426ec 100644
--- a/rational.c
+++ b/rational.c
@@ -554,16 +554,24 @@ f_rational_new_no_reduce2(VALUE klass, VALUE x, VALUE y)
 static VALUE nurat_s_convert(int argc, VALUE *argv, VALUE klass);
 /*
  * call-seq:
- *    Rational(x[, y])  ->  numeric
+ *    Rational(x, y)  ->  rational
+ *    Rational(arg)   ->  rational
  *
- * Returns x/y;
+ * Returns +x/y+ or +arg+ as a Rational.
  *
- *    Rational(1, 2)   #=> (1/2)
- *    Rational('1/2')  #=> (1/2)
- *    Rational(nil)    #=> TypeError
- *    Rational(1, nil) #=> TypeError
+ *    Rational(2, 3)   #=> (2/3)
+ *    Rational(5)      #=> (5/1)
+ *    Rational(0.5)    #=> (1/2)
+ *    Rational(0.3)    #=> (5404319552844595/18014398509481984)
+ *
+ *    Rational("2/3")  #=> (2/3)
+ *    Rational("0.3")  #=> (3/10)
  *
- * Syntax of string form:
+ *    Rational("10 cents")  #=> ArgumentError
+ *    Rational(nil)         #=> TypeError
+ *    Rational(1, nil)      #=> TypeError
+ *
+ * Syntax of the string form:
  *
  *   string form = extra spaces , rational , extra spaces ;
  *   rational = [ sign ] , unsigned rational ;
@@ -577,7 +585,7 @@ static VALUE nurat_s_convert(int argc, VALUE *argv, VALUE klass);
  *   digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
  *   extra spaces = ? \s* ? ;
  *
- * See String#to_r.
+ * See also String#to_r.
  */
 static VALUE
 nurat_f_rational(int argc, VALUE *argv, VALUE klass)
@@ -613,7 +621,6 @@ nurat_numerator(VALUE self)
  *    Rational(7, 1).denominator          #=> 1
  *    Rational(9, -4).denominator         #=> 4
  *    Rational(-2, -10).denominator       #=> 5
- *    rat.numerator.gcd(rat.denominator)  #=> 1
  */
 static VALUE
 nurat_denominator(VALUE self)
@@ -772,7 +779,7 @@ rb_rational_plus(VALUE self, VALUE other)
  *    Rational(2, 3)  - Rational(2, 3)   #=> (0/1)
  *    Rational(900)   - Rational(1)      #=> (899/1)
  *    Rational(-2, 9) - Rational(-9, 2)  #=> (77/18)
- *    Rational(9, 8)  - 4                #=> (23/8)
+ *    Rational(9, 8)  - 4                #=> (-23/8)
  *    Rational(20, 9) - 9.8              #=> -7.577777777777778
  */
 static VALUE
@@ -945,7 +952,7 @@ static VALUE nurat_to_f(VALUE self);
  * call-seq:
  *    rat.fdiv(numeric)  ->  float
  *
- * Performs division and returns the value as a float.
+ * Performs division and returns the value as a Float.
  *
  *    Rational(2, 3).fdiv(1)       #=> 0.6666666666666666
  *    Rational(2, 3).fdiv(0.5)     #=> 1.3333333333333333
@@ -982,12 +989,12 @@ f_odd_p(VALUE integer)
  *
  * Performs exponentiation.
  *
- *    Rational(2)    ** Rational(3)    #=> (8/1)
- *    Rational(10)   ** -2             #=> (1/100)
- *    Rational(10)   ** -2.0           #=> 0.01
- *    Rational(-4)   ** Rational(1,2)  #=> (1.2246063538223773e-16+2.0i)
- *    Rational(1, 2) ** 0              #=> (1/1)
- *    Rational(1, 2) ** 0.0            #=> 1.0
+ *    Rational(2)    ** Rational(3)     #=> (8/1)
+ *    Rational(10)   ** -2              #=> (1/100)
+ *    Rational(10)   ** -2.0            #=> 0.01
+ *    Rational(-4)   ** Rational(1, 2)  #=> (0.0+2.0i)
+ *    Rational(1, 2) ** 0               #=> (1/1)
+ *    Rational(1, 2) ** 0.0             #=> 1.0
  */
 static VALUE
 nurat_expt(VALUE self, VALUE other)
@@ -1067,17 +1074,20 @@ nurat_expt(VALUE self, VALUE other)
 
 /*
  * call-seq:
- *    rational <=> numeric  ->  -1, 0, +1 or nil
+ *    rational <=> numeric  ->  -1, 0, +1, or nil
  *
- * Performs comparison and returns -1, 0, or +1.
+ * Returns -1, 0, or +1 depending on whether +rational+ is
+ * less than, equal to, or greater than +numeric+.
  *
  * +nil+ is returned if the two values are incomparable.
  *
- *    Rational(2, 3)  <=> Rational(2, 3)  #=> 0
- *    Rational(5)     <=> 5               #=> 0
- *    Rational(2,3)   <=> Rational(1,3)   #=> 1
- *    Rational(1,3)   <=> 1               #=> -1
- *    Rational(1,3)   <=> 0.3             #=> 1
+ *    Rational(2, 3) <=> Rational(2, 3)  #=> 0
+ *    Rational(5)    <=> 5               #=> 0
+ *    Rational(2, 3) <=> Rational(1, 3)  #=> 1
+ *    Rational(1, 3) <=> 1               #=> -1
+ *    Rational(1, 3) <=> 0.3             #=> 1
+ *
+ *    Rational(1, 3) <=> "0.3"           #=> nil
  */
 VALUE
 rb_rational_cmp(VALUE self, VALUE other)
@@ -1123,7 +1133,7 @@ rb_rational_cmp(VALUE self, VALUE other)
  * call-seq:
  *    rat == object  ->  true or false
  *
- * Returns true if rat equals object numerically.
+ * Returns +true+ if +rat+ equals +object+ numerically.
  *
  *    Rational(2, 3)  == Rational(2, 3)   #=> true
  *    Rational(5)     == 5                #=> true
@@ -1229,7 +1239,7 @@ nurat_true(VALUE self)
 
 /*
  *  call-seq:
- *     rat.positive? ->  true or false
+ *     rat.positive?  ->  true or false
  *
  *  Returns +true+ if +rat+ is greater than 0.
  */
@@ -1242,7 +1252,7 @@ nurat_positive_p(VALUE self)
 
 /*
  *  call-seq:
- *     rat.negative? ->  true or false
+ *     rat.negative?  ->  true or false
  *
  *  Returns +true+ if +rat+ is less than 0.
  */
@@ -1255,15 +1265,15 @@ nurat_negative_p(VALUE self)
 
 /*
  *  call-seq:
- *     rat.abs       -> rat
- *     rat.magnitude -> rat
+ *     rat.abs        ->  rational
+ *     rat.magnitude  ->  rational
  *
  *  Returns the absolute value of +rat+.
  *
- *     (1/2r).abs    #=> 1/2r
- *     (-1/2r).abs   #=> 1/2r
+ *     (1/2r).abs    #=> (1/2)
+ *     (-1/2r).abs   #=> (1/2)
  *
- *  Rational#magnitude is an alias of Rational#abs.
+ *  Rational#magnitude is an alias for Rational#abs.
  */
 
 VALUE
@@ -1299,11 +1309,11 @@ nurat_ceil(VALUE self)
  *
  * Equivalent to Rational#truncate.
  *
- *    Rational(2, 3).to_i   #=> 0
- *    Rational(3).to_i      #=> 3
- *    Rational(300.6).to_i  #=> 300
- *    Rational(98,71).to_i  #=> 1
- *    Rational(-30,2).to_i  #=> -15
+ *    Rational(2, 3).to_i    #=> 0
+ *    Rational(3).to_i       #=> 3
+ *    Rational(300.6).to_i   #=> 300
+ *    Rational(98, 71).to_i  #=> 1
+ *    Rational(-31, 2).to_i  #=> -15
  */
 static VALUE
 nurat_truncate(VALUE self)
@@ -1429,20 +1439,20 @@ f_round_common(int argc, VALUE *argv, VALUE self, VALUE (*func)(VALUE))
 /*
  * call-seq:
  *    rat.floor               ->  integer
- *    rat.floor(precision=0)  ->  rational
+ *    rat.floor(precision=0)  ->  integer or rational
  *
  * Returns the truncated value (toward negative infinity).
  *
  *    Rational(3).floor      #=> 3
  *    Rational(2, 3).floor   #=> 0
- *    Rational(-3, 2).floor  #=> -1
+ *    Rational(-3, 2).floor  #=> -2
  *
  *      #    decimal      -  1  2  3 . 4  5  6
  *      #                   ^  ^  ^  ^   ^  ^
  *      #   precision      -3 -2 -1  0  +1 +2
  *
- *    '%f' % Rational('-123.456').floor(+1)  #=> "-123.500000"
- *    '%f' % Rational('-123.456').floor(-1)  #=> "-130.000000"
+ *    Rational('-123.456').floor(+1).to_f  #=> -123.5
+ *    Rational('-123.456').floor(-1)       #=> -130
  */
 static VALUE
 nurat_floor_n(int argc, VALUE *argv, VALUE self)
@@ -1453,7 +1463,7 @@ nurat_floor_n(int argc, VALUE *argv, VALUE self)
 /*
  * call-seq:
  *    rat.ceil               ->  integer
- *    rat.ceil(precision=0)  ->  rational
+ *    rat.ceil(precision=0)  ->  integer or rational
  *
  * Returns the truncated value (toward positive infinity).
  *
@@ -1465,8 +1475,8 @@ nurat_floor_n(int argc, VALUE *argv, VALUE self)
  *      #                   ^  ^  ^  ^   ^  ^
  *      #   precision      -3 -2 -1  0  +1 +2
  *
- *    '%f' % Rational('-123.456').ceil(+1)  #=> "-123.400000"
- *    '%f' % Rational('-123.456').ceil(-1)  #=> "-120.000000"
+ *    Rational('-123.456').ceil(+1).to_f  #=> -123.4
+ *    Rational('-123.456').ceil(-1)       #=> -120
  */
 static VALUE
 nurat_ceil_n(int argc, VALUE *argv, VALUE self)
@@ -1477,7 +1487,7 @@ nurat_ceil_n(int argc, VALUE *argv, VALUE self)
 /*
  * call-seq:
  *    rat.truncate               ->  integer
- *    rat.truncate(precision=0)  ->  rational
+ *    rat.truncate(precision=0)  ->  integer or rational
  *
  * Returns the truncated value (toward zero).
  *
@@ -1489,8 +1499,8 @@ nurat_ceil_n(int argc, VALUE *argv, VALUE self)
  *      #                   ^  ^  ^  ^   ^  ^
  *      #   precision      -3 -2 -1  0  +1 +2
  *
- *    '%f' % Rational('-123.456').truncate(+1)  #=>  "-123.400000"
- *    '%f' % Rational('-123.456').truncate(-1)  #=>  "-120.000000"
+ *    Rational('-123.456').truncate(+1).to_f  #=> -123.4
+ *    Rational('-123.456').truncate(-1)       #=> -120
  */
 static VALUE
 nurat_truncate_n(int argc, VALUE *argv, VALUE self)
@@ -1501,7 +1511,7 @@ nurat_truncate_n(int argc, VALUE *argv, VALUE self)
 /*
  * call-seq:
  *    rat.round               ->  integer
- *    rat.round(precision=0)  ->  rational
+ *    rat.round(precision=0)  ->  integer or rational
  *
  * Returns the truncated value (toward the nearest integer;
  * 0.5 => 1; -0.5 => -1).
@@ -1514,8 +1524,8 @@ nurat_truncate_n(int argc, VALUE *argv, VALUE self)
  *      #                   ^  ^  ^  ^   ^  ^
  *      #   precision      -3 -2 -1  0  +1 +2
  *
- *    '%f' % Rational('-123.456').round(+1)  #=> "-123.500000"
- *    '%f' % Rational('-123.456').round(-1)  #=> "-120.000000"
+ *    Rational('-123.456').round(+1).to_f  #=> -123.5
+ *    Rational('-123.456').round(-1)       #=> -120
  */
 static VALUE
 nurat_round_n(int argc, VALUE *argv, VALUE self)
@@ -1539,7 +1549,7 @@ nurat_to_double(VALUE self)
  * call-seq:
  *    rat.to_f  ->  float
  *
- * Return the value as a float.
+ * Returns the value as a Float.
  *
  *    Rational(2).to_f      #=> 2.0
  *    Rational(9, 4).to_f   #=> 2.25
@@ -1669,8 +1679,8 @@ nurat_rationalize_internal(VALUE a, VALUE b, VALUE *p, VALUE *q)
  *    rat.rationalize(eps)  ->  rational
  *
  * Returns a simpler approximation of the value if the optional
- * argument eps is given (rat-|eps| <= result <= rat+|eps|), self
- * otherwise.
+ * argument +eps+ is given (rat-|eps| <= result <= rat+|eps|),
+ * self otherwise.
  *
  *    r = Rational(5033165, 16777216)
  *    r.rationalize                    #=> (5033165/16777216)
@@ -1839,11 +1849,12 @@ rb_rational_reciprocal(VALUE x)
 
 /*
  * call-seq:
- *    int.gcd(int2)  ->  integer
+ *    int.gcd(other_int)  ->  integer
  *
- * Returns the greatest common divisor (always positive).  0.gcd(x)
- * and x.gcd(0) return abs(x).
+ * Returns the greatest common divisor of the two integers.
+ * The result is always positive. 0.gcd(x) and x.gcd(0) return x.abs.
  *
+ *    36.gcd(60)                  #=> 12
  *    2.gcd(2)                    #=> 2
  *    3.gcd(-7)                   #=> 1
  *    ((1<<31)-1).gcd((1<<61)-1)  #=> 1
@@ -1857,11 +1868,12 @@ rb_gcd(VALUE self, VALUE other)
 
 /*
  * call-seq:
- *    int.lcm(int2)  ->  integer
+ *    int.lcm(other_int)  ->  integer
  *
- * Returns the least common multiple (always positive).  0.lcm(x) and
- * x.lcm(0) return zero.
+ * Returns the least common multiple of the two integers.
+ * The result is always positive. 0.lcm(x) and x.lcm(0) return zero.
  *
+ *    36.lcm(60)                  #=> 180
  *    2.lcm(2)                    #=> 2
  *    3.lcm(-7)                   #=> 21
  *    ((1<<31)-1).lcm((1<<61)-1)  #=> 4951760154835678088235319297
@@ -1875,10 +1887,12 @@ rb_lcm(VALUE self, VALUE other)
 
 /*
  * call-seq:
- *    int.gcdlcm(int2)  ->  array
+ *    int.gcdlcm(other_int)  ->  array
  *
- * Returns an array; [int.gcd(int2), int.lcm(int2)].
+ * Returns an array with the greatest common divisor and
+ * the least common multiple of the two integers, [gcd, lcm].
  *
+ *    36.gcdlcm(60)                  #=> [12, 180]
  *    2.gcdlcm(2)                    #=> [2, 2]
  *    3.gcdlcm(-7)                   #=> [1, 21]
  *    ((1<<31)-1).gcdlcm((1<<61)-1)  #=> [1, 4951760154835678088235319297]
@@ -1962,7 +1976,7 @@ numeric_denominator(VALUE self)
  *     num.quo(int_or_rat)   ->  rat
  *     num.quo(flo)          ->  flo
  *
- *  Returns most exact division (rational for integers, float for floats).
+ *  Returns the most exact division (rational for integers, float for floats).
  */
 
 static VALUE
@@ -2016,6 +2030,8 @@ static VALUE float_to_r(VALUE self);
  *    n = 0.3.numerator    #=> 5404319552844595
  *    d = 0.3.denominator  #=> 18014398509481984
  *    n.fdiv(d)            #=> 0.3
+ *
+ * See also Float#denominator.
  */
 static VALUE
 float_numerator(VALUE self)
@@ -2033,7 +2049,7 @@ float_numerator(VALUE self)
  * Returns the denominator (always positive).  The result is machine
  * dependent.
  *
- * See numerator.
+ * See also Float#numerator.
  */
 static VALUE
 float_denominator(VALUE self)
@@ -2060,7 +2076,7 @@ nilclass_to_r(VALUE self)
  * call-seq:
  *    nil.rationalize([eps])  ->  (0/1)
  *
- * Returns zero as a rational.  The optional argument eps is always
+ * Returns zero as a rational.  The optional argument +eps+ is always
  * ignored.
  */
 static VALUE
@@ -2089,7 +2105,7 @@ integer_to_r(VALUE self)
  * call-seq:
  *    int.rationalize([eps])  ->  rational
  *
- * Returns the value as a rational.  The optional argument eps is
+ * Returns the value as a rational.  The optional argument +eps+ is
  * always ignored.
  */
 static VALUE
@@ -2129,15 +2145,19 @@ float_decode(VALUE self)
  *
  * Returns the value as a rational.
  *
- * NOTE: 0.3.to_r isn't the same as '0.3'.to_r.  The latter is
- * equivalent to '3/10'.to_r, but the former isn't so.
- *
  *    2.0.to_r    #=> (2/1)
  *    2.5.to_r    #=> (5/2)
  *    -0.75.to_r  #=> (-3/4)
  *    0.0.to_r    #=> (0/1)
+ *    0.3.to_r    #=> (5404319552844595/18014398509481984)
+ *
+ * NOTE: 0.3.to_r isn't the same as "0.3".to_r.  The latter is
+ * equivalent to "3/10".to_r, but the former isn't so.
+ *
+ *    0.3.to_r   == 3/10r  #=> false
+ *    "0.3".to_r == 3/10r  #=> true
  *
- * See rationalize.
+ * See also Float#rationalize.
  */
 static VALUE
 float_to_r(VALUE self)
@@ -2223,14 +2243,14 @@ rb_flt_rationalize(VALUE flt)
  *    flt.rationalize([eps])  ->  rational
  *
  * Returns a simpler approximation of the value (flt-|eps| <= result
- * <= flt+|eps|).  if the optional eps is not given, it will be chosen
- * automatically.
+ * <= flt+|eps|).  If the optional argument +eps+ is not given,
+ * it will be chosen automatically.
  *
  *    0.3.rationalize          #=> (3/10)
  *    1.333.rationalize        #=> (1333/1000)
  *    1.333.rationalize(0.01)  #=> (4/3)
  *
- * See to_r.
+ * See also Float#to_r.
  */
 static VALUE
 float_rationalize(int argc, VALUE *argv, VALUE self)
@@ -2428,24 +2448,29 @@ string_to_r_strict(VALUE self)
  * call-seq:
  *    str.to_r  ->  rational
  *
- * Returns a rational which denotes the string form.  The parser
- * ignores leading whitespaces and trailing garbage.  Any digit
- * sequences can be separated by an underscore.  Returns zero for null
- * or garbage string.
- *
- * NOTE: '0.3'.to_r isn't the same as 0.3.to_r.  The former is
- * equivalent to '3/10'.to_r, but the latter isn't so.
+ * Returns the result of interpreting leading characters in +str+
+ * as a rational.  Leading whitespace and extraneous characters
+ * past the end of a valid number are ignored.
+ * Digit sequences can be separated by an underscore.
+ * If there is not a valid number at the start of +str+,
+ * zero is returned.  This method never raises an exception.
  *
  *    '  2  '.to_r       #=> (2/1)
  *    '300/2'.to_r       #=> (150/1)
  *    '-9.2'.to_r        #=> (-46/5)
  *    '-9.2e2'.to_r      #=> (-920/1)
  *    '1_234_567'.to_r   #=> (1234567/1)
- *    '21 june 09'.to_r  #=> (21/1)
+ *    '21 June 09'.to_r  #=> (21/1)
  *    '21/06/09'.to_r    #=> (7/2)
- *    'bwv 1079'.to_r    #=> (0/1)
+ *    'BWV 1079'.to_r    #=> (0/1)
+ *
+ * NOTE: "0.3".to_r isn't the same as 0.3.to_r.  The former is
+ * equivalent to "3/10".to_r, but the latter isn't so.
+ *
+ *    "0.3".to_r == 3/10r  #=> true
+ *    0.3.to_r   == 3/10r  #=> false
  *
- * See Kernel.Rational.
+ * See also Kernel#Rational.
  */
 static VALUE
 string_to_r(VALUE self)
@@ -2536,12 +2561,13 @@ nurat_s_convert(int argc, VALUE *argv, VALUE klass)
 }
 
 /*
- * A rational number can be represented as a paired integer number;
- * a/b (b>0).  Where a is numerator and b is denominator.  Integer a
- * equals rational a/1 mathematically.
+ * A rational number can be represented as a pair of integer numbers:
+ * a/b (b>0), where a is the numerator and b is the denominator.
+ * Integer a equals rational a/1 mathematically.
  *
- * In ruby, you can create rational object with Rational, to_r,
- * rationalize method or suffixing r to a literal.  The return values will be irreducible.
+ * In Ruby, you can create rational objects with the Kernel#Rational,
+ * to_r, or rationalize methods or by suffixing +r+ to a literal.
+ * The return values will be irreducible fractions.
  *
  *    Rational(1)      #=> (1/1)
  *    Rational(2, 3)   #=> (2/3)
@@ -2549,7 +2575,7 @@ nurat_s_convert(int argc, VALUE *argv, VALUE klass)
  *    3.to_r           #=> (3/1)
  *    2/3r             #=> (2/3)
  *
- * You can also create rational object from floating-point numbers or
+ * You can also create rational objects from floating-point numbers or
  * strings.
  *
  *    Rational(0.3)    #=> (5404319552844595/18014398509481984)
@@ -2562,13 +2588,13 @@ nurat_s_convert(int argc, VALUE *argv, VALUE klass)
  *    0.3.rationalize  #=> (3/10)
  *
  * A rational object is an exact number, which helps you to write
- * program without any rounding errors.
+ * programs without any rounding errors.
  *
- *    10.times.inject(0){|t,| t + 0.1}              #=> 0.9999999999999999
- *    10.times.inject(0){|t,| t + Rational('0.1')}  #=> (1/1)
+ *    10.times.inject(0) {|t| t + 0.1 }              #=> 0.9999999999999999
+ *    10.times.inject(0) {|t| t + Rational('0.1') }  #=> (1/1)
  *
- * However, when an expression has inexact factor (numerical value or
- * operation), will produce an inexact result.
+ * However, when an expression includes an inexact component (numerical value
+ * or operation), it will produce an inexact result.
  *
  *    Rational(10) / 3   #=> (10/3)
  *    Rational(10) / 3.0 #=> 3.3333333333333335