Revamp documentation for _Complex types extension

While cleaning up the bug database, I noticed there was a request
to improve the documentation of the _Complex type extensions.
So I rewrote part of the documentation to make things clearer on
__real/__imag and even added documentation about casts between
the scalar and the complex type.
I moved the documentation of __builtin_complex under this section
too because it makes more sense than having it in the other
built-in section and reference it.

OK? Built make info and make html and checked out the results to
make sure the tables look decent.

gcc/ChangeLog:

	PR c/33193
	* doc/extend.texi: Extend the documentation about Complex
	types for casting and also rewrite the __real__/__imag__
	expression portion to use tables.
	Move __builtin_complex to the Complex type section.

1 files changed, 54 insertions, 19 deletions

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index c430741..5eec94e 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -986,22 +986,57 @@ The ISO C++14 library also defines the @samp{i} suffix, so C++14 code
 that includes the @samp{<complex>} header cannot use @samp{i} for the
 GNU extension.  The @samp{j} suffix still has the GNU meaning.
 
+GCC can handle both implicit and explicit casts between the @code{_Complex}
+types and other @code{_Complex} types as casting both the real and imaginary
+parts to the scalar type.
+GCC can handle implicit and explicit casts from a scalar type to a @code{_Complex}
+type and where the imaginary part will be considered zero.
+The C front-end can handle implicit and explicit casts from a @code{_Complex} type
+to a scalar type where the imaginary part will be ignored. In C++ code, this cast
+is considered illformed and G++ will error out.
+
+GCC provides a built-in function @code{__builtin_complex} will can be used to
+construct a complex value.
+
 @cindex @code{__real__} keyword
 @cindex @code{__imag__} keyword
-To extract the real part of a complex-valued expression @var{exp}, write
-@code{__real__ @var{exp}}.  Likewise, use @code{__imag__} to
-extract the imaginary part.  This is a GNU extension; for values of
-floating type, you should use the ISO C99 functions @code{crealf},
-@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
-@code{cimagl}, declared in @code{<complex.h>} and also provided as
+
+GCC has a few extensions which can be used to extract the real
+and the imaginary part of the complex-valued expression. Note
+these expressions are lvalues if the @var{exp} is an lvalue.
+These expressions operands have the type of a complex type
+which might get prompoted to a complex type from a scalar type.
+E.g. @code{__real__ (int)@var{x}} is the same as casting to
+@code{_Complex int} before @code{__real__} is done.
+
+@multitable @columnfractions .4 .6
+@headitem Expression @tab Description
+@item @code{__real__ @var{exp}}
+@tab Extract the real part of @var{exp}.
+@item @code{__imag__ @var{exp}}
+@tab Extract the imaginary part of @var{exp}.
+@end multitable
+
+For values of floating point, you should use the ISO C99
+functions, declared in @code{<complex.h>} and also provided as
 built-in functions by GCC@.
 
+@multitable @columnfractions .4 .2 .2 .2
+@headitem Expression @tab float @tab double @tab long double
+@item @code{__real__ @var{exp}}
+@tab @code{crealf} @tab @code{creal} @tab @code{creall}
+@item @code{__imag__ @var{exp}}
+@tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl}
+@end multitable
+
 @cindex complex conjugation
 The operator @samp{~} performs complex conjugation when used on a value
 with a complex type.  This is a GNU extension; for values of
 floating type, you should use the ISO C99 functions @code{conjf},
 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
-provided as built-in functions by GCC@.
+provided as built-in functions by GCC@. Note unlike the @code{__real__}
+and @code{__imag__} operators, this operator will not do an implicit cast
+to the complex type because the @samp{~} is already a normal operator.
 
 GCC can allocate complex automatic variables in a noncontiguous
 fashion; it's even possible for the real part to be in a register while
@@ -1013,6 +1048,18 @@ If the variable's actual name is @code{foo}, the two fictitious
 variables are named @code{foo$real} and @code{foo$imag}.  You can
 examine and set these two fictitious variables with your debugger.
 
+@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
+
+The built-in function @code{__builtin_complex} is provided for use in
+implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
+@code{CMPLXL}.  @var{real} and @var{imag} must have the same type, a
+real binary floating-point type, and the result has the corresponding
+complex type with real and imaginary parts @var{real} and @var{imag}.
+Unlike @samp{@var{real} + I * @var{imag}}, this works even when
+infinities, NaNs and negative zeros are involved.
+
+@end deftypefn
+
 @node Floating Types
 @section Additional Floating Types
 @cindex additional floating types
@@ -13834,18 +13881,6 @@ an error if there is no such function.
 
 @end deftypefn
 
-@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
-
-The built-in function @code{__builtin_complex} is provided for use in
-implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
-@code{CMPLXL}.  @var{real} and @var{imag} must have the same type, a
-real binary floating-point type, and the result has the corresponding
-complex type with real and imaginary parts @var{real} and @var{imag}.
-Unlike @samp{@var{real} + I * @var{imag}}, this works even when
-infinities, NaNs and negative zeros are involved.
-
-@end deftypefn
-
 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
 You can use the built-in function @code{__builtin_constant_p} to
 determine if a value is known to be constant at compile time and hence