* math.c: RDoc formatting of Math core docs with domains and codomains

  Patch by @eLobato [Fixes GH-309]


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

1 files changed, 218 insertions, 96 deletions

diff --git a/math.c b/math.c
index 96bd1e9f73..2017e43d91 100644
--- a/math.c
+++ b/math.c
@@ -35,10 +35,14 @@ VALUE rb_eMathDomainError;
 
 /*
  *  call-seq:
- *     Math.atan2(y, x)  -> float
+ *     Math.atan2(y, x)  -> Float
  *
- *  Computes the arc tangent given <i>y</i> and <i>x</i>. Returns
- *  -PI..PI.
+ *  Computes the arc tangent given +y+ and +x+.
+ *  Returns a Float in the range -PI..PI.
+ *
+ *  Domain: (−INFINITY, INFINITY)
+ *
+ *  Codomain: [-PI, PI]
  *
  *    Math.atan2(-0.0, -1.0) #=> -3.141592653589793
  *    Math.atan2(-1.0, -1.0) #=> -2.356194490192345
@@ -77,10 +81,17 @@ math_atan2(VALUE obj, VALUE y, VALUE x)
 
 /*
  *  call-seq:
- *     Math.cos(x)    -> float
+ *     Math.cos(x)    -> Float
+ *
+ *  Computes the cosine of +x+ (expressed in radians).
+ *  Returns a Float in the range -1.0..1.0.
+ *
+ *  Domain: (−INFINITY, INFINITY)
+ *
+ *  Codomain: [-1, 1]
+ *
+ *    Math.cos(Math::PI) #=> -1.0
  *
- *  Computes the cosine of <i>x</i> (expressed in radians). Returns
- *  -1..1.
  */
 
 static VALUE
@@ -92,41 +103,61 @@ math_cos(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.sin(x)    -> float
+ *     Math.sin(x)    -> Float
+ *
+ *  Computes the cosine of +x+ (expressed in radians).
+ *  Returns a Float in the range -1.0..1.0.
+ *
+ *  Domain: (−INFINITY, INFINITY)
+ *
+ *  Codomain: [-1, 1]
+ *
+ *    Math.sin(Math::PI/2) #=> 1.0
  *
- *  Computes the sine of <i>x</i> (expressed in radians). Returns
- *  -1..1.
  */
 
 static VALUE
 math_sin(VALUE obj, VALUE x)
 {
     Need_Float(x);
-
     return DBL2NUM(sin(RFLOAT_VALUE(x)));
 }
 
 
 /*
  *  call-seq:
- *     Math.tan(x)    -> float
+ *     Math.tan(x)    -> Float
+ *
+ *  Computes the tangent of +x+ (expressed in radians).
+ *  Returns a Float in the range -1.0..1.0.
+ *
+ *  Domain: n * (-PI/2, PI/2)
+ *
+ *  Codomain: (−INFINITY, INFINITY)
+ *
+ *    Math.tan(5 * (Math::PI/2)) #=> 3266247870639074.0
  *
- *  Returns the tangent of <i>x</i> (expressed in radians).
  */
 
 static VALUE
 math_tan(VALUE obj, VALUE x)
 {
     Need_Float(x);
-
     return DBL2NUM(tan(RFLOAT_VALUE(x)));
 }
 
 /*
  *  call-seq:
- *     Math.acos(x)    -> float
+ *     Math.acos(x)    -> Float
+ *
+ *  Computes the arc cosine of +x+. Returns 0..PI.
+ *
+ *  Domain: [-1, 1]
+ *
+ *  Codomain: [0, PI]
+ *
+ *    Math.acos(0) == Math::PI/2  #=> true
  *
- *  Computes the arc cosine of <i>x</i>. Returns 0..PI.
  */
 
 static VALUE
@@ -144,9 +175,15 @@ math_acos(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.asin(x)    -> float
+ *     Math.asin(x)    -> Float
+ *
+ *  Computes the arc sine of +x+. Returns -PI/2..PI/2.
+ *
+ *  Domain: [-1, -1]
  *
- *  Computes the arc sine of <i>x</i>. Returns -{PI/2} .. {PI/2}.
+ *  Codomain: [-PI/2, PI/2]
+ *
+ *    Math.asin(1) == Math::PI/2  #=> true
  */
 
 static VALUE
@@ -164,9 +201,15 @@ math_asin(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.atan(x)    -> float
+ *     Math.atan(x)    -> Float
+ *
+ *  Computes the arc tangent of +x+. Returns -PI/2..PI/2.
  *
- *  Computes the arc tangent of <i>x</i>. Returns -{PI/2} .. {PI/2}.
+ *  Domain: (−INFINITY, INFINITY)
+ *
+ *  Codomain: (-PI/2, PI/2)
+ *
+ *    Math.atan(0) #=> 0.0
  */
 
 static VALUE
@@ -186,16 +229,22 @@ cosh(double x)
 
 /*
  *  call-seq:
- *     Math.cosh(x)    -> float
+ *     Math.cosh(x)    -> Float
+ *
+ *  Computes the hyperbolic cosine of +x+ (expressed in radians).
+ *
+ *  Domain: (−INFINITY, INFINITY)
+ *
+ *  Codomain: [1, INFINITY)
+ *
+ *    Math.cosh(0) #=> 1.0
  *
- *  Computes the hyperbolic cosine of <i>x</i> (expressed in radians).
  */
 
 static VALUE
 math_cosh(VALUE obj, VALUE x)
 {
     Need_Float(x);
-
     return DBL2NUM(cosh(RFLOAT_VALUE(x)));
 }
 
@@ -209,10 +258,16 @@ sinh(double x)
 
 /*
  *  call-seq:
- *     Math.sinh(x)    -> float
+ *     Math.sinh(x)    -> Float
+ *
+ *  Computes the hyperbolic sine of +x+ (expressed in radians).
+ *
+ *  Domain: (−INFINITY, INFINITY)
+ *
+ *  Codomain: (−INFINITY, INFINITY)
+ *
+ *    Math.sinh(0) #=> 0.0
  *
- *  Computes the hyperbolic sine of <i>x</i> (expressed in
- *  radians).
  */
 
 static VALUE
@@ -232,10 +287,16 @@ tanh(double x)
 
 /*
  *  call-seq:
- *     Math.tanh()    -> float
+ *     Math.tanh(x)    -> Float
+ *
+ *  Computes the hyperbolic tangent of +x+ (expressed in radians).
+ *
+ *  Domain: (−INFINITY, INFINITY)
+ *
+ *  Codomain: (−1, 1)
+ *
+ *    Math.tanh(0) #=> 0.0
  *
- *  Computes the hyperbolic tangent of <i>x</i> (expressed in
- *  radians).
  */
 
 static VALUE
@@ -247,9 +308,16 @@ math_tanh(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.acosh(x)    -> float
+ *     Math.acosh(x)    -> Float
+ *
+ *  Computes the inverse hyperbolic cosine of +x+.
+ *
+ *  Domain: [1, INFINITY)
+ *
+ *  Codomain: [0, INFINITY)
+ *
+ *    Math.acosh(1) #=> 0.0
  *
- *  Computes the inverse hyperbolic cosine of <i>x</i>.
  */
 
 static VALUE
@@ -267,9 +335,16 @@ math_acosh(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.asinh(x)    -> float
+ *     Math.asinh(x)    -> Float
+ *
+ *  Computes the inverse hyperbolic sine of +x+.
+ *
+ *  Domain: (-INFINITY, INFINITY)
+ *
+ *  Codomain: (-INFINITY, INFINITY)
+ *
+ *    Math.asinh(1) #=> 0.881373587019543
  *
- *  Computes the inverse hyperbolic sine of <i>x</i>.
  */
 
 static VALUE
@@ -281,9 +356,16 @@ math_asinh(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.atanh(x)    -> float
+ *     Math.atanh(x)    -> Float
+ *
+ *  Computes the inverse hyperbolic tangent of +x+.
+ *
+ *  Domain: (-1, 1)
+ *
+ *  Codomain: (-INFINITY, INFINITY)
+ *
+ *   Math.atanh(1) #=> Infinity
  *
- *  Computes the inverse hyperbolic tangent of <i>x</i>.
  */
 
 static VALUE
@@ -304,10 +386,14 @@ math_atanh(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.exp(x)    -> float
+ *     Math.exp(x)    -> Float
  *
  *  Returns e**x.
  *
+ *  Domain: (-INFINITY, INFINITY)
+ *
+ *  Codomain: (0, INFINITY)
+ *
  *    Math.exp(0)       #=> 1.0
  *    Math.exp(1)       #=> 2.718281828459045
  *    Math.exp(1.5)     #=> 4.4816890703380645
@@ -332,13 +418,17 @@ math_exp(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.log(numeric)    -> float
- *     Math.log(num,base)   -> float
+ *     Math.log(x)    -> Float
+ *     Math.log(num, base)   -> Float
  *
- *  Returns the natural logarithm of <i>numeric</i>.
+ *  Returns the natural logarithm of +x+.
  *  If additional second argument is given, it will be the base
  *  of logarithm.
  *
+ *  Domain: (0, INFINITY)
+ *
+ *  Codomain: (-INFINITY, INFINITY)
+ *
  *    Math.log(1)          #=> 0.0
  *    Math.log(Math::E)    #=> 1.0
  *    Math.log(Math::E**3) #=> 3.0
@@ -381,9 +471,13 @@ extern double log2(double);
 
 /*
  *  call-seq:
- *     Math.log2(numeric)    -> float
+ *     Math.log2(x)    -> Float
+ *
+ *  Returns the base 2 logarithm of +x+.
+ *
+ *  Domain: (0, INFINITY)
  *
- *  Returns the base 2 logarithm of <i>numeric</i>.
+ *  Codomain: (-INFINITY, INFINITY)
  *
  *    Math.log2(1)      #=> 0.0
  *    Math.log2(2)      #=> 1.0
@@ -409,9 +503,13 @@ math_log2(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.log10(numeric)    -> float
+ *     Math.log10(x)    -> Float
  *
- *  Returns the base 10 logarithm of <i>numeric</i>.
+ *  Returns the base 10 logarithm of +x+.
+ *
+ *  Domain: (0, INFINITY)
+ *
+ *  Codomain: (-INFINITY, INFINITY)
  *
  *    Math.log10(1)       #=> 0.0
  *    Math.log10(10)      #=> 1.0
@@ -436,26 +534,28 @@ math_log10(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.sqrt(numeric)    -> float
+ *     Math.sqrt(x)    -> Float
+ *
+ *  Returns the non-negative square root of +x+.
  *
- *  Returns the non-negative square root of <i>numeric</i>.
+ *  Domain: [0, INFINITY)
+ *
+ *  Codomain:[0, INFINITY)
  *
  *    0.upto(10) {|x|
  *      p [x, Math.sqrt(x), Math.sqrt(x)**2]
  *    }
- *    #=>
- *    [0, 0.0, 0.0]
- *    [1, 1.0, 1.0]
- *    [2, 1.4142135623731, 2.0]
- *    [3, 1.73205080756888, 3.0]
- *    [4, 2.0, 4.0]
- *    [5, 2.23606797749979, 5.0]
- *    [6, 2.44948974278318, 6.0]
- *    [7, 2.64575131106459, 7.0]
- *    [8, 2.82842712474619, 8.0]
- *    [9, 3.0, 9.0]
- *    [10, 3.16227766016838, 10.0]
- *
+ *    #=> [0, 0.0, 0.0]
+ *    #   [1, 1.0, 1.0]
+ *    #   [2, 1.4142135623731, 2.0]
+ *    #   [3, 1.73205080756888, 3.0]
+ *    #   [4, 2.0, 4.0]
+ *    #   [5, 2.23606797749979, 5.0]
+ *    #   [6, 2.44948974278318, 6.0]
+ *    #   [7, 2.64575131106459, 7.0]
+ *    #   [8, 2.82842712474619, 8.0]
+ *    #   [9, 3.0, 9.0]
+ *    #   [10, 3.16227766016838, 10.0]
  */
 
 static VALUE
@@ -474,33 +574,36 @@ math_sqrt(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.cbrt(numeric)    -> float
+ *     Math.cbrt(x)    -> Float
  *
- *  Returns the cube root of <i>numeric</i>.
+ *  Returns the cube root of +x+.
+ *
+ *  Domain: [0, INFINITY)
+ *
+ *  Codomain:[0, INFINITY)
  *
  *    -9.upto(9) {|x|
  *      p [x, Math.cbrt(x), Math.cbrt(x)**3]
  *    }
- *    #=>
- *    [-9, -2.0800838230519, -9.0]
- *    [-8, -2.0, -8.0]
- *    [-7, -1.91293118277239, -7.0]
- *    [-6, -1.81712059283214, -6.0]
- *    [-5, -1.7099759466767, -5.0]
- *    [-4, -1.5874010519682, -4.0]
- *    [-3, -1.44224957030741, -3.0]
- *    [-2, -1.25992104989487, -2.0]
- *    [-1, -1.0, -1.0]
- *    [0, 0.0, 0.0]
- *    [1, 1.0, 1.0]
- *    [2, 1.25992104989487, 2.0]
- *    [3, 1.44224957030741, 3.0]
- *    [4, 1.5874010519682, 4.0]
- *    [5, 1.7099759466767, 5.0]
- *    [6, 1.81712059283214, 6.0]
- *    [7, 1.91293118277239, 7.0]
- *    [8, 2.0, 8.0]
- *    [9, 2.0800838230519, 9.0]
+ *    #=> [-9, -2.0800838230519, -9.0]
+ *    #   [-8, -2.0, -8.0]
+ *    #   [-7, -1.91293118277239, -7.0]
+ *    #   [-6, -1.81712059283214, -6.0]
+ *    #   [-5, -1.7099759466767, -5.0]
+ *    #   [-4, -1.5874010519682, -4.0]
+ *    #   [-3, -1.44224957030741, -3.0]
+ *    #   [-2, -1.25992104989487, -2.0]
+ *    #   [-1, -1.0, -1.0]
+ *    #   [0, 0.0, 0.0]
+ *    #   [1, 1.0, 1.0]
+ *    #   [2, 1.25992104989487, 2.0]
+ *    #   [3, 1.44224957030741, 3.0]
+ *    #   [4, 1.5874010519682, 4.0]
+ *    #   [5, 1.7099759466767, 5.0]
+ *    #   [6, 1.81712059283214, 6.0]
+ *    #   [7, 1.91293118277239, 7.0]
+ *    #   [8, 2.0, 8.0]
+ *    #   [9, 2.0800838230519, 9.0]
  *
  */
 
@@ -513,11 +616,10 @@ math_cbrt(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.frexp(numeric)    -> [ fraction, exponent ]
+ *     Math.frexp(x)    -> [fraction, exponent]
  *
- *  Returns a two-element array containing the normalized fraction (a
- *  <code>Float</code>) and exponent (a <code>Fixnum</code>) of
- *  <i>numeric</i>.
+ *  Returns a two-element array containing the normalized fraction (a Float)
+ *  and exponent (a Fixnum) of +x+.
  *
  *     fraction, exponent = Math.frexp(1234)   #=> [0.6025390625, 11]
  *     fraction * 2**exponent                  #=> 1234.0
@@ -537,9 +639,9 @@ math_frexp(VALUE obj, VALUE x)
 
 /*
  *  call-seq:
- *     Math.ldexp(flt, int) -> float
+ *     Math.ldexp(fraction, exponent) -> float
  *
- *  Returns the value of <i>flt</i>*(2**<i>int</i>).
+ *  Returns the value of +fraction+*(2**+exponent+).
  *
  *     fraction, exponent = Math.frexp(1234)
  *     Math.ldexp(fraction, exponent)   #=> 1234.0
@@ -554,10 +656,10 @@ math_ldexp(VALUE obj, VALUE x, VALUE n)
 
 /*
  *  call-seq:
- *     Math.hypot(x, y)    -> float
+ *     Math.hypot(x, y)    -> Float
  *
- *  Returns sqrt(x**2 + y**2), the hypotenuse of a right-angled triangle
- *  with sides <i>x</i> and <i>y</i>.
+ *  Returns sqrt(x**2 + y**2), the hypotenuse of a right-angled triangle with
+ *  sides +x+ and +y+.
  *
  *     Math.hypot(3, 4)   #=> 5.0
  */
@@ -571,9 +673,16 @@ math_hypot(VALUE obj, VALUE x, VALUE y)
 
 /*
  * call-seq:
- *    Math.erf(x)  -> float
+ *    Math.erf(x)  -> Float
+ *
+ *  Calculates the error function of +x+.
+ *
+ *  Domain: (-INFINITY, INFINITY)
+ *
+ *  Codomain: (-1, 1)
+ *
+ *    Math.erf(0) #=> 0.0
  *
- *  Calculates the error function of x.
  */
 
 static VALUE
@@ -585,9 +694,16 @@ math_erf(VALUE obj, VALUE x)
 
 /*
  * call-seq:
- *    Math.erfc(x)  -> float
+ *    Math.erfc(x)  -> Float
  *
  *  Calculates the complementary error function of x.
+ *
+ *  Domain: (-INFINITY, INFINITY)
+ *
+ *  Codomain: (0, 2)
+ *
+ *    Math.erfc(0) #=> 1.0
+ *
  */
 
 static VALUE
@@ -599,7 +715,7 @@ math_erfc(VALUE obj, VALUE x)
 
 /*
  * call-seq:
- *    Math.gamma(x)  -> float
+ *    Math.gamma(x)  -> Float
  *
  *  Calculates the gamma function of x.
  *
@@ -690,12 +806,14 @@ math_gamma(VALUE obj, VALUE x)
  * call-seq:
  *    Math.lgamma(x)  -> [float, -1 or 1]
  *
- *  Calculates the logarithmic gamma of x and
- *  the sign of gamma of x.
+ *  Calculates the logarithmic gamma of +x+ and the sign of gamma of +x+.
  *
  *  Math.lgamma(x) is same as
  *   [Math.log(Math.gamma(x).abs), Math.gamma(x) < 0 ? -1 : 1]
  *  but avoid overflow by Math.gamma(x) for large x.
+ *
+ *    Math.lgamma(0) #=> [Infinity, 1]
+ *
  */
 
 static VALUE
@@ -767,10 +885,12 @@ exp1(sqrt)
 /*
  *  Document-class: Math
  *
- *  The <code>Math</code> module contains module functions for basic
+ *  The Math module contains module functions for basic
  *  trigonometric and transcendental functions. See class
- *  <code>Float</code> for a list of constants that
+ *  Float for a list of constants that
  *  define Ruby's floating point accuracy.
+ *
+ *  Domains and codomains are given only for real (not complex) numbers.
  */
 
 
@@ -781,12 +901,14 @@ Init_Math(void)
     rb_eMathDomainError = rb_define_class_under(rb_mMath, "DomainError", rb_eStandardError);
 
 #ifdef M_PI
+    /*  Definition of the mathematical constant PI as a Float number. */
     rb_define_const(rb_mMath, "PI", DBL2NUM(M_PI));
 #else
     rb_define_const(rb_mMath, "PI", DBL2NUM(atan(1.0)*4.0));
 #endif
 
 #ifdef M_E
+    /*  Definition of the mathematical constant E (e) as a Float number. */
     rb_define_const(rb_mMath, "E", DBL2NUM(M_E));
 #else
     rb_define_const(rb_mMath, "E", DBL2NUM(exp(1.0)));