Re: [PATCH] document that alias and target must have the same type

[Sandra Loosemore <sandra@codesourcery.com>]

On 2/5/20 1:13 PM, Martin Sebor wrote:

> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index ec99c38a607..3634ce1c423 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -2557,8 +2557,11 @@ __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (c
>  
>  @item alias ("@var{target}")
>  @cindex @code{alias} function attribute
> -The @code{alias} attribute causes the declaration to be emitted as an
> -alias for another symbol, which must be specified.  For instance,
> +The @code{alias} attribute causes the declaration to be emitted as an alias
> +for another symbol, which must have been previously declared with the same
> +type, and for variables same size and alignment.  Declaring an alias with
> +a different type than the target is undefined and may be diagnosed.  For
> +instance, an alias for another symbol, which must be specified.  For instance,
>  
>  @smallexample
>  void __f () @{ /* @r{Do something.} */; @}

This is kind of garbled.  Do you have an extraneous sentence beginning 
"For instance" in there?  It doesn't flow from the text you added before 
that.

> @@ -3919,31 +3922,41 @@ results in warning on line 5.
>  
>  @item weak
>  @cindex @code{weak} function attribute
> -The @code{weak} attribute causes the declaration to be emitted as a weak
> -symbol rather than a global.  This is primarily useful in defining
> -library functions that can be overridden in user code, though it can
> -also be used with non-function declarations.  Weak symbols are supported
> -for ELF targets, and also for a.out targets when using the GNU assembler
> -and linker.
> +The @code{weak} attribute causes a declaration of an external symbol
> +to be emitted as a weak symbol rather than a global.  This is primarily
> +useful in defining library functions that can be overridden in user code,
> +though it can also be used with non-function declarations.  The overriding
> +symbol must have the same type, and for variables size, and alignment as
> +the weak symbol.  Weak symbols are supported for ELF targets, and also for
> +a.out targets when using the GNU assembler and linker.

The "for variables" clause is awkward and has a comma in the wrong 
place.  I'd split this into a separate sentence, like

The overriding symbol must have the same type as the weak symbol.  If it 
is a variable it must also have the same size and alignment.

>  @item weakref
>  @itemx weakref ("@var{target}")
>  @cindex @code{weakref} function attribute
>  The @code{weakref} attribute marks a declaration as a weak reference.
>  Without arguments, it should be accompanied by an @code{alias} attribute
> -naming the target symbol.  Optionally, the @var{target} may be given as
> -an argument to @code{weakref} itself.  In either case, @code{weakref}
> -implicitly marks the declaration as @code{weak}.  Without a
> -@var{target}, given as an argument to @code{weakref} or to @code{alias},
> -@code{weakref} is equivalent to @code{weak}.
> +naming the target symbol.  Alernatively, @var{target} may be given as

s/Alernatively/Alternatively/

> +an argument to @code{weakref} itself, naming the target definition of
> +the alias.  The the @var{target} must have the same type, and for

s/The the/The/

> +variables also the same size and alignment as the declaration.  In either

Same comments above re splitting this into two sentences to avoid 
awkward wording.

The rest of this patch looks OK.

-Sandra