Re: [PATCH] Improve -Wmaybe-uninitialized documentation

[Jeff Law <law at redhat dot com>]

On 11/16/2017 03:49 AM, Jonathan Wakely wrote:
> On 15/11/17 20:28 -0700, Martin Sebor wrote:
>> On 11/15/2017 07:31 AM, Jonathan Wakely wrote:
>>> The docs for -Wmaybe-uninitialized have some issues:
>>>
>>> - That first sentence is looooooong.
>>> - Apparently some C++ programmers think "automatic variable" means one
>>> declared with C++11 `auto`, rather than simply a local variable.
>>> - The sentence about only warning when optimizing is stuck in between
>>> two chunks talking about longjmp, which could be inferred to mean
>>> only the setjmp/longjmp part of the warning depends on optimization.
>>>
>>> This attempts to make it easier to parse and understand.
>>
>> I've always found the description remarkably precise.  Particularly
>> the bit where it talks about the two paths, one initialized and the
>> other not.  Your rewording loses that distinction so I don't think
>> it's as accurate, or even correct.
>>
>> To use an example, this would satisfy the new description:
>>
>>  int f (void)
>>  {
>>    int i;
>>    return i;
>>  }
>>
>> but it doesn't match GCC behavior (it triggers -Wuninitialized,
>> not -Wmaybe-uninitialized).  Unless the distinction is more
>> subtle than I ascribe to it I think it needs to be preserved
>> in the rewording.
> 
> Ah, I tested a similar case and missed that the warning I got was from
> -Wuninitialized not -Wmaybe-uninitialized, which made me think that
> "a use of the variable that is initialized" was wrong.
> 
> OK, so then here's an alternative patch which doesn't touch that first
> sentence except to add "(i.e. local)". That makes the first sentence
> even longer, but if it's accurate maybe that's OK. This still adds
> "These warnings are only possible in optimizing compilation, because
> otherwise GCC does not keep track of the state of variables." And
> removes the similar text from the middle of the setjmp/longjmp
> discussion.
> 
> 
> 
> patch.txt
> 
> 
> commit 3ebe2a74817bbbbb63e27f961e91e6c044d00245
> Author: Jonathan Wakely <jwakely@redhat.com>
> Date:   Thu Nov 16 10:43:51 2017 +0000
> 
>     Improve -Wmaybe-uninitialized documentation
>     
>             * doc/invoke.texi (-Wmaybe-uninitialized): Rephrase for clarity.
> 
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 85c980bdfc9..bb68c308166 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -4970,11 +4970,16 @@ void store (int *i)
>  @item -Wmaybe-uninitialized
>  @opindex Wmaybe-uninitialized
>  @opindex Wno-maybe-uninitialized
> -For an automatic variable, if there exists a path from the function
> -entry to a use of the variable that is initialized, but there exist
> +For an automatic (i.e.@ local) variable, if there exists a path from the
> +function entry to a use of the variable that is initialized, but there exist
s/exist/exists/

?

I think with that nit it's ok.

jeff