From e1d995a96cf99387ce1798904c3051ba11e43d18 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Mon, 11 Dec 2023 14:38:16 -0600
Subject: [PATCH] [DOC] Complex doc (#9185)

---
 complex.c | 34 +++++++++++++++++++++++++---------
 1 file changed, 25 insertions(+), 9 deletions(-)

diff --git a/complex.c b/complex.c
index 88b4e021779260..af4de452890edb 100644
--- a/complex.c
+++ b/complex.c
@@ -524,14 +524,15 @@ static VALUE nucomp_s_convert(int argc, VALUE *argv, VALUE klass);
 
 /*
  * call-seq:
- *   Complex(abs, arg = 0, exception: true) -> complex or nil
+ *   Complex(real, imag = 0, exception: true) -> complex or nil
  *   Complex(s, exception: true) -> complex or nil
  *
  * Returns a new \Complex object if the arguments are valid;
  * otherwise raises an exception if +exception+ is +true+;
  * otherwise returns +nil+.
  *
- * With Numeric argument +abs+, returns <tt>Complex.rect(abs, arg)</tt> if the arguments are valid.
+ * With Numeric arguments +real+ and +imag+,
+ * returns <tt>Complex.rect(real, imag)</tt> if the arguments are valid.
  *
  * With string argument +s+, returns a new \Complex object if the argument is valid;
  * the string may have:
@@ -751,12 +752,19 @@ nucomp_s_polar(int argc, VALUE *argv, VALUE klass)
 
 /*
  * call-seq:
- *    cmp.real  ->  real
+ *   real -> numeric
  *
- * Returns the real part.
+ * Returns the real value for +self+:
+ *
+ *   Complex(7).real      #=> 7
+ *   Complex(9, -4).real  #=> 9
+ *
+ * If +self+ was created with
+ * {polar coordinates}[rdoc-ref:Complex@Polar+Coordinates], the returned value
+ * is computed, and may be inexact:
+ *
+ *   Complex.polar(1, Math::PI/4).real # => 0.7071067811865476 # Square root of 2.
  *
- *    Complex(7).real      #=> 7
- *    Complex(9, -4).real  #=> 9
  */
 VALUE
 rb_complex_real(VALUE self)
@@ -767,13 +775,21 @@ rb_complex_real(VALUE self)
 
 /*
  * call-seq:
- *    cmp.imag       ->  real
- *    cmp.imaginary  ->  real
+ *   imag -> numeric
  *
- * Returns the imaginary part.
+ * Returns the imaginary value for +self+:
  *
  *    Complex(7).imaginary      #=> 0
  *    Complex(9, -4).imaginary  #=> -4
+ *
+ * If +self+ was created with
+ * {polar coordinates}[rdoc-ref:Complex@Polar+Coordinates], the returned value
+ * is computed, and may be inexact:
+ *
+ *   Complex.polar(1, Math::PI/4).imag # => 0.7071067811865476 # Square root of 2.
+ *
+ * \Complex#imaginary is an alias for \Complex#imag.
+ *
  */
 VALUE
 rb_complex_imag(VALUE self)