Re: [PATCH] clarify doc for __builtin_return_address

[Martin Sebor <msebor at redhat dot com>]

On 05/21/2015 02:05 PM, Sandra Loosemore wrote:
> On 05/21/2015 01:19 PM, Martin Sebor wrote:
>
> > 2015-05-21  Martin Sebor  <msebor@redhat.com>
> >
> >      * extend.texi (Return Address): Clarify possible effects
> >      of calling the functions with non-zero arguments.
> >
> > diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> > index 7470e40..b37e893 100644
> > --- a/gcc/doc/extend.texi
> > +++ b/gcc/doc/extend.texi
> > @@ -7959,7 +7959,8 @@ Additional post-processing of the returned value
> > may be needed, see
> >   @code{__builtin_extract_return_addr}.
> >
> >   This function should only be used with a nonzero argument for debugging
> > -purposes.
> > +purposes since such calls to it can have unpredictable effects,
> > including
> > +crashing the calling program.
> >   @end deftypefn
> >
> >   @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr
> > (void *@var{addr})
>
> I think the problem is that the original sentence parses ambiguously --
> is it telling you that you must pass a nonzero argument to use it for
> debugging purposes, or telling you that you must use calls with a
> nonzero argument only for debugging?  And adding an additional clause
> onto the end only makes it harder to parse.
>
> I suggest rewriting it as something like
>
> Calling this function with a nonzero argument can have unpredictable
> effects, including crashing the calling program.  Such calls are
> typically only useful in debugging situations.

Thanks. I agree that's better. I'll wait for further comments
or approval to commit your version.

Martin