Re: [PATCH] clarify doc for __builtin_return_address

[Martin Sebor <msebor@redhat.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