Add RDoc comments to math.c

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

2 files changed, 188 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 50a77b2fcf..92eafb62dd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Mon Dec 29 00:41:44 2003  Dave Thomas  <dave@pragprog.com>
+
+	* math.c: Add RDoc comments
+
 Sun Dec 28 20:19:11 2003  Tanaka Akira  <akr@m17n.org>
 
 	* ext/stringio/stringio.c (strio_sysread): StringIO.new.sysread didn't
diff --git a/math.c b/math.c
index 5268598750..5b9294e781 100644
--- a/math.c
+++ b/math.c
@@ -22,6 +22,16 @@ VALUE rb_mMath;
     Need_Float(y);\
 } while (0)
 
+
+/*
+ *  call-seq:
+ *     Math.atan2(y, x)  => float
+ *  
+ *  Computes the arc tangent given <i>y</i> and <i>x</i>. Returns
+ *  -PI..PI.
+ *     
+ */
+
 static VALUE
 math_atan2(obj, y, x)
     VALUE obj, x, y;
@@ -30,6 +40,16 @@ math_atan2(obj, y, x)
     return rb_float_new(atan2(RFLOAT(y)->value, RFLOAT(x)->value));
 }
 
+
+
+/*
+ *  call-seq:
+ *     Math.cos(x)    => float
+ *  
+ *  Computes the cosine of <i>x</i> (expressed in radians). Returns
+ *  -1..1.
+ */
+
 static VALUE
 math_cos(obj, x)
     VALUE obj, x;
@@ -38,6 +58,14 @@ math_cos(obj, x)
     return rb_float_new(cos(RFLOAT(x)->value));
 }
 
+/*
+ *  call-seq:
+ *     Math.sin(x)    => float
+ *  
+ *  Computes the sine of <i>x</i> (expressed in radians). Returns
+ *  -1..1.
+ */
+
 static VALUE
 math_sin(obj, x)
     VALUE obj, x;
@@ -47,6 +75,14 @@ math_sin(obj, x)
     return rb_float_new(sin(RFLOAT(x)->value));
 }
 
+
+/*
+ *  call-seq:
+ *     Math.tan(x)    => float
+ *  
+ *  Returns the tangent of <i>x</i> (expressed in radians).
+ */
+
 static VALUE
 math_tan(obj, x)
     VALUE obj, x;
@@ -56,6 +92,13 @@ math_tan(obj, x)
     return rb_float_new(tan(RFLOAT(x)->value));
 }
 
+/*
+ *  call-seq:
+ *     Math.acos(x)    => float
+ *  
+ *  Computes the arc cosine of <i>x</i>. Returns 0..PI.
+ */
+
 static VALUE
 math_acos(obj, x)
     VALUE obj, x;
@@ -71,6 +114,13 @@ math_acos(obj, x)
     return rb_float_new(d);
 }
 
+/*
+ *  call-seq:
+ *     Math.asin(x)    => float
+ *  
+ *  Computes the arc sine of <i>x</i>. Returns 0..PI.
+ */
+
 static VALUE
 math_asin(obj, x)
     VALUE obj, x;
@@ -86,6 +136,13 @@ math_asin(obj, x)
     return rb_float_new(d);
 }
 
+/*
+ *  call-seq:
+ *     Math.atan(x)    => float
+ *  
+ *  Computes the arc tangent of <i>x</i>. Returns -{PI/2} .. {PI/2}.
+ */
+
 static VALUE
 math_atan(obj, x)
     VALUE obj, x;
@@ -103,6 +160,13 @@ cosh(x)
 }
 #endif
 
+/*
+ *  call-seq:
+ *     Math.cosh(x)    => float
+ *  
+ *  Computes the hyperbolic cosine of <i>x</i> (expressed in radians).
+ */
+
 static VALUE
 math_cosh(obj, x)
     VALUE obj, x;
@@ -121,6 +185,14 @@ sinh(x)
 }
 #endif
 
+/*
+ *  call-seq:
+ *     Math.sinh(x)    => float
+ *  
+ *  Computes the hyperbolic sine of <i>x</i> (expressed in
+ *  radians).
+ */
+
 static VALUE
 math_sinh(obj, x)
     VALUE obj, x;
@@ -138,6 +210,14 @@ tanh(x)
 }
 #endif
 
+/*
+ *  call-seq:
+ *     Math.tanh()    => float
+ *  
+ *  Computes the hyperbolic tangent of <i>x</i> (expressed in
+ *  radians).
+ */
+
 static VALUE
 math_tanh(obj, x)
     VALUE obj, x;
@@ -146,6 +226,13 @@ math_tanh(obj, x)
     return rb_float_new(tanh(RFLOAT(x)->value));
 }
 
+/*
+ *  call-seq:
+ *     Math.acosh(x)    => float
+ *  
+ *  Computes the inverse hyperbolic cosine of <i>x</i>.
+ */
+
 static VALUE
 math_acosh(obj, x)
     VALUE obj, x;
@@ -161,6 +248,13 @@ math_acosh(obj, x)
     return rb_float_new(d);
 }
 
+/*
+ *  call-seq:
+ *     Math.asinh(x)    => float
+ *  
+ *  Computes the inverse hyperbolic sine of <i>x</i>.
+ */
+
 static VALUE
 math_asinh(obj, x)
     VALUE obj, x;
@@ -169,6 +263,13 @@ math_asinh(obj, x)
     return rb_float_new(asinh(RFLOAT(x)->value));
 }
 
+/*
+ *  call-seq:
+ *     Math.atanh(x)    => float
+ *  
+ *  Computes the inverse hyperbolic tangent of <i>x</i>.
+ */
+
 static VALUE
 math_atanh(obj, x)
     VALUE obj, x;
@@ -184,6 +285,13 @@ math_atanh(obj, x)
     return rb_float_new(d);
 }
 
+/*
+ *  call-seq:
+ *     Math.exp(x)    => float
+ *  
+ *  Returns e**x.
+ */
+
 static VALUE
 math_exp(obj, x)
     VALUE obj, x;
@@ -201,6 +309,13 @@ math_exp(obj, x)
 # define log10(x) ((x) < 0.0 ? nan("") : log10(x))
 #endif
 
+/*
+ *  call-seq:
+ *     Math.log(numeric)    => float
+ *  
+ *  Returns the natural logarithm of <i>numeric</i>.
+ */
+
 static VALUE
 math_log(obj, x)
     VALUE obj, x;
@@ -216,6 +331,13 @@ math_log(obj, x)
     return rb_float_new(d);
 }
 
+/*
+ *  call-seq:
+ *     Math.log10(numeric)    => float
+ *  
+ *  Returns the base 10 logarithm of <i>numeric</i>.
+ */
+
 static VALUE
 math_log10(obj, x)
     VALUE obj, x;
@@ -231,6 +353,14 @@ math_log10(obj, x)
     return rb_float_new(d);
 }
 
+/*
+ *  call-seq:
+ *     Math.sqrt(numeric)    => float
+ *  
+ *  Returns the non-negative square root of <i>numeric</i>. Raises
+ *  <code>ArgError</code> if <i>numeric</i> is less than zero.
+ */
+
 static VALUE
 math_sqrt(obj, x)
     VALUE obj, x;
@@ -246,6 +376,18 @@ math_sqrt(obj, x)
     return rb_float_new(d);
 }
 
+/*
+ *  call-seq:
+ *     Math.frexp(numeric)    => [ 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>.
+ *     
+ *     fraction, exponent = Math.frexp(1234)   #=> [0.6025390625, 11]
+ *     fraction * 2**exponent                  #=> 1234.0
+ */
+
 static VALUE
 math_frexp(obj, x)
     VALUE obj, x;
@@ -259,6 +401,16 @@ math_frexp(obj, x)
     return rb_assoc_new(rb_float_new(d), INT2NUM(exp));
 }
 
+/*
+ *  call-seq:
+ *     Math.ldexp(flt, int) -> float
+ *  
+ *  Returns the value of <i>flt</i>*(2**<i>int</i>).
+ *     
+ *     fraction, exponent = Math.frexp(1234)
+ *     Math.ldexp(fraction, exponent)   #=> 1234.0
+ */
+
 static VALUE
 math_ldexp(obj, x, n)
     VALUE obj, x, n;
@@ -267,6 +419,16 @@ math_ldexp(obj, x, n)
     return rb_float_new(ldexp(RFLOAT(x)->value, NUM2INT(n)));
 }
 
+/*
+ *  call-seq:
+ *     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>.
+ *     
+ *     Math.hypot(3, 4)   #=> 5.0
+ */
+
 static VALUE
 math_hypot(obj, x, y)
     VALUE obj, x, y;
@@ -275,6 +437,13 @@ math_hypot(obj, x, y)
     return rb_float_new(hypot(RFLOAT(x)->value, RFLOAT(y)->value));
 }
 
+/*
+ * call-seq:
+ *    Math.erf(x)  => float
+ *
+ *  Calculates the error function of x.
+ */
+
 static VALUE
 math_erf(obj, x)
     VALUE obj, x;
@@ -283,6 +452,13 @@ math_erf(obj, x)
     return rb_float_new(erf(RFLOAT(x)->value));
 }
 
+/*
+ * call-seq:
+ *    Math.erfc(x)  => float
+ *
+ *  Calculates the complementary error function of x.
+ */
+
 static VALUE
 math_erfc(obj, x)
     VALUE obj, x;
@@ -291,6 +467,14 @@ math_erfc(obj, x)
     return rb_float_new(erfc(RFLOAT(x)->value));
 }
 
+/*
+ *  The <code>Math</code> module contains module functions for basic
+ *  trigonometric and transcendental functions. See class
+ *  <code>Float</code> for a list of constants that
+ *  define Ruby's floating point accuracy.
+ */     
+
+
 void
 Init_Math()
 {