From 9b289d58f78e80362984ffb2920e859beeaec2ce Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 22 Dec 2023 21:31:18 -0600 Subject: [PATCH] [DOC] RDoc for Complex (#9307) --- complex.c | 87 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 53 insertions(+), 34 deletions(-) diff --git a/complex.c b/complex.c index 5b91c5f2407e4d..d104bb8dea8b2e 100644 --- a/complex.c +++ b/complex.c @@ -1779,14 +1779,15 @@ rb_dbl_complex_new(double real, double imag) /* * call-seq: - * cmp.to_i -> integer + * to_i -> integer * - * Returns the value as an integer if possible (the imaginary part - * should be exactly zero). + * Returns the value of self.real as an Integer, if possible: * - * Complex(1, 0).to_i #=> 1 - * Complex(1, 0.0).to_i # RangeError - * Complex(1, 2).to_i # RangeError + * Complex(1, 0).to_i # => 1 + * Complex(1, Rational(0, 1)).to_i # => 1 + * + * Raises RangeError if self.imag is not exactly zero + * (either Integer(0) or Rational(0, _n_)). */ static VALUE nucomp_to_i(VALUE self) @@ -1802,14 +1803,15 @@ nucomp_to_i(VALUE self) /* * call-seq: - * cmp.to_f -> float + * to_f -> float + * + * Returns the value of self.real as a Float, if possible: * - * Returns the value as a float if possible (the imaginary part should - * be exactly zero). + * Complex(1, 0).to_f # => 1.0 + * Complex(1, Rational(0, 1)).to_f # => 1.0 * - * Complex(1, 0).to_f #=> 1.0 - * Complex(1, 0.0).to_f # RangeError - * Complex(1, 2).to_f # RangeError + * Raises RangeError if self.imag is not exactly zero + * (either Integer(0) or Rational(0, _n_)). */ static VALUE nucomp_to_f(VALUE self) @@ -1825,16 +1827,17 @@ nucomp_to_f(VALUE self) /* * call-seq: - * cmp.to_r -> rational + * to_r -> rational * - * Returns the value as a rational if possible (the imaginary part - * should be exactly zero). + * Returns the value of self.real as a Rational, if possible: * - * Complex(1, 0).to_r #=> (1/1) - * Complex(1, 0.0).to_r # RangeError - * Complex(1, 2).to_r # RangeError + * Complex(1, 0).to_r # => (1/1) + * Complex(1, Rational(0, 1)).to_r # => (1/1) * - * See rationalize. + * Raises RangeError if self.imag is not exactly zero + * (either Integer(0) or Rational(0, _n_)). + * + * Related: Complex#rationalize. */ static VALUE nucomp_to_r(VALUE self) @@ -1850,16 +1853,35 @@ nucomp_to_r(VALUE self) /* * call-seq: - * cmp.rationalize([eps]) -> rational - * - * Returns the value as a rational if possible (the imaginary part - * should be exactly zero). - * - * Complex(1.0/3, 0).rationalize #=> (1/3) - * Complex(1, 0.0).rationalize # RangeError - * Complex(1, 2).rationalize # RangeError - * - * See to_r. + * rationalize(epsilon = nil) -> rational + * + * Returns a Rational object whose value is exactly or approximately + * equivalent to that of self.real. + * + * With no argument +epsilon+ given, returns a \Rational object + * whose value is exactly equal to that of self.real.rationalize: + * + * Complex(1, 0).rationalize # => (1/1) + * Complex(1, Rational(0, 1)).rationalize # => (1/1) + * Complex(3.14159, 0).rationalize # => (314159/100000) + * + * With argument +epsilon+ given, returns a \Rational object + * whose value is exactly or approximately equal to that of self.real + * to the given precision: + * + * Complex(3.14159, 0).rationalize(0.1) # => (16/5) + * Complex(3.14159, 0).rationalize(0.01) # => (22/7) + * Complex(3.14159, 0).rationalize(0.001) # => (201/64) + * Complex(3.14159, 0).rationalize(0.0001) # => (333/106) + * Complex(3.14159, 0).rationalize(0.00001) # => (355/113) + * Complex(3.14159, 0).rationalize(0.000001) # => (7433/2366) + * Complex(3.14159, 0).rationalize(0.0000001) # => (9208/2931) + * Complex(3.14159, 0).rationalize(0.00000001) # => (47460/15107) + * Complex(3.14159, 0).rationalize(0.000000001) # => (76149/24239) + * Complex(3.14159, 0).rationalize(0.0000000001) # => (314159/100000) + * Complex(3.14159, 0).rationalize(0.0) # => (3537115888337719/1125899906842624) + * + * Related: Complex#to_r. */ static VALUE nucomp_rationalize(int argc, VALUE *argv, VALUE self) @@ -1877,12 +1899,9 @@ nucomp_rationalize(int argc, VALUE *argv, VALUE self) /* * call-seq: - * complex.to_c -> self - * - * Returns self. + * to_c -> self * - * Complex(2).to_c #=> (2+0i) - * Complex(-8, 6).to_c #=> (-8+6i) + * Returns +self+. */ static VALUE nucomp_to_c(VALUE self)