* 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
This commit is contained in:
zzak 2013-05-19 22:29:26 +00:00
Родитель 2439bc9e69
Коммит c1f176974c
2 изменённых файлов: 223 добавлений и 96 удалений

Просмотреть файл

@ -1,3 +1,8 @@
Mon May 20 07:27:41 2013 Zachary Scott <zachary@zacharyscott.net>
* math.c: RDoc formatting of Math core docs with domains and codomains
Patch by @eLobato [Fixes GH-309]
Mon May 20 05:58:12 2013 Zachary Scott <zachary@zacharyscott.net>
* ext/bigdecimal/bigdecimal.c: Formatting for BigMath [Fixes GH-306]

314
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 <i>x</i>. Returns -{PI/2} .. {PI/2}.
* Computes the arc sine of +x+. Returns -PI/2..PI/2.
*
* Domain: [-1, -1]
*
* 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 <i>x</i>. Returns -{PI/2} .. {PI/2}.
* Computes the arc tangent of +x+. 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 <i>numeric</i>.
* Returns the base 2 logarithm of +x+.
*
* Domain: (0, INFINITY)
*
* 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 <i>numeric</i>.
* Returns the non-negative square root of +x+.
*
* 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)));