Re: [PATCH v4 5/5] Add documentation for musttail attribute

[Sandra Loosemore <sloosemore@baylibre.com>]

On 2/2/24 02:09, Andi Kleen wrote:
> gcc/ChangeLog:
> 
> 	* doc/extend.texi: Document [[musttail]]
> ---
>   gcc/doc/extend.texi | 16 ++++++++++++++++
>   1 file changed, 16 insertions(+)
> 
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index 142e41ab8fbf..866f6c4a9fed 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -9875,6 +9875,22 @@ foo (int x, int y)
>   @code{y} is not actually incremented and the compiler can but does not
>   have to optimize it to just @code{return 42 + 42;}.
>   
> +@cindex @code{musttail} statement attribute
> +@item musttail
> +
> +The @code{gnu::musttail} or @code{clang::musttail} attribute
> +can be applied to a return statement that returns the value
> +of a call to indicate that the call must be a tail call
> +that does not allocate extra stack space.

It took me about 3 attempts to parse this.  :-S  I think this might be a 
little better:

...can be applied to a @code{return} statement with a return-value 
expression that is a function call.  It asserts that the call must be a 
tail call that does not allocate extra stack space.

> +
> +@smallexample
> +[[gnu::musttail]] return foo();
> +@end smallexample
> +
> +If the compiler cannot generate a tail call it will generate

s/will generate/generates/

I'm a big fan of writing in the present tense.  ;-)

> +an error. Tail calls generally require enabling optimization.
> +On some targets they may not be supported.
> +
>   @end table
>   
>   @node Attribute Syntax

In addition to these changes, at the beginning of this section we have

@node Statement Attributes
@section Statement Attributes
@cindex Statement Attributes

GCC allows attributes to be set on null statements.  @xref{Attribute 
Syntax},
for details of the exact syntax for using attributes. [...]

Well, we now have an attribute that goes on a non-null statement, so we 
have to fix this.  The documentation for the other statement attributes 
is already explicit that they go on null statements so those already 
would be OK if we just removed the "null" restriction here.  OTOH, the 
Attribute Syntax section, in discussing GCC's traditional attribute 
syntax, says:

@subsubheading Statement Attributes
In GNU C, an attribute specifier list may appear as part of a null
statement.  The attribute goes before the semicolon.

If "musttail" is only supported in the standard attribute syntax, its 
new entry in the Statement Attributes node must say that, and the blurb 
at the top of the node quoted above must say something to the effect 
that the traditional syntax only allows statement attributes on null 
statements and attributes on non-null statements are only permitted in 
the new standard attribute form.

-Sandra