[DOC] Complex doc (#9185)

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)