Re: [PATCH] Improve -Wmaybe-uninitialized documentation

[Jonathan Wakely <jwakely@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 1791 bytes --]

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.



[-- Attachment #2: patch.txt --]
[-- Type: text/x-patch, Size: 1915 bytes --]

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
 some other paths for which the variable is not initialized, the compiler
 emits a warning if it cannot prove the uninitialized paths are not
-executed at run time. These warnings are made optional because GCC is
+executed at run time.
+
+These warnings are only possible in optimizing compilation, because otherwise
+GCC does not keep track of the state of variables.
+
+These warnings are made optional because GCC is
 not smart enough to see all the reasons why the code might be correct
 in spite of appearing to have an error.  Here is one example of how
 this can happen:
@@ -5004,9 +5009,7 @@ similar code.
 
 @cindex @code{longjmp} warnings
 This option also warns when a non-volatile automatic variable might be
-changed by a call to @code{longjmp}.  These warnings as well are possible
-only in optimizing compilation.
-
+changed by a call to @code{longjmp}.
 The compiler sees only the calls to @code{setjmp}.  It cannot know
 where @code{longjmp} will be called; in fact, a signal handler could
 call it at any point in the code.  As a result, you may get a warning