[v4,5/5] Add documentation for musttail attribute

gcc/ChangeLog:

	* doc/extend.texi: Document [[musttail]]
---
 gcc/doc/extend.texi | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

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

On Sat, Feb 03, 2024 at 09:35:43PM -0700, Sandra Loosemore wrote:
> 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

FWIW we always had, they just were ignored (with a warning)


Thanks Sandra. I applied the changes. Diff appeneded for reference.


diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 866f6c4a9fed..fe1ee245ed69 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9818,7 +9818,7 @@ same manner as the @code{deprecated} attribute.
 @section Statement Attributes
 @cindex Statement Attributes
 
-GCC allows attributes to be set on null statements.  @xref{Attribute Syntax},
+GCC allows attributes to be set on statements.  @xref{Attribute Syntax},
 for details of the exact syntax for using attributes.  Other attributes are
 available for functions (@pxref{Function Attributes}), variables
 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
@@ -9879,15 +9879,15 @@ have to optimize it to just @code{return 42 + 42;}.
 @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.
+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
+If the compiler cannot generate a tail call it generates
 an error. Tail calls generally require enabling optimization.
 On some targets they may not be supported.
 
@@ -10014,7 +10014,9 @@ the constant expression, if present.
 
 @subsubheading Statement Attributes
 In GNU C, an attribute specifier list may appear as part of a null
-statement.  The attribute goes before the semicolon.
+statement. The attribute goes before the semicolon.
+Some attributes in new style syntax are also supported
+on non-null statements.
 
 @subsubheading Type Attributes