doc: Extend musttail attribute docs

On Wed, Apr 02, 2025 at 10:32:20AM +0200, Richard Biener wrote:
> I wonder if we can amend the documentation to suggest to end lifetime
> of variables explicitly by proper scoping?

In the -Wmaybe-musttail-local-addr attribute description I've already
tried to show that in the example, but if you think something like
the following would make it clearer.

2025-04-02  Jakub Jelinek  <jakub@redhat.com>

	* doc/extend.texi (musttail statement attribute): Hint how
	to avoid -Wmaybe-musttail-local-addr warnings.

1 files changed, 25 insertions, 0 deletions

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 9bf401b..109c7d2 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9368,6 +9368,31 @@ baz (int *x)
     @}
 @}
 @end smallexample
+
+To avoid the @option{-Wmaybe-musttail-local-addr} warning in the
+above @code{*x == 2} case and similar code, consider defining the
+maybe escaped variables in a separate scope which will end before the
+return statement if possible to make it clear that the variable is not
+live during the call.  So
+
+@smallexample
+  else if (*x == 2)
+    @{
+      @{
+        int a = 42;
+        bar (&a);
+      @}
+      /* The call will be tail called (would not be without the
+         attribute), if bar stores the pointer anywhere, dereferencing
+         it in foo will be undefined behavior and there will be a warning
+         emitted for this with @option{-Wextra}, which implies
+         @option{-Wmaybe-musttail-local-addr}.  */
+      [[gnu::musttail]] return foo (nullptr);
+    @}
+@end smallexample
+
+in this case.  That is not possible if it is function argument which
+is address taken because those are in scope for the whole function.
 @end table
 
 @node Attribute Syntax