[patch, fortran, committed] Document COMPLEX*k syntax quirk.

[Brooks Moses]

Tobias Burnus wrote:
> you missed the diff, one can find it at:
> http://gcc.gnu.org/viewcvs/trunk/gcc/fortran/gfortran.texi?r1=121201&r2=122238&pathrev=122238&diff_format=h
> http://gcc.gnu.org/viewcvs/trunk/gcc/fortran/decl.c?r1=121830&r2=122238&pathrev=122238&diff_format=h

Thanks!  I also attached it to a followup post.

> trunk/gcc/fortran/decl.c:
> -/* Match an extended-f77 kind specification.  */
> +/* Match an extended-f77 kind specification.  This assumes that the kind
> +   number is equal to the byte size for non-COMPLEX types, and equal to 
> +   half of the byte size for COMPLEX.  */
> 
> Well, the kind number matches the complete byte-size of the complex variable (Re+Im). I think something like:
> 
> +/* Match an extended-f77 kind specification.  This assumes that the kind
> +   number is equal to the byte size; for COMPLEX it is the total byte size
> +   of real plus imaginary part.  */

You're confusing "kind number" and "the integer following the '*'".  The 
latter is the byte size (as the documentation now says), not the kind 
number.  The kind number is the value that gets assigned to ts->kind, 
just like it is in the rest of GFortran.  _That_ kind number is equal to 
half of the (total) byte size for a COMPLEX number.

Does the comment need to clarify that?  If so, I can try to make it clearer.

> Similarily for gfortran.texi; instead of
> 
>  where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
> +etc.), and where @code{size} is a byte count corresponding to a valid
> +kind for that type. The statement then declares @code{x}, @code{y} and
> +@code{z} to be of type @code{TYPESPEC} with the appropriate kind. This
> +is equivalent to the standard conforming declaration
>  @smallexample
>        TYPESPEC(k) x,y,z
>  @end smallexample
> +where @code{k} is equal to @code{size} for most types, but is equal to
> +@code{size/2} for the @code{COMPLEX} type.
> 
> I would prefer something like:
> 
>  where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
> +etc.), and where @code{size} is a byte count corresponding to a valid
> +kind for that type; for the @code{COMPLEX} type the @code{size} is
> +byte count of real plus imaginary part.
> +The statement then declares @code{x}, @code{y} and
> +@code{z} to be of type @code{TYPESPEC} with the appropriate kind. This
> +is equivalent to the standard conforming declaration
>  @smallexample
>        TYPESPEC(k) x,y,z
>  @end smallexample
> +where @code{k} is equal to @code{size} for most types, but is equal to
> +@code{size/2} for the @code{COMPLEX} type.

Hmm.  How about "...a byte count corresponding to the storage size of a 
valid kind for that type."?  Since the storage size of a complex number 
obviously includes both parts, that should make it clear without making 
it overly complicated.

- Brooks